From 5238273e9f40ed378003cd72fbab3817674be9d8 Mon Sep 17 00:00:00 2001 From: Robert Luke Date: Wed, 19 May 2021 21:31:49 +1000 Subject: [PATCH 1/4] Restructure fNIRS IO tutorial --- tutorials/io/30_reading_fnirs_data.py | 79 ++++++++++++++++++++------- 1 file changed, 58 insertions(+), 21 deletions(-) diff --git a/tutorials/io/30_reading_fnirs_data.py b/tutorials/io/30_reading_fnirs_data.py index 7e34899d573..e0823a440aa 100644 --- a/tutorials/io/30_reading_fnirs_data.py +++ b/tutorials/io/30_reading_fnirs_data.py @@ -6,39 +6,78 @@ 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 expects a specific formatting of channel names. + Manual modification of channel names is not recommended. + + +.. _import-snirf: + +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`. + +.. 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. + + +*********************** +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. -.. _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 +107,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 ======================================== From 7084e59cc1d92211feadee129a2237264c1269eb Mon Sep 17 00:00:00 2001 From: Robert Luke <748691+rob-luke@users.noreply.github.com> Date: Thu, 20 May 2021 09:51:43 +1000 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Eric Larson --- tutorials/io/30_reading_fnirs_data.py | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/tutorials/io/30_reading_fnirs_data.py b/tutorials/io/30_reading_fnirs_data.py index e0823a440aa..105137047df 100644 --- a/tutorials/io/30_reading_fnirs_data.py +++ b/tutorials/io/30_reading_fnirs_data.py @@ -30,11 +30,15 @@ .. _import-snirf: +***************** +Standardized data +***************** + SNIRF (.snirf) -================================ +============== The Shared Near Infrared Spectroscopy Format -(`SNIRF `_) +(`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). @@ -55,7 +59,7 @@ .. _import-nirx: NIRx (directory or hdr) -================================ +======================= NIRx produce continuous wave fNIRS devices. NIRx recordings can be read in using :func:`mne.io.read_raw_nirx`. From 0ea662a9979b68b90662248f4290f91a567ed328 Mon Sep 17 00:00:00 2001 From: Robert Luke <748691+rob-luke@users.noreply.github.com> Date: Thu, 20 May 2021 11:44:46 +1000 Subject: [PATCH 3/4] Update 30_reading_fnirs_data.py --- tutorials/io/30_reading_fnirs_data.py | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/tutorials/io/30_reading_fnirs_data.py b/tutorials/io/30_reading_fnirs_data.py index 105137047df..fadeab756d4 100644 --- a/tutorials/io/30_reading_fnirs_data.py +++ b/tutorials/io/30_reading_fnirs_data.py @@ -10,14 +10,14 @@ 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, +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, +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. @@ -46,9 +46,9 @@ Data stored in the SNIRF format can be read in using :func:`mne.io.read_raw_snirf`. -.. 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. +.. 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. *********************** @@ -66,6 +66,7 @@ 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-hitachi: From 3b885fb46c91c4c77e002c9eda8fa76cafbcb06c Mon Sep 17 00:00:00 2001 From: Robert Luke <748691+rob-luke@users.noreply.github.com> Date: Thu, 20 May 2021 13:00:02 +1000 Subject: [PATCH 4/4] Update 30_reading_fnirs_data.py --- tutorials/io/30_reading_fnirs_data.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/tutorials/io/30_reading_fnirs_data.py b/tutorials/io/30_reading_fnirs_data.py index fadeab756d4..7661ba454ac 100644 --- a/tutorials/io/30_reading_fnirs_data.py +++ b/tutorials/io/30_reading_fnirs_data.py @@ -24,8 +24,10 @@ Different vendors save the data as different data types, and MNE will load the data as the appropriate type. -.. warning:: MNE expects a specific formatting of channel names. - Manual modification of channel names is not recommended. +.. 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: