Specification reference

ISA RO-Crate Profile

Persistent identifier: https://w3id.org/arc/ro-crate/isa/0.1

View this specification's source

#Overview

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

Diagram source
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 Core profile. In particular, the Investigation object MUST follow the Dataset profile defined in the Administrative Core profile with the following adaptions and additions to the properties defined in that profile.

PropertyRequiredExpected TypeDescription
@idMUSTText or URLShould be “./”, the investigation object represents the root data entity.
additionalTypeMUSTText or URL‘Investigation’ or ontology term to identify it as an Investigation
datePublishedMUSTDateTimeWhen the Investigation was published. If the Investigation is not (yet) published, use the date of the crate creation as default value.
dateCreatedSHOULDDateTimeWhen the Investigation was created
hasPartSHOULDschema.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.
commentCOULDschema.org/CommentComment
mentionsCOULDschema.org/DefinedTermSetOntologies referenced in this investigation.
urlCOULDURLThe 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 Provenance Core profile. In particular, the Study object MUST follow the Provenance Core Dataset profile and the Administrative Core Dataset profile with the following adaptions and additions to the properties defined in that profile.

PropertyRequiredExpected TypeDescription
@idMUSTText or URLShould be a subdirectory corresponding to this study.
additionalTypeMUSTText or URL‘Study’ or ontology term to identify it as a Study
creatorSHOULDschema.org/PersonThe performer of the study.
dateCreatedSHOULDDateTimeWhen the Study was created
licenseCOULDText or URL-
datePublishedSHOULDDateTimeWhen the Study was published
descriptionSHOULDTextA short description of the study (e.g. an abstract).
hasPartSHOULDschema.org/Dataset (Assay) or FileAssays contained in this study or actual data files resulting from the process sequence.
commentCOULDschema.org/CommentComment
urlCOULDURLThe 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 Provenance Core profile. In particular, the Assay object MUST follow the Provenance Core Dataset profile and the Administrative Core Dataset profile with the following adaptions and additions to the properties defined in that profile.

PropertyRequiredExpected TypeDescription
@idMUSTText or URLShould be a subdirectory corresponding to this assay.
additionalTypeMUSTText or URL‘Assay’ or ontology term to identify it as an Assay
identifierMUSTText or URLIdentifying descriptor of the assay.
nameSHOULDTextA title of the assay.
descriptionSHOULDTextA short description of the assay (e.g. an abstract).
hasPartSHOULDFileThe data files resulting from the process sequence. MUST not be used to directly point to data fragments.
licenseCOULDText or URL-
measurementMethodSHOULDURL or schema.org/DefinedTermDescribes the type measurement e.g Complexomics or Transcriptomics as an ontology term
measurementTechniqueSHOULDURL or schema.org/DefinedTermDescribes the type of technology used to take the measurement, e.g mass spectrometry or deep sequencing
commentCOULDschema.org/CommentComment
urlCOULDURLThe filename or path of the metadata file describing the assay. Optional, since in some contexts like an ARC the filename is implicit.
variableMeasuredCOULDText or schema.org/PropertyValueThe 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 Provenance Core profile, with the following additions to the properties defined in that profile.

PropertyRequiredExpected TypeDescription
agentSHOULDschema.org/PersonThe performer
endTimeSHOULDDateTime
disambiguatingDescriptionCOULDTextComments

#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 Provenance Core 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 Provenance Core 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 Provenance Core profile, with the following additions to the properties defined in that profile.

PropertyRequiredExpected TypeDescription
commentCOULDschema.org/CommentComment
disambiguatingDescriptionCOULDTextThe 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 Core profile. Addionally, the following properties are defined for the ISA RO-Crate profile to describe a person in more detail.

PropertyRequiredExpected TypeDescription
disambiguatingDescriptionCOULDText
faxNumberCOULDText

#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 Core profile. Additionally, the following properties are defined for the ISA RO-Crate profile to describe a scholarly article in more detail.

PropertyRequiredExpected TypeDescription
commentCOULDschema.org/CommentComment

#Comment

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

PropertyRequiredExpected TypeDescription
@idMUSTText or URL
@typeMUSTTextMUST be 'schema.org/Comment'
nameSHOULDText
textSHOULDText

#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 Core profile, with the following additions to the properties defined in that profile.

PropertyRequiredExpected TypeDescription
disambiguatingDescriptionCOULDTextISA 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 Core 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 Core profile, with the following additions to the properties defined in that profile.

PropertyRequiredExpected TypeDescription
additionalTypeMUSTTextMUST 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 Core profile, with the following additions to the properties defined in that profile.

PropertyRequiredExpected TypeDescription
additionalTypeMUSTTextMUST 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 Core profile, with the following additions to the properties defined in that profile.

PropertyRequiredExpected TypeDescription
additionalTypeMUSTTextMUST 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 Core profile, with the following additions to the properties defined in that profile.

PropertyRequiredExpected TypeDescription
additionalTypeMUSTTextMUST 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 Core 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 Core profile.

#Example ro-crate-metadata.json

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