zach review

Author: h-mayorquin

neo/io/neuralynxio.py

@@ -75,7 +75,7 @@ def __init__(
             detailed gap report. If a float value is provided, gaps smaller than this
             threshold (in milliseconds) are ignored, and gaps larger create new segments.
         strict_gap_mode : bool | None, default: None
-            Deprecated. Use gap_tolerance_ms instead.
+            Deprecated and will be removed in version 0.16.0. Use gap_tolerance_ms instead.
         """
 
         if filename is not None:

neo/rawio/neuralynxrawio/ncssections.py

@@ -285,7 +285,7 @@ def build_for_ncs_file(ncsMemMap, nlxHdr, gap_tolerance_us=None, **kwargs):
 
         if gapTolerance is not None:
             warnings.warn(
-                "The `gapTolerance` parameter is deprecated and will be removed in version 0.16. "
+                "The `gapTolerance` parameter is deprecated and will be removed in version 0.16.0. "
                 "Use `gap_tolerance_us` instead.",
                 DeprecationWarning,
                 stacklevel=2,
@@ -295,20 +295,23 @@ def build_for_ncs_file(ncsMemMap, nlxHdr, gap_tolerance_us=None, **kwargs):
 
         if strict_gap_mode is not None:
             warnings.warn(
-                "The `strict_gap_mode` parameter is deprecated and will be removed in version 0.16. "
+                "The `strict_gap_mode` parameter is deprecated and will be removed in version 0.16.0. "
                 "Use `gap_tolerance_us` instead.",
                 DeprecationWarning,
                 stacklevel=2,
             )
 
+        if gap_tolerance_us is not None and gap_tolerance_us < 0:
+            raise ValueError(f"`gap_tolerance_us` must be non-negative, got {gap_tolerance_us}")
+
         acqType = nlxHdr.type_of_recording()
         freq = nlxHdr["sampling_rate"]
 
         # Deprecation shim for strict_gap_mode (the boolean predecessor of gap_tolerance_us).
         # strict_gap_mode True/None already match the modern per-type defaults below; only
         # strict_gap_mode=False differed, tolerating a quarter-packet gap (PRE4 was 0 either way).
         # Translating that single case here keeps the per-type branches on gap_tolerance_us only.
-        # Remove this block when strict_gap_mode is dropped in v0.16.
+        # Remove this block when strict_gap_mode is dropped in v0.16.0.
         if gap_tolerance_us is None and strict_gap_mode is not None and not strict_gap_mode and acqType != AcqType.PRE4:
             gap_tolerance_us = round(0.25 * NcsSection._RECORD_SIZE * 1e6 / freq)
 

neo/rawio/neuralynxrawio/neuralynxrawio.py

@@ -100,7 +100,7 @@ class NeuralynxRawIO(BaseRawIO):
         Use gap_tolerance_ms=0.0 to segment on all detected gaps.
     strict_gap_mode : bool | None, default: None
         .. deprecated::
-            Use ``gap_tolerance_ms`` instead. Will be removed in version 0.16.
+            Use ``gap_tolerance_ms`` instead. Will be removed in version 0.16.0.
         If explicitly set, uses legacy gap detection behavior:
         strict_gap_mode=True uses tight tolerance (0.2 sample intervals),
         strict_gap_mode=False uses loose tolerance (quarter of 512-sample packet).
@@ -204,13 +204,18 @@ def __init__(
         else:
             self.rawmode = "one-dir"
 
+        if gap_tolerance_ms is not None and gap_tolerance_ms < 0:
+            raise ValueError(f"`gap_tolerance_ms` must be non-negative, got {gap_tolerance_ms}")
+
         # Handle gap_tolerance_ms and deprecated strict_gap_mode
         if strict_gap_mode is not None:
             warnings.warn(
-                "`strict_gap_mode` is deprecated and will be removed in version 0.16. "
-                "Use `gap_tolerance_ms` instead to control gap handling. "
+                "`strict_gap_mode` is deprecated and will be removed in version 0.16.0. "
+                "Use `gap_tolerance_ms` instead to control gap handling. The equivalent value "
+                "depends on the sampling rate: 0.2 / rate * 1000 ms reproduces strict_gap_mode=True "
+                "and 128 / rate * 1000 ms reproduces strict_gap_mode=False (at 32 kHz, 0.00625 and 4.0). "
                 "See issue #1773 for details.",
-                DeprecationWarning,
+                FutureWarning,
                 stacklevel=2,
             )
             if gap_tolerance_ms is not None:

neo/test/rawiotest/test_neuralynxrawio.py

@@ -287,21 +287,29 @@ def test_gap_tolerance_ms_large_tolerance(self):
         rawio.parse_header()
         self.assertEqual(rawio._nb_segment, 1)
 
+    def test_negative_gap_tolerance_ms_raises(self):
+        """A negative tolerance would treat every record as a gap, so it is rejected up front."""
+        with self.assertRaises(ValueError):
+            NeuralynxRawIO(
+                self.get_local_path("neuralynx/Cheetah_v5.5.1/original_data"),
+                gap_tolerance_ms=-10.0,
+            )
+
     def test_no_gaps_no_error(self):
         """Test that datasets without gaps load fine without gap_tolerance_ms."""
         rawio = NeuralynxRawIO(self.get_local_path("neuralynx/Cheetah_v4.0.2/original_data"))
         rawio.parse_header()
         self.assertEqual(rawio._nb_segment, 1)
 
     def test_strict_gap_mode_deprecation(self):
-        """Test that strict_gap_mode emits DeprecationWarning."""
-        with self.assertWarns(DeprecationWarning):
+        """Test that strict_gap_mode emits FutureWarning."""
+        with self.assertWarns(FutureWarning):
             rawio = NeuralynxRawIO(
                 self.get_local_path("neuralynx/BML/original_data"),
                 strict_gap_mode=True,
             )
 
-        with self.assertWarns(DeprecationWarning):
+        with self.assertWarns(FutureWarning):
             rawio = NeuralynxRawIO(
                 self.get_local_path("neuralynx/BML/original_data"),
                 strict_gap_mode=False,
@@ -310,7 +318,7 @@ def test_strict_gap_mode_deprecation(self):
     def test_strict_gap_mode_legacy_behavior(self):
         """Test that strict_gap_mode still works for backward compatibility."""
         # strict_gap_mode=True should segment like gap_tolerance_ms=0.0
-        with self.assertWarns(DeprecationWarning):
+        with self.assertWarns(FutureWarning):
             rawio = NeuralynxRawIO(
                 self.get_local_path("neuralynx/Cheetah_v5.5.1/original_data"),
                 strict_gap_mode=True,
@@ -320,7 +328,7 @@ def test_strict_gap_mode_legacy_behavior(self):
 
     def test_strict_gap_mode_false_legacy_behavior(self):
         """The deprecated strict_gap_mode=False (lenient) path still loads, warns, and segments."""
-        with self.assertWarns(DeprecationWarning):
+        with self.assertWarns(FutureWarning):
             rawio = NeuralynxRawIO(
                 self.get_local_path("neuralynx/Cheetah_v5.5.1/original_data"),
                 strict_gap_mode=False,