improve

Author: h-mayorquin

doc/how_to/physical_units.rst

@@ -1,15 +1,20 @@
 Working with physical units in SpikeInterface recordings
 ========================================================
 
-In neurophysiology recordings, data is often stored in raw ADC (Analog-to-Digital Converter) units but at various points in an analysis pipeline the end-user may want to observe their data in physical units.
+In neurophysiology recordings, data is often stored in raw ADC (Analog-to-Digital Converter) integer values 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.
 
-It's important to note that **most spike sorters work fine on raw digital (ADC) units** and scaling is not needed.
+It's important to note that **most spike sorters work fine on raw digital (ADC) units** and scaling is not needed. Going a step further, some sorters, such as Kilosort 3, require their input to be in raw ADC units.
+The specific behavior however depends on the spike sorter, so it's important to understand the specific input requirements in a case per case basis.
+
 Many preprocessing tools are also linear transformations, and if the ADC is implemented as a linear transformation which is fairly common, then the overall effect can be preserved.
-That is, **preprocessing steps can often be applied either before or after unit conversion without affecting the outcome.**
+That is, **preprocessing steps can often be applied either before or after unit conversion without affecting the outcome.**. That said, there are rough edges to this approach.
+preprocessing algorithms like filtering, whitening, centering, interpolation and common reference require casting to float within the pipeline. We advise users to experiment
+with different approaches to find the best one for their specific use case.
+
 
-Therefore, **it is usually safe to work in raw ADC units unless a specific tool or analysis requires physical units**.
+Therefore, **it is usually safe to work in raw ADC integer values unless a specific tool or analysis requires physical units**.
 If you are interested in visualizations, comparability across devices, or outputs with interpretable physical scales (e.g., microvolts), converting to physical units is recommended.
 Otherwise, remaining in raw units can simplify processing and preserve performance.
 
@@ -36,13 +41,12 @@ SpikeInterface provides two preprocessing classes for converting recordings to p
 ``RecordingExtractor`` class and ensures that the data is returned in physical units when calling `get_traces <https://spikeinterface.readthedocs.io/en/stable/api.html#spikeinterface.core.BaseRecording.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 plotting
-   and analyzing functions in SpikeInterface expect data in microvolts, so this is the recommended approach for most users.
+    extracellular recordings, and this function is designed to convert the data to microvolts (µV).
 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.
+    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:
+For most users working with extracellular recordings, ``scale_to_uV`` is the recommended choice if they want to work in physical units:
 
 .. code-block:: python
 
@@ -71,7 +75,7 @@ Both preprocessors automatically:
 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
@@ -88,7 +92,7 @@ You need to set these properties for every channel, which allows for the case wh
     # Set custom physical units
     num_channels = recording.get_num_channels()
     values = ["volts"] * num_channels
-    recording.set_property(key='physical_unit', value=values)
+    recording.set_property(key='physical_unit', values=values)
 
     gain_values = [0.001] * num_channels  # Convert from ADC to volts
     recording.set_property(key='gain_to_unit', values=gain_values)  # Convert to volts

src/spikeinterface/preprocessing/scale.py

@@ -64,7 +64,7 @@ def __init__(self, recording):
         self.set_channel_offsets(offsets=0.0)
 
 
-scale_to_physical_units = define_function_handling_dict_from_class(ScaleToPhysicalUnits, "scale_to_physical_units")
+scale_to_physical_units = define_function_handling_dict_from_class(ScaleToPhysicalUnits, name="scale_to_physical_units")
 
 
 def scale_to_uV(recording: BasePreprocessor) -> BasePreprocessor: