diff --git a/tutorials/io/30_reading_fnirs_data.py b/tutorials/io/30_reading_fnirs_data.py index 7e34899d573..7661ba454ac 100644 --- a/tutorials/io/30_reading_fnirs_data.py +++ b/tutorials/io/30_reading_fnirs_data.py @@ -6,39 +6,85 @@ Importing data from fNIRS devices ================================= -MNE includes various functions and utilities for reading NIRS -data and optode locations. - -fNIRS devices consist of light sources and light detectors. A channel is formed -by source-detector pairs. MNE stores the location of the channels, sources, and +MNE includes various functions and utilities for reading fNIRS +data and optode locations. Regardless of the manufacturer and file format, +MNE stores both the measurement data and metadata in a consistent manner. + +fNIRS devices consist of light sources and light detectors, +often also termed emitter/transmitter and receiver respectively. +A channel is formed by source-detector pairs, and MNE represents the +channel location as the midpoint between source and detector. +MNE stores the location of the channels, sources, and detectors. +There are a variety of fNIRS data types which can be represented in MNE. +For continuous wave fNIRS data this includes amplitude, optical density, +oxyhaemoglobin, and deoxyhemoglobin. +And for frequency domain fNIRS this additionally includes +AC amplitude and phase. +Different vendors save the data as different data types, and MNE will load +the data as the appropriate type. + +.. warning:: MNE stores metadata internally with a specific structure, + and internal functions expect specific naming conventions. + Manual modification of channel names and metadata + is not recommended. + + +.. _import-snirf: + +***************** +Standardized data +***************** + +SNIRF (.snirf) +============== + +The Shared Near Infrared Spectroscopy Format +(`SNIRF `__) +is designed by the fNIRS community in an effort to facilitate +sharing and analysis of fNIRS data. And is the official format of the +Society for functional near-infrared spectroscopy (SfNIRS). +SNIRF is the preferred format for reading data in to MNE. +Data stored in the SNIRF format can be read in +using :func:`mne.io.read_raw_snirf`. + +.. note:: The SNIRF format has provisions for many different types of fNIRS + recordings. MNE currently only supports reading continuous wave data + stored in the .snirf format. + + +*********************** +Continuous Wave Devices +*********************** -.. warning:: Information about device light wavelength is stored in channel - names. Manual modification of channel names is not recommended. .. _import-nirx: -NIRx (directory) -================================ +NIRx (directory or hdr) +======================= +NIRx produce continuous wave fNIRS devices. NIRx recordings can be read in using :func:`mne.io.read_raw_nirx`. The NIRx device stores data directly to a directory with multiple file types, MNE extracts the appropriate information from each file. MNE only supports NIRx files recorded with NIRStar version 15.0 and above. +MNE supports reading data from NIRScout and NIRSport 1 devices. -.. _import-snirf: +.. _import-hitachi: -SNIRF (.snirf) -================================ +Hitachi (.csv) +============== -Data stored in the SNIRF format can be read in -using :func:`mne.io.read_raw_snirf`. +Hitachi produce continuous wave fNIRS devices. +Hitachi fNIRS recordings can be read using :func:`mne.io.read_raw_hitachi`. +No optode information is stored so you'll need to set the montage manually, +see the Notes section of :func:`mne.io.read_raw_hitachi`. -.. warning:: The SNIRF format has provisions for many different types of NIRS - recordings. MNE currently only supports continuous wave data - stored in the .snirf format. +************************ +Frequency Domain Devices +************************ .. _import-boxy: @@ -68,12 +114,10 @@ If triggers are sent using the ``digaux`` port of the recording hardware, MNE will also read the ``digaux`` data and create annotations for any triggers. -Hitachi (.csv) -============== -Hitachi fNIRS recordings can be read using :func:`mne.io.read_raw_hitachi`. -No electrode information is stored so you'll need to set the montage manually, -see the Notes section of :func:`mne.io.read_raw_hitachi`. +****************** +Custom Data Import +****************** Loading legacy data in CSV or TSV format ========================================