Merge pull request #2320 from zm711/get_traces-fixes

Fix for docstring of `get_traces`

doc/modules/core.rst

@@ -92,6 +92,11 @@ with 16 channels:
     timestamps = np.arange(num_samples) / sampling_frequency + 300
     recording.set_times(timestamps, segment_index=0)
 
+**Note**:
+Raw data formats often store data as integer values for memory efficiency. To give these integers meaningful physical units (uV), you can apply a gain and an offset.
+Many devices have their own gains and offsets necessary to convert their data and these values are handled by SpikeInterface for its extractors. This
+is triggered by the :code:`return_scaled` parameter in :code:`get_traces()`, (see above example), which will return the traces in uV.
+
 
 Sorting
 -------

examples/modules_gallery/extractors/plot_2_working_with_unscaled_traces.py

@@ -56,8 +56,8 @@
 # With gain and offset information, we can retrieve traces both in their unscaled (raw) type, and in their scaled
 # type:
 
-traces_unscaled = recording.get_traces(return_scaled=False)
-traces_scaled = recording.get_traces(return_scaled=True)  # return_scaled is True by default
+traces_unscaled = recording.get_traces(return_scaled=False) # return_scaled is False by default
+traces_scaled = recording.get_traces(return_scaled=True)
 
 print(f"Traces dtype after scaling: {traces_scaled.dtype}")
 

src/spikeinterface/core/baserecording.py

@@ -1,6 +1,6 @@
+from __future__ import annotations
 import warnings
 from pathlib import Path
-from typing import Iterable, List, Union
 from warnings import warn
 
 import numpy as np
@@ -36,12 +36,12 @@ class BaseRecording(BaseRecordingSnippets):
         "noise_level_mad_scaled",
     ]
 
-    def __init__(self, sampling_frequency: float, channel_ids: List, dtype):
+    def __init__(self, sampling_frequency: float, channel_ids: list, dtype):
         BaseRecordingSnippets.__init__(
             self, channel_ids=channel_ids, sampling_frequency=sampling_frequency, dtype=dtype
         )
 
-        self._recording_segments: List[BaseRecordingSegment] = []
+        self._recording_segments: list[BaseRecordingSegment] = []
 
         # initialize main annotation and properties
         self.annotate(is_filtered=False)
@@ -242,34 +242,34 @@ def get_total_memory_size(self) -> int:
 
     def get_traces(
         self,
-        segment_index: Union[int, None] = None,
-        start_frame: Union[int, None] = None,
-        end_frame: Union[int, None] = None,
-        channel_ids: Union[Iterable, None] = None,
-        order: Union[str, None] = None,
-        return_scaled=False,
-        cast_unsigned=False,
+        segment_index: int | None = None,
+        start_frame: int | None = None,
+        end_frame: int | None = None,
+        channel_ids: list | np.array | tuple | None = None,
+        order: "C" | "F" | None = None,
+        return_scaled: bool = False,
+        cast_unsigned: bool = False,
     ):
         """Returns traces from recording.
 
         Parameters
         ----------
-        segment_index : Union[int, None], default: None
+        segment_index : int | None, default: None
             The segment index to get traces from. If recording is multi-segment, it is required, default: None
-        start_frame : Union[int, None], default: None
+        start_frame : int | None, default: None
             The start frame. If None, 0 is used, default: None
-        end_frame : Union[int, None], default: None
+        end_frame : int | None, default: None
             The end frame. If None, the number of samples in the segment is used, default: None
-        channel_ids : Union[Iterable, None], default: None
+        channel_ids : list | np.array | tuple | None, default: None
             The channel ids. If None, all channels are used, default: None
-        order : Union[str, None], default: None
-            The order of the traces ("C" | "F"). If None, traces are returned as they are, default: None
-        return_scaled : bool, default: None
+        order : "C" | "F" | None, default: None
+            The order of the traces ("C" | "F"). If None, traces are returned as they are
+        return_scaled : bool, default: False
             If True and the recording has scaling (gain_to_uV and offset_to_uV properties),
-            traces are scaled to uV, default: False
-        cast_unsigned : bool, default: None
+            traces are scaled to uV
+        cast_unsigned : bool, default: False
             If True and the traces are unsigned, they are cast to integer and centered
-            (an offset of (2**nbits) is subtracted), default: False
+            (an offset of (2**nbits) is subtracted)
 
         Returns
         -------
@@ -321,7 +321,7 @@ def get_traces(
                 traces = traces.astype("float32", copy=False) * gains + offsets
         return traces
 
-    def has_scaled_traces(self):
+    def has_scaled_traces(self) -> bool:
         """Checks if the recording has scaled traces
 
         Returns
@@ -613,9 +613,9 @@ def _select_segments(self, segment_indices):
 
         return SelectSegmentRecording(self, segment_indices=segment_indices)
 
-    def is_binary_compatible(self):
+    def is_binary_compatible(self) -> bool:
         """
-        Inform is this recording is "binary" compatible.
+        Checks if the recording is "binary" compatible.
         To be used before calling `rec.get_binary_description()`
 
         Returns
@@ -766,24 +766,21 @@ def get_num_samples(self) -> int:
 
     def get_traces(
         self,
-        start_frame: Union[int, None] = None,
-        end_frame: Union[int, None] = None,
-        channel_indices: Union[List, None] = None,
+        start_frame: int | None = None,
+        end_frame: int | None = None,
+        channel_indices: list | np.array | tuple | None = None,
     ) -> np.ndarray:
         """
         Return the raw traces, optionally for a subset of samples and/or channels
 
         Parameters
         ----------
-        start_frame: Union[int, None], default: None
+        start_frame: int | None, default: None
             start sample index, or zero if None
-        end_frame: Union[int, None], default: None
+        end_frame: int | None, default: None
             end_sample, or number of samples if None
-        channel_indices: Union[List, None], default: None
+        channel_indices: list | np.array | tuple | None, default: None
             Indices of channels to return, or all channels if None
-        order: list or None, default: None
-            The memory order of the returned array.
-            Use Order.C for C order, Order.F for Fortran order, or Order.K to keep the order of the underlying data
 
         Returns
         -------