Skip to content

NIRS Meta Data

Sean Mullen edited this page Jun 18, 2024 · 8 revisions

This page specifies the meta-data for NIRS recordings.

If a stream has the content-type NIRS, we recommend that meta-data about the stream adheres to the structure and naming laid out below. While all meta-data is optional, we recommend that any stream should describe at least those tags marked with an * below (and their parent containers).

<channels>                # per-channel meta-data
  <channel>               # description of one channel (one per channel in the time series)
                          # channels which have, at minimum, a <source>, <detector> and <wavelen>
                          # tags are considered standard NIRS channels; other channel types
                          # may be included (i.e., aux channels, dark measurement channels) where
                          # one or more of those tags are omitted; all other tags are optional
    <label>               # unique channel label; an example naming scheme that references
                          # the source, detector and wavelength is: S23-D06:750
    <type>                # type of data measured in this channel
                          # Typically Intensity, assumed if unspecified
                          # some devices may yield different or additional data types, e.g.:
                          #  ** dOD: (delta) optical density
                          #  ** HbO, HbR: oxyhemoglobin, deoxyhemoglobin concentration
                          #  ** HbT: Total hemoglobin concentration
                          #  ** H2O, Lipid, CCO: water / lipid / Cytochrome c oxidase concentration
                          #  ** mua, musp: absorption coefficient, scattering coefficient
                          #  ** BFi: blood flow index
    <measure>             # the name of the quantity being measured in this channel, where applicable
                          # (depends on NIRS technology used), e.g.:
                          #  ** Amplitude
                          #  ** Phase (FD-NIRS)
                          #  ** ACAmplitude (FD-NIRS)
                          #  ** FluorescenceAmplitude
                          #  ** FluorescencePhase (FD-NIRS)
    <unit>                # measurement unit for this channel, e.g.: lumens, micromolars, nanovolts
    <source>*             # unique identifier of the source; should match a <optode><label>; omit this
                          # for "dark measurement" channels which have no source
    <detector>*           # unique identifier of the detector; should match a <optode><label>
    <power>               # source power, in milliwatts
    <gain>                # detector gain setting, in decibels
    <wavelen>*            # nominal (excitation) wavelength, in nanometers
    <wavelen_measured>    # the actual (excitation) wavelength if measured, in nanometers
    <fd>                  # mandatory field for Frequency Domain (FD) NIRS
      <frequency>         # channel frequency, in Hz (FD-NIRS)
    </fd>
    <td>                  # mandatory field for Time Domain (TD-Gated or TD-Moments) NIRS
      <delay>             # time delay, in picoseconds (for TD-Gated NIRS)
      <width>             # time delay bin width, in picoseconds (for TD-Gated NIRS)
      <order>             # moment order, as an integer representing an ordinal (for TD-Moments NIRS)
    </td>
    <dcs>                 # mandatory field for Diffuse Correlation Spectroscopy (DCS)
      <delay>             # time delay for DCS measurements, in picoseconds
      <width>             # time delay bin width for DCS measurements, in picoseconds
    </dcs>
    <fluorescence>        # information related to fluorescence agent measured, if any
      <wavelen>           # nominal fluorescence emission wavelength, in nanometers
      <wavelen_measured>  # actual fluorescence emission wavelength, if measured, in nanometers
    </fluorescence>
    <illumination>        # illumination pattern used, matches an <illumination><label> if latter is specified
  </channel>
</channels>

<optodes>                 # per-optode meta-data
  <optode>                # description of a single optode, repeated for each optode
    <function>*           # optode type based on its function; one of:
                          #  ** Source
                          #  ** Detector
    <label>*              # source/detector label (e.g., a number)
                          # referenced in <channel><source> or <channel><detector>
    <location>            # measured optode location, in the same coordinate system as the <fiducials> if specified
                          # at least one of <location> or <location_planar> should be provided (<location> is preferred)
      <X>                 # coordinate axis pointing from the center of the head to the right, in millimeters
      <Y>                 # coordinate axis pointing from the center of the head to the front, in millimeters
      <Z>                 # coordinate axis pointing from the center of the head to the top, in millimeters
    </location>
    <location_planar>     # optional channel location mapped onto a 2D surface
      <X>                 # coordinate X axis in millimeters (horizontal)
      <Y>                 # coordinate Y axis in millimeters (vertical)
                          # the direction into the plane is assumed to go towards the head
    </location_planar>
    <source>              # additional information specific to source optodes
    </source>
    <detector>            # additional information specific to detector optodes
    </detector>
    <hardware>            # references the name of an optode hardware defined in a <hardware> entry, if specified
    <module>              # references the name of a module/group defined in a <module> entry, if specified
  </optode>
</optodes>

<hardwares>               # optional information about optode hardware
  <hardware>              # describes one type of optode hardware;
                          # repeated for each type of source or detector hardware used on this device
                          # includes other vendor-specific tags as needed (e.g., spring type, light guide length)
    <label>               # unique name of the hardware; referenced in <optode><hardware>
    <function>            # the function of the optode:
                          #  ** Source
                          #  ** Detector
    <manufacturer>        # manufacturer of the optode
    <model>               # model of the optode
    <type>                # type of source or detector hardware, e.g.:
                          # for sources: Laser, LED
                          # for detectors: SiPD, APD
    <surface>             # type of the contact surface (e.g., Plate, Pins, Bristle, Pad, Dual-Tip, Multi-Tip)
    <mount>               # type of optode mount used (e.g., Spring-Loaded, Dock)
  </hardware>
</hardwares>

<modules>                 # optional list of modules/groupings of optodes
  <module>                # information describing a module/group of optodes
                          # (may correspond to, e.g., docks, amplifiers, sensor bundles)
                          # may include other vendor-specific tags as needed
                          # optodes can be referenced to modules using the <optodes><optode><module> tag
    <label>               # the name of the module
  </module>
</modules>

<illuminations>           # optional information about source illumination patterns
  <illumination>          # describes an illumination pattern; may be repeated
    <label>               # unique name of an illumination pattern (e.g., bilateral, a number, etc.)
    <num_steps>           # total number of steps (time bins) that a sample (illumination cycle) is divided into
    <duration>            # the duration of each step in the pattern, in microseconds
    <pulse>               # duration of source pulse or oscillation, in picoseconds,
                          # if different from the duration (e.g., for TD-NIRS)
    <sources>             # a list of sources firing simultaneously in this pattern
      <source>            # a source included in this pattern
        <label>           # the name of the source, should match a <optode><label>
        <step>            # the sequential step number when this source is fired, an integer (1-base)
      </source>
    </sources>
  </illumination>
</illuminations>

<fiducials>               # optional locations of fiducials/landmarks
                          # see <coord_origins> for what coordinate origin is assumed
  <fiducial>              # information about a single fiducial/landmark, repeated for each fiducial
    <label>               # name of the location, e.g.:
                          #  ** Nasion, Inion
                          #  ** Cz
                          #  ** LPF, RPF
    <location>            # measured location, in same coordinate system as optode locations
                          # for 2D positions, the missing axis (<Z>) should be omitted
      <X>                 # axis pointing from the center of the head (origin) to the right, in millimeters
      <Y>                 # axis pointing from the center of the head (origin) to the front, in millimeters
      <Z>                 # axis pointing from the center of the head (origin) to the top, in millimeters
    </location>
  </fiducial>
</fiducials>

<coord_origins>           # optional definition of coordinate system origins
  <head>                  # 3d head coordinate origin, which can be one of the following predefined positions:
                          # ** MidPreAuricular:      midpoint between left and right preauricular points (LPA/RPA)
                          #                          (assumed if omitted)
                          # ** PreAuricularXNasion:  intersection of LPA/RPA line and an orthogonal line to the nasion
                          # ** AnteriorCommissure:   origin in various MRI scanner coordinate systems (e.g., MNI, Talairach)
                          # ** BregmaPoint:          a skull landmark
                          # ** Device:               a (NIRS) device-specific origin (fiducials are needed to relate to head)
                          # ** Custom:               other origin; fiducials are needed to relate to head
  <planar>                # origin of planar locations; typically a surface point, e.g., a 10-20 location such as FPz
</coord_origins>

<cap>                     # optional information about the NIRS cap
                          # may include additional vendor-specific tags describing the features of the cap
  <manufacturer>          # manufacturer of the cap
  <name>                  # unique name/descriptor of the cap (e.g., serial number)
  <size>                  # cap size as the head circumference, in centimeters (e.g., 54, 56, 58)
  <label_scheme>          # the labelling scheme used for montages (e.g., 10-20)
</cap>

<acquisition>             # information about the signal acquisition device (amplifier/hub)
  <modality>              # NIRS modality measured, or comma-separated list if multiple NIRS modalities in one stream (rare):
                          #  ** CW: Continuous Wave (assumed if not specified)
                          #  ** FD: Frequency Domain
                          #  ** TD-G: Time Domain Gated
                          #  ** TD-M: Time Domain Moments
                          #  ** DCS: Diffuse Correlation Spectroscopy
  <manufacturer>          # manufacturer of the amplifier
  <model>                 # model of the amplifier
  <serial_number>         # serial number of the amplifier
  <precision>             # the theoretical number of bits of precision delivered by the amplifier
                          # (typical values are 8, 16, 24, 32)
  <compensated_lag>       # amount of hardware/system lag that has been implicitly compensated for
                          # in the stream's time stamps, in seconds
  <settings>              # vendor-specific settings of the amplifier
    <setting>             # a vendor-specific setting, may be repeated
      <label>             # name of the setting
      <value>             # value of the setting
    </setting>
  </settings>
</acquisition>