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:

sub-<label>/
    [ses-<label>/]
        nirs/
            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_channels.json
            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_channels.tsv
            sub-<label>[_ses-<label>][_acq-<label>]_coordsystem.json
            sub-<label>[_ses-<label>][_acq-<label>]_optodes.json
            sub-<label>[_ses-<label>][_acq-<label>]_optodes.tsv
            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_nirs.json
            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_nirs.snirf
            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_events.json
            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_events.tsv

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"` will correspond to task label `facesnback`.
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:

sub-<label>/
    [ses-<label>/]
        nirs/
            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_channels.json
            sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>]_channels.tsv

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:

sub-<label>/
    [ses-<label>/]
        nirs/
            sub-<label>[_ses-<label>][_acq-<label>]_optodes.json
            sub-<label>[_ses-<label>][_acq-<label>]_optodes.tsv

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:

sub-<label>/
    [ses-<label>/]
        nirs/
            sub-<label>[_ses-<label>][_acq-<label>]_coordsystem.json

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"
}