RO-Crate Commands

This document provides detailed information about the RO-Crate commands available in fairscape-cli.

Overview

The rocrate command group provides operations for creating and manipulating Research Object Crates (RO-Crates). RO-Crates are a lightweight approach to packaging research data with their metadata, making them more FAIR (Findable, Accessible, Interoperable, and Reusable).

fairscape-cli rocrate [COMMAND] [OPTIONS]

Available Commands

  • create - Create a new RO-Crate in a specified directory
  • init - Initialize an RO-Crate in the current working directory
  • register - Add metadata to an existing RO-Crate
  • add - Add a file to the RO-Crate and register its metadata
    • dataset - Add a dataset file and its metadata
    • software - Add a software file and its metadata

Command Details

create

Create a new RO-Crate in a specified directory.

fairscape-cli rocrate create [OPTIONS] ROCRATE_PATH

Options:

  • --guid TEXT - Optional custom identifier for the RO-Crate
  • --name TEXT - Name of the RO-Crate [required]
  • --organization-name TEXT - Name of the organization [required]
  • --project-name TEXT - Name of the project [required]
  • --description TEXT - Description of the RO-Crate [required]
  • --keywords TEXT - Keywords (can be specified multiple times) [required]
  • --license TEXT - License URL (default: "https://creativecommons.org/licenses/by/4.0/")
  • --date-published TEXT - Publication date (ISO format)
  • --author TEXT - Author name (default: "Unknown")
  • --version TEXT - Version number (default: "1.0")
  • --associated-publication TEXT - Associated publication
  • --conditions-of-access TEXT - Conditions of access
  • --copyright-notice TEXT - Copyright notice
  • --custom-properties TEXT - JSON string with additional properties to include

Example:

fairscape-cli rocrate create \
  --name "test rocrate" \
  --description "Example RO Crate for Tests" \
  --organization-name "UVA" \
  --project-name "B2AI"  \
  --keywords "b2ai" \
  --keywords "cm4ai" \
  "./test_rocrate"

init

Initialize an RO-Crate in the current working directory.

fairscape-cli rocrate init [OPTIONS]

Options: The same options as for the create command are available. The difference is that init creates the RO-Crate in the current working directory.

Example:

fairscape-cli rocrate init \
  --name "test rocrate" \
  --description "Example RO Crate for Tests" \
  --organization-name "UVA" \
  --project-name "B2AI"  \
  --keywords "b2ai" \
  --keywords "cm4ai"

register

Add metadata to an existing RO-Crate. This command has several subcommands depending on the type of metadata to register.

register dataset

Register dataset metadata with an existing RO-Crate.

fairscape-cli rocrate register dataset [OPTIONS] ROCRATE_PATH

Options:

  • --guid TEXT - Optional custom identifier for the dataset
  • --name TEXT - Name of the dataset [required]
  • --author TEXT - Author of the dataset [required]
  • --version TEXT - Version of the dataset [required]
  • --description TEXT - Description of the dataset [required]
  • --keywords TEXT - Keywords (can be specified multiple times) [required]
  • --data-format TEXT - Format of the dataset (e.g., csv, json) [required]
  • --filepath TEXT - Path to the dataset file (relative to crate root)
  • --content-url TEXT - URL to the dataset file (if hosted externally)
  • --embargoed - Flag indicating the dataset is embargoed (default: false)
  • --url TEXT - URL reference for the dataset
  • --date-published TEXT - Publication date of the dataset (ISO format) [required]
  • --schema TEXT - Schema identifier for the dataset
  • --used-by TEXT - Identifiers of computations that use this dataset (can be specified multiple times)
  • --derived-from TEXT - Identifiers of datasets this one is derived from (can be specified multiple times)
  • --generated-by TEXT - Identifiers of computations that generated this dataset (can be specified multiple times)
  • --summary-statistics-filepath TEXT - Path to summary statistics file
  • --associated-publication TEXT - Associated publication identifier
  • --additional-documentation TEXT - Additional documentation
  • --custom-properties TEXT - JSON string with additional properties to include

File Location Options: You must specify exactly one of the following options to indicate where the dataset is located:

  • --filepath - For datasets stored within the RO-Crate
  • --content-url - For datasets hosted externally at a URL
  • --embargoed - For datasets that are embargoed/restricted

If multiple options are provided, they are prioritized in this order: filepath > content-url > embargoed.

Example:

# Register a dataset file within the crate
fairscape-cli rocrate register dataset \
  --name "AP-MS embeddings" \
  --author "Krogan lab" \
  --version "1.0" \
  --date-published "2023-04-23" \
  --description "APMS embeddings for each protein" \
  --keywords "proteomics" \
  --data-format "CSV" \
  --filepath "./test_rocrate/embeddings.csv" \
  "./test_rocrate"

# Register an external dataset
fairscape-cli rocrate register dataset \
  --name "External Dataset" \
  --author "External Provider" \
  --version "1.0" \
  --date-published "2023-04-23" \
  --description "Dataset hosted externally" \
  --keywords "external" \
  --data-format "CSV" \
  --content-url "https://example.com/dataset.csv" \
  "./test_rocrate"

# Register an embargoed dataset
fairscape-cli rocrate register dataset \
  --name "Embargoed Dataset" \
  --author "Research Team" \
  --version "1.0" \
  --date-published "2023-04-23" \
  --description "Dataset under embargo" \
  --keywords "embargoed" \
  --data-format "CSV" \
  --embargoed \
  "./test_rocrate"

register software

Register software metadata with an existing RO-Crate.

fairscape-cli rocrate register software [OPTIONS] ROCRATE_PATH

Options:

  • --guid TEXT - Optional custom identifier for the software
  • --name TEXT - Name of the software [required]
  • --author TEXT - Author of the software [required]
  • --version TEXT - Version of the software [required]
  • --description TEXT - Description of the software [required]
  • --keywords TEXT - Keywords (can be specified multiple times) [required]
  • --file-format TEXT - Format of the software (e.g., py, js) [required]
  • --url TEXT - URL reference for the software
  • --date-modified TEXT - Last modification date of the software (ISO format)
  • --filepath TEXT - Path to the software file (relative to crate root)
  • --content-url TEXT - URL to the software file (if hosted externally)
  • --embargoed - Flag indicating the software is embargoed (default: false)
  • --used-by-computation TEXT - Identifiers of computations that use this software (can be specified multiple times)
  • --associated-publication TEXT - Associated publication identifier
  • --additional-documentation TEXT - Additional documentation
  • --custom-properties TEXT - JSON string with additional properties

File Location Options: You must specify exactly one of the following options to indicate where the software is located:

  • --filepath - For software stored within the RO-Crate
  • --content-url - For software hosted externally at a URL
  • --embargoed - For software that is embargoed/restricted

If multiple options are provided, they are prioritized in this order: filepath > content-url > embargoed.

Example:

# Register software file within the crate
fairscape-cli rocrate register software \
  --name "calibrate pairwise distance" \
  --author "Qin, Y." \
  --version "1.0" \
  --description "script written in python to calibrate pairwise distance." \
  --keywords "b2ai" \
  --file-format "py" \
  --filepath "./test_rocrate/calibrate_pairwise_distance.py" \
  --date-modified "2023-04-23" \
  "./test_rocrate"

# Register external software
fairscape-cli rocrate register software \
  --name "External Analysis Tool" \
  --author "External Developer" \
  --version "2.1" \
  --description "Analysis tool hosted on GitHub" \
  --keywords "analysis" \
  --file-format "py" \
  --content-url "https://github.com/user/repo/blob/main/analysis.py" \
  --date-modified "2023-04-23" \
  "./test_rocrate"

# Register embargoed software
fairscape-cli rocrate register software \
  --name "Proprietary Algorithm" \
  --author "Research Team" \
  --version "1.0" \
  --description "Proprietary analysis algorithm" \
  --keywords "proprietary" \
  --file-format "py" \
  --embargoed \
  --date-modified "2023-04-23" \
  "./test_rocrate"

register computation

Register computation metadata with an existing RO-Crate.

fairscape-cli rocrate register computation [OPTIONS] ROCRATE_PATH

Options:

  • --guid TEXT - Optional custom identifier for the computation
  • --name TEXT - Name of the computation [required]
  • --run-by TEXT - Person or entity that ran the computation [required]
  • --command TEXT - Command used to run the computation (string or JSON list)
  • --date-created TEXT - Date the computation was run (ISO format) [required]
  • --description TEXT - Description of the computation [required]
  • --keywords TEXT - Keywords (can be specified multiple times) [required]
  • --used-software TEXT - Software identifiers used by this computation (can be specified multiple times)
  • --used-dataset TEXT - Dataset identifiers used by this computation (can be specified multiple times)
  • --generated TEXT - Dataset/Software identifiers generated by this computation (can be specified multiple times)
  • --associated-publication TEXT - Associated publication identifier
  • --additional-documentation TEXT - Additional documentation
  • --custom-properties TEXT - JSON string with additional properties

Example:

fairscape-cli rocrate register computation \
  --name "calibrate pairwise distance" \
  --run-by "Qin, Y." \
  --date-created "2023-05-23" \
  --description "Average the predicted proximities" \
  --keywords "b2ai" \
  --keywords "cm4ai" \
  "./test_rocrate"

register sample

Register sample metadata with an existing RO-Crate.

fairscape-cli rocrate register sample [OPTIONS] ROCRATE_PATH

Options:

  • --guid TEXT - Optional custom identifier for the sample
  • --name TEXT - Name of the sample [required]
  • --author TEXT - Author or creator of the sample [required]
  • --description TEXT - Description of the sample [required]
  • --keywords TEXT - Keywords (can be specified multiple times) [required]
  • --filepath TEXT - Path to the sample documentation file
  • --cell-line-reference TEXT - Reference to the cell line used
  • --custom-properties TEXT - JSON string with additional properties

Example:

fairscape-cli rocrate register sample \
  --name "HeLa Cell Sample" \
  --author "Lab Technician" \
  --description "HeLa cells prepared for proteomics analysis" \
  --keywords "cell-culture" \
  --keywords "proteomics" \
  --cell-line-reference "ATCC CCL-2" \
  "./test_rocrate"

register instrument

Register instrument metadata with an existing RO-Crate.

fairscape-cli rocrate register instrument [OPTIONS] ROCRATE_PATH

Options:

  • --guid TEXT - Optional custom identifier for the instrument
  • --name TEXT - Name of the instrument [required]
  • --manufacturer TEXT - Manufacturer of the instrument [required]
  • --model TEXT - Model number/name of the instrument [required]
  • --description TEXT - Description of the instrument [required]
  • --filepath TEXT - Path to instrument documentation file
  • --used-by-experiment TEXT - Identifiers of experiments using this instrument (can be specified multiple times)
  • --associated-publication TEXT - Associated publication identifier
  • --additional-documentation TEXT - Additional documentation
  • --custom-properties TEXT - JSON string with additional properties

Example:

fairscape-cli rocrate register instrument \
  --name "Mass Spectrometer MS-1000" \
  --manufacturer "Thermo Fisher Scientific" \
  --model "Orbitrap Fusion Lumos" \
  --description "High-resolution mass spectrometer for proteomics" \
  --filepath "./instruments/ms1000_manual.pdf" \
  "./test_rocrate"

register experiment

Register experiment metadata with an existing RO-Crate.

fairscape-cli rocrate register experiment [OPTIONS] ROCRATE_PATH

Options:

  • --guid TEXT - Optional custom identifier for the experiment
  • --name TEXT - Name of the experiment [required]
  • --experiment-type TEXT - Type of experiment conducted [required]
  • --run-by TEXT - Person or entity that ran the experiment [required]
  • --description TEXT - Description of the experiment [required]
  • --date-performed TEXT - Date the experiment was performed (ISO format) [required]
  • --used-instrument TEXT - Instrument identifiers used in this experiment (can be specified multiple times)
  • --used-sample TEXT - Sample identifiers used in this experiment (can be specified multiple times)
  • --used-treatment TEXT - Treatment identifiers used in this experiment (can be specified multiple times)
  • --used-stain TEXT - Stain identifiers used in this experiment (can be specified multiple times)
  • --generated TEXT - Identifiers of entities generated by this experiment (can be specified multiple times)
  • --protocol TEXT - Protocol identifier or description
  • --associated-publication TEXT - Associated publication identifier
  • --custom-properties TEXT - JSON string with additional properties

Example:

fairscape-cli rocrate register experiment \
  --name "Proteomics Analysis Experiment" \
  --experiment-type "Mass Spectrometry" \
  --run-by "Research Team" \
  --description "Comprehensive proteomics analysis of cell samples" \
  --date-performed "2023-05-15" \
  --used-instrument "ark:/12345/instrument-1" \
  --used-sample "ark:/12345/sample-1" \
  --protocol "Standard MS Protocol v2.1" \
  "./test_rocrate"

register subrocrate

Register a new RO-Crate within an existing RO-Crate directory.

fairscape-cli rocrate register subrocrate [OPTIONS] ROCRATE_PATH SUBROCRATE_PATH

Options:

  • --guid TEXT - Optional custom identifier for the sub-crate
  • --name TEXT - Name of the sub-crate [required]
  • --organization-name TEXT - Name of the organization [required]
  • --project-name TEXT - Name of the project [required]
  • --description TEXT - Description of the sub-crate [required]
  • --keywords TEXT - Keywords (can be specified multiple times) [required]
  • --author TEXT - Author name (default: "Unknown")
  • --version TEXT - Version number (default: "1.0")
  • --license TEXT - License URL (default: "https://creativecommons.org/licenses/by/4.0/")

Example:

fairscape-cli rocrate register subrocrate \
  --name "Sub-Crate Example" \
  --organization-name "UVA" \
  --project-name "B2AI" \
  --description "A sub-crate within the main RO-Crate" \
  --keywords "sub-crate" \
  "./test_rocrate" "./test_rocrate/sub_crate"

add

Add a file to the RO-Crate and register its metadata. This command copies local files into the RO-Crate directory structure and registers their metadata.

add dataset

Add a dataset file and its metadata to an RO-Crate.

fairscape-cli rocrate add dataset [OPTIONS] ROCRATE_PATH

Options:

  • --guid TEXT - Optional custom identifier for the dataset
  • --name TEXT - Name of the dataset [required]
  • --author TEXT - Author of the dataset [required]
  • --version TEXT - Version of the dataset (default: "1.0")
  • --description TEXT - Description of the dataset [required]
  • --keywords TEXT - Keywords (can be specified multiple times) [required]
  • --data-format TEXT - Format of the dataset (e.g., csv, json) [required]
  • --source-filepath TEXT - Path to the source dataset file on your local filesystem [required]
  • --destination-filepath TEXT - Path where the dataset file will be copied in the RO-Crate [required]
  • --url TEXT - URL reference for the dataset
  • --date-published TEXT - Publication date of the dataset (ISO format)
  • --schema TEXT - Schema identifier for the dataset
  • --used-by TEXT - Identifiers of computations that use this dataset (can be specified multiple times)
  • --derived-from TEXT - Identifiers of datasets this one is derived from (can be specified multiple times)
  • --generated-by TEXT - Identifiers of computations that generated this dataset (can be specified multiple times)
  • --summary-statistics-source TEXT - Path to source summary statistics file on your local filesystem
  • --summary-statistics-destination TEXT - Path where summary statistics file will be copied in the RO-Crate
  • --associated-publication TEXT - Associated publication identifier
  • --additional-documentation TEXT - Additional documentation
  • --custom-properties TEXT - JSON string with additional properties

Example:

fairscape-cli rocrate add dataset \
  --name "AP-MS embeddings" \
  --author "Krogan lab" \
  --version "1.0" \
  --date-published "2023-04-23" \
  --description "APMS embeddings for each protein" \
  --keywords "proteomics" \
  --data-format "CSV" \
  --source-filepath "./data/embeddings.csv" \
  --destination-filepath "./test_rocrate/embeddings.csv" \
  "./test_rocrate"

add software

Add a software file and its metadata to an RO-Crate.

fairscape-cli rocrate add software [OPTIONS] ROCRATE_PATH

Options:

  • --guid TEXT - Optional custom identifier for the software
  • --name TEXT - Name of the software [required]
  • --author TEXT - Author of the software [required]
  • --version TEXT - Version of the software [required]
  • --description TEXT - Description of the software [required]
  • --keywords TEXT - Keywords (can be specified multiple times) [required]
  • --file-format TEXT - Format of the software (e.g., py, js) [required]
  • --url TEXT - URL reference for the software
  • --source-filepath TEXT - Path to the source software file on your local filesystem [required]
  • --destination-filepath TEXT - Path where the software file will be copied in the RO-Crate [required]
  • --date-modified TEXT - Last modification date of the software (ISO format)
  • --used-by-computation TEXT - Identifiers of computations that use this software (can be specified multiple times)
  • --associated-publication TEXT - Associated publication identifier
  • --additional-documentation TEXT - Additional documentation
  • --custom-properties TEXT - JSON string with additional properties

Example:

fairscape-cli rocrate add software \
  --name "calibrate pairwise distance" \
  --author "Qin, Y." \
  --version "1.0" \
  --description "script written in python to calibrate pairwise distance." \
  --keywords "b2ai" \
  --file-format "py" \
  --source-filepath "./scripts/calibrate_pairwise_distance.py" \
  --destination-filepath "./test_rocrate/calibrate_pairwise_distance.py" \
  --date-modified "2023-04-23" \
  "./test_rocrate"