Quick Start

General Usage

The tool is invoked from the command line using the main script name (assumed here to be FAIRLinked), followed by a command and its specific arguments.

FAIRLinked [COMMAND] [OPTIONS]

To see the help message for any command, use the -h or --help flag.

FAIRLinked filter -h
FAIRLinked generate-template --help

InterfaceMDS Commands

These commands are used for interacting with the Materials Data Schema (MDS) ontology.

filter

Get terms associated with a certain Domain, Subdomain, or Study Stage.

Description: Term search using Domain, SubDomain, or Study Stage. For a complete list of Domains and SubDomains, run FAIRLinked view-domains and FAIRLinked dir-make. The current list of Study Stages includes: Synthesis, Formulation, Materials Processing, Sample, Tool, Recipe, Result, Analysis, Modelling. For more details, please visit the SDLE homepage.

Usage:

FAIRLinked filter -t <SEARCH_TYPES> -q <QUERY_TERM> [OPTIONS]

Arguments:

  • -t, --search_types: (Required) Specifies the search criteria. Choices: "Domain", "SubDomain", "Study Stage". You can provide one or more.

  • -q, --query_term: (Required) Enter the domain, subdomain, or study stage.

  • -op, --ontology_path: Path to the ontology file. Defaults to "default".

  • -te, --ttl_extr: Specifies whether to save search results. Choices: "T" or "F". Defaults to "F".

  • -tp, --ttl_path: If saving results (-te T), provide the full path and filename for the output.

Example: Search for the term “Chem-rxn” within the “Domain” search type.

FAIRLinked filter -t "Domain" -q "Chem-rxn"

Search for terms in the “Sample” Study Stage and save the results to a file.

FAIRLinked filter -t "Study Stage" -q "Sample" -te "T" -tp "/path/to/save/sample_terms.ttl"

view-domains

Display unique Domains and SubDomains from the ontology.

Usage:

FAIRLinked view-domains

dir-make

View and make a directory tree of turtle files based on domains and subdomains.

Usage:

FAIRLinked dir-make

add-terms

Add new terms to an existing ontology file. This command launches an interactive session to guide you through the process.

Usage:

FAIRLinked add-terms -op <PATH_TO_ONTOLOGY>

Arguments:

  • -op, --onto_file_path: Path to the ontology file you want to modify.

Example:

FAIRLinked add-terms -op "/path/to/my_ontology.ttl"

generate-template

Generate a JSON-LD template based on a CSV file.

Description: This command generates a template that allows users to fill in metadata about columns in their dataframe, including units, definitions, and explanatory notes. For column labels that can be matched to a term in MDS-Onto, the definition will be pre-filled.

Usage:

FAIRLinked generate-template -cp <CSV_PATH> -out <OUTPUT_PATH> -lp <LOG_PATH> [OPTIONS]

Arguments:

  • -cp, --csv_path: (Required) Path to the input CSV file.

  • -out, --output_path: (Required) Path to save the output JSON-LD template file.

  • -lp, --log_path: (Required) Path to a directory to store log files detailing which labels were matched.

  • -op, --ontology_path: Path to the ontology file. Use "default" for the official MDS-Onto.

Example:

FAIRLinked generate-template -cp "./data/experiments.csv" -out "./metadata/template.json" -lp "./logs/" -op "default"

serialize-data

Create a directory of JSON-LD files from a single CSV file and a metadata template.

Usage:

FAIRLinked serialize-data -mdt <TEMPLATE_PATH> -cf <CSV_PATH> -rkc <ROW_KEY_COLS> -orc <ORCID> -of <OUTPUT_FOLDER> [OPTIONS]

Arguments:

  • -mdt, --metadata_template: (Required) Path to the completed JSON-LD metadata template file.

  • -cf, --csv_file: (Required) Path to the CSV file containing the data.

  • -rkc, --row_key_cols: (Required) Comma-separated list of column names that uniquely identify rows (e.g., "col1,col2,col3"). No spaces between names.

  • -orc, --orcid: (Required) ORCID identifier of the researcher (e.g., "0000-0001-2345-6789").

  • -of, --output_folder: (Required) Directory where the generated JSON-LD files will be saved.

  • -pc, --prop_col: A Python dictionary literal (as a string) defining relationships between columns.

  • -op, --ontology_path: Path to the ontology file. Required if -pc is provided.

  • -base, --base_uri: Base URI used to construct subject and object URIs. Defaults to https://cwrusdle.bitbucket.io/mds/.

Example:

FAIRLinked serialize-data \
    -mdt "./metadata/template.json" \
    -cf "./data/experiments.csv" \
    -rkc "SampleID,RunNumber" \
    -orc "0000-0001-2345-6789" \
    -of "./output/jsonld_files/"

Example with ``-pc`` argument: This example states that the value in the ProcessStep column is related to the value in the MaterialID column via the hasInput property.

FAIRLinked serialize-data \
    -mdt "./metadata/template.json" \
    -cf "./data/experiments.csv" \
    -rkc "SampleID" \
    -orc "0000-0001-2345-6789" \
    -of "./output/jsonld_files/" \
    -op "default" \
    -pc '{"hasInput": [("ProcessStep", "MaterialID")], "hasOutput":[("ProcessStep", "OutputMaterialID")]}'

deserialize-data

Deserialize a directory of JSON-LD files back into a CSV file.

Usage:

FAIRLinked deserialize-data -jd <JSONLD_DIRECTORY> -on <OUTPUT_NAME> -od <OUTPUT_DIR>

Arguments:

  • -jd, --jsonld_directory: (Required) Directory containing the JSON-LD files.

  • -on, --output_name: (Required) The base name for the output files (e.g., “my_deserialized_data”).

  • -od, --output_dir: (Required) Path to the directory where the output CSV will be saved.

Example:

FAIRLinked deserialize-data \
    -jd "./output/jsonld_files/" \
    -on "reconstructed_data" \
    -od "./data/reconstructed/"

QBWorkflow Commands

Commands related to the RDF Data Cube workflow.

data-cube-run

Start the RDF Data Cube Workflow.

Description: The RDF Data Cube is a comprehensive FAIRification workflow designed for users familiar with the RDF Data Cube vocabulary. This workflow supports the creation of richly structured, multidimensional datasets that adhere to linked data best practices and can be easily queried, combined, and analyzed. This command will launch an interactive workflow.

Usage:

FAIRLinked data-cube-run