ENH: Add fNIRS-motor dataset and tutorial stub

.circleci/config.yml

@@ -186,6 +186,9 @@ jobs:
                     if [[ $(cat $FNAME | grep -x ".*datasets.*multimodal.*" | wc -l) -gt 0 ]]; then
                       python -c "import mne; print(mne.datasets.multimodal.data_path(update_path=True))";
                     fi;
+                    if [[ $(cat $FNAME | grep -x ".*datasets.*fnirs_motor.*" | wc -l) -gt 0 ]]; then
+                      python -c "import mne; print(mne.datasets.fnirs_motor.data_path(update_path=True))";
+                    fi;
                     if [[ $(cat $FNAME | grep -x ".*datasets.*opm.*" | wc -l) -gt 0 ]]; then
                       python -c "import mne; print(mne.datasets.opm.data_path(update_path=True))";
                     fi;

doc/overview/datasets_index.rst

@@ -192,6 +192,24 @@ with auditory, visual, and somatosensory stimuli.
 
     * :ref:`ex-io-ave-fiff`
 
+.. _fnirs-motor-dataset:
+
+fNIRS motor
+===========
+:func:`mne.datasets.fnirs_motor.data_path`
+
+This dataset contains a single subject recorded at Macquarie University.
+It has optodes placed over the motor cortex. There are three conditions:
+
+- tapping the left thumb to fingers
+- tapping the right thumb to fingers
+- a control where nothing happens
+
+The tapping lasts 5 seconds, and there are 30 trials of each condition.
+
+.. topic:: Examples
+
+    * :ref:`tut-fnirs-processing`
 
 High frequency SEF
 ==================

doc/python_reference.rst

@@ -188,6 +188,7 @@ Datasets
    fetch_aparc_sub_parcellation
    fetch_fsaverage
    fetch_hcp_mmp_parcellation
+   fnirs_motor.data_path
    hf_sef.data_path
    kiloword.data_path
    limo.load_data

mne/datasets/__init__.py

@@ -14,6 +14,7 @@
 from . import sample
 from . import somato
 from . import multimodal
+from . import fnirs_motor
 from . import opm
 from . import spm_face
 from . import testing

mne/datasets/fnirs_motor/__init__.py

@@ -0,0 +1,3 @@
+"""fNIRS motor dataset."""
+
+from .fnirs_motor import data_path, has_fnirs_motor_data, get_version

mne/datasets/fnirs_motor/fnirs_motor.py

@@ -0,0 +1,30 @@
+# Authors: Eric Larson <[email protected]>
+# License: BSD Style.
+
+from functools import partial
+
+from ...utils import verbose
+from ..utils import (has_dataset, _data_path, _data_path_doc,
+                     _get_version, _version_doc)
+
+
+has_fnirs_motor_data = partial(has_dataset, name='fnirs_motor')
+
+
+@verbose
+def data_path(path=None, force_update=False, update_path=True, download=True,
+              verbose=None):  # noqa: D103
+    return _data_path(path=path, force_update=force_update,
+                      update_path=update_path, name='fnirs_motor',
+                      download=download)
+
+
+data_path.__doc__ = _data_path_doc.format(name='fnirs_motor',
+                                          conf='MNE_DATASETS_FNIRS_MOTOR_PATH')
+
+
+def get_version():  # noqa: D103
+    return _get_version('fnirs_motor')
+
+
+get_version.__doc__ = _version_doc.format(name='fnirs_motor')

mne/datasets/utils.py

@@ -226,6 +226,7 @@ def _data_path(path=None, force_update=False, update_path=True, download=True,
         'brainstorm': 'MNE_DATASETS_BRAINSTORM_PATH',
         'testing': 'MNE_DATASETS_TESTING_PATH',
         'multimodal': 'MNE_DATASETS_MULTIMODAL_PATH',
+        'fnirs_motor': 'MNE_DATASETS_FNIRS_MOTOR_PATH',
         'opm': 'MNE_DATASETS_OPM_PATH',
         'visual_92_categories': 'MNE_DATASETS_VISUAL_92_CATEGORIES_PATH',
         'kiloword': 'MNE_DATASETS_KILOWORD_PATH',
@@ -262,6 +263,7 @@ def _data_path(path=None, force_update=False, update_path=True, download=True,
         testing='https://codeload.github.com/mne-tools/mne-testing-data/'
                 'tar.gz/%s' % releases['testing'],
         multimodal='https://ndownloader.figshare.com/files/5999598',
+        fnirs_motor='https://osf.io/dj3eh/download?version=1',
         opm='https://osf.io/p6ae7/download?version=2',
         visual_92_categories=[
             'https://osf.io/8ejrs/download?version=1',
@@ -279,6 +281,7 @@ def _data_path(path=None, force_update=False, update_path=True, download=True,
         misc='mne-misc-data-%s.tar.gz' % releases['misc'],
         mtrf='mTRF_1.5.zip',
         multimodal='MNE-multimodal-data.tar.gz',
+        fnirs_motor='MNE-fNIRS-motor-data.tgz',
         opm='MNE-OPM-data.tar.gz',
         sample='MNE-sample-data-processed.tar.gz',
         somato='MNE-somato-data.tar.gz',
@@ -322,6 +325,7 @@ def _data_path(path=None, force_update=False, update_path=True, download=True,
         spm='9f43f67150e3b694b523a21eb929ea75',
         testing='e825eec08cfd75e85f33ed2b06fc82f1',
         multimodal='26ec847ae9ab80f58f204d09e2c08367',
+        fnirs_motor='c4935d19ddab35422a69f3326a01fef8',
         opm='370ad1dcfd5c47e029e692c85358a374',
         visual_92_categories=['74f50bbeb65740903eadc229c9fa759f',
                               '203410a98afc9df9ae8ba9f933370e20'],
@@ -538,6 +542,7 @@ def has_dataset(name):
             'somato': 'MNE-somato-data',
             'spm': 'MNE-spm-face',
             'multimodal': 'MNE-multimodal-data',
+            'fnirs_motor': 'MNE-fNIRS-motor-data',
             'opm': 'MNE-OPM-data',
             'testing': 'MNE-testing-data',
             'visual_92_categories': 'MNE-visual_92_categories-data',
@@ -564,14 +569,16 @@ def _download_all_example_data(verbose=True):
     # Consider adding datasets from here to CircleCI for PR-auto-build
     from . import (sample, testing, misc, spm_face, somato, brainstorm,
                    eegbci, multimodal, opm, hf_sef, mtrf, fieldtrip_cmc,
-                   kiloword, phantom_4dbti, sleep_physionet, limo)
+                   kiloword, phantom_4dbti, sleep_physionet, limo,
+                   fnirs_motor)
     sample.data_path()
     testing.data_path()
     misc.data_path()
     spm_face.data_path()
     somato.data_path()
     hf_sef.data_path()
     multimodal.data_path()
+    fnirs_motor.data_path()
     opm.data_path()
     mtrf.data_path()
     fieldtrip_cmc.data_path()

mne/utils/config.py

@@ -95,6 +95,7 @@ def set_memmap_min_size(memmap_min_size):
     'MNE_DATASETS_SAMPLE_PATH',
     'MNE_DATASETS_SOMATO_PATH',
     'MNE_DATASETS_MULTIMODAL_PATH',
+    'MNE_DATASETS_FNIRS_MOTOR_PATH',
     'MNE_DATASETS_OPM_PATH',
     'MNE_DATASETS_SPM_FACE_DATASETS_TESTS',
     'MNE_DATASETS_SPM_FACE_PATH',

tutorials/preprocessing/plot_70_fnirs_processing.py

@@ -0,0 +1,42 @@
+"""
+.. _tut-fnirs-processing:
+
+Preprocessing fNIRS data
+========================
+
+This tutorial covers how to convert fNIRS data from raw measurements to
+HbO/HbR.
+
+.. contents:: Page contents
+   :local:
+   :depth: 2
+
+Here we will work with the :ref:`fNIRS motor data <fnirs-motor-dataset>`.
+"""
+# sphinx_gallery_thumbnail_number = 3
+
+import os
+import mne
+
+fnirs_data_folder = mne.datasets.fnirs_motor.data_path()
+fnirs_raw_dir = os.path.join(fnirs_data_folder, 'Participant-1')
+raw_intensity = mne.io.read_raw_nirx(fnirs_raw_dir, verbose=True).load_data()
+raw_intensity.plot()
+
+###############################################################################
+# Converting from raw intensity to optical density
+# ------------------------------------------------
+#
+# The first thing we should do is convert from raw intensity values ...
+
+raw_od = mne.preprocessing.optical_density(raw_intensity)
+raw_od.plot()
+
+###############################################################################
+# Converting from optical density to hemoglobin
+# ---------------------------------------------
+#
+# Next we Beer-Lambert ...
+
+raw_fnirs = mne.preprocessing.beer_lambert_law(raw_od)
+raw_fnirs.plot()