Merge pull request #3860 from fededagos/feature/3d_acg

Add "3D Auto-correlograms" (3D ACGs) postprocessing extension

Author: alejoe91

doc/api.rst

@@ -215,6 +215,7 @@ spikeinterface.postprocessing
     .. autofunction:: compute_spike_locations
     .. autofunction:: compute_template_similarity
     .. autofunction:: compute_correlograms
+    .. autofunction:: compute_acgs_3d
     .. autofunction:: compute_isi_histograms
     .. autofunction:: get_template_metric_names
     .. autofunction:: align_sorting

doc/modules/postprocessing.rst

@@ -358,6 +358,26 @@ with shape (num_units, num_units, num_bins) with all correlograms for each pair
 For more information, see :py:func:`~spikeinterface.postprocessing.compute_correlograms`
 
 
+acgs_3d
+^^^^^^^
+
+This extension computes the 3D Autocorrelograms (3D-ACG) from units' spike times to analyze how a neuron's temporal
+firing pattern varies with its firing rate. The 3D-ACG, described in [Beau]_ et al., 2025, provides rich
+representations of a unit's spike train statistics while accounting for firing rate modulations.
+
+.. code-block:: python
+
+    acg3d = sorting_analyzer.compute(
+        input="acgs_3d",
+        window_ms=50.0,
+        bin_ms=1.0,
+        num_firing_rate_quantiles=10,
+        smoothing_factor=250,
+    )
+
+For more information, see :py:func:`~spikeinterface.postprocessing.compute_acgs_3d`
+
+
 isi_histograms
 ^^^^^^^^^^^^^^
 

doc/references.rst

@@ -44,6 +44,11 @@ please include the appropriate citation for the :code:`sorter_name` parameter yo
 - :code:`wavclus` [Chaure]_
 - :code:`yass` [Lee]_
 
+Postprocessing Module
+---------------------
+
+If you use the :code:`acgs_3d` extensions, (i.e. :code:`postprocessing.compute_acgs_3d`, :code:`postprocessing.ComputeACG3D`) please cite [Beau]_
+
 Qualitymetrics Module
 ---------------------
 If you use the :code:`qualitymetrics` module, i.e. you use the :code:`analyzer.compute()`
@@ -76,6 +81,8 @@ If you use the :code:`get_potential_auto_merge` method from the curation module,
 References
 ----------
 
+.. [Beau] `A deep learning strategy to identify cell types across species from high-density extracellular recordings. 2025. <https://doi.org/10.1016/j.cell.2025.01.041>`_
+
 .. [Buccino] `SpikeInterface, a unified framework for spike sorting. 2020. <https://pubmed.ncbi.nlm.nih.gov/33170122/>`_
 
 .. [Buzsáki] `The Log-Dynamic Brain: How Skewed Distributions Affect Network Operations. 2014. <https://pubmed.ncbi.nlm.nih.gov/24569488/>`_
@@ -112,6 +119,8 @@ References
 
 .. [Niediek] `Reliable Analysis of Single-Unit Recordings from the Human Brain under Noisy Conditions: Tracking Neurons over Hours. 2016. <https://pubmed.ncbi.nlm.nih.gov/27930664/>`_
 
+.. [npyx] `NeuroPyxels: loading, processing and plotting Neuropixels data in python. 2021. <https://doi.org/10.5281/zenodo.5509776>_`
+
 .. [Pachitariu] `Spike sorting with Kilosort4. 2024. <https://pubmed.ncbi.nlm.nih.gov/38589517/>`_
 
 .. [Pouzat] `Using noise signature to optimize spike-sorting and to assess neuronal classification quality. 2002. <https://pubmed.ncbi.nlm.nih.gov/12535763/>`_

src/spikeinterface/postprocessing/__init__.py

@@ -19,7 +19,9 @@
 from .spike_amplitudes import compute_spike_amplitudes, ComputeSpikeAmplitudes
 
 from .correlograms import (
+    ComputeACG3D,
     ComputeCorrelograms,
+    compute_acgs_3d,
     compute_correlograms,
     correlogram_for_one_segment,
 )