-
Notifications
You must be signed in to change notification settings - Fork 34
NIRS Meta Data
Sean Mullen edited this page Jun 18, 2024
·
8 revisions
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>