MRG: Add helper functions for label data (#5805)

* ENH: Add helper functions for label data

* FIX: Reqs

* FIX: Coverage

* FIX: Backport

* STY: Comment [ci skip]

* FIX: Fix fixes more

* FIX: More doc cleanups

* DOC: See also

* FIX: Dont need

* FIX: Flake

* FIX: Axis

Author: larsoner

doc/python_reference.rst

@@ -689,6 +689,8 @@ Source Space Data
    grade_to_vertices
    grow_labels
    label_sign_flip
+   labels_to_stc
+   morph_labels
    random_parcellation
    read_labels_from_annot
    read_dipole

doc/whats_new.rst

@@ -31,6 +31,11 @@ Changelog
 
 - Add use of :func:`scipy.signal.windows.dpss` for faster multitaper window computations in PSD functions by `Eric Larson`_
 
+- Add :func:`mne.morph_labels` to facilitate morphing label sets obtained from parcellations, by `Eric Larson`_
+
+- Add :func:`mne.labels_to_stc` to facilitate working with label data, by `Eric Larson`_
+
+- Add ``overlap`` argument to :func:`mne.make_fixed_length_events` by `Eric Larson`_
 - Add 448-labels subdivided aparc cortical parcellation by `Denis Engemann`_ and `Sheraz Khan`_
 
 - Add keyboard shortcuts to nativate volume source estimates in time using (shift+)left/right arrow keys by `Mainak Jas`_
@@ -3127,4 +3132,4 @@ of commits):
 
 .. _David Haslacher: https://github.com/davidhaslacher
 
-.. _lneisenman:  https://github.com/lneisenman
+.. _lneisenman:  https://github.com/lneisenman

mne/__init__.py

@@ -75,7 +75,8 @@
 from .evoked import Evoked, EvokedArray, read_evokeds, write_evokeds, combine_evoked
 from .label import (read_label, label_sign_flip,
                     write_label, stc_to_label, grow_labels, Label, split_label,
-                    BiHemiLabel, read_labels_from_annot, write_labels_to_annot, random_parcellation)
+                    BiHemiLabel, read_labels_from_annot, write_labels_to_annot,
+                    random_parcellation, morph_labels, labels_to_stc)
 from .misc import parse_config, read_reject_parameters
 from .coreg import (create_default_subject, scale_bem, scale_mri, scale_labels,
                     scale_source_space)

mne/event.py

@@ -824,7 +824,7 @@ def shift_time_events(events, ids, tshift, sfreq):
 
 
 def make_fixed_length_events(raw, id=1, start=0, stop=None, duration=1.,
-                             first_samp=True):
+                             first_samp=True, overlap=0.):
     """Make a set of events separated by a fixed duration.
 
     Parameters
@@ -846,6 +846,10 @@ def make_fixed_length_events(raw, id=1, start=0, stop=None, duration=1.,
         returned events will be combined with event times that already
         have ``raw.first_samp`` added to them, e.g. event times that come
         from :func:`mne.find_events`.
+    overlap : float
+        The overlap between events. Must be ``0 <= overlap < duration``.
+
+        .. versionadded:: 0.18
 
     Returns
     -------
@@ -856,6 +860,11 @@ def make_fixed_length_events(raw, id=1, start=0, stop=None, duration=1.,
     _validate_type(raw, BaseRaw, "raw")
     _validate_type(id, int, "id")
     _validate_type(duration, "numeric", "duration")
+    _validate_type(overlap, "numeric", "overlap")
+    duration, overlap = float(duration), float(overlap)
+    if not 0 <= overlap < duration:
+        raise ValueError('overlap must be >=0 but < duration (%s), got %s'
+                         % (duration, overlap))
 
     start = raw.time_as_index(start, use_rounding=True)[0]
     if stop is not None:
@@ -870,7 +879,8 @@ def make_fixed_length_events(raw, id=1, start=0, stop=None, duration=1.,
     # Make sure we don't go out the end of the file:
     stop -= int(np.round(raw.info['sfreq'] * duration))
     # This should be inclusive due to how we generally use start and stop...
-    ts = np.arange(start, stop + 1, raw.info['sfreq'] * duration).astype(int)
+    ts = np.arange(start, stop + 1,
+                   raw.info['sfreq'] * (duration - overlap)).astype(int)
     n_events = len(ts)
     if n_events == 0:
         raise ValueError('No events produced, check the values of start, '

mne/fixes.py

@@ -1065,6 +1065,66 @@ def _remove_duplicate_rows(arr):
         return arr[~remove, :]
 
 
+###############################################################################
+# csr_matrix.argmax from SciPy 0.19+
+
+def _find_missing_index(ind, n):
+    for k, a in enumerate(ind):
+        if k != a:
+            return k
+
+    k += 1
+    if k < n:
+        return k
+    else:
+        return -1
+
+
+def _sparse_argmax(mat, axis):
+    import scipy
+    if LooseVersion(scipy.__version__) >= '0.19':
+        return mat.argmax(axis)
+    else:
+        op = np.argmax
+        compare = np.greater
+        self = mat
+        if self.shape[axis] == 0:
+            raise ValueError("Can't apply the operation along a zero-sized "
+                             "dimension.")
+
+        if axis < 0:
+            axis += 2
+
+        zero = self.dtype.type(0)
+
+        mat = self.tocsc() if axis == 0 else self.tocsr()
+        mat.sum_duplicates()
+
+        ret_size, line_size = mat._swap(mat.shape)
+        ret = np.zeros(ret_size, dtype=int)
+
+        nz_lines, = np.nonzero(np.diff(mat.indptr))
+        for i in nz_lines:
+            p, q = mat.indptr[i:i + 2]
+            data = mat.data[p:q]
+            indices = mat.indices[p:q]
+            am = op(data)
+            m = data[am]
+            if compare(m, zero) or q - p == line_size:
+                ret[i] = indices[am]
+            else:
+                zero_ind = _find_missing_index(indices, line_size)
+                if m == zero:
+                    ret[i] = min(am, zero_ind)
+                else:
+                    ret[i] = zero_ind
+
+        if axis == 1:
+            ret = ret.reshape(-1, 1)
+
+        return np.asmatrix(ret)
+
+
 ###############################################################################
 # From nilearn