Specification reference

WR-XLSX format, version 1.0.0-draft.1

View this specification's source

Status: Draft.

Persistent identifier: https://w3id.org/arc/workspace/isa-arc/wr-xlsx

Authors:

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:

#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:

LabelDatatypeDescription
Workflow IdentifierStringA 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 TitleStringA concise phrase used to encapsulate the purpose and goal of the workflow.
Workflow DescriptionStringA textual description of the workflow, with components such as objective or goals.
Workflow Subworkflow IdentifiersStringIdentifiers 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 TypeStringTerm 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 NumberStringThe accession number from the Term Source associated with the selected term.
Workflow Type Term Source REFStringIdentifies 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 URIStringPointer to workflow resources external to the WR-XLSX document that can be accessed by their Uniform Resource Identifier (URI).
Workflow VersionStringAn identifier for the version to ensure workflow tracking.
Workflow Parameters NameStringA 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 NumberStringThe accession number from the Term Source associated with the selected term.
Workflow Parameters Term Source REFStringIdentifies 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 NameStringA 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 TypeStringTerm 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 NumberStringThe accession number from the Source associated to the selected terms.
Workflow Components Type Term Source REFStringIdentifies 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 NameStringA 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 IdentifierProteomIQonPipeline
Workflow TitleProteome Quantification
Workflow DescriptionCalculate protein abundancies using ProteomIQon.
Workflow Subworkflow IdentifiersPeptideSpectrumMatching;ProteinInference;ProteinQuantification
Workflow TypeProteomic Quantification Method
Workflow Type Term Accession Numberhttp://purl.obolibrary.org/obo/NCIT_C161810
Workflow Type Term Source REFNCIT
Workflow URI
Workflow Version
Workflow Parameters NameProtein quantification
Workflow Parameters Name Term Accession Numberhttp://edamontology.org/operation_3630
Workflow Parameters Name Term Source REFEDAM
Workflow Components NameProteomiqon
Workflow Components Typesoftware
Workflow Components Type Term Accession Numberhttp://purl.obolibrary.org/obo/IAO_0000010
Workflow Components Type Term Source REFIAO
Workflow File Nameworkflows/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:

LabelDatatypeDescription
Workflow Person Last NameStringThe last name of a person associated with the workflow.
Workflow Person First NameStringWorkflow Person Name
Workflow Person Mid InitialsStringThe middle initials of a person associated with the workflow.
Workflow Person EmailString formatted as emailThe email address of a person associated with the workflow.
Workflow Person PhoneStringThe telephone number of a person associated with the workflow.
Workflow Person FaxStringThe fax number of a person associated with the workflow.
Workflow Person AddressStringThe address of a person associated with the workflow.
Workflow Person AffiliationStringThe organization affiliation for a person associated with the workflow.
Workflow Person RolesString or Ontology Annotation if accompanied by Term Accession Numbers and Term Source REFsTerm 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 NumberStringThe accession number from the Term Source associated with the selected term.
Workflow Person Roles Term Source REFStringIdentifies 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 NameOttZimmer
Workflow Person First NameCarolineDavid
Workflow Person Mid Initials
Workflow Person Email
Workflow Person Phone
Workflow Person Fax
Workflow Person AddressErwin-Schrödinger-Straße 56, 67663 Kaiserslautern, GermanyErwin-Schrödinger-Straße 56, 67663 Kaiserslautern, Germany
Workflow Person AffiliationRPTU Kaiserslautern-LandauRPTU Kaiserslautern-Landau
Workflow Person RolesData ManagerStatistician
Workflow Person Roles Term Accession Numberhttp://purl.obolibrary.org/obo/NCIT_C51820http://purl.obolibrary.org/obo/NCIT_C51877
Workflow Person Roles Term Source REFNCITNCIT

#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:

LabelDatatypeDescription
Run IdentifierStringA 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 TitleStringA concise phrase used to encapsulate the purpose and goal of the run.
Run DescriptionStringA textual description of the run, with components such as objective or goals.
Run Workflow IdentifiersStringIdentifiers 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 TypeStringA 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 NumberStringThe accession number from the Term Source associated with the selected term.
Run Measurement Type Term Source REFStringThe Source REF has to match one of the Term Source Name declared in the Ontology Source Reference section.
Run Technology TypeStringTerm 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 NumberStringThe accession number from the Term Source associated with the selected term.
Run Technology Type Term Source REFStringIdentifies 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 PlatformStringSoftware Publisher/Creator and/or Software name used for the computation.
Run File NameStringA 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 IdentifierProteomicsAnalysis
Run TitlePreparatory Proteome Quantification
Run DescriptionRaw Data Files measured from Orbitrap device were processed using ProteomIQon to calculate protein quantities.
Run Workflow IdentifiersProteomIQonPipeline
Run Measurement TypeProteomics
Run Measurement Type Term Accession Numberhttp://purl.obolibrary.org/obo/NCIT_C20085
Run Measurement Type Term Source REFNCIT
Run Technology TypeProtein quantification
Run Technology Type Term Accession Numberhttp://edamontology.org/operation_3630
Run Technology Type Term Source REFEDAM
Run Technology PlatformProteomIQon
Run File Nameruns/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:

LabelDatatypeDescription
Run Person Last NameStringThe last name of a person associated with the run.
Run Person First NameStringRun Person Name
Run Person Mid InitialsStringThe middle initials of a person associated with the run.
Run Person EmailString formatted as emailThe email address of a person associated with the run.
Run Person PhoneStringThe telephone number of a person associated with the run.
Run Person FaxStringThe fax number of a person associated with the run.
Run Person AddressStringThe address of a person associated with the run.
Run Person AffiliationStringThe organization affiliation for a person associated with the run.
Run Person RolesString or Ontology Annotation if accompanied by Term Accession Numbers and Term Source REFsTerm 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 NumberStringThe accession number from the Term Source associated with the selected term.
Run Person Roles Term Source REFStringIdentifies 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 NameOttZimmer
Run Person First NameCarolineDavid
Run Person Mid Initials
Run Person Email
Run Person Phone
Run Person Fax
Run Person AddressErwin-Schrödinger-Straße 56, 67663 Kaiserslautern, GermanyErwin-Schrödinger-Straße 56, 67663 Kaiserslautern, Germany
Run Person AffiliationRPTU Kaiserslautern-LandauRPTU Kaiserslautern-Landau
Run Person RolesData ManagerStatistician
Run Person Roles Term Accession Numberhttp://purl.obolibrary.org/obo/NCIT_C51820http://purl.obolibrary.org/obo/NCIT_C51877
Run Person Roles Term Source REFNCITNCIT

#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.