mne-tools · larsoner · Nov 20, 2020 · May 4, 2020 · May 4, 2020 · May 4, 2020
diff --git a/doc/_includes/data_formats.rst b/doc/_includes/data_formats.rst
@@ -72,6 +72,7 @@ EEG           :ref:`Persyst <import-persyst>`               .lay       :func:`mn
 
 NIRS          :ref:`NIRx <import-nirx>`                     directory  :func:`mne.io.read_raw_nirx`
 
+NIRS          :ref:`BOXY <import-boxy>`                     directory  :func:`mne.io.read_raw_boxy`
 ============  ============================================  =========  ===================================
 
 More details are provided in the tutorials in the :ref:`tut-data-formats`

diff --git a/doc/changes/latest.inc b/doc/changes/latest.inc
@@ -20,11 +20,15 @@ Current (0.22.dev0)
 
 .. |Victoria Peterson| replace:: **Victoria Peterson**
 
+.. |Jonathan Kuziek| replace:: **Jonathan Kuziek**
+
 
 Enhancements
 ~~~~~~~~~~~~
 - Add :class:`mne.decoding.SSD` for spatial filtering with spatio-spectral-decomposition (:gh:`7070` **by new contributor** |Victoria Peterson|_ and `Denis Engemann`_)
 
+- Add reader for optical imaging data recorded using ISS Imgagent I/II hardware and BOXY recording software in :func:`mne.io.read_raw_boxy` (:gh:`7717` **by new contributor** |Jonathan Kuziek|_ and `Kyle Mathewson`_)
+
 - Add options to use labels in :func:`mne.minimum_norm.get_point_spread` and :func:`mne.minimum_norm.get_cross_talk` (:gh:`8275` by `Olaf Hauk`_)
 
 - Update ``surfaces`` argument in :func:`mne.viz.plot_alignment` to allow dict for transparency values, and set default for sEEG data to have transparency (:gh:`8445` by `Keith Doelling`_)

diff --git a/doc/changes/names.inc b/doc/changes/names.inc
@@ -318,6 +318,8 @@
 
 .. _Rahul Nadkarni: https://github.com/rahuln
 
+.. _Jonathan Kuziek:  https://github.com/kuziekj
+
 .. _Lau Møller Andersen: https://github.com/ualsbombe
 
 .. _Martin Schulz: https://github.com/marsipu

diff --git a/doc/conf.py b/doc/conf.py
@@ -677,7 +677,7 @@ def reset_warnings(gallery_conf, fname):
     'n_dipoles_fwd', 'n_picks_ref', 'n_coords',
     # Undocumented (on purpose)
     'RawKIT', 'RawEximia', 'RawEGI', 'RawEEGLAB', 'RawEDF', 'RawCTF', 'RawBTi',
-    'RawBrainVision', 'RawCurry', 'RawNIRX', 'RawGDF', 'RawSNIRF',
+    'RawBrainVision', 'RawCurry', 'RawNIRX', 'RawGDF', 'RawSNIRF', 'RawBOXY',
     'RawPersyst', 'RawNihon',
     # sklearn subclasses
     'mapping', 'to', 'any',

diff --git a/doc/python_reference.rst b/doc/python_reference.rst
@@ -72,6 +72,7 @@ Reading raw data
    read_raw_fif
    read_raw_eximia
    read_raw_fieldtrip
+   read_raw_boxy
    read_raw_persyst
    read_raw_nihon
 

diff --git a/mne/channels/channels.py b/mne/channels/channels.py
@@ -80,7 +80,8 @@ def _get_ch_type(inst, ch_type, allow_ref_meg=False):
     """
     if ch_type is None:
         allowed_types = ['mag', 'grad', 'planar1', 'planar2', 'eeg', 'csd',
-                         'fnirs_cw_amplitude', 'fnirs_od', 'hbo', 'hbr',
+                         'fnirs_cw_amplitude', 'fnirs_fd_ac_amplitude',
+                         'fnirs_fd_phase', 'fnirs_od', 'hbo', 'hbr',
                          'ecog', 'seeg']
         allowed_types += ['ref_meg'] if allow_ref_meg else []
         for type_ in allowed_types:
@@ -410,7 +411,8 @@ def set_channel_types(self, mapping, verbose=None):
         The following sensor types are accepted:
 
             ecg, eeg, emg, eog, exci, ias, misc, resp, seeg, stim, syst, ecog,
-            hbo, hbr, fnirs_cw_amplitude, fnirs_od
+            hbo, hbr, fnirs_cw_amplitude, fnirs_fd_ac_amplitude,
+            fnirs_fd_phase, fnirs_od
 
         .. versionadded:: 0.9.0
         """
@@ -452,6 +454,10 @@ def set_channel_types(self, mapping, verbose=None):
                 coil_type = FIFF.FIFFV_COIL_FNIRS_HBR
             elif ch_type == 'fnirs_cw_amplitude':
                 coil_type = FIFF.FIFFV_COIL_FNIRS_CW_AMPLITUDE
+            elif ch_type == 'fnirs_fd_ac_amplitude':
+                coil_type = FIFF.FIFFV_COIL_FNIRS_FD_AC_AMPLITUDE
+            elif ch_type == 'fnirs_fd_phase':
+                coil_type = FIFF.FIFFV_COIL_FNIRS_FD_PHASE
             elif ch_type == 'fnirs_od':
                 coil_type = FIFF.FIFFV_COIL_FNIRS_OD
             else:

diff --git a/mne/channels/layout.py b/mne/channels/layout.py
@@ -17,7 +17,7 @@
 import numpy as np
 
 from ..transforms import _pol_to_cart, _cart_to_sph
-from ..io.pick import pick_types, _picks_to_idx
+from ..io.pick import pick_types, _picks_to_idx, _FNIRS_CH_TYPES_SPLIT
 from ..io.constants import FIFF
 from ..io.meas_info import Info
 from ..utils import (_clean_names, warn, _check_ch_locs, fill_doc,
@@ -917,7 +917,7 @@ def _merge_ch_data(data, ch_type, names, method='rms'):
     if ch_type == 'grad':
         data = _merge_grad_data(data, method)
     else:
-        assert ch_type in ('hbo', 'hbr', 'fnirs_cw_amplitude', 'fnirs_od')
+        assert ch_type in _FNIRS_CH_TYPES_SPLIT
         data, names = _merge_nirs_data(data, names)
     return data, names
 

diff --git a/mne/cov.py b/mne/cov.py
@@ -1253,7 +1253,8 @@ class _RegCovariance(BaseEstimator):
     """Aux class."""
 
     def __init__(self, info, grad=0.1, mag=0.1, eeg=0.1, seeg=0.1, ecog=0.1,
-                 hbo=0.1, hbr=0.1, fnirs_cw_amplitude=0.1, fnirs_od=0.1,
+                 hbo=0.1, hbr=0.1, fnirs_cw_amplitude=0.1,
+                 fnirs_fd_ac_amplitude=0.1, fnirs_fd_phase=0.1, fnirs_od=0.1,
                  csd=0.1, store_precision=False, assume_centered=False):
         self.info = info
         # For sklearn compat, these cannot (easily?) be combined into
@@ -1266,6 +1267,8 @@ def __init__(self, info, grad=0.1, mag=0.1, eeg=0.1, seeg=0.1, ecog=0.1,
         self.hbo = hbo
         self.hbr = hbr
         self.fnirs_cw_amplitude = fnirs_cw_amplitude
+        self.fnirs_fd_ac_amplitude = fnirs_fd_ac_amplitude
+        self.fnirs_fd_phase = fnirs_fd_phase
         self.fnirs_od = fnirs_od
         self.csd = csd
         self.store_precision = store_precision
@@ -1545,7 +1548,8 @@ def _smart_eigh(C, info, rank, scalings=None, projs=None,
 @verbose
 def regularize(cov, info, mag=0.1, grad=0.1, eeg=0.1, exclude='bads',
                proj=True, seeg=0.1, ecog=0.1, hbo=0.1, hbr=0.1,
-               fnirs_cw_amplitude=0.1, fnirs_od=0.1, csd=0.1,
+               fnirs_cw_amplitude=0.1, fnirs_fd_ac_amplitude=0.1,
+               fnirs_fd_phase=0.1, fnirs_od=0.1, csd=0.1,
                rank=None, scalings=None, verbose=None):
     """Regularize noise covariance matrix.
 
@@ -1587,7 +1591,11 @@ def regularize(cov, info, mag=0.1, grad=0.1, eeg=0.1, exclude='bads',
     hbr : float (default 0.1)
         Regularization factor for HBR signals.
     fnirs_cw_amplitude : float (default 0.1)
-        Regularization factor for fNIRS raw signals.
+        Regularization factor for fNIRS CW raw signals.
+    fnirs_fd_ac_amplitude : float (default 0.1)
+        Regularization factor for fNIRS FD AC raw signals.
+    fnirs_fd_phase : float (default 0.1)
+        Regularization factor for fNIRS raw phase signals.
     fnirs_od : float (default 0.1)
         Regularization factor for fNIRS optical density signals.
     csd : float (default 0.1)
@@ -1619,7 +1627,8 @@ def regularize(cov, info, mag=0.1, grad=0.1, eeg=0.1, exclude='bads',
     scalings = _handle_default('scalings_cov_rank', scalings)
     regs = dict(eeg=eeg, seeg=seeg, ecog=ecog, hbo=hbo, hbr=hbr,
                 fnirs_cw_amplitude=fnirs_cw_amplitude,
-                fnirs_od=fnirs_od, csd=csd)
+                fnirs_fd_ac_amplitude=fnirs_fd_ac_amplitude,
+                fnirs_fd_phase=fnirs_fd_phase, fnirs_od=fnirs_od, csd=csd)
 
     if exclude is None:
         raise ValueError('exclude must be a list of strings or "bads"')

diff --git a/mne/defaults.py b/mne/defaults.py
@@ -11,22 +11,26 @@
                ref_meg='steelblue', misc='k', stim='k', resp='k', chpi='k',
                exci='k', ias='k', syst='k', seeg='saddlebrown', dipole='k',
                gof='k', bio='k', ecog='k', hbo='#AA3377', hbr='b',
-               fnirs_cw_amplitude='k', fnirs_od='k', csd='k'),
+               fnirs_cw_amplitude='k', fnirs_fd_ac_amplitude='k',
+               fnirs_fd_phase='k', fnirs_od='k', csd='k'),
     units=dict(mag='fT', grad='fT/cm', eeg='µV', eog='µV', ecg='µV', emg='µV',
                misc='AU', seeg='mV', dipole='nAm', gof='GOF', bio='µV',
                ecog='µV', hbo='µM', hbr='µM', ref_meg='fT',
-               fnirs_cw_amplitude='V', fnirs_od='V', csd='mV/m²'),
+               fnirs_cw_amplitude='V', fnirs_fd_ac_amplitude='V',
+               fnirs_fd_phase='rad', fnirs_od='V', csd='mV/m²'),
     # scalings for the units
     scalings=dict(mag=1e15, grad=1e13, eeg=1e6, eog=1e6, emg=1e6, ecg=1e6,
                   misc=1.0, seeg=1e3, dipole=1e9, gof=1.0, bio=1e6, ecog=1e6,
                   hbo=1e6, hbr=1e6, ref_meg=1e15, fnirs_cw_amplitude=1.0,
+                  fnirs_fd_ac_amplitude=1.0, fnirs_fd_phase=1.,
                   fnirs_od=1.0, csd=1e3),
     # rough guess for a good plot
     scalings_plot_raw=dict(mag=1e-12, grad=4e-11, eeg=20e-6, eog=150e-6,
                            ecg=5e-4, emg=1e-3, ref_meg=1e-12, misc='auto',
                            stim=1, resp=1, chpi=1e-4, exci=1, ias=1, syst=1,
                            seeg=1e-4, bio=1e-6, ecog=1e-4, hbo=10e-6,
                            hbr=10e-6, whitened=10., fnirs_cw_amplitude=2e-2,
+                           fnirs_fd_ac_amplitude=2e-2, fnirs_fd_phase=2e-1,
                            fnirs_od=2e-2, csd=200e-4),
     scalings_cov_rank=dict(mag=1e12, grad=1e11, eeg=1e5,  # ~100x scalings
                            seeg=1e1, ecog=1e4, hbo=1e4, hbr=1e4),
@@ -39,6 +43,8 @@
                 dipole='Dipole', ecog='ECoG', hbo='Oxyhemoglobin',
                 ref_meg='Reference Magnetometers',
                 fnirs_cw_amplitude='fNIRS (CW amplitude)',
+                fnirs_fd_ac_amplitude='fNIRS (FD AC amplitude)',
+                fnirs_fd_phase='fNIRS (FD phase)',
                 fnirs_od='fNIRS (OD)', hbr='Deoxyhemoglobin',
                 gof='Goodness of fit', csd='Current source density'),
     mask_params=dict(marker='o',

diff --git a/mne/evoked.py b/mne/evoked.py
@@ -31,7 +31,7 @@
 from .io.open import fiff_open
 from .io.tag import read_tag
 from .io.tree import dir_tree_find
-from .io.pick import pick_types, _picks_to_idx
+from .io.pick import pick_types, _picks_to_idx, _FNIRS_CH_TYPES_SPLIT
 from .io.meas_info import read_meas_info, write_meas_info
 from .io.proj import ProjMixin
 from .io.write import (start_file, start_block, end_file, end_block,
@@ -392,9 +392,9 @@ def animate_topomap(self, ch_type=None, times=None, frame_rate=None,
         ----------
         ch_type : str | None
             Channel type to plot. Accepted data types: 'mag', 'grad', 'eeg',
-            'hbo', 'hbr', 'fnirs_od, and 'fnirs_cw_amplitude'.
-            If None, first available channel type from ('mag', 'grad', 'eeg',
-            'hbo', 'hbr', 'fnirs_od, 'fnirs_cw_amplitude') is used.
+            'hbo', 'hbr', 'fnirs_cw_amplitude',
+            'fnirs_fd_ac_amplitude', 'fnirs_fd_phase', and 'fnirs_od'.
+            If None, first available channel type from the above list is used.
             Defaults to None.
         times : array of float | None
             The time points to plot. If None, 10 evenly spaced samples are
@@ -521,7 +521,7 @@ def get_peak(self, ch_type=None, tmin=None, tmax=None,
 
         Parameters
         ----------
-        ch_type : 'mag', 'grad', 'eeg', 'seeg', 'ecog', 'hbo', hbr', 'misc', None
+        ch_type : str | None
             The channel type to use. Defaults to None. If more than one sensor
             Type is present in the data the channel type has to be explicitly
             set.
@@ -558,8 +558,8 @@ def get_peak(self, ch_type=None, tmin=None, tmax=None,
 
             .. versionadded:: 0.16
         """  # noqa: E501
-        supported = ('mag', 'grad', 'eeg', 'seeg', 'ecog', 'misc', 'hbo',
-                     'hbr', 'None', 'fnirs_cw_amplitude', 'fnirs_od')
+        supported = ('mag', 'grad', 'eeg', 'seeg', 'ecog', 'misc',
+                     'None') + _FNIRS_CH_TYPES_SPLIT
         types_used = self.get_channel_types(unique=True, only_data_chs=True)
 
         _check_option('ch_type', str(ch_type), supported)
@@ -592,7 +592,7 @@ def get_peak(self, ch_type=None, tmin=None, tmax=None,
             seeg = True
         elif ch_type == 'ecog':
             ecog = True
-        elif ch_type in ('hbo', 'hbr', 'fnirs_cw_amplitude', 'fnirs_od'):
+        elif ch_type in _FNIRS_CH_TYPES_SPLIT:
             fnirs = ch_type
 
         if ch_type is not None:

diff --git a/mne/io/__init__.py b/mne/io/__init__.py
@@ -27,6 +27,7 @@
 from . import kit
 from . import nicolet
 from . import nirx
+from . import boxy
 from . import persyst
 from . import eeglab
 from . import pick
@@ -47,6 +48,7 @@
 from .eeglab import read_raw_eeglab, read_epochs_eeglab
 from .eximia import read_raw_eximia
 from .nirx import read_raw_nirx
+from .boxy import read_raw_boxy
 from .snirf import read_raw_snirf
 from .persyst import read_raw_persyst
 from .fieldtrip import (read_raw_fieldtrip, read_epochs_fieldtrip,

diff --git a/mne/io/boxy/__init__.py b/mne/io/boxy/__init__.py
@@ -0,0 +1,7 @@
+"""fNIRS module for conversion to FIF."""
+
+# Authors: Kyle Mathewson, Jonathan Kuziek <kuziek@ualberta.ca>
+#
+# License: BSD (3-clause)
+
+from .boxy import read_raw_boxy