Add PIDINST IDs to your Inventory Items 🧪

Introduction

PIDINST IDs

PIDINST IDs are persistent, globally resolvable, and unique identifiers (PIDs) for instruments. By associating a PIDINST ID with an instrument, you enable transparency and traceability between research objects. This is achieved by providing a publicly accessible web page (called a landing page) that contains the instrument metadata, serving as a unique "source of truth" when referencing the instrument in research outputs.

The PIDINST ID metadata can also describe relationships between the resource and other related materials, such as projects, institutions, people, and research outputs; it can also be used to identify an individual instrument, a group of instruments, or a feature-of-interest (e.g. a collection site for instruments).

Create a PIDINST ID

RSpace offers a direct approach for creating and managing PIDINST IDs and linking them to your instruments in RSpace Inventory.

Register a PIDINST ID

This approach begins with an existing Instrument in RSpace Inventory and creates a PIDINST ID directly from the item's Identifiers section. When you create a PIDINST ID this way, the metadata for the identifier is automatically populated with information from your Instrument in RSpace, streamlining the setup process.

RSpace reserves a PIDINST ID in Draft state and associates it with the RSpace Instrument. PIDINST ID metadata will be available to fill out in RSpace, but the metadata and identifier are not made public at this stage.

The Draft PIDINST ID can be deleted, or published to explicitly make the metadata publicly accessible.

To create an automatically linked PIDINST ID:

1. Open the Identifiers section on the Instrument:

   

2. Press the "Create new PIDINST ID" button to create a PIDINST ID. Each Instrument can only be assigned 1 PIDINST ID. Note that if you are in the process of creating a new item, you will need to save the item first before being able to create a PIDINST ID for it.

   

   If the button is disabled, or you get a "The Identifier could not be created. PIDINST integration is not enabled on this RSpace instance." error after pressing the button, please contact your System Administrator.
3. The identifier section now shows the Draft PIDINST ID and its metadata fields. Required fields have been pre-populated with default values.
   RSpace does not send metadata to DataCite when a PIDINST ID is in Draft state, the metadata is only made public when publishing the PIDINST ID.

   

Add geolocation information

You can associate various geolocation data with each PIDINST ID, e.g. to describe the location of the instrument, or the reach of its sensors. The specification for how this data is captured is quite complex, so here's an overview.

Format options

First, each geolocation can be described using one or more methods: as a point, a description, a box, and/or a polygon.

All longitudes and latitudes use decimal degrees rather than minutes and seconds, so any decimal value between -90.0 and 90.0 inclusively for latitudes, and -180.0 and 180.0 inclusively for longitudes, is valid.

• The point is a single longitude and latitude pair. Both values need to be set to define a point.
• The description is a textual description of the place. An instrument may be located at a particular site, with the site's location described by the other geolocation properties, while the address is included here.
• The box is a region defined by four bounds, in each of the cardinal directions. This is useful for describing approximate regions, again, using decimal degrees.
• The polygon method provides a mechanism for accurately describing a region based on a series of vertices. The first and last points are always the same, enclosing an area. For the avoidance of any ambiguity, an additional point within the enclosed region can also be specified, but this is only really necessary when it may not be obvious whether the region is the area inside the points, or the rest of the Earth.

  

  Preview map

The point, box, and polygon are shown on a map both in Inventory and on the public page, alongside the numerical coordinates, to make it easier to visualise the location being described. Points are shown as a blue circle, with the precise point being at the circle's center. Boxes are shown as red rectangles, and the polygons are shown in orange.

The partial screenshot below shows a point at the Royal Observatory and a region of Greenwich park by means of a bounding box.

Note that you can pan the map by clicking and dragging, and use the plus and minus icons to zoom in/out. You can also temporarily toggle the visibility of various data on the map, by using the toggles below it (the selection resets once you refresh a page).

Publish geolocations

Each geolocation entry needs to be defined by at least one of these methods, but can also be described by all four. Multiple geolocation entries can be added to the same PIDINST, and the methods they use to describe a location can be different.

Whilst the Inventory item with the PIDINST can be saved at any time, if the geolocation data is invalid, e.g. a coordinate is missing or outside of the valid range, then the PIDINST cannot be published.

Include Instrument metadata

Various metadata associated with the Instrument, but not part of the PIDINST schema, can be included on the PIDINST landing page to provide a comprehensive, domain-specific record of the item. This includes description, tags, the custom fields as populated from the template, and any extra fields that have been added to the item.

1. To include these fields on the public page, simply check the box labelled "Include Inventory fields on landing page".

   

2. To set these changes live, Preview the updated landing page to make sure you are happy with the fields that will be made public, then Publish or Republish the identifier, which will publish or update the public landing page.

   

3. The fields will now be visible on the public page, and within the preview dialog going forward. Note that any updates to these fields will not automatically show on the public page, as the PIDINST must be explicitly republished first.

Publish a PIDINST ID

The publishing process for a PIDINST ID depends on whether your RSpace instance uses DataCite or B2INST as a registry.

For DataCite, Publishing sets the PIDINST ID state to Findable on DataCite. The PIDINST ID and its metadata, alongside a landing page generated by RSpace, will be made publicly accessible through DataCite websites and their respective APIs. A persistent, citable PIDINST ID URL will be created, pointing to the landing page.

After publishing, the PIDINST ID cannot be returned to a Draft state. Changing the state to Registered keeps the metadata visible via the DataCite.

For B2INST, the publishing process depends on the B2INST community your RSpace instance is publishing to. The community setup determines whether further curation steps are involved to publish your Instruments. Please contact your administrator for further details on the process used at your institution.

See DataCite DOI States or the B2INST documentation for more information.

To publish a PIDINST ID:

1. Click on Publish in the Identifiers section. The button is only enabled if all required fields are filled in.

   

2. The state of the PIDINST ID changes to Findable. A persistent and public landing page is generated and hosted by RSpace. The PIDINST ID redirects to this landing page, providing a stable URL that can be used to share and reference this item.

   

Add PIDINST IDs to Dataverse export metadata

When you export your research data from RSpace to Dataverse, the PIDINST IDs of associated instruments will be automatically included in the Dataverse dataset metadata as Related Materials. This enables reviewers, collaborators, and future researchers to easily access the authoritative sample information from the Dataverse dataset page.

The following process ensures PIDINST IDs are added to the Dataverse export metadata:

1. Ensure you've got a Dataverse Integration set up.
2. Add PIDINST IDs to relevant Instruments.
3. Attach those Instruments to documents using a List of Materials, which is used to keep track of Inventory items used during experiments.
4. When you are ready to export your research, select those documents and export them to Dataverse in a format of your choice.
   During the export setup, you can increase the depth of linked documents that get included in the export. Any PIDINST IDs in the Lists of Materials of those linked documents will be included in the export metadata as well.
5. The Dataverse export's metadata panel will display a full list of PIDINST IDs associated with the export. This list includes all Instruments with PIDINST IDs that were present in Lists of Materials of the exported documents.

   

Update a PIDINST ID

Any PIDINST ID metadata changes you make in RSpace are not made public until you explicitly publish them. We recommend only updating a PIDINST ID to provide additional metadata, or to correct any errors.

If the item has been modified significantly enough to exhibit different properties, you need to decide whether it is important for you that a PIDINST ID always points to a specific version of the item, e.g. if the PIDINST ID is going to be referenced in a paper. If so, we recommend creating a separate item in RSpace, assigning it a new PIDINST ID, and clearly indicating the link between the historical and new item in their metadata.

To update a PIDINST ID:

1. Make required changes to the PIDINST ID metadata fields
2. Click on Republish
3. The landing page will now reflect the latest version of the metadata

Delete a PIDINST ID

Deleting removes the PIDINST ID and its association with this item.

To delete a PIDINST ID:

1. Click on Delete in the Identifiers section.

   

2. The PIDINST ID is deleted and removed from the section.
   A new Draft PIDINST ID can be created and associated with the item in the future, whether the item had a Draft PIDINST ID previously or not. However, only one PIDINST ID can be associated with an item at any one time.
   Deleting a PIDINST ID also removes all metadata you might have filled in, therefore we recommend only deleting a PIDINST ID if you are confident this item will not require one for the time being.

Retract a PIDINST ID

Click on Retract to change a Findable PIDINST ID into a Registered PIDINST ID. This will remove the PIDINST ID from either the DataCite or B2INST repository, as well as display no metadata on the landing page. Keep in mind the appropriate API can still be used to access historical metadata about the item.

If you wish to have the instrument be public again, you can Republish it to turn it back to Findable.