Add documentation to handle (physical) units of recording channels

doc/how_to/index.rst

@@ -17,3 +17,4 @@ Guides on how to solve specific, short problems in SpikeInterface. Learn how to.
     drift_with_lfp
     auto_curation_training
     auto_curation_prediction
+    physical_units

doc/how_to/physical_units.rst

@@ -0,0 +1,96 @@
+Working with Units in SpikeInterface Recordings
+===============================================
+
+In neurophysiology recordings, data is often stored in raw ADC (Analog-to-Digital Converter) units
+but needs to be analyzed in physical units. For extracellular recordings, this is typically microvolts (µV),
+but some recording devices may use different physical units. SpikeInterface provides tools to handle both
+situations.
+
+Understanding Physical Units
+----------------------------
+
+Most recording devices store data in ADC units (integers) to save space and preserve the raw data.
+To convert these values to physical units, two parameters are needed:
+
+* **gain**: A multiplicative factor to scale the raw values
+* **offset**: An additive factor to shift the values
+
+The conversion formula is:
+
+.. code-block:: text
+
+    physical_value = raw_value * gain + offset
+
+
+Converting to Physical Units
+-------------------------
+
+SpikeInterface provides two preprocessing classes for converting recordings to physical units. Both wrap the
+``RecordingExtractor`` class and ensures that the data is returned in physical units when calling get_traces()
+
+1. ``scale_to_uV``: The primary function for extracellular recordings. SpikeInterface is centered around
+   extracellular recordings, and this function is designed to convert the data to microvolts (µV). Many plottinf
+   and analyzing functions in SpikeInterface expect data in microvolts, so this is the recommended approach for most users.
+2. ``scale_to_physical_units``: A general function for any physical unit conversion. This will allow you to extract the data in any
+   physical unit, not just microvolts. This is useful for other types of recordings, such as force measurements in Newtons but should be
+   handled with care.
+
+For most users working with extracellular recordings, ``scale_to_uV`` is the recommended choice:
+
+.. code-block:: python
+
+    from spikeinterface.extractors import read_intan
+    from spikeinterface.preprocessing import scale_to_uV
+
+    # Load recording (data is in ADC units)
+    recording = read_intan("path/to/file.rhs")
+
+    # Convert to microvolts
+    recording_uv = scale_to_uV(recording)
+
+For recordings with non-standard units (e.g., force measurements in Newtons), use ``scale_to_physical_units``:
+
+.. code-block:: python
+
+    from spikeinterface.preprocessing import scale_to_physical_units
+
+    # Convert to physical units (whatever they may be)
+    recording_physical = scale_to_physical_units(recording)
+
+Both preprocessors automatically:
+
+1. Detect the appropriate gain and offset from the recording properties
+2. Apply the conversion to all channels
+3. Update the recording properties to reflect that data is now in physical units
+
+Setting Custom Physical Units
+---------------------------
+
+While most extractors automatically set the appropriate ``gain_to_uV`` and ``offset_to_uV`` values,
+there might be cases where you want to set custom physical units. In these cases, you can set
+the following properties:
+
+* ``physical_unit``: The target physical unit (e.g., 'uV', 'mV', 'N')
+* ``gain_to_unit``: The gain to convert from raw values to the target unit
+* ``offset_to_unit``: The offset to convert from raw values to the target unit
+
+Here's an example of how to set custom units:
+
+.. code-block:: python
+
+    # Set custom physical units
+    num_channels = recording.get_num_channels()
+    values = ["volts"] * num_channels
+    recording.set_property(key='physical_unit', value=values)
+
+    values = [0.001] * num_channels  # Convert from ADC to volts
+    recording.set_property(key='gain_to_unit', values=values)  # Convert to volts
+
+    values = [0] * num_channels  # No offset
+    recording.set_property(key='offset_to_unit', values=values)  # No offset
+
+    # Apply the conversion using scale_to_physical_units
+    recording_physical = scale_to_physical_units(recording)
+
+This approach gives you full control over the unit conversion process while maintaining
+compatibility with SpikeInterface's preprocessing pipeline.

src/spikeinterface/core/baserecording.py

@@ -20,7 +20,15 @@ class BaseRecording(BaseRecordingSnippets):
     """
 
     _main_annotations = BaseRecordingSnippets._main_annotations + ["is_filtered"]
-    _main_properties = ["group", "location", "gain_to_uV", "offset_to_uV"]
+    _main_properties = [
+        "group",
+        "location",
+        "gain_to_uV",
+        "offset_to_uV",
+        "gain_to_physical_unit",
+        "offset_to_physical_unit",
+        "physical_unit",
+    ]
     _main_features = []  # recording do not handle features
 
     _skip_properties = [

src/spikeinterface/preprocessing/preprocessinglist.py

@@ -25,7 +25,7 @@
     CenterRecording,
     center,
 )
-from .scale import scale_to_uV
+from .scale import scale_to_uV, scale_to_physical_units
 
 from .whiten import WhitenRecording, whiten, compute_whitening_matrix
 from .rectify import RectifyRecording, rectify

src/spikeinterface/preprocessing/scale.py

@@ -6,6 +6,55 @@
 from spikeinterface.preprocessing.basepreprocessor import BasePreprocessor
 
 
+def scale_to_physical_units(recording: BasePreprocessor) -> BasePreprocessor:
+    """
+    Scale raw traces to their physical units using gain_to_physical_unit and offset_to_physical_unit.
+
+    This preprocessor uses the channel-specific gain and offset information
+    stored in the recording extractor to convert the raw traces to their physical units.
+    Most commonly this will be microvolts (µV) for voltage recordings, but some extractors
+    might use different physical units (e.g., Newtons for force measurements).
+
+    Parameters
+    ----------
+    recording : BaseRecording
+        The recording extractor to be scaled. The recording extractor must
+        have gain_to_physical_unit and offset_to_physical_unit properties set.
+
+    Returns
+    -------
+    BasePreprocessor
+        The recording with traces scaled to physical units.
+
+    Raises
+    ------
+    ValueError
+        If the recording extractor does not have gain_to_physical_unit and offset_to_physical_unit properties.
+    """
+    # To avoid a circular import
+    from spikeinterface.preprocessing import ScaleRecording
+
+    if "gain_to_physical_unit" not in recording.get_property_keys():
+        raise ValueError("Recording must have 'gain_to_physical_unit' property to convert to physical units")
+    if "offset_to_physical_unit" not in recording.get_property_keys():
+        raise ValueError("Recording must have 'offset_to_physical_unit' property to convert to physical units")
+
+    gain = recording.get_property("gain_to_physical_unit")
+    offset = recording.get_property("offset_to_physical_unit")
+
+    scaled_recording = ScaleRecording(recording, gain=gain, offset=offset)
+
+    # Reset gain/offset since data is now in physical units
+    scaled_recording.set_property(
+        key="gain_to_physical_unit", values=np.ones(recording.get_num_channels(), dtype="float32")
+    )
+    scaled_recording.set_property(
+        key="offset_to_physical_unit", values=np.zeros(recording.get_num_channels(), dtype="float32")
+    )
+
+    return scaled_recording
+
+
 def scale_to_uV(recording: BasePreprocessor) -> BasePreprocessor:
     """
     Scale raw traces to microvolts (µV).

src/spikeinterface/preprocessing/tests/test_scaling.py

@@ -1,7 +1,7 @@
 import pytest
 import numpy as np
 from spikeinterface.core.testing_tools import generate_recording
-from spikeinterface.preprocessing import scale_to_uV, CenterRecording
+from spikeinterface.preprocessing import scale_to_uV, CenterRecording, scale_to_physical_units
 
 
 def test_scale_to_uV():
@@ -70,6 +70,48 @@ def test_scaling_in_preprocessing_chain():
     np.testing.assert_allclose(traces_scaled_with_preprocessor, traces_scaled_with_preprocessor_and_argument)
 
 
+def test_scale_to_physical_units():
+    # Create a sample recording extractor with fake physical unit gains and offsets
+    num_channels = 4
+    sampling_frequency = 30_000.0
+    durations = [1.0]  # seconds
+    recording = generate_recording(
+        num_channels=num_channels,
+        durations=durations,
+        sampling_frequency=sampling_frequency,
+    )
+
+    rng = np.random.default_rng(0)
+    gains = rng.random(size=(num_channels)).astype(np.float32)
+    offsets = rng.random(size=(num_channels)).astype(np.float32)
+
+    # Set physical unit gains/offsets instead of regular gains/offsets
+    recording.set_property("gain_to_physical_unit", gains)
+    recording.set_property("offset_to_physical_unit", offsets)
+
+    # Apply the preprocessor
+    scaled_recording = scale_to_physical_units(recording=recording)
+
+    # Get raw traces and apply scaling manually
+    raw_traces = recording.get_traces(segment_index=0)
+    expected_traces = raw_traces * gains + offsets
+
+    # Get scaled traces
+    scaled_traces = scaled_recording.get_traces(segment_index=0)
+
+    # Check if the traces are scaled correctly
+    np.testing.assert_allclose(scaled_traces, expected_traces)
+
+    # Test for the error when recording doesn't have physical unit properties
+    recording_no_gains = generate_recording(
+        num_channels=num_channels,
+        durations=durations,
+        sampling_frequency=sampling_frequency,
+    )
+    with pytest.raises(ValueError):
+        scale_to_physical_units(recording_no_gains)
+
+
 if __name__ == "__main__":
     test_scale_to_uV()
     test_scaling_in_preprocessing_chain()