Status: Draft.
Persistent identifier: https://w3id.org/arc/workspace/isa-arc/wr-xlsx
Authors:
- Heinrich Lukas Weil - https://orcid.org/0000-0003-1945-6342
- Kevin Schneider - https://orcid.org/0000-0002-2198-5262
- Dominik Brilhaus - https://orcid.org/0000-0001-9021-3197
- Florian Wetzels - https://orcid.org/0000-0002-5526-7138
- Caroline Ott - https://orcid.org/0000-0003-1512-9504
- Kevin Frey - https://orcid.org/0000-0002-8510-6810
- Christoph Garth - https://orcid.org/0000-0003-1669-8549
- Timo Mühlhaus - https://orcid.org/0000-0003-3925-6778
This specification extends ISA-XLSX, version 3.0.0-draft.1 with metadata for computational workflows and runs. The XLSX representation and ISA terminology are defined by that base specification.
The existing folder layout and data-path conventions are defined by the ISA-ARC Workspace specification, version 3.0.0-draft.2. Separating these specifications does not change those workspace requirements.
WR-XLSX files MUST conform to the general conventions and the shared sheet rules referenced below, except where this specification explicitly extends them. Those rules retain their stated MUST, SHOULD, and MAY requirements. This specification defines the additional file names, worksheet names, sections, and fields for workflows and runs.
Table of contents
WR-XLSX extends the ISA-XLSX format by introducing additional files and sheets to capture computational workflows and runs. Specifically, it defines:
- Run file
- Workflow file
The workspace's Workflow Description and Run Description identify WR-XLSX metadata files by the following names:
isa.workflow.xlsxfor identifying the Workflow fileisa.run.xlsxfor identifying the Run file
#Workflow File
The Workflow represents the prospective orchestration of other tools or workflows. A Workflow File contains contextualizing information about the workflow.
The Workflow File MUST contain one Top-Level Metadata sheet. This sheet MUST be named isa_workflow and MUST contain the following sections:
#Run File
The Run represents the application of a workflow, i.e. the execution of a computational tool that has orchestrated the execution of other tools. A Run File contains metadata about the executed workflows, information about the people creating, picking and parametrizing these workflow exections, and most importantly, details about the input data, parametrization and the result data.
The Run File MUST contain one Top-Level Metadata sheet. This sheet MUST be named isa_run and MUST contain the following sections:
Additionally, the Run File SHOULD contain one or more Annotation Table sheet(s), which MAY record provenance of data through application of computational workflows and the parameters that describe these computations.
Therefore, the main entities of the Run File should be Data.
#Top-level metadata sheets
Workflow and Run metadata sheets MUST follow the Top-level metadata sheets rules in ISA-XLSX, including section and field layout, capitalization, and comment handling. The following sections define the WR-specific metadata fields.
Within an Investigation, workflow and run metadata use the ontology source declarations in that Investigation's Ontology Source Reference section. The Term Source REF fields below refer to those declarations.
#WORKFLOW section
The following subsections form a metadata block implementing the metadata for a Workflow.
#WORKFLOW
This section MUST contain zero or one values.
This section MUST contain the following labels, with the specified datatypes for values supported:
| Label | Datatype | Description |
|---|---|---|
| Workflow Identifier | String | A mandatory unique identifier, either a temporary identifier supplied by users or one generated by a repository or other database. For example, it could be an identifier complying with the LSID specification. A value MUST be given for this label. |
| Workflow Title | String | A concise phrase used to encapsulate the purpose and goal of the workflow. |
| Workflow Description | String | A textual description of the workflow, with components such as objective or goals. |
| Workflow Subworkflow Identifiers | String | Identifiers of the Workflows who're orchestrated in the context of this workflow. Multiple values can be provided by using a semicolon (“;”) Unicode (U0003+B) as a separator (e.g.: Imputation;Testing;Plotting). |
| Workflow Type | String | Term to classify the workflow. The term can be free text or from, for example, a controlled vocabulary or an ontology. If the latter source is used the Term Accession Number and Term Source REF fields below are required. |
| Workflow Type Term Accession Number | String | The accession number from the Term Source associated with the selected term. |
| Workflow Type Term Source REF | String | Identifies the controlled vocabulary or ontology that this term comes from. The Source REF has to match one of the Term Source Name declared in the Ontology Source Reference section. |
| Workflow URI | String | Pointer to workflow resources external to the WR-XLSX document that can be accessed by their Uniform Resource Identifier (URI). |
| Workflow Version | String | An identifier for the version to ensure workflow tracking. |
| Workflow Parameters Name | String | A semicolon-delimited (“;”) list of parameter names, used as an identifier within the WR-XLSX document. These names identify the Parameter columns in Run Annotation Tables that list the values used for each Workflow parameter. Refer to section Multiple values on how to encode multiple values in one field and match term sources. |
| Workflow Parameters Term Accession Number | String | The accession number from the Term Source associated with the selected term. |
| Workflow Parameters Term Source REF | String | Identifies the controlled vocabulary or ontology that this term comes from. The Source REF has to match one of the Term Source Name declared in the Ontology Source Reference section. |
| Workflow Components Name | String | A semicolon-delimited (“;”) list of a workflow’s components; e.g. software names. Refer to section Multiple values on how to encode multiple values in one field and match term sources. |
| Workflow Components Type | String | Term to classify the workflow components listed, e.g command line tool or software. The term can be free text or from, for example, a controlled vocabulary or an ontology. If the latter source is used the Term Accession Number and Term Source REF fields below are required. |
| Workflow Components Type Term Accession Number | String | The accession number from the Source associated to the selected terms. |
| Workflow Components Type Term Source REF | String | Identifies the controlled vocabulary or ontology that this term comes from. The Source REF has to match a Term Source Name previously declared in the Ontology Source Reference section |
| Workflow File Name | String | A field to specify the name of the Workflow Table file corresponding the definition of that workflow. There can be only one file per cell. |
Example
For example, the WORKFLOW section of a WR-XLSX isa.workflow.xlsx file may look as follows:
| WORKFLOW | |
| Workflow Identifier | ProteomIQonPipeline |
| Workflow Title | Proteome Quantification |
| Workflow Description | Calculate protein abundancies using ProteomIQon. |
| Workflow Subworkflow Identifiers | PeptideSpectrumMatching;ProteinInference;ProteinQuantification |
| Workflow Type | Proteomic Quantification Method |
| Workflow Type Term Accession Number | http://purl.obolibrary.org/obo/NCIT_C161810 |
| Workflow Type Term Source REF | NCIT |
| Workflow URI | |
| Workflow Version | |
| Workflow Parameters Name | Protein quantification |
| Workflow Parameters Name Term Accession Number | http://edamontology.org/operation_3630 |
| Workflow Parameters Name Term Source REF | EDAM |
| Workflow Components Name | Proteomiqon |
| Workflow Components Type | software |
| Workflow Components Type Term Accession Number | http://purl.obolibrary.org/obo/IAO_0000010 |
| Workflow Components Type Term Source REF | IAO |
| Workflow File Name | workflows/ProteomIQon/isa.workflow.xlsx |
#WORKFLOW CONTACTS
This section MUST contain zero or more values.
This section MUST contain the following labels, with the specified datatypes for values supported:
| Label | Datatype | Description |
|---|---|---|
| Workflow Person Last Name | String | The last name of a person associated with the workflow. |
| Workflow Person First Name | String | Workflow Person Name |
| Workflow Person Mid Initials | String | The middle initials of a person associated with the workflow. |
| Workflow Person Email | String formatted as email | The email address of a person associated with the workflow. |
| Workflow Person Phone | String | The telephone number of a person associated with the workflow. |
| Workflow Person Fax | String | The fax number of a person associated with the workflow. |
| Workflow Person Address | String | The address of a person associated with the workflow. |
| Workflow Person Affiliation | String | The organization affiliation for a person associated with the workflow. |
| Workflow Person Roles | String or Ontology Annotation if accompanied by Term Accession Numbers and Term Source REFs | Term to classify the role(s) performed by this person in the context of the workflow, which means that the roles reported here need not correspond to roles held withing their affiliated organization. Multiple annotations or values attached to one person can be provided by using a semicolon (“;”) Unicode (U0003+B) as a separator (e.g.: submitter;funder;sponsor) .The term can be free text or from, for example, a controlled vocabulary or an ontology. If the latter source is used the Term Accession Number and Term Source REF fields below are required. Refer to section Multiple values on how to encode multiple values in one field and match term sources. |
| Workflow Person Roles Term Accession Number | String | The accession number from the Term Source associated with the selected term. |
| Workflow Person Roles Term Source REF | String | Identifies the controlled vocabulary or ontology that this term comes from. The Source REF has to match one of the Term Source Names declared in the Ontology Source Reference section. |
Example
For example, the WORKFLOW CONTACTS section of a WR-XLSX isa.workflow.xlsx file may look as follows:
| WORKFLOW CONTACTS | ||
| Workflow Person Last Name | Ott | Zimmer |
| Workflow Person First Name | Caroline | David |
| Workflow Person Mid Initials | ||
| Workflow Person Email | ||
| Workflow Person Phone | ||
| Workflow Person Fax | ||
| Workflow Person Address | Erwin-Schrödinger-Straße 56, 67663 Kaiserslautern, Germany | Erwin-Schrödinger-Straße 56, 67663 Kaiserslautern, Germany |
| Workflow Person Affiliation | RPTU Kaiserslautern-Landau | RPTU Kaiserslautern-Landau |
| Workflow Person Roles | Data Manager | Statistician |
| Workflow Person Roles Term Accession Number | http://purl.obolibrary.org/obo/NCIT_C51820 | http://purl.obolibrary.org/obo/NCIT_C51877 |
| Workflow Person Roles Term Source REF | NCIT | NCIT |
#RUN section
The following subsections form a metadata block implementing the metadata for a Run.
#RUN
This section MUST contain zero or one values.
This section MUST contain the following labels, with the specified datatypes for values supported:
| Label | Datatype | Description |
|---|---|---|
| Run Identifier | String | A mandatory unique identifier, either a temporary identifier supplied by users or one generated by a repository or other database. For example, it could be an identifier complying with the LSID specification. A value MUST be given for this label. |
| Run Title | String | A concise phrase used to encapsulate the purpose and goal of the run. |
| Run Description | String | A textual description of the run, with components such as objective or goals. |
| Run Workflow Identifiers | String | Identifiers of the Workflows whose execution was orchestrated in the context of this run. Multiple values can be provided by using a semicolon (“;”) Unicode (U0003+B) as a separator (e.g.: Imputation;Testing;Plotting). |
| Run Measurement Type | String | A term to qualify the endpoint, or what is being computed (e.g. gene expression profiling or protein identification). The term can be free text or from, for example, a controlled vocabulary or an ontology. If the latter source is used the Term Accession Number and Term Source REF fields below are required. |
| Run Measurement Type Term Accession Number | String | The accession number from the Term Source associated with the selected term. |
| Run Measurement Type Term Source REF | String | The Source REF has to match one of the Term Source Name declared in the Ontology Source Reference section. |
| Run Technology Type | String | Term to identify the technology used to perform the computation, e.g. statistical testing. The term can be free text or from, for example, a controlled vocabulary or an ontology. If the latter source is used the Term Accession Number and Term Source REF fields below are required. |
| Run Technology Type Term Accession Number | String | The accession number from the Term Source associated with the selected term. |
| Run Technology Type Term Source REF | String | Identifies the controlled vocabulary or ontology that this term comes from. The Source REF has to match one of the Term Source Names declared in the Ontology Source Reference section. |
| Run Technology Platform | String | Software Publisher/Creator and/or Software name used for the computation. |
| Run File Name | String | A field to specify the name of the Run Table file corresponding the definition of that run. There can be only one file per cell. |
Example
For example, the RUN section of a WR-XLSX isa.run.xlsx file may look as follows:
| RUN | |
| Run Identifier | ProteomicsAnalysis |
| Run Title | Preparatory Proteome Quantification |
| Run Description | Raw Data Files measured from Orbitrap device were processed using ProteomIQon to calculate protein quantities. |
| Run Workflow Identifiers | ProteomIQonPipeline |
| Run Measurement Type | Proteomics |
| Run Measurement Type Term Accession Number | http://purl.obolibrary.org/obo/NCIT_C20085 |
| Run Measurement Type Term Source REF | NCIT |
| Run Technology Type | Protein quantification |
| Run Technology Type Term Accession Number | http://edamontology.org/operation_3630 |
| Run Technology Type Term Source REF | EDAM |
| Run Technology Platform | ProteomIQon |
| Run File Name | runs/ProteomicsAnalysis/isa.run.xlsx |
#RUN PERFORMERS
This section MUST contain zero or more values.
This section MUST contain the following labels, with the specified datatypes for values supported:
| Label | Datatype | Description |
|---|---|---|
| Run Person Last Name | String | The last name of a person associated with the run. |
| Run Person First Name | String | Run Person Name |
| Run Person Mid Initials | String | The middle initials of a person associated with the run. |
| Run Person Email | String formatted as email | The email address of a person associated with the run. |
| Run Person Phone | String | The telephone number of a person associated with the run. |
| Run Person Fax | String | The fax number of a person associated with the run. |
| Run Person Address | String | The address of a person associated with the run. |
| Run Person Affiliation | String | The organization affiliation for a person associated with the run. |
| Run Person Roles | String or Ontology Annotation if accompanied by Term Accession Numbers and Term Source REFs | Term to classify the role(s) performed by this person in the context of the run, which means that the roles reported here need not correspond to roles held withing their affiliated organization. Multiple annotations or values attached to one person can be provided by using a semicolon (“;”) Unicode (U0003+B) as a separator (e.g.: submitter;funder;sponsor) .The term can be free text or from, for example, a controlled vocabulary or an ontology. If the latter source is used the Term Accession Number and Term Source REF fields below are required. Refer to section Multiple values on how to encode multiple values in one field and match term sources. |
| Run Person Roles Term Accession Number | String | The accession number from the Term Source associated with the selected term. |
| Run Person Roles Term Source REF | String | Identifies the controlled vocabulary or ontology that this term comes from. The Source REF has to match one of the Term Source Names declared in the Ontology Source Reference section. |
Example
For example, the RUN PERFORMERS section of a WR-XLSX isa.run.xlsx file may look as follows:
| RUN PERFORMERS | ||
| Run Person Last Name | Ott | Zimmer |
| Run Person First Name | Caroline | David |
| Run Person Mid Initials | ||
| Run Person Email | ||
| Run Person Phone | ||
| Run Person Fax | ||
| Run Person Address | Erwin-Schrödinger-Straße 56, 67663 Kaiserslautern, Germany | Erwin-Schrödinger-Straße 56, 67663 Kaiserslautern, Germany |
| Run Person Affiliation | RPTU Kaiserslautern-Landau | RPTU Kaiserslautern-Landau |
| Run Person Roles | Data Manager | Statistician |
| Run Person Roles Term Accession Number | http://purl.obolibrary.org/obo/NCIT_C51820 | http://purl.obolibrary.org/obo/NCIT_C51877 |
| Run Person Roles Term Source REF | NCIT | NCIT |
#Multiple values
Where a top-level metadata field permits multiple annotation values, their encoding MUST follow the Multiple values rules in ISA-XLSX.
#Annotation Table sheets
Run annotation tables MUST follow the Annotation Table sheets rules in ISA-XLSX. These include table structure, inputs and outputs, protocol columns, ontology annotations, units, parameters, comments, and additional payload.
#Datamap Table sheets
Workflow and run datamaps described in the workspace's Workflow Description and Run Description use the Datamap File and Datamap Table sheets rules from ISA-XLSX.