Skip to content

Near-Infrared Spectroscopy

Support for Near-Infrared Spectroscopy (NIRS) was developed as a BIDS Extension Proposal. Please see Citing BIDS on how to appropriately credit this extension when referring to it in the context of the academic literature.

Several example NIRS datasets have been formatted using this specification and can be used for practical guidance when curating a new dataset.

NIRS recording data

Template:

Legend:
  • For more information about filename elements (for example, entities, suffixes, extensions), follow the links embedded in the filename template.

  • Filename entities or directories between square brackets (for example, [_ses-<label>]) are OPTIONAL.

  • Some entities may only allow specific values, in which case those values are listed in <>, separated by |.

  • _<suffix> means that there are several (>6) valid suffixes for this filename pattern.

  • .<extension> means that there are several (>6) valid extensions for this file type.

  • [.gz] means that both the unzipped and gzipped versions of the extension are valid.

Only the Shared Near Infrared Spectroscopy Format (SNIRF) file specification is supported in BIDS. The SNIRF specification supports one or more NIRS datasets to be stored in a single .snirf file. However, to be BIDS compatible, each SNIRF file MUST contain only a single run. A limited set of fields from the SNIRF specification are replicated in the BIDS specification. This redundancy allows the data to be easily parsed by humans and machines that do not have a SNIRF reader at hand, which improves findability and tooling development.

Raw NIRS data in the native format, if different from SNIRF, can also be stored in the /sourcedata directory along with code to convert the data to SNIRF in the /code directory. The unprocessed raw data should be stored in the manufacturer's format before any additional processing or conversion is applied. Retaining the native file format is especially valuable in a case when conversion elicits the loss of crucial metadata unique to specific manufacturers and NIRS systems.

Terminology

For proper documentation of NIRS recording metadata, it is important to understand the difference between a Source, Detector, and Channel as these are defined differently to other modalities, such as EEG. The following definitions apply in this document:

  • Source - A light emitting device, sometimes called a transmitter.

  • Detector - A photoelectric transducer, sometimes called a receiver.

  • Optode - Refers to either a source or detector.

  • Channel - A paired coupling of a source and a detector with one specific wavelength of light. It is common for a single Source-Detector pair to result in two or more channels with different wavelengths.

Sidecar JSON (*_nirs.json)

It is common within the NIRS community for researchers to build their own caps and optode holders to position their sources and detectors, or for optodes to be directly attached to the scalp with adhesive. To facilitate description of the wide variety of possible configurations, several fields are RECOMMENDED within the *_nirs.json file. Additionally, in certain situations, reserved keywords MUST be used. When custom modifications are made to a commercially available cap or a custom cap is used, then the reserved keyword custom MUST be used for the CapManufacturersModelName field. When a custom-made cap is used, that is, no (modified) commercially available cap, the reserved keyword custom MUST be used in the CapManufacturer field. If no cap is used, the reserved keyword none MUST be used in the CapManufacturer and CapManufacturersModelName field. The use of NIRSPlacementScheme is RECOMMENDED when no cap or a customized cap is used, and describes the positioning of the optodes. This field may also contain a reference to a file providing a graphical depiction of the cap, for example a PDF file, a photo, or a bitmap drawing. If the referred file is not specified in BIDS, it MAY be placed in the /sourcedata directory. To clarify the usage and interaction of these fields, the following examples are provided:

  • If a commercial cap such as EasyCap actiCAP 64 Ch Standard-2 was used:

    "CapManufacturer": "EasyCap",
    "CapManufacturersModelName": "actiCAP 64 Ch Standard-2",
    "NIRSPlacementScheme": "10-20"
    

  • If an Artinis Medical Systems cap with custom positions, as may be done by cutting custom holes in the cap, was used:

    "CapManufacturer": "Artinis Medical Systems",
    "CapManufacturersModelName": "headcap with print, size L, it was modified by adding holes for the optodes according to the NIRSPlacementScheme and optode_layout.pdf",
    "NIRSPlacementScheme": "see optode_layout.pdf: 2 groups over the left and right dlPFC, 2 groups over the left and right PPC, 1 group over the left M1 and PMC"
    

  • If a completely custom cap was knitted:

    "CapManufacturer": "custom",
    "CapManufacturersModelName": "custom knitted cap with holes for optodes according to the NIRSPlacementScheme and optode_knitted_layout.jpg",
    "NIRSPlacementScheme": "see optode_knitted_layout.jpg: 2 groups over the left and right dlPFC, 2 groups over the left and right PPC."
    

  • If no cap was used and optodes were taped to the scalp at positions Cz, C1 and C2:

    "CapManufacturer": "none",
    "CapManufacturersModelName": "none",
    "NIRSPlacementScheme": ["Cz", "C1", "C2"],
    
    In these cases additional information regarding channels and optodes SHOULD be placed in *_channels.tsv and *_optodes.tsv files.

Closely spaced or short-separation source-detector pairs are often included in NIRS measurements to obtain a measure of systemic, rather than neural, activity. These source-detector pairs are referred to as short channels. There is variation in how manufacturers implement these short channels, some use specialised sources or detectors, and the placement mechanisms vary. It is beyond the scope of the BIDS specification to define what constitutes a short channel, and detailed characteristics of channels may be stored within the SNIRF file (for example, in the sourcePower field). However, to improve searchability and ease of access for users, it is useful to know if short channels were included in the NIRS measurements; the presence of short channels is is stored in the field ShortChannelCount. If the field ShortChannelCount is populated, then the optional column short_channel may be used in *_channels.tsv to describe which channels were specified as short.

Generic fields: For consistency between studies and institutions, we encourage users to extract the values of these fields from the actual raw data. Whenever possible, please avoid using ad hoc wording.

Key name Requirement Level Data type Description
TaskName REQUIRED string Name of the task. No two tasks should have the same name. The task label included in the file name is derived from this "TaskName" field by removing all non-alphanumeric characters (that is, all except those matching [0-9a-zA-Z]). For example "TaskName" "faces n-back" or "head nodding" will correspond to task labelsfacesnbackandheadnodding`, respectively.
InstitutionName RECOMMENDED string The name of the institution in charge of the equipment that produced the measurements.
InstitutionAddress RECOMMENDED string The address of the institution in charge of the equipment that produced the measurements.
Manufacturer RECOMMENDED string Manufacturer of the equipment that produced the measurements.
ManufacturersModelName RECOMMENDED string Manufacturer's model name of the equipment that produced the measurements.
SoftwareVersions RECOMMENDED string Manufacturer's designation of software version of the equipment that produced the measurements.
TaskDescription RECOMMENDED string Longer description of the task.
Instructions RECOMMENDED string Text of the instructions given to participants before the recording.
CogAtlasID RECOMMENDED string URI of the corresponding Cognitive Atlas Task term.
CogPOID RECOMMENDED string URI of the corresponding CogPO term.
DeviceSerialNumber RECOMMENDED string The serial number of the equipment that produced the measurements. A pseudonym can also be used to prevent the equipment from being identifiable, so long as each pseudonym is unique within the dataset.
RecordingDuration RECOMMENDED number Length of the recording in seconds (for example, 3600).
HeadCircumference RECOMMENDED number Circumference of the participant's head, expressed in cm (for example, 58).

Must be a number greater than 0.
HardwareFilters RECOMMENDED object of objects or "n/a" Object of temporal hardware filters applied, or "n/a" if the data is not available. Each key-value pair in the JSON object is a name of the filter and an object in which its parameters are defined as key-value pairs. For example, {"Highpass RC filter": {"Half amplitude cutoff (Hz)": 0.0159, "Roll-off": "6dB/Octave"}}.
SubjectArtefactDescription RECOMMENDED string Freeform description of the observed subject artefact and its possible cause (for example, "Vagus Nerve Stimulator", "non-removable implant"). If this field is set to "n/a", it will be interpreted as absence of major source of artifacts except cardiac and blinks.

Specific NIRS fields that are REQUIRED or may be REQUIRED depending on other metadata values:

Key name Requirement Level Data type Description
SamplingFrequency REQUIRED number or "n/a" Sampling frequency (in Hz) of all the data in the recording, regardless of their type (for example, 2400). Sampling frequency (in Hz) of all the data in the recording, regardless of their type (for example, 12). If individual channels have different sampling rates, then the field here MUST be specified as n/a and the values MUST be specified in the sampling_frequency column in channels.tsv.")
NIRSChannelCount REQUIRED integer Total number of NIRS channels, including short channels. Corresponds to the number of rows in channels.tsv with any NIRS type.

Must be a number greater than or equal to 0.
NIRSSourceOptodeCount REQUIRED integer Number of NIRS sources. Corresponds to the number of rows in optodes.tsv with type "source".

Must be a number greater than or equal to 1.
NIRSDetectorOptodeCount REQUIRED integer Number of NIRS detectors. Corresponds to the number of rows in optodes.tsv with type "detector".

Must be a number greater than or equal to 1.
ACCELChannelCount OPTIONAL, but REQUIRED if any channel type is ACC integer Number of accelerometer channels.

Must be a number greater than or equal to 0.
GYROChannelCount OPTIONAL, but REQUIRED if any channel type is GYRO integer Number of gyrometer channels.

Must be a number greater than or equal to 0.
MAGNChannelCount OPTIONAL, but REQUIRED if any channel type is MAGN integer Number of magnetometer channels.

Must be a number greater than or equal to 0.

Specific NIRS fields that SHOULD be present:

Key name Requirement Level Data type Description
CapManufacturer RECOMMENDED string Name of the cap manufacturer (for example, "EasyCap"). If no cap was used, such as with optodes that are directly taped to the scalp, then the string none MUST be used and the NIRSPlacementScheme field MAY be used to specify the optode placement.
CapManufacturersModelName RECOMMENDED string Manufacturer's designation of the cap model (for example, "actiCAP 64 Ch Standard-2"). If there is no official model number then a description may be provided (for example, Headband with print (S-M)). If a cap from a manufacturer was modified, then the field MUST be set to custom. If no cap was used, then the CapManufacturer field MUST be none and this field MUST be n/a.")
SourceType RECOMMENDED string Type of source. Preferably a specific model/part number is supplied. This is a freeform description, but the following keywords are suggested: "LED", "LASER", "VCSEL". If individual channels have different SourceType, then the field here should be specified as "mixed" and this column should be included in optodes.tsv.
DetectorType RECOMMENDED string Type of detector. This is a free form description with the following suggested terms: "SiPD", "APD". Preferably a specific model/part number is supplied. If individual channels have different DetectorType, then the field here should be specified as "mixed" and this column should be included in optodes.tsv.
ShortChannelCount RECOMMENDED integer The number of short channels. 0 indicates no short channels.

Must be a number greater than or equal to 0.
NIRSPlacementScheme RECOMMENDED string or array of strings Placement scheme of NIRS optodes. Either the name of a standardized placement system (for example, "10-20") or an array of standardized position names (for example, ["Cz", "Pz"]). This field should only be used if a cap was not used. If a standard cap was used, then it should be specified in CapManufacturer and CapManufacturersModelName and this field should be set to "n/a"

Example *_nirs.json

{
  "TaskName": "visual",
  "InstitutionName": "Macquarie University. Australian Hearing Hub",
  "InstitutionAddress": "6 University Ave, Macquarie University NSW 2109 Australia",
  "Manufacturer": "NIRx",
  "ManufacturersModelName": "NIRScout",
  "TaskDescription": "visual gratings and noise patterns",
  "Instructions": "look at the dot in the center of the screen and press the button when it changes color",
  "SamplingFrequency": 3.7,
  "NIRSChannelCount": 56,
  "NIRSSourceOptodeCount": 16,
  "NIRSDetectorOptodeCount": 16,
  "ACCELChannelCount": 0,
  "SoftwareFilters": "n/a",
  "RecordingDuration": 233.639,
  "HardwareFilters": {"Highpass RC filter": {"Half amplitude cutoff (Hz)": 0.0159, "Roll-off": "6dBOctave"}},
  "CapManafacturer": "NIRx",
  "CapManufacturersModelName": "Headband with print (S-M)",
  "NIRSPlacementScheme": "n/a",
}

Channels description (*_channels.tsv)

Template:

Legend:
  • For more information about filename elements (for example, entities, suffixes, extensions), follow the links embedded in the filename template.

  • Filename entities or directories between square brackets (for example, [_ses-<label>]) are OPTIONAL.

  • Some entities may only allow specific values, in which case those values are listed in <>, separated by |.

  • _<suffix> means that there are several (>6) valid suffixes for this filename pattern.

  • .<extension> means that there are several (>6) valid extensions for this file type.

  • [.gz] means that both the unzipped and gzipped versions of the extension are valid.

This file is RECOMMENDED as it provides easily searchable information across BIDS datasets. Channels are a pairing of source and detector optodes with a specific wavelength of light. Unlike in other modalities, not all pairings of optodes correspond to meaningful data and not all pairs have to be recorded or represented in the data. Note that the source and detector names used in the channel specifications are specified in the *_optodes.tsv file below. If a *_channels.tsv file is specified, an *_optodes.tsv file MUST be specified as well. The required columns in the *_channels.tsv file MUST be ordered as listed below.

The BIDS specification supports several types of NIRS devices which output raw data in different forms. The type of measurement is specified in the type column. For example, when measurements are taken with a continuous wave (CW) device that saves the data as optical density, the type should be NIRSCWOPTICALDENSITY and the units should be unitless, this is equivalent to SNIRF data type dOD.

The columns of the channels description table stored in *_channels.tsv are:

Column name Requirement Level Data type Description
name REQUIRED string Label of the channel.

This column must appear first in the file.
type REQUIRED string Type of channel; MUST use the channel types listed below. Note that the type MUST be in upper-case.

This column must appear second in the file.

For a list of valid values for this column, see the associated glossary entry.
source REQUIRED string or "n/a" Name of the source as specified in the *_optodes.tsv file. n/a for channels that do not contain fNIRS signals (for example, acceleration).

This column must appear third in the file.
detector REQUIRED string or "n/a" Name of the detector as specified in the *_optodes.tsv file. n/a for channels that do not contain NIRS signals (for example, acceleration).

This column must appear fourth in the file.
wavelength_nominal REQUIRED number or "n/a" Specified wavelength of light in nm. n/a for channels that do not contain raw NIRS signals (for example, acceleration). This field is equivalent to /nirs(i)/probe/wavelengths in the SNIRF specification.

This column must appear fifth in the file.
units REQUIRED string Physical unit of the value represented in this channel, specified according to the SI unit symbol and possibly prefix symbol, or as a derived SI unit (for example, V, or unitless for changes in optical densities). For guidelines about units see the Appendix and Common Principles pages.

This column must appear sixth in the file.
sampling_frequency OPTIONAL, but REQUIRED if SamplingFrequency is n/a in _nirs.json number Sampling rate of the channel in Hz.

This column may appear anywhere in the file.
orientation_component OPTIONAL, but REQUIRED if type is ACCEL, GYRO or MAGN string Description of the orientation of the channel.

This column may appear anywhere in the file.

Must be one of: "x", "y", "z".
wavelength_actual OPTIONAL number Measured wavelength of light in nm. n/a for channels that do not contain raw NIRS signals (acceleration). This field is equivalent to measurementList.wavelengthActual in the SNIRF specification.

This column may appear anywhere in the file.
description OPTIONAL string Brief free-text description of the channel, or other information of interest.

This column may appear anywhere in the file.
wavelength_emission_actual OPTIONAL number Measured emission wavelength of light in nm. n/a for channels that do not contain raw NIRS signals (acceleration). This field is equivalent to measurementList.wavelengthEmissionActual in the SNIRF specification.

This column may appear anywhere in the file.
short_channel OPTIONAL boolean Is the channel designated as short. The total number of channels listed as short channels SHOULD be stored in ShortChannelCount in *_nirs.json.

This column may appear anywhere in the file.

Must be one of: "true", "false".
status OPTIONAL string Data quality observed on the channel. A channel is considered bad if its data quality is compromised by excessive noise. If quality is unknown, then a value of n/a may be used. Description of noise type SHOULD be provided in [status_description].

This column may appear anywhere in the file.

Must be one of: "good", "bad", "n/a".
status_description OPTIONAL string Freeform text description of noise or artifact affecting data quality on the channel. It is meant to explain why the channel was declared bad in the status column.

This column may appear anywhere in the file.
Additional Columns OPTIONAL n/a Additional columns are allowed if they are defined in the associated metadata file.

Restricted keyword list for the channel types

All NIRS channels types MUST correspond to a valid SNIRF data type. Additional channels that are recorded simultaneously with the NIRS device and stored in the same data file SHOULD be included as well. However, additional channels that are simultaneously recorded with a different device SHOULD be stored according to their appropriate modality specification. For example, motion data that was simultaneously recorded with a different device should be specified according to BEP029 and not according to the NIRS data type. Whereas, if the motion data was acquired in with the NIRS device itself, it should be included here with the NIRS data. Any of the channel types defined in other BIDS specification MAY be used here as well such as ACCEL or MAGN. As several of these data types are commonly acquired using NIRS devices they are included as an example at the base of the table. Note that upper-case is REQUIRED.

Keyword Description
NIRSCWAMPLITUDE Continuous wave amplitude measurements. Equivalent to dataType 001 in SNIRF.
NIRSCWFLUORESCENSEAMPLITUDE Continuous wave fluorescence amplitude measurements. Equivalent to dataType 051 in SNIRF.
NIRSCWOPTICALDENSITY Continuous wave change in optical density measurements. Equivalent to dataTypeLabel dOD in SNIRF.
NIRSCWHBO Continuous wave oxygenated hemoglobin (oxyhemoglobin) concentration measurements. Equivalent to dataTypeLabel HbO in SNIRF.
NIRSCWHBR Continuous wave deoxygenated hemoglobin (deoxyhemoglobin) concentration measurements. Equivalent to dataTypeLabel HbR in SNIRF.
NIRSCWMUA Continuous wave optical absorption measurements. Equivalent to dataTypeLabel mua in SNIRF.
ACCEL Accelerometer channel, one channel for each orientation. An extra column component for the axis of the orientation MUST be added to the *_channels.tsv file (x, y or z).
GYRO Gyrometer channel, one channel for each orientation. An extra column component for the axis of the orientation MUST be added to the *_channels.tsv file (x, y or z).
MAGN Magnetomenter channel, one channel for each orientation. An extra column component for the axis of the orientation MUST be added to the *_channels.tsv file (x, y or z).
MISC Miscellaneous

Example *_channels.tsv

Name         type                   source      detector      wavelength_nominal   units
S1-D1        NIRSCWAMPLITUDE        A1          Fz            760                  V
S1-D1        NIRSCWAMPLITUDE        A1          Fz            850                  V
S1-D2        NIRSCWAMPLITUDE        A1          Cz            760                  V
S2-D1        NIRSCWAMPLITUDE        A2          Fz            760                  V
S3-D4        NIRSCWAMPLITUDE        VisS2       VisD4         760                  V

Optode description (*_optodes.tsv)

Template:

Legend:
  • For more information about filename elements (for example, entities, suffixes, extensions), follow the links embedded in the filename template.

  • Filename entities or directories between square brackets (for example, [_ses-<label>]) are OPTIONAL.

  • Some entities may only allow specific values, in which case those values are listed in <>, separated by |.

  • _<suffix> means that there are several (>6) valid suffixes for this filename pattern.

  • .<extension> means that there are several (>6) valid extensions for this file type.

  • [.gz] means that both the unzipped and gzipped versions of the extension are valid.

File that provides the location and type of optodes. Note that coordinates MUST be expressed in Cartesian coordinates according to the NIRSCoordinateSystem and NIRSCoordinateSystemUnits fields in *_coordsystem.json. If an *_optodes.tsv file is specified, a *_coordsystem.json file MUST be specified as well. The order of the required columns in the *_optodes.tsv file MUST be as listed below.

The x, y, and z positions are for measured locations, for example, with a polhemus digitizer. If you also have idealized positions, where you wish the optodes to be placed, these can be listed in the template values (for example for "template positions" computed on a sphere). SNIRF contains arrays for both the 3D and 2D locations of data. In BIDS the *_optodes.tsv file MUST contain the 3D locations. Only in case 3D positions are unavailable the 2D locations should be used, setting the z field to an n/a value.

The columns of the optodes description table stored in *_optodes.tsv are:

Column name Requirement Level Data type Description
name REQUIRED string Name of the optode, must be unique.

This column must appear first in the file.
type REQUIRED string The type of the optode.

This column must appear second in the file.

Must be one of: "source", "detector", "n/a".
x REQUIRED number or "n/a" Recorded position along the x-axis. "n/a" if not available.

This column must appear third in the file.
y REQUIRED number or "n/a" Recorded position along the y-axis. "n/a" if not available.

This column must appear fourth in the file.
z REQUIRED number or "n/a" Recorded position along the z-axis. "n/a" if not available.

This column must appear fifth in the file.
template_x OPTIONAL, but REQUIRED if x is n/a number or "n/a" Assumed or ideal position along the x axis.

This column may appear anywhere in the file.
template_y OPTIONAL, but REQUIRED if y is n/a number or "n/a" Assumed or ideal position along the y axis.

This column may appear anywhere in the file.
template_z OPTIONAL, but REQUIRED if z is n/a number or "n/a" Assumed or ideal position along the z axis.

This column may appear anywhere in the file.
description OPTIONAL string Free-form text description of the optode, or other information of interest.

This column may appear anywhere in the file.
detector_type OPTIONAL string The type of detector. Only to be used if the field DetectorType in *_nirs.json is set to mixed.

This column may appear anywhere in the file.
source_type OPTIONAL string The type of source. Only to be used if the field SourceType in *_nirs.json is set to mixed.

This column may appear anywhere in the file.
Additional Columns OPTIONAL n/a Additional columns are allowed if they are defined in the associated metadata file.

Example *_optodes.tsv

name    type         x          y         z          template_x    template_y   template_z
A1      source       -0.0707    0.0000    -0.0707    -0.07         0.00         0.07
Fz      detector     0.0000     0.0714    0.0699     0.0           0.07         0.07
S1      source       -0.2707    0.0200    -0.1707    -0.03         0.02         -0.2
D2      detector     0.0022     0.1214    0.0299     0.0           0.12         0.03
VisS2   source       -0.1707    0.1200    -0.3707    -0.1          0.1          -0.4
VisD4   detector     0.0322     0.2214    0.2299     0.02          0.22         0.23

Coordinate System JSON (*_coordsystem.json)

Template:

Legend:
  • For more information about filename elements (for example, entities, suffixes, extensions), follow the links embedded in the filename template.

  • Filename entities or directories between square brackets (for example, [_ses-<label>]) are OPTIONAL.

  • Some entities may only allow specific values, in which case those values are listed in <>, separated by |.

  • _<suffix> means that there are several (>6) valid suffixes for this filename pattern.

  • .<extension> means that there are several (>6) valid extensions for this file type.

  • [.gz] means that both the unzipped and gzipped versions of the extension are valid.

A *_coordsystem.json file is used to specify the fiducials, the location of anatomical landmarks, and the coordinate system and units in which the position of optodes and landmarks is expressed. Fiducials are objects with a well-defined location used to facilitate the localization of sensors and co-registration, anatomical landmarks are locations on a research subject such as the nasion (for a detailed definition see coordinate system appendix). The *_coordsystem.json is REQUIRED if the optional *_optodes.tsv is present. If a corresponding anatomical MRI is available, the locations of anatomical landmarks in that scan should also be stored in the *_T1w.json file which goes alongside the NIRS data.

Not all NIRS systems provide 3D coordinate information or digitization capabilities. In this case, only x and y are specified and z is "n/a".

General fields:

Key name Requirement Level Data type Description
IntendedFor OPTIONAL string or array The paths to files for which the associated file is intended to be used. Contains one or more BIDS URIs. Using forward-slash separated paths relative to the participant subdirectory is DEPRECATED. This identifies the MRI or CT scan associated with the optodes, landmarks, and fiducials.

Fields relating to the NIRS optode positions:

Key name Requirement Level Data type Description
NIRSCoordinateSystem REQUIRED string Defines the coordinate system in which the optode positions are expressed.
See Appendix VIII for a list of restricted keywords for coordinate systems. If "Other", a definition of the coordinate system MUST be provided in NIRSCoordinateSystemDescription.

For a list of valid values for this field, see the associated glossary entry.
NIRSCoordinateUnits REQUIRED string Units of the coordinates of NIRSCoordinateSystem.

Must be one of: "m", "mm", "cm", "n/a".
NIRSCoordinateProcessingDescription RECOMMENDED string Has any post-processing (such as projection) been done on the optode positions (for example, "surface_projection", "n/a").
NIRSCoordinateSystemDescription RECOMMENDED, but REQUIRED if NIRSCoordinateSystem is "other" string Free-form text description of the coordinate system. May also include a link to a documentation page or paper describing the system in greater detail.

Fields relating to the position of fiducials measured during an NIRS session/run:

Key name Requirement Level Data type Description
FiducialsDescription OPTIONAL string Free-form text description of how the fiducials such as vitamin-E capsules were placed relative to anatomical landmarks, and how the position of the fiducials were measured (for example, "both with Polhemus and with T1w MRI").
FiducialsCoordinates RECOMMENDED object of arrays Key-value pairs of the labels and 3-D digitized position of anatomical landmarks, interpreted following the "FiducialsCoordinateSystem" (for example, {"NAS": [12.7,21.3,13.9], "LPA": [5.2,11.3,9.6], "RPA": [20.2,11.3,9.1]}). Each array MUST contain three numeric values corresponding to x, y, and z axis of the coordinate system in that exact order.
FiducialsCoordinateUnits RECOMMENDED string Units in which the coordinates that are listed in the field "FiducialsCoordinateSystem" are represented.

Must be one of: "m", "mm", "cm", "n/a".
FiducialsCoordinateSystem RECOMMENDED string Defines the coordinate system for the fiducials. Preferably the same as the "EEGCoordinateSystem". See the Coordinate Systems Appendix for a list of restricted keywords for coordinate systems. If "Other", provide definition of the coordinate system in "FiducialsCoordinateSystemDescription".

For a list of valid values for this field, see the associated glossary entry.
FiducialsCoordinateSystemDescription RECOMMENDED, but REQUIRED if FiducialsCoordinateSystem is "other" string Free-form text description of the coordinate system. May also include a link to a documentation page or paper describing the system in greater detail.

Fields relating to the position of anatomical landmarks measured during an NIRS session/run:

Key name Requirement Level Data type Description
AnatomicalLandmarkCoordinates RECOMMENDED object of arrays Key-value pairs of the labels and 3-D digitized locations of anatomical landmarks, interpreted following the "AnatomicalLandmarkCoordinateSystem" (for example, {"NAS": [12.7,21.3,13.9], "LPA": [5.2,11.3,9.6], "RPA": [20.2,11.3,9.1]}. Each array MUST contain three numeric values corresponding to x, y, and z axis of the coordinate system in that exact order.
AnatomicalLandmarkCoordinateSystem RECOMMENDED string Defines the coordinate system for the anatomical landmarks. See the Coordinate Systems Appendix for a list of restricted keywords for coordinate systems. If "Other", provide definition of the coordinate system in "AnatomicalLandmarkCoordinateSystemDescription".

For a list of valid values for this field, see the associated glossary entry.
AnatomicalLandmarkCoordinateUnits RECOMMENDED string Units of the coordinates of "AnatomicalLandmarkCoordinateSystem".

Must be one of: "m", "mm", "cm", "n/a".
AnatomicalLandmarkCoordinateSystemDescription RECOMMENDED, but REQUIRED if NIRSCoordinateSystem is "other" string Free-form text description of the coordinate system. May also include a link to a documentation page or paper describing the system in greater detail.

Example *_coordsystem.json

{
  "NIRSCoordinateSystem": "Other",
  "NIRSCoordinateUnits": "mm",
  "NIRSCoordinateSystemDescription": "RAS orientation: Origin halfway between LPA and RPA, positive x-axis towards RPA, positive y-axis orthogonal to x-axis through Nasion, z-axis orthogonal to xy-plane, pointing in superior direction.",
  "FiducialsDescription": "Optodes and fiducials were digitized with Polhemus, fiducials were recorded as the centre of vitamin E capsules sticked on the left/right pre-auricular and on the nasion, these are also visible on the T1w MRI"
}