View on GitHub

ARC RO-Crate Profile

Profiles for representing ARCs (Annotated Research Contexts) as RO-Crate.

ISA RO-Crate Profile

Overview

The ISA RO-Crate profile is an instantiation of the Administrative Crate and Process Core Crate profiles to describe datasets following the Investigation-Study-Assay (ISA) model. In particular, it describes a nested collection of datasets, all following the Process Core Crate profile. Each datset in the collection uses Administrative Crate vocabulary to describe its administrative information, with the top-level dataset (Investigation) precisely following the Administrative Crate profile.

A significant part of the previous work on this RO-Crate profile for ISA was produced as part of the Annotated Research Context (ARC) project, through arc-to-rocrate.

During the ELIXIR Biohackathon 2023, as part of Project 14: Enabling continuous RDM using Annotated Research Contexts with RO-Crate profiles for ISA, the profile was further fine tuned and defined, and some remaining unresolved mappings resolved.

The aim of the profile is to be able to fully represent ISA-JSON as RO-Crate, fully capturing the metadata and files in a non-lossy form such that it should be possible to convert between one to the other, in either direction, without loss of information.

The ISA RO-Crate has led to a few changes to Bioschemas types:

LabProtocol - Has been redefined as a child of HowTo to make it clearer that it is intended to specifically describe the planned instructions for a lab process.

LabProcess - A new type has been defined as a child of Action, to specifically describe the details and outcomes of an executed LabProtocol. Thereby separating the “what was planned” and “what happened” between LabProtocol and LabProcess respectively. A working group is working on the new type and adaptations of existing types.

An important change to the Bioschemas specification that is still pending is the following:

Dataset - A new property processSequence to describe how the Dataset was created.

The following graph summarizes the ISA model in terms of Bioschemas/Schema.org vocabulary:

flowchart TD

dataset[Investigation/Study/Assay=Dataset]

Process[LabProcess]

Protocol[Protocol=LabProtocol]

BioSample[Source/Sample/Material=Sample]

DataFile[Data=File]

ont[OntologyAnnotation=DefinedTerm]

prop[ParameterValue=PropertyValue]

dataset --hasPart--> dataset
dataset --hasPart----> DataFile
dataset --about--> Process

Process --"result"---> DataFile
Process --"result"--> BioSample
Process --"object"--> BioSample
Process --executesLabProtocol--> Protocol
Process --parameterValue---> prop

BioSample --derivesFrom--> BioSample
BioSample --additionalProperty--> prop

Protocol --purpose---> ont
Protocol --labEquipment---> ont
Protocol --reagent---> ont

Requirements

Investigation

Is based upon schema.org/Dataset and maps to the ISA-JSON Investigation. A dataset following this profile also follows the Administrative Crate profile. In particular, the Investigation object MUST follow the Dataset profile defined in the Administrative Crate profile with the following adaptions and additions to the properties defined in that profile.

Property Required Expected Type Description
@id MUST Text or URL Should be “./”, the investigation object represents the root data entity.
additionalType MUST Text or URL ‘Investigation’ or ontology term to identify it as an Investigation
datePublished MUST DateTime When the Investigation was published. If the Investigation is not (yet) published, use the date of the crate creation as default value.
dateCreated SHOULD DateTime When the Investigation was created
hasPart SHOULD schema.org/Dataset (Study or Assay) An Investigation object should contain other datasets representing the studies of the investigation. The dataset objects in this list MUST follow the Study profile or the Assay profile defined in this document.
comment COULD schema.org/Comment Comment
mentions COULD schema.org/DefinedTermSet Ontologies referenced in this investigation.
url COULD URL The filename or path of the metadata file describing the investigation. Optional, since in some contexts like an ARC the filename is implicit.

Study

Is based upon schema.org/Dataset and maps to the ISA-JSON Study. A dataset following this profile also follows the Process Core Crate profile. In particular, the Study object MUST follow the Process Core Crate Dataset profile and the Administrative Crate Dataset profile with the following adaptions and additions to the properties defined in that profile.

Property Required Expected Type Description
@id MUST Text or URL Should be a subdirectory corresponding to this study.
additionalType MUST Text or URL ‘Study’ or ontology term to identify it as a Study
creator SHOULD schema.org/Person The performer of the study.
dateCreated SHOULD DateTime When the Study was created
license COULD Text or URL -
datePublished SHOULD DateTime When the Study was published
description SHOULD Text A short description of the study (e.g. an abstract).
hasPart SHOULD schema.org/Dataset (Assay) or File Assays contained in this study or actual data files resulting from the process sequence.
comment COULD schema.org/Comment Comment
url COULD URL The filename or path of the metadata file describing the study. Optional, since in some contexts like an ARC the filename is implicit.

Assay

Is based upon schema.org/Dataset and maps to the ISA-JSON Assay. A dataset following this profile also follows the Process Core Crate profile. In particular, the Assay object MUST follow the Process Core Crate Dataset profile and the Administrative Crate Dataset profile with the following adaptions and additions to the properties defined in that profile.

Property Required Expected Type Description
@id MUST Text or URL Should be a subdirectory corresponding to this assay.
additionalType MUST Text or URL ‘Assay’ or ontology term to identify it as an Assay
identifier MUST Text or URL Identifying descriptor of the assay.
name SHOULD Text A title of the assay.
description SHOULD Text A short description of the assay (e.g. an abstract).
hasPart SHOULD File The data files resulting from the process sequence. MUST not be used to directly point to data fragments.
license COULD Text or URL -
measurementMethod SHOULD URL or schema.org/DefinedTerm Describes the type measurement e.g Complexomics or Transcriptomics as an ontology term
measurementTechnique SHOULD URL or schema.org/DefinedTerm Describes the type of technology used to take the measurement, e.g mass spectrometry or deep sequencing
comment COULD schema.org/Comment Comment
url COULD URL The filename or path of the metadata file describing the assay. Optional, since in some contexts like an ARC the filename is implicit.
variableMeasured COULD Text or schema.org/PropertyValue The target variable being measured, e.g protein concentration

LabProcess

Has the new Bioschemas DRAFT bioschemas.org/LabProcess type and maps to the ISA-JSON Process. An ISA Process MUST follow the Process profile defined in the Process Core Crate profile, with the following additions to the properties defined in that profile.

Property Required Expected Type Description
agent SHOULD schema.org/Person The performer
endTime SHOULD DateTime  
disambiguatingDescription COULD Text Comments

LabProtocol

Is based on the Bioschemas bioschemas.org/LabProtocol type and maps to the ISA-JSON Protocol. An ISA Protocol MUST follow the Protocol profile defined in the Process Core Crate profile.

Sample

Is based on the Bioschemas bioschemas.org/Sample type, and represents the ISA-JSON Sample, Source and Material. An ISA Sample MUST follow the Sample profile defined in the Process Core Crate profile.

Data

Describes and points to a Data file or a segment of a Data file (via data fragment selectors), and maps to the ISA-JSON Data. An ISA Data object MUST follow the Data profile defined in the Process Core Crate profile, with the following additions to the properties defined in that profile.

Property Required Expected Type Description
comment COULD schema.org/Comment Comment
disambiguatingDescription COULD Text The type of the data file (“Raw Data File”, “Derived Data File” or “Image File”).

Person

It is based on schema.org/Person, and maps to the ISA-JSON Person. An ISA Person MUST follow the Person profile defined in the Administrative Crate profile. Addionally, the following properties are defined for the ISA RO-Crate profile to describe a person in more detail.

Property Required Expected Type Description
disambiguatingDescription COULD Text  
faxNumber COULD Text  

ScholarlyArticle

It is based on schema.org/ScholarlyArticle and maps to the ISA-JSON Publication. An ISA ScholarlyArticle MUST follow the ScholarlyArticle profile defined in the Administrative Crate profile. Additionally, the following properties are defined for the ISA RO-Crate profile to describe a scholarly article in more detail.

Property Required Expected Type Description
comment COULD schema.org/Comment Comment

Comment

It is based on schema.org/Comment and maps to the ISA-JSON Comment

Property Required Expected Type Description
@id MUST Text or URL  
@type MUST Text MUST be ‘schema.org/Comment’
name SHOULD Text  
text SHOULD Text  

DefinedTerm

It is based on schema.org/DefinedTerm and maps to the ISA-JSON OntologyAnnotation. An ISA DefinedTerm MUST follow the DefinedTerm profile defined in the Administrative Crate profile, with the following additions to the properties defined in that profile.

Property Required Expected Type Description
disambiguatingDescription COULD Text ISA comments

PropertyValue

General profile for key-value pairs. It is based on schema.org/PropertyValue. ISA PropertyValue objects, in general, MUST follow the PropertyValue profile defined in the Administrative Crate profile.

PropertyValue - Parameter

Represents a process parameter. It is based on schema.org/PropertyValue and maps to the ISA-JSON Key-Value-Unit Triples Process Parameter Value. An ISA process parameter MUST follow the PropertyValue profile defined in the Administrative Crate profile, with the following additions to the properties defined in that profile.

Property Required Expected Type Description
additionalType MUST Text MUST be "ParameterValue"

PropertyValue - Characteristic

Represents a characteristic. It is based on schema.org/PropertyValue and maps to the ISA-JSON Key-Value-Unit Triple Material Attribute Value. ISA characteristics MUST follow the PropertyValue profile defined in the Administrative Crate profile, with the following additions to the properties defined in that profile.

Property Required Expected Type Description
additionalType MUST Text MUST be "CharacteristicValue"

PropertyValue - Factor

Represents a factor. It is based on schema.org/PropertyValue and maps to the ISA-JSON Key-Value-Unit Triple Factor Value. An ISA factor MUST follow the PropertyValue profile defined in the Administrative Crate profile, with the following additions to the properties defined in that profile.

Property Required Expected Type Description
additionalType MUST Text MUST be "FactorValue"

PropertyValue - Component

Represents a protocol component. It is based on schema.org/PropertyValue and maps to the a component of an ISA-JSON protocol. An ISA protocol component MUST follow the PropertyValue profile defined in the Administrative Crate profile, with the following additions to the properties defined in that profile.

Property Required Expected Type Description
additionalType MUST Text MUST be "Component"

PropertyValue - DOI

If a schema.org/PropertyValue object represents a DOI identifier of an article, it is supposed to have the exact values described in the PropertyValue - DOI section of the Administrative Crate profile.

PropertyValue - PubMedID

If a schema.org/PropertyValue object represents a PubMedID identifier of an article, it is supposed to have the exact values described in the PropertyValue - PubMedID section of the Administrative Crate profile.

Example ro-crate-metadata.json

TODO: simple example and a link to a more complete example