[ENH] BEP030: Functional Near-Infrared Spectroscopy (#802)

* Add fNIRS

* Rename

* Review

* Review

* Use macros

* Update metadata.yaml

* Update 11-functional-near-infrared-spectroscopy.md

* Update columns.yaml

* Update columns.yaml

* Update metadata.yaml

* Use master schemacode

* Revert "Use master schemacode"

This reverts commit b35cfe3.

* SCHEMA: Update datatype rules to be named, have datatypes key

* Update src/04-modality-specific-files/11-functional-near-infrared-spectroscopy.md

Co-authored-by: Stefan Appelhoff <stefan.appelhoff@mailbox.org>

* Update src/04-modality-specific-files/11-functional-near-infrared-spectroscopy.md

Co-authored-by: Stefan Appelhoff <stefan.appelhoff@mailbox.org>

* Update src/schema/objects/columns.yaml

Co-authored-by: Stefan Appelhoff <stefan.appelhoff@mailbox.org>

* Update src/schema/objects/columns.yaml

Co-authored-by: Stefan Appelhoff <stefan.appelhoff@mailbox.org>

* Update src/04-modality-specific-files/11-functional-near-infrared-spectroscopy.md

Co-authored-by: Stefan Appelhoff <stefan.appelhoff@mailbox.org>

* Update src/04-modality-specific-files/11-functional-near-infrared-spectroscopy.md

Co-authored-by: Stefan Appelhoff <stefan.appelhoff@mailbox.org>

* Update src/04-modality-specific-files/11-functional-near-infrared-spectroscopy.md

Co-authored-by: Stefan Appelhoff <stefan.appelhoff@mailbox.org>

* Update src/schema/objects/columns.yaml

Co-authored-by: Stefan Appelhoff <stefan.appelhoff@mailbox.org>

* Update src/schema/objects/columns.yaml

Co-authored-by: Stefan Appelhoff <stefan.appelhoff@mailbox.org>

* Update src/schema/objects/columns.yaml

Co-authored-by: Stefan Appelhoff <stefan.appelhoff@mailbox.org>

* Update src/04-modality-specific-files/11-functional-near-infrared-spectroscopy.md

Co-authored-by: Stefan Appelhoff <stefan.appelhoff@mailbox.org>

* Update src/04-modality-specific-files/11-functional-near-infrared-spectroscopy.md

Co-authored-by: Stefan Appelhoff <stefan.appelhoff@mailbox.org>

* Update src/04-modality-specific-files/11-functional-near-infrared-spectroscopy.md

Co-authored-by: Stefan Appelhoff <stefan.appelhoff@mailbox.org>

* Update src/04-modality-specific-files/11-functional-near-infrared-spectroscopy.md

Co-authored-by: Stefan Appelhoff <stefan.appelhoff@mailbox.org>

* Update src/04-modality-specific-files/11-functional-near-infrared-spectroscopy.md

Co-authored-by: Stefan Appelhoff <stefan.appelhoff@mailbox.org>

* Update src/04-modality-specific-files/11-functional-near-infrared-spectroscopy.md

Co-authored-by: Stefan Appelhoff <stefan.appelhoff@mailbox.org>

* Fix missing info in render

* Fix missing rules for type in nirs

* Add acquisition

* Remove acquisition from photo

* add SPEC_ROOT prefix to links from schema to internal spec

* add sidecar and check rules for nirs

* misisng  : in context.yaml

* yamllint fixes

* add level adendum for recommended descriptions

* harmonize objects and rules

* we must appease the linting gods

* add missing display_name fields in objects. I am wildly inconsistent about capitalization in the display names.

* change links to point at md not html in schema objects

* associations should be a suffix, can't nest them like I tried for nirs

* add coordsystem to associations, adjust rules accordingly

* Update src/schema/rules/datatypes/nirs.yaml

Co-authored-by: Taylor Salo <tsalo006@fiu.edu>

* Update src/schema/rules/datatypes/nirs.yaml

Co-authored-by: Taylor Salo <tsalo006@fiu.edu>

* Update src/schema/rules/sidecars/nirs.yaml

Co-authored-by: Taylor Salo <tsalo006@fiu.edu>

* Update src/schema/rules/sidecars/nirs.yaml

Co-authored-by: Taylor Salo <tsalo006@fiu.edu>

* Update src/schema/objects/metadata.yaml

Co-authored-by: Taylor Salo <tsalo006@fiu.edu>

* Update src/schema/objects/metadata.yaml

Co-authored-by: Taylor Salo <tsalo006@fiu.edu>

* detector__optoedes --> detector_type

* SourceType format set to be just string

* Add make_sidecar_table macros alongside old style tables to compare for nirs

* correct mislabeled addendums

* uncapitalize requirement level

* add missing _ to make sidecar table macro, and fix spelling

* update coordsystem.json tables to use rules/sidecars/nirs entries.

* fix typos in schema

Co-authored-by: Taylor Salo <tsalo006@fiu.edu>

* Update src/schema/rules/checks/nirs.yaml

Co-authored-by: Chris Markiewicz <markiewicz@stanford.edu>

* Update src/schema/rules/checks/nirs.yaml

Co-authored-by: Chris Markiewicz <markiewicz@stanford.edu>

* Update src/schema/rules/checks/nirs.yaml

Co-authored-by: Chris Markiewicz <markiewicz@stanford.edu>

* add nirs to common principles schema object

* no space in infra red even if for an acronym

* Update src/04-modality-specific-files/11-functional-near-infrared-spectroscopy.md

Co-authored-by: Julia Guiomar Niso Galán <guiomar.niso@ctb.upm.es>

* Update src/04-modality-specific-files/11-functional-near-infrared-spectroscopy.md

Co-authored-by: Julia Guiomar Niso Galán <guiomar.niso@ctb.upm.es>

* Implement cap description changes

Following suggestions from https://github.com/bids-standard/bids-specification/pull/802/files#r904838368

* Improvements to cap description fields

https://github.com/bids-standard/bids-specification/pull/802/files#r896527960
https://github.com/bids-standard/bids-specification/pull/802/files#r896519445

* Move age details to modality agnostic page

* Update src/04-modality-specific-files/11-functional-near-infrared-spectroscopy.md

Co-authored-by: Julia Guiomar Niso Galán <guiomar.niso@ctb.upm.es>

* Lint

* Update README.md

* Make aux channel counts optional

* Update metadata.yaml

* apply small wording and typo fixes

Co-authored-by: Chris Markiewicz <markiewicz@stanford.edu>

* add citation placeholder NIRS

* Update src/schema/objects/metadata.yaml

Co-authored-by: Chris Markiewicz <markiewicz@stanford.edu>

* fix appendix links

* Update README.md

Co-authored-by: Stefan Appelhoff <stefan.appelhoff@mailbox.org>

* Revert redundant NIRS age column suggestion

* Add link to coordinate system appendix

* Clarify relation between rows in channels.tsv and NIRSChannelCount

* Change NIRSCoordinateProcessingDescription example from none to n/a

* Update src/schema/meta/context.yaml

Co-authored-by: Chris Markiewicz <markiewicz@stanford.edu>

* Try and fix path bug

* Still trying to fix appendix path bug

* Still trying to get path working

* Path bug

* Update src/schema/rules/checks/nirs.yaml

Co-authored-by: Chris Markiewicz <markiewicz@stanford.edu>

* Step one of adding IntendedFor

* Step two of adding IntendedFor

* Step three of adding IntendedFor

* Revert naming change

* Move cap fields to recommended

* update documentation regarding cap manufacturing. (#1285)

* SCHEMA: Sync table definitions, render from schema

* SCHEMA: Update schema rules, including *ChannelCount checks

* Channels is recommended. Optodes is required if channels is present.

* Variable naming changes suggested by tsalo

Co-authored-by: Stefan Appelhoff <stefan.appelhoff@mailbox.org>
Co-authored-by: Christopher J. Markiewicz <markiewicz@stanford.edu>
Co-authored-by: Ross Blair <rosswilsonblair@gmail.com>
Co-authored-by: Taylor Salo <tsalo006@fiu.edu>
Co-authored-by: Julia Guiomar Niso Galán <guiomar.niso@ctb.upm.es>
Co-authored-by: Helena Cockx <54403982+helenacockx@users.noreply.github.com>

README.md

@@ -27,6 +27,7 @@ BIDS currently supports the following data modalities with more to come in the f
 - physiological
 - PET
 - microscopy
+- fNIRS
 
 # Formatting your data with BIDS
 

mkdocs.yml

@@ -65,6 +65,7 @@ nav:
         - Genetic Descriptor: 04-modality-specific-files/08-genetic-descriptor.md
         - Positron Emission Tomography: 04-modality-specific-files/09-positron-emission-tomography.md
         - Microscopy: 04-modality-specific-files/10-microscopy.md
+        - Functional Near-Infrared Spectroscopy: 04-modality-specific-files/11-functional-near-infrared-spectroscopy.md
       - Derivatives:
         - BIDS Derivatives: 05-derivatives/01-introduction.md
         - Common data types and metadata: 05-derivatives/02-common-data-types.md

src/01-introduction.md

@@ -156,6 +156,10 @@ For example:
     **qMRI-BIDS: An extension to the brain imaging data structure for quantitative magnetic resonance imaging data.**
     Scientific Data 9, 517 (2022). [doi:10.1038/s41597-022-01571-4](https://doi.org/10.1038/s41597-022-01571-4)
 
+#### NIRS
+
+-   (publication forthcoming)
+
 ### Research Resource Identifier (RRID)
 
 BIDS has also a

src/schema/meta/context.yaml

@@ -187,7 +187,25 @@ context:
             n_cols:
               description: 'Number of columns in bvec file'
               type: integer
-
+        channels:
+          description: 'Channels file'
+          type: object
+          properties:
+            path:
+              description: 'Path to associated channels file'
+              type: string
+            type:
+              description: 'Contents of the type column'
+              type: array
+              items:
+                type: string
+        coordsystem:
+          description: 'Coordinate system file'
+          type: object
+          properties:
+            path:
+              description: 'Path to associated coordsystem file'
+              type: string
     # The following properties are populated if the current file is of an appropriate type
     columns:
       description: 'TSV columns, indexed by column header, values are arrays with column contents'

src/schema/objects/columns.yaml

@@ -52,6 +52,24 @@ color:
     Hexadecimal. Label color for visualization.
   type: string
   unit: hexadecimal
+detector__channels:
+  name: detector
+  display_name: Detector Name
+  description: |
+    Name of the detector as specified in the `*_optodes.tsv` file.
+    `n/a` for channels that do not contain fNIRS signals (for example, acceleration).
+  anyOf:
+    - type: string
+    - type: string
+      enum:
+        - n/a
+detector_type:
+  name: detector_type
+  display_name: Detector Type
+  description: |
+    The type of detector. Only to be used if the field `DetectorType` in `*_nirs.json` is set to `mixed`.
+  anyOf:
+    - type: string
 derived_from:
   name: derived_from
   display_name: Derived from
@@ -66,6 +84,12 @@ description:
   description: |
     Brief free-text description of the channel, or other information of interest.
   type: string
+description__optode:
+  name: description
+  display_name: Description
+  description: |
+    Free-form text description of the optode, or other information of interest.
+  type: string
 dimension:
   name: dimension
   display_name: Dimension
@@ -240,6 +264,12 @@ name__electrodes:
   description: |
     Name of the electrode contact point.
   type: string
+name__optodes:
+  name: name
+  display_name: Optode name
+  description: |
+    Name of the optode, must be unique.
+  type: string
 # name column for dseg.tsv files
 name__segmentations:
   name: name
@@ -278,6 +308,16 @@ onset:
     acquired data point.
   type: number
   unit: s
+orientation_component:
+  name: orientation_component
+  display_name: Orientation Component
+  description: |
+    Description of the orientation of the channel.
+  type: string
+  enum:
+    - x
+    - y
+    - z
 pathology:
   name: pathology
   display_name: Pathology
@@ -420,6 +460,14 @@ sex:
     - OTHER
     - Other
     - n/a
+short_channel:
+  name: short_channel
+  display_name: Short Channel
+  description: |
+    Is the channel designated as short.
+    The total number of channels listed as short channels
+    SHOULD be stored in `ShortChannelCount` in `*_nirs.json`.
+  type: boolean
 size:
   name: size
   display_name: Electrode size
@@ -440,6 +488,24 @@ software_filters:
     - type: string
       enum:
         - n/a
+source__channels:
+  name: source
+  display_name: Source name
+  description: |
+    Name of the source as specified in the `*_optodes.tsv` file.
+    `n/a` for channels that do not contain fNIRS signals (for example, acceleration).
+  anyOf:
+    - type: string
+    - type: string
+      enum:
+        - n/a
+source__optodes:
+  name: source_type
+  display_name: Source type
+  description: |
+    The type of source. Only to be used if the field `SourceType` in `*_nirs.json` is set to `mixed`.
+  anyOf:
+    - type: string
 species:
   name: species
   display_name: Species
@@ -614,13 +680,69 @@ type__ieeg_channels:
     - DAC
     - REF
     - OTHER
+type__nirs_channels:
+  name: type
+  display_name: Channel type
+  description: |
+    Type of channel; MUST use the channel types listed below.
+    Note that the type MUST be in upper-case.
+  type: string
+  enum:
+    - NIRSCWAMPLITUDE
+    - NIRSCWFLUORESCENSEAMPLITUDE
+    - NIRSCWOPTICALDENSITY
+    - NIRSCWHBO
+    - NIRSCWHBR
+    - NIRSCWMUA
+    - MEGMAG
+    - MEGGRADAXIAL
+    - MEGGRADPLANAR
+    - MEGREFMAG
+    - MEGREFGRADAXIAL
+    - MEGREFGRADPLANAR
+    - MEGOTHER
+    - EEG
+    - ECOG
+    - SEEG
+    - DBS
+    - VEOG
+    - HEOG
+    - EOG
+    - ECG
+    - EMG
+    - TRIG
+    - AUDIO
+    - PD
+    - EYEGAZE
+    - PUPIL
+    - MISC
+    - SYSCLOCK
+    - ADC
+    - DAC
+    - HLU
+    - FITERR
+    - ACCEL
+    - GYRO
+    - MAGN
+    - MISC
+    - OTHER
 # type column for electrodes.tsv files
 type__electrodes:
   name: type
   display_name: Electrode type
   description: |
     Type of the electrode (for example, cup, ring, clip-on, wire, needle).
   type: string
+type__optodes:
+  name: type
+  display_name: Type
+  description: |
+    The type of the optode.
+  type: string
+  enum:
+    - source
+    - detector
+    - n/a
 units:
   name: units
   display_name: Units
@@ -630,6 +752,17 @@ units:
     (see [Units](SPEC_ROOT/02-common-principles.md#units)).
   type: string
   format: unit
+units__nirs:
+  name: units
+  display_name: Units
+  description: |
+    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](SPEC_ROOT/appendices/units.md)
+    and [Common Principles](SPEC_ROOT/02-common-principles.md#units) pages.
+  type: string
+  format: unit
 value:
   name: value
   display_name: Marker value
@@ -652,6 +785,34 @@ volume_type:
     - m0scan
     - deltam
     - cbf
+wavelength_nominal:
+  name: wavelength_nominal
+  display_name: Wavelength nominal
+  description: |
+    Specified wavelength of light in nm.
+    `n/a` for channels that do not contain raw fNIRS signals (for example, acceleration).
+    This field is equivalent to `/nirs(i)/probe/wavelengths` in the SNIRF specification.
+  anyOf:
+    - type: number
+    - type: string
+      enum:
+        - n/a
+wavelength_actual:
+  name: wavelength_actual
+  display_name: Wavelength actual
+  description: |
+    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.
+  type: number
+wavelength_emission_actual:
+  name: wavelength_emission_actual
+  display_name: Wavelength emission actual
+  description: |
+    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.
+  type: number
 whole_blood_radioactivity:
   name: whole_blood_radioactivity
   display_name: Whole blood radioactivity
@@ -681,3 +842,66 @@ z:
     - type: string
       enum:
         - n/a
+x__optodes:
+  name: x
+  display_name: X position
+  description: |
+    Recorded position along the x-axis.
+    `"n/a"` if not available.
+  anyOf:
+    - type: number
+    - type: string
+      enum:
+        - n/a
+y__optodes:
+  name: y
+  display_name: Y position
+  description: |
+    Recorded position along the y-axis.
+    `"n/a"` if not available.
+  anyOf:
+    - type: number
+    - type: string
+      enum:
+        - n/a
+z__optodes:
+  name: z
+  display_name: Z position
+  description: |
+    Recorded position along the z-axis.
+    `"n/a"` if not available.
+  anyOf:
+    - type: number
+    - type: string
+      enum:
+        - n/a
+template_x:
+  name: template_x
+  display_name: X template position
+  description: |
+    Assumed or ideal position along the x axis.
+  anyOf:
+    - type: number
+    - type: string
+      enum:
+        - n/a
+template_y:
+  name: template_y
+  display_name: Y template position
+  description: |
+    Assumed or ideal position along the y axis.
+  anyOf:
+    - type: number
+    - type: string
+      enum:
+        - n/a
+template_z:
+  name: template_z
+  display_name: Z template position
+  description: |
+    Assumed or ideal position along the z axis.
+  anyOf:
+    - type: number
+    - type: string
+      enum:
+        - n/a

src/schema/objects/common_principles.yaml

@@ -39,6 +39,8 @@ data_type:
         10. `pet` (positron emission tomography)
 
         11. `micr` (microscopy)
+
+        12. `nirs` (near infrared spectroscopy)
 dataset:
   name: Dataset
   display_name: Dataset

src/schema/objects/datatypes.yaml

@@ -53,3 +53,8 @@ pet:
   display_name: Positron Emission Tomography
   description: |
     Positron emission tomography data
+nirs:
+  value: nirs
+  display_name: Functional Near-Infrared Spectroscopy
+  description:
+    Near-Infrared data organized around the SNIRF format

src/schema/objects/extensions.yaml

@@ -237,6 +237,11 @@ set:
 
     The format used by the MATLAB toolbox [EEGLAB](https://sccn.ucsd.edu/eeglab).
     Each recording consists of a `.set` file with an optional `.fdt` file.
+snirf:
+  value: .snirf
+  display_name: Shared Near Infrared Spectroscopy Format
+  description: |
+    HDF5 file organized according to the [SNIRF specification](https://github.com/fNIRS/snirf)
 sqd:
   value: .sqd
   display_name: SQD