WIP: Add NIRSport support

doc/python_reference.rst

@@ -364,6 +364,7 @@ Projections:
    annotate_flat
    annotate_movement
    annotate_muscle_zscore
+   annotate_nan
    compute_average_dev_head_t
    compute_current_source_density
    compute_fine_calibration

mne/datasets/utils.py

@@ -245,7 +245,7 @@ def _data_path(path=None, force_update=False, update_path=True, download=True,
     path = _get_path(path, key, name)
     # To update the testing or misc dataset, push commits, then make a new
     # release on GitHub. Then update the "releases" variable:
-    releases = dict(testing='0.110', misc='0.7')
+    releases = dict(testing='0.111', misc='0.7')
     # And also update the "md5_hashes['testing']" variable below.
     # To update any other dataset, update the data archive itself (upload
     # an updated version) and update the md5 hash.
@@ -331,7 +331,7 @@ def _data_path(path=None, force_update=False, update_path=True, download=True,
         sample='12b75d1cb7df9dfb4ad73ed82f61094f',
         somato='32fd2f6c8c7eb0784a1de6435273c48b',
         spm='9f43f67150e3b694b523a21eb929ea75',
-        testing='c4cd3385f321cd1151ed9de34fc4ce5a',
+        testing='e7ece4615882b99026edb76fb708a3ce',
         multimodal='26ec847ae9ab80f58f204d09e2c08367',
         fnirs_motor='c4935d19ddab35422a69f3326a01fef8',
         opm='370ad1dcfd5c47e029e692c85358a374',

mne/io/nirx/nirx.py

@@ -20,15 +20,17 @@
 
 
 @fill_doc
-def read_raw_nirx(fname, preload=False, verbose=None):
+def read_raw_nirx(fname, saturated='ignore', preload=False, verbose=None):
     """Reader for a NIRX fNIRS recording.
 
-    This function has only been tested with NIRScout devices.
-
     Parameters
     ----------
     fname : str
         Path to the NIRX data folder or header file.
+    saturated : str
+        (Only relevant for NIRSport1 devices). If 'ignore' (default),
+        use *.nosatflags_wlX instead of standard *.wlX files. If 'nan',
+        use standard *.wlX files. Irrelevant if there is no *.nosatflags file.
     %(preload)s
     %(verbose)s
 
@@ -40,8 +42,22 @@ def read_raw_nirx(fname, preload=False, verbose=None):
     See Also
     --------
     mne.io.Raw : Documentation of attribute and methods.
+
+    Notes
+    -----
+    This function has only been tested with NIRScout and NIRSport1 devices.
+
+        - Re: saturated flag
+    The NIRSport probes can saturate during the experiment. Starting from
+    NIRStar 14.2, those saturated values are replaced by NaN in the
+    standard *.wlX files. The measured values are stored in another file
+    called *.nosatflags_wlX, which is a copy of the corresponding *.wlX
+    file where the saturated data didn't get replaced. Since NaN values can
+    cause unexpected behaviour with mathematical functions, you can chose
+    to use the original, non-modified data by setting the ``saturated`` flag to
+    'ignore' (default) or set it to 'nan' to use NaN values.
     """
-    return RawNIRX(fname, preload, verbose)
+    return RawNIRX(fname, saturated, preload, verbose)
 
 
 def _open(fname):
@@ -56,18 +72,39 @@ class RawNIRX(BaseRaw):
     ----------
     fname : str
         Path to the NIRX data folder or header file.
+    saturated : str
+        (Only relevant for NIRSport1 devices). If 'ignore' (default),
+        use *.nosatflags_wlX instead of standard *.wlX files. If 'nan',
+        use standard *.wlX files. Irrelevant if there is no *.nosatflags file.
+
     %(preload)s
     %(verbose)s
 
     See Also
     --------
     mne.io.Raw : Documentation of attribute and methods.
+
+    Notes
+    -----
+    This function has only been tested with NIRScout and NIRSport1 devices.
+
+        - Re: saturated flag
+    The NIRSport probes can saturate during the experiment. Starting from
+    NIRStar 14.2, those saturated values are replaced by NaN in the
+    standard *.wlX files. The measured values are stored in another file
+    called *.nosatflags_wlX, which is a copy of the corresponding *.wlX
+    file where the saturated data didn't get replaced. Since NaN values can
+    cause unexpected behaviour with mathematical functions, you can chose
+    to use the original, non-modified data by setting the ``saturated`` flag of
+    the read_raw_nirx() method to 'ignore' (default) or set it to 'nan' to
+    use NaN values.
     """
 
     @verbose
-    def __init__(self, fname, preload=False, verbose=None):
+    def __init__(self, fname, saturated, preload=False, verbose=None):
         from ...externals.pymatreader import read_mat
         from ...coreg import get_mni_fiducials  # avoid circular import prob
+        from ...preprocessing import annotate_nan  # avoid circular import prob
         logger.info('Loading %s' % fname)
 
         if fname.endswith('.hdr'):
@@ -83,9 +120,40 @@ def __init__(self, fname, preload=False, verbose=None):
         for key in keys:
             files[key] = glob.glob('%s/*%s' % (fname, key))
             if len(files[key]) != 1:
-                raise RuntimeError('Expect one %s file, got %d' %
-                                   (key, len(files[key]),))
-            files[key] = files[key][0]
+                if (key == 'wl1' or key == 'wl2') \
+                    and len(glob.glob('%s/*%s' %
+                                      (fname, 'nosatflags_' + key))) == 1:
+                    if saturated == 'nan':
+                        warn('You provided saturated data and specified '
+                             'to use the standard *.wlX files.')
+                        files[key] = files[key][1]
+                    elif saturated == 'annotate':
+                        warn('You provided saturated data and specified '
+                             'to annotate your data with a \'nan\' flag.')
+                        files[key] = files[key][1]
+                    else:
+                        if saturated == 'ignore':
+                            warn('The data you provided contains NaN entries '
+                                 'which were put by NIRStar in the *.wlX '
+                                 'files. You chose to ignore them and use the '
+                                 '*.nosatflags_wlX files instead. You can '
+                                 'change this behaviour by setting '
+                                 '``saturated`` to "nan" when calling '
+                                 'read_raw_nirx()')
+                        else:
+                            warn('The value specified for ``saturated`` is '
+                                 'not recognized. Falling back to default '
+                                 'behaviour and using *.nosatflags_wlX files. '
+                                 'You can change this behaviour by setting '
+                                 '``saturated`` to "nan" when calling '
+                                 'read_raw_nirx()')
+                        files[key] = glob.glob('%s/*%s' %
+                                               (fname, 'nosatflags_' + key))[0]
+                else:
+                    raise RuntimeError('Expect one %s file, got %d' %
+                                       (key, len(files[key]),))
+            else:
+                files[key] = files[key][0]
         if len(glob.glob('%s/*%s' % (fname, 'dat'))) != 1:
             warn("A single dat file was expected in the specified path, but "
                  "got %d. This may indicate that the file structure has been "
@@ -111,7 +179,8 @@ def __init__(self, fname, preload=False, verbose=None):
         if hdr['GeneralInfo']['NIRStar'] not in ['"15.0"', '"15.2"', '"15.3"']:
             raise RuntimeError('MNE does not support this NIRStar version'
                                ' (%s)' % (hdr['GeneralInfo']['NIRStar'],))
-        if "NIRScout" not in hdr['GeneralInfo']['Device']:
+        if "NIRScout" not in hdr['GeneralInfo']['Device'] \
+                and "NIRSport" not in hdr['GeneralInfo']['Device']:
             warn("Only import of data from NIRScout devices have been "
                  "thoroughly tested. You are using a %s device. " %
                  hdr['GeneralInfo']['Device'])
@@ -320,6 +389,10 @@ def prepend(li, str):
             annot = Annotations(onset, duration, description)
             self.set_annotations(annot)
 
+        if saturated == "annotate":
+            annot = annotate_nan(self)
+            self.set_annotations(annot)
+
     def _read_segment_file(self, data, idx, fi, start, stop, cals, mult):
         """Read a segment of data from a file.
 

mne/io/nirx/tests/test_nirx.py

@@ -72,6 +72,24 @@ def test_nirx_dat_warn(tmpdir):
         read_raw_nirx(fname, preload=True)
 
 
+@requires_testing_data
+def test_nirx_nosatflags_v1_warn(tmpdir):
+    """Test reading NIRSportv1 files with saturated data."""
+    shutil.copytree(fname_nirx_15_2_short, str(tmpdir) + "/data/")
+    shutil.copyfile(str(tmpdir) + "/data" + "/NIRS-2019-08-23_001.wl1",
+                    str(tmpdir) + "/data" +
+                                  "/NIRS-2019-08-23_001.nosatflags_wl1")
+    fname = str(tmpdir) + "/data" + "/NIRS-2019-08-23_001.hdr"
+    with pytest.raises(RuntimeWarning, match='specified to use the standard'):
+        read_raw_nirx(fname, saturated='nan', preload=True)
+    with pytest.raises(RuntimeWarning, match='specified to annotate your'):
+        read_raw_nirx(fname, saturated='annotate', preload=True)
+    with pytest.raises(RuntimeWarning, match='You chose to ignore them'):
+        read_raw_nirx(fname, saturated='ignore', preload=True)
+    with pytest.raises(RuntimeWarning, match='Falling back to default'):
+        read_raw_nirx(fname, saturated='foobar', preload=True)
+
+
 @requires_testing_data
 def test_nirx_15_2_short():
     """Test reading NIRX files."""

mne/preprocessing/__init__.py

@@ -28,3 +28,4 @@
 from ._regress import regress_artifact
 from ._fine_cal import (compute_fine_calibration,  read_fine_calibration,
                         write_fine_calibration)
+from .annotate_nan import annotate_nan

mne/preprocessing/annotate_nan.py

@@ -0,0 +1,47 @@
+# Author: David Julien <david.julien@ifsttar.fr>
+#
+# License: BSD (3-clause)
+
+import numpy as np
+
+import warnings
+
+from ..annotations import Annotations
+from ..utils import _mask_to_onsets_offsets
+
+
+def annotate_nan(raw):
+    """Detect segments with NaN and return a new Annotations instance.
+
+    Parameters
+    ----------
+    raw : instance of Raw
+        Data to find segments with NaN values.
+
+    Returns
+    -------
+    annot : instance of Annotations
+        Updated annotations for raw data.
+    """
+    annot = raw.annotations.copy()
+    data, times = raw.get_data(return_times=True)
+    sampling_duration = 1 / raw.info['sfreq']
+
+    nans = np.any(np.isnan(data), axis=0)
+    starts, stops = _mask_to_onsets_offsets(nans)
+
+    if len(starts) > 0:
+        starts, stops = np.array(starts), np.array(stops)
+        onsets = (starts + raw.first_samp) * sampling_duration
+        durations = (stops - starts) * sampling_duration
+    else:
+        warnings.warn("The dataset you provided does not contain 'NaN' "
+                      "values. No annotation were made.")
+        return
+
+    if annot is None:
+        annot = Annotations(onsets, durations, 'bad_NAN')
+    else:
+        annot.append(onsets, durations, 'bad_NAN')
+
+    return annot