Merge pull request #4184 from alejoe91/np-adc-sample-order

Update `get_neuropixels_sample_shifts_from_probe` to use `adc_sample_order`

Author: chrishalcrow

src/spikeinterface/extractors/neuropixels_utils.py

@@ -24,17 +24,17 @@ def get_neuropixels_sample_shifts_from_probe(probe: Probe, stream_name: str = "a
     sample_shifts : np.ndarray
         Array of relative phase shifts for each channel.
     """
-    # get inter-sample shifts based on the probe information and mux channels
-    model_description = probe.annotations.get("description", None)
+    # get inter-sample shifts based on the probe information and ADC sampling pattern
     num_channels_per_adc = probe.annotations.get("num_channels_per_adc", None)
-    mux_channels = probe.contact_annotations.get("mux_channels", None)
-    num_readouts_channels = probe.annotations.get("num_readout_channels", None)
+    adc_sample_order = probe.contact_annotations.get("adc_sample_order", None)
+    ap_sample_frequency_hz = probe.annotations.get("ap_sample_frequency_hz", None)
+    lf_sample_frequency_hz = probe.annotations.get("lf_sample_frequency_hz", None)
 
     if (
-        model_description is None
-        or num_channels_per_adc is None
-        or mux_channels is None
-        or num_readouts_channels is None
+        num_channels_per_adc is None
+        or adc_sample_order is None
+        or ap_sample_frequency_hz is None
+        or lf_sample_frequency_hz is None
     ):
         warning_message = (
             "Unable to find inter-sample shifts in the Neuropixels probe metadata. "
@@ -43,17 +43,18 @@ def get_neuropixels_sample_shifts_from_probe(probe: Probe, stream_name: str = "a
         warnings.warn(warning_message, UserWarning, stacklevel=2)
         return None
 
-    if "2.0" in model_description:
-        # for Neuropixels 2.0 (and newer), the number of cycles in ADC is equal to the number of channels per ADC
-        num_cycles_in_adc = num_channels_per_adc
-    else:
-        # for Neuropixels 1.0 technology, the number of cycles for the AP stream is +1 because
-        # the last cycle is used for the LFP stream
-        num_cycles_in_adc = num_channels_per_adc + 1 if "ap" in stream_name.lower() else num_channels_per_adc
+    # The number of cycles is determined by the number of channels per ADC times 1 + the ratio
+    # between the lf and ap sample rate.
+    # For NP 1.0, this gives 13 cycles: 12 * (1 + 2500 / 30000) = 13
+    # For NP 2.0, the lf sample rate is 0 and so the number of cycles is equal to the number of
+    # channels per ADC.
+    # see: https://github.com/billkarsh/ProbeTable/issues/3#issuecomment-3438263027
+    num_cycles_in_adc = int(num_channels_per_adc * (1 + lf_sample_frequency_hz / ap_sample_frequency_hz))
 
-    sample_shifts = np.zeros_like(mux_channels, dtype=float)
-    for mux_channel in mux_channels:
-        sample_shifts[mux_channels == mux_channel] = np.arange(num_channels_per_adc) / num_cycles_in_adc
+    # The inter-sample shifts are given by the adc sample order divided by the number of cycles in ADC
+    # This makes sure we also handle cases where only a subset of channels are recorded
+    # see: https://github.com/SpikeInterface/spikeinterface/issues/4144
+    sample_shifts = adc_sample_order / num_cycles_in_adc
 
     return sample_shifts
 
@@ -157,7 +158,7 @@ def get_neuropixels_channel_groups(num_channels=384, num_channels_per_adc=12):
     """
     warnings.warn(
         "`get_neuropixels_channel_groups` is deprecated and will be removed in 0.104.0. "
-        "Use the `mux_channels` contact annotation from the `Probe` instead.",
+        "Use the `adc_group` contact annotation from the `Probe` instead.",
         DeprecationWarning,
         stacklevel=2,
     )