🏃‍♀️ Usage

Overview

A DOI (Digital Object Identifier) is a URI which is used to permanently identify a digital object: dataset or document. The DOI is then used to cite the digital object, especially in scientific papers.

In the context of PDS, the DOIs follows this workflow: - reserve: before a dataset is published in PDS, a DOI can be reserved so that the researchers working with the digital resource at early stage can cite it in their papers. This step is optional. - draft: the metadata associated to the DOI is elaborated and validated. - release: the offcial DOI is registered at OSTI and dataCite. - deactivate (To Be Done): although it is not supposed to happen, due to error in the release one might deactivate a DOI.

The reserve, draft and release steps can be repeated multiple time to update a DOI metadata.

The inputs to the DOI creation are either PDS4 labels or ad hoc spreadsheets (for the reserve step).

The metadata managed with DOIs is meant to be preserved and traceable as it is used to permanently cite a digital resource. For this reason all the transactions, creations, updates with the PDS DOI management system are registered in a database.

Currently the tool provided is activated with a command line and used by a PDS Engineering Node operator interacting with the Discipline Nodes. A later version will provide a web API, a web UI and a cmd API client to enable Discipline Nodes to directly manage their DOIs.

Usage Information

PDS core command for DOI management. The available subcommands are: reserve (Create or update a DOI before the data is published), draft (Prepare an OSTI record from PDS4 labels), release (create or update a DOI on OSTI server), check (Check DOI pending status at OSTI and update the local database. Should be run regularly, for example in a crontab.), list (extract doi descriptions with criteria),

usage: pds-doi-cmd [-h] {reserve,draft,release,check,list} ...

Positional Arguments

subcommand

Possible choices: reserve, draft, release, check, list

Sub-commands:

reserve

Create a DOI for one or more unpublished datasets. The input is a spreadsheet or CSV file containing records to reserve DOIs for.

pds-doi-cmd reserve [-h] -n "img" [-f] -i input/DOI_Reserved_GEO_200318.csv -s
                    "my.email@node.gov" [-dry-run]
Named Arguments
-n, --node

The PDS Discipline Node in charge of the submission of the DOI. Authorized values are: atm,eng,geo,img,naif,ppi,rms,sbn

-f, --force

If provided, forces the reserve action to proceed even if warnings are encountered during submission of the reserve to OSTI. Without this flag, any warnings encountered are treated as fatal exceptions.

Default: False

-i, --input

A PDS4 XML label, OSTI XML/JSON label or XLS/CSV spreadsheet file with the following columns: status,title,publication_date,product_type_specific,author_last_name,author_first_name,related_resource

-s, --submitter-email

The email address to associate with the Reserve request.

-dry-run, --dry-run

Performs the Reserve request without submitting the record to OSTI. The record is logged to the local database with a status of ‘reserved_not_submitted’.

Default: False

draft

Create a draft of OSTI records, from existing PDS4 or OSTI labels

pds-doi-cmd draft [-h] [-i input/bundle_in_with_contributors.xml] -n "img" -s
                  "my.email@node.gov"
                  [-l urn:nasa:pds:lab_shocked_feldspars::1.0] [-f]
                  [-k "Image"] [-t osti]
Named Arguments
-i, --input

An input PDS4/OSTI label. May be a local path or an HTTP address resolving to a label file. Multiple inputs may be provided via comma-delimited list. Must be provided if –lidvid is not specified.

-n, --node

The PDS Discipline Node in charge of the DOI. Authorized values are: atm,eng,geo,img,naif,ppi,rms,sbn

-s, --submitter

The email address to associate with the Draft record.

-l, --lidvid

A LIDVID for an existing DOI record to move back to draft status. Must be provided if –input is not specified.

-f, --force

If provided, forces the action to proceed even if warnings are encountered during submission of the draft record to the database. Without this flag, any warnings encountered are treated as fatal exceptions.

Default: False

-k, --keywords

Extra keywords to associate with the Draft record. Multiple keywords must be separated by “,”. Ignored when used with the –lidvid option.

Default: “”

-t, --target

The system target to mint the DOI. Currently, only the value “osti” is supported.

Default: “osti”

release

Release a DOI, in draft or reserve status, for review. A DOI may also be released to the OSTI server directly.

pds-doi-cmd release [-h] -n "img" [-f] -i input/DOI_Update_GEO_200318.xml -s
                    "my.email@node.gov" [--no-review]
Named Arguments
-n, --node

The PDS Discipline Node in charge of the released DOI. Authorized values are: atm,eng,geo,img,naif,ppi,rms,sbn

-f, --force

If provided, forces the release action to proceed even if warning are encountered during submission of the release to OSTI. Without this flag, any warnings encountered are treated as fatal exceptions.

Default: False

-i, --input

A file containing a list of DOI metadata to update/release in OSTI JSON/XML format (see https://www.osti.gov/iad2/docs#record-model).The input is produced by the Reserve and Draft actions, and can be retrieved for a DOI with the List action.

-s, --submitter

The email address to associate with the Release request.

--no-review

If provided, the requested DOI will be released directly to the OSTI server for registration. Use to override the default behavior of releasing a DOI to “review” status.

Default: False

check

Undocumented

pds-doi-cmd check [-h] [-e] [-a] [-s "my.email@node.gov"]
Named Arguments
-e, --email

If provided, the check action sends results to the default recipients and pending DOI submitters.

Default: False

-a, --attachment

If provided, the check action sends results as an email attachment. Has no effect if –email is not also provided.

Default: False

-s, --submitter

The email address of the user to register as author of the check action.

list

Extracts the submitted DOI from the local transaction database using the following selection criteria.

pds-doi-cmd list [-h] [-n "img,eng"] [-status draft,review] [-f JSON]
                 [-doi 10.17189/21734]
                 [-lid urn:nasa:pds:lab_shocked_feldspars]
                 [-lidvid urn:nasa:pds:lab_shocked_feldspars::1.0]
                 [-start 2020-01-01T19:02:15.000000]
                 [-end 2020-12-311T23:59:00.000000] [-s "my.email@node.gov"]
Named Arguments
-n, --node

A list of node names comma separated to return the matching DOI. Authorized values are: atm,eng,geo,img,naif,ppi,rms,sbn

-status, --status

A list of comma-separated submission status values to pass as input to the database query. Valid status values are: error, unknown, reserved_not_submitted, reserved, draft, review, pending, registered

-f, --format

The format of the output from the database query. Currently, only JSON format is supported.

Default: “JSON”

-doi, --doi

A list of comma-delimited DOIs to pass as input to the database query.

-lid, --lid

A list of comma-delimited LIDs to pass as input to the database query. Each LID may contain one or more wildcards (*) to pattern match against.

-lidvid, --lidvid

A list of comma-delimited LIDVIDs to pass as input to the database query. Each LIDVID may contain one or more wildcards (*) to pattern match against.

-start, --start-update

The start time of the record update to pass as input to the database query.

-end, --end-update

The end time for record update time to pass as input to the database query.

-s, --submitter

A list of email addresses comma separated to pass as input to the database query.