Skip to content
isa4js

Study Schema

This reference document defines the structural properties of the ISAStudyJSONSchema object and explains how the underlying Directed Acyclic Graph (DAG) converts experimental sequences into a flat, tab-separated matrix file (s_*.txt).

Object Properties

Section titled “Object Properties”

The ISAStudyJSONSchema object contains the following top-level properties:

Property Type Description
@type "Study" The strictly enforced type identifier for the object.
@id string Optional JSON-LD identifier.
@context string Optional JSON-LD context string.
filename string Explicit name value targeted when writing out metadata files.
identifier string Unique alphanumeric string denoting the explicit study.
title string The title string assigned to the study context.
description string Abstract or summary outlining study boundaries.
submissionDate string Submission logging timestamp.
publicReleaseDate string Release authorization threshold date.
publications ISAPublicationSchema[] Maps to the STUDY PUBLICATIONS section in ISA-Tab.
people ISAPersonSchema[] Maps to the STUDY CONTACTS section in ISA-Tab.
materials { "sources": SourceSchema[], "samples": SampleSchema[], "otherMaterials": MaterialSchema[]} Object containing the materials used in the study.
protocols ISAProtocolSchema[] Maps to the STUDY PROTOCOLS section in ISA-Tab.
processSequence ISAProcessSchema[] The execution tracking graph connecting inputs, protocols, and outputs.
assays ISAAssaySchema[] Array containing the assays of the study.
factors ISAFactorSchema[] Maps to the STUDY FACTORS section in ISA-Tab.
characteristicCategories MaterialAttributeSchema[] Array of the characteristics categories defined in the study.
unitCategories OntologyAnnotationSchema[] List of all the units defined in the study.
comments ISACommentSchema[] It corresponds to ISA Comment objects.

Matrix Generation & Column Architecture

Section titled “Matrix Generation & Column Architecture”

When converting an ISA Study structure using convertTable(tableData: ISAStudyJSONSchema) into horizontal, tab-delimited files, columns are dynamically generated by evaluating linear sequences via a graph model.

1. Structural Element Columns

Section titled “1. Structural Element Columns”

Columns are determined sequentially based on the longest pathway in the DAG sequence topology:

  • Node Columns: Represent material steps (e.g., Source Name, Sample Name, Extract Name). Values map directly from the entity name.
  • Protocol Columns: Formulated as a literal Protocol REF cell string, mapping directly from the associated protocolName property on an experimental transaction boundary.

2. Annotation & Qualifier Modifiers

Section titled “2. Annotation & Qualifier Modifiers”

Nodes and Protocols append structural qualifier columns immediately to their right if annotations are populated:

Node Attributes (Characteristics & Comments)

Section titled “Node Attributes (Characteristics & Comments)”
  • Characteristics [Category]: Rendered whenever a node possesses an entity in its characteristics collection. The category label inside the brackets is inferred from characteristicType.annotationValue.
    • Each characteristic block generates two sequential qualifier tracking columns: Term Accession Number and Term Source REF.
  • Comment [Name]: Triggered for entries residing inside a node’s comments array matching the target comment property value string.

Protocol Attributes (Parameters)

Section titled “Protocol Attributes (Parameters)”
  • Parameter Value [Name]: Triggered when a workflow item includes discrete parameter measurements. The name token reflects parameterName.annotationValue.
    • Each distinct parameter value generates two structural qualifier tracking columns: Term Accession Number and Term Source REF.

Output Structural Integrity Constraints

Section titled “Output Structural Integrity Constraints”
  • Cell Compiling: All string tokens within generated body cells are strictly wrapped inside double-quotes ("") and broken down by uniform tab delimiters (\t).
  • Intermediary Null Safe Fallbacks: If shorter alternate pathways exist within the graph topology, columns belonging strictly to longer parallel routes evaluate cleanly to empty strings ("") to preserve structural row symmetry.
  • Termination Rule: If the input processSequence contains zero entries, calls to the matrix compiler break immediately and return an empty string ('').