DOC: document first_samp behavior after crop and RawArray workaround (#13685)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: Famous077

doc/changes/dev/13685.other.rst

@@ -0,0 +1 @@
+Document the behavior of :term:`first_samp` after :meth:`~mne.io.Raw.crop` and add ``reset_first_samp`` parameter to reset it to 0 after cropping, by :newcontrib:`Famous077`.

mne/io/base.py

@@ -1568,7 +1568,15 @@ def rescale(self, scalings, *, verbose=None):
         return self
 
     @verbose
-    def crop(self, tmin=0.0, tmax=None, include_tmax=True, *, verbose=None):
+    def crop(
+        self,
+        tmin=0.0,
+        tmax=None,
+        include_tmax=True,
+        *,
+        reset_first_samp=False,
+        verbose=None,
+    ):
         """Crop raw data file.
 
         Limit the data from the raw file to go between specific times. Note
@@ -1585,12 +1593,51 @@ def crop(self, tmin=0.0, tmax=None, include_tmax=True, *, verbose=None):
         %(tmin_raw)s
         %(tmax_raw)s
         %(include_tmax)s
+        reset_first_samp : bool
+            If True, reset :term:`first_samp` to 0 after cropping, treating
+            the cropped segment as an independent recording. Note that this
+            can break things if you extracted events before cropping and try
+            to use them afterward. Default is False.
+
+            .. versionadded:: 1.12
         %(verbose)s
 
         Returns
         -------
         raw : instance of Raw
             The cropped raw object, modified in-place.
+
+        Notes
+        -----
+        After cropping, :term:`first_samp` is updated to reflect the new
+        start of the data, preserving the original recording timeline.
+        This means ``raw.times`` will still start at ``0.0``, but
+        ``raw.first_samp`` will reflect the offset from the original
+        recording. If you want to treat the cropped segment as an
+        independent signal with ``first_samp=0``, you can convert it
+        to a :class:`~mne.io.RawArray`::
+
+            raw_array = mne.io.RawArray(raw.get_data(), raw.info)
+
+        Examples
+        --------
+        By default, cropping preserves the original recording timeline,
+        so :term:`first_samp` remains non-zero after cropping::
+
+            >>> raw = mne.io.read_raw_fif(fname)  # doctest: +SKIP
+            >>> print(raw.first_samp)  # doctest: +SKIP
+            25800
+            >>> raw.crop(tmin=10, tmax=20)  # doctest: +SKIP
+            >>> print(raw.first_samp)  # doctest: +SKIP
+            27810
+
+        If you want to treat the cropped segment as an independent
+        recording, use ``reset_first_samp=True``::
+
+            >>> raw2 = raw.copy().crop(tmin=10, tmax=20,
+            ...                        reset_first_samp=True)  # doctest: +SKIP
+            >>> print(raw2.first_samp)  # doctest: +SKIP
+            0
         """
         max_time = (self.n_times - 1) / self.info["sfreq"]
         if tmax is None:
@@ -1648,7 +1695,11 @@ def crop(self, tmin=0.0, tmax=None, include_tmax=True, *, verbose=None):
             # set_annotations will put it back.
             annotations.onset -= self.first_time
         self.set_annotations(annotations, False)
-
+        if reset_first_samp:
+            delta = self._first_samps[0]
+            self._first_samps -= delta
+            self._last_samps -= delta
+            self._cropped_samp -= delta
         return self
 
     @verbose

mne/io/tests/test_raw.py

@@ -1087,3 +1087,23 @@ def test_rescale():
     orig = raw.get_data()
     raw.rescale(4)  # a scalar works
     assert_allclose(raw.get_data(), orig * 4)
+
+
+def test_crop_reset_first_samp():
+    """Regression test for GH-13278.
+
+    crop(reset_first_samp=True) must reset first_samp to 0.
+    """
+    info = create_info(ch_names=["CH1"], sfreq=1000.0, ch_types=["eeg"])
+    data = np.zeros((1, 10000))
+    raw = RawArray(data, info)
+
+    # crop and reset first_samp
+    raw.crop(tmin=2.0, tmax=5.0, reset_first_samp=True)
+    assert raw.first_samp == 0
+    assert raw.times[0] == 0.0
+
+    # crop without reset_first_samp (default behaviour)
+    raw2 = RawArray(data, info)
+    raw2.crop(tmin=2.0, tmax=5.0)
+    assert raw2.first_samp != 0