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.
Example datasets
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
sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_recording-<label>]_physio.json
sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_recording-<label>]_physio.tsv.gz
sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_recording-<label>]_stim.json
sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_recording-<label>]_stim.tsv.gz
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.
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:
In these cases additional information regarding channels and optodes SHOULD be placed in"CapManufacturer": "none", "CapManufacturersModelName": "none", "NIRSPlacementScheme": ["Cz", "C1", "C2"],
*_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 specialized 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.
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.
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 ACCEL | integer | Number of acceleration 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" |
Generic information
Key name | Requirement Level | Data type | Description |
---|---|---|---|
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 artifact 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. |
Hardware information
Key name | Requirement Level | Data type | Description |
---|---|---|---|
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. |
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. |
Institution information
Key name | Requirement Level | Data type | Description |
---|---|---|---|
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. |
InstitutionalDepartmentName | RECOMMENDED | string | The department in the institution in charge of the equipment that produced the measurements. |
Task information
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 filename 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 labels facesnback and headnodding , respectively. |
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. |
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. |
component | OPTIONAL, but REQUIRED if type is ACCEL , GYRO or MAGN |
string | Description of the spatial axis or label of quaternion component associated with the channel. For example, x ,y ,z for position channels, or quat_x , quat_y , quat_z , quat_w for quaternion orientation channels. This column may appear anywhere in the file. Must be one of: "x" , "y" , "z" , "quat_x" , "quat_y" , "quat_z" , "quat_w" , "n/a" . |
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. |
low_cutoff | OPTIONAL | number or "n/a" |
Frequencies used for the high-pass filter applied to the channel in Hz. If no high-pass filter applied, use n/a . This column may appear anywhere in the file. |
high_cutoff | OPTIONAL | number or "n/a" |
Frequencies used for the low-pass filter applied to the channel in Hz. If no low-pass filter applied, use n/a . Note that hardware anti-aliasing in A/D conversion of all MEG/EEG electronics applies a low-pass filter; specify its frequency here if applicable. 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 the Motion 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 spatial axis. An extra column component for the axis MUST be added to the *_channels.tsv file (x, y or z). |
GYRO | Gyrometer channel, one channel for each spatial axis. An extra column component for the axis MUST be added to the *_channels.tsv file (x, y or z). |
MAGN | Magnetomenter channel, one channel for each spatial axis. An extra column component for the axis 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 center of vitamin E capsules sticked on the left/right pre-auricular and on the nasion, these are also visible on the T1w MRI"
}