Fixed length epochs overlap (#9096)

* Added the 'overlap' parameter to the make_fixed_length_epochs function and written the consequent test in test_epochs

* moved parameter position in function arguments and added version

* Minor fixes

* corrected the order of the parameters of make_fixed_length_epochs in docstring

* deleted extra newline in docstring

* Deleted extra space char in docstring and edited the tests to avoid preloading epochs

* Added what's new entry

* Apply suggestions from code review

Co-authored-by: Richard Höchenberger <richard.hoechenberger@gmail.com>

doc/changes/latest.inc

@@ -41,8 +41,12 @@ Current (0.23.dev0)
 
 .. |Cora Kim| replace:: **Cora Kim**
 
+.. |Silvia Cotroneo| replace:: **Silvia Cotroneo**
+
 Enhancements
 ~~~~~~~~~~~~
+- Add ``overlap`` parameter to :func:`mne.epochs.make_fixed_length_epochs` to allow creating overlapping fixed length epochs (:gh:`9096` **by new contributor** |Silvia Cotroneo|_)
+
 - Add :meth:`mne.Dipole.to_mni` for more convenient  dipole.pos to MNI conversion (:gh:`9043` **by new contributor** |Valerii Chirkov|_)
 
 - Update citations in maxwell.py (:gh:`9043` **by new contributor** |Valerii Chirkov|_)
@@ -218,4 +222,3 @@ API changes
 - ``mne.read_selection`` has been deprecated in favor of `mne.read_vectorview_selection`. ``mne.read_selection`` will be removed in MNE-Python 0.24 (:gh:`8870` by `Richard Höchenberger`_)
 
 - ``mne.beamformer.tf_dics`` has been deprecated and will be removed in MNE-Python 0.24 (:gh:`9122` by `Britta Westner`_)
-

doc/changes/names.inc

@@ -371,3 +371,5 @@
 .. _Matteo Anelli: https://github.com/matteoanelli
 
 .. _Cora Kim: https://github.com/kimcoco
+
+.. _Silvia Cotroneo: https://github.com/sfc-neuro

mne/epochs.py

@@ -3668,7 +3668,7 @@ def average_movements(epochs, head_pos=None, orig_sfreq=None, picks=None,
 
 @verbose
 def make_fixed_length_epochs(raw, duration=1., preload=False,
-                             reject_by_annotation=True, proj=True,
+                             reject_by_annotation=True, proj=True, overlap=0.,
                              verbose=None):
     """Divide continuous raw data into equal-sized consecutive epochs.
 
@@ -3685,6 +3685,11 @@ def make_fixed_length_epochs(raw, duration=1., preload=False,
     %(proj_epochs)s
 
         .. versionadded:: 0.22.0
+    overlap : float
+        The overlap between epochs, in seconds. Must be
+        ``0 <= overlap < duration``. Default is 0, i.e., no overlap.
+
+        .. versionadded:: 0.23.0
     %(verbose)s
 
     Returns
@@ -3696,7 +3701,8 @@ def make_fixed_length_epochs(raw, duration=1., preload=False,
     -----
     .. versionadded:: 0.20
     """
-    events = make_fixed_length_events(raw, 1, duration=duration)
+    events = make_fixed_length_events(raw, 1, duration=duration,
+                                      overlap=overlap)
     delta = 1. / raw.info['sfreq']
     return Epochs(raw, events, event_id=[1], tmin=0, tmax=duration - delta,
                   baseline=None, preload=preload,

mne/tests/test_epochs.py

@@ -3254,6 +3254,18 @@ def test_make_fixed_length_epochs():
     assert len(epochs_annot) > 10
     assert len(epochs) > len(epochs_annot)
 
+    # overlaps
+    epochs = make_fixed_length_epochs(raw, duration=1)
+    assert len(epochs.events) > 10
+    epochs_ol = make_fixed_length_epochs(raw, duration=1, overlap=0.5)
+    assert len(epochs_ol.events) > 20
+    epochs_ol_2 = make_fixed_length_epochs(raw, duration=1, overlap=0.9)
+    assert len(epochs_ol_2.events) > 100
+    assert_array_equal(epochs_ol_2.events[:, 0],
+                       np.unique(epochs_ol_2.events[:, 0]))
+    with pytest.raises(ValueError, match='overlap must be'):
+        make_fixed_length_epochs(raw, duration=1, overlap=1.1)
+
 
 def test_epochs_huge_events(tmpdir):
     """Test epochs with event numbers that are too large."""