Merge pull request #1981 from alejoe91/additional-quality-metrics

Additional quality metrics

doc/modules/qualitymetrics.rst

@@ -25,9 +25,11 @@ For more details about each metric and it's availability and use within SpikeInt
   :glob:
 
   qualitymetrics/amplitude_cutoff
+  qualitymetrics/amplitude_cv
   qualitymetrics/amplitude_median
   qualitymetrics/d_prime
   qualitymetrics/drift
+  qualitymetrics/firing_range
   qualitymetrics/firing_rate
   qualitymetrics/isi_violations
   qualitymetrics/isolation_distance

doc/modules/qualitymetrics/amplitude_cutoff.rst

@@ -21,12 +21,12 @@ Example code
 
 .. code-block:: python
 
-	import spikeinterface.qualitymetrics as qm
+	import spikeinterface.qualitymetrics as sqm
 
 	# It is also recommended to run `compute_spike_amplitudes(wvf_extractor)`
 	# in order to use amplitudes from all spikes
-	fraction_missing = qm.compute_amplitude_cutoffs(wvf_extractor, peak_sign="neg")
-	# fraction_missing is a dict containing the units' IDs as keys,
+	fraction_missing = sqm.compute_amplitude_cutoffs(wvf_extractor, peak_sign="neg")
+	# fraction_missing is a dict containing the unit IDs as keys,
 	# and their estimated fraction of missing spikes as values.
 
 Reference

doc/modules/qualitymetrics/amplitude_cv.rst

@@ -0,0 +1,55 @@
+Amplitude CV (:code:`amplitude_cv_median`, :code:`amplitude_cv_range`)
+======================================================================
+
+
+Calculation
+-----------
+
+The amplitude CV (coefficient of variation) is a measure of the amplitude variability.
+It is computed as the ratio between the standard deviation and the amplitude mean.
+To obtain a better estimate of this measure, it is first computed separately for several temporal bins.
+Out of these values, the median and the range (percentile distance, by default between the
+5th and 95th percentiles) are computed.
+
+The computation requires either spike amplitudes (see :py:func:`~spikeinterface.postprocessing.compute_spike_amplitudes()`)
+or amplitude scalings (see :py:func:`~spikeinterface.postprocessing.compute_amplitude_scalings()`) to be pre-computed.
+
+
+Expectation and use
+-------------------
+
+The amplitude CV median is expected to be relatively low for well-isolated units, indicating a "stereotypical" spike shape.
+
+The amplitude CV range can be high in the presence of noise contamination, due to amplitude outliers like in
+the example below.
+
+.. image:: amplitudes.png
+    :width: 600
+
+
+Example code
+------------
+
+.. code-block:: python
+
+    import spikeinterface.qualitymetrics as sqm
+
+    # Make recording, sorting and wvf_extractor object for your data.
+	# It is required to run `compute_spike_amplitudes(wvf_extractor)` or
+	# `compute_amplitude_scalings(wvf_extractor)` (if missing, values will be NaN)
+    amplitude_cv_median, amplitude_cv_range = sqm.compute_amplitude_cv_metrics(wvf_extractor)
+    # amplitude_cv_median and  amplitude_cv_range are dicts containing the unit ids as keys,
+    # and their amplitude_cv metrics as values.
+
+
+
+References
+----------
+
+.. autofunction:: spikeinterface.qualitymetrics.misc_metrics.compute_amplitude_cv_metrics
+
+
+Literature
+----------
+
+Designed by Simon Musall and adapted to SpikeInterface by Alessio Buccino.

doc/modules/qualitymetrics/amplitude_median.rst

@@ -20,12 +20,12 @@ Example code
 
 .. code-block:: python
 
-	import spikeinterface.qualitymetrics as qm
+	import spikeinterface.qualitymetrics as sqm
 
 	# It is also recommended to run `compute_spike_amplitudes(wvf_extractor)`
 	# in order to use amplitude values from all spikes.
-	amplitude_medians = qm.compute_amplitude_medians(wvf_extractor)
-	# amplitude_medians is a dict containing the units' IDs as keys,
+	amplitude_medians = sqm.compute_amplitude_medians(wvf_extractor)
+	# amplitude_medians is a dict containing the unit IDs as keys,
 	# and their estimated amplitude medians as values.
 
 Reference

doc/modules/qualitymetrics/d_prime.rst

@@ -32,9 +32,9 @@ Example code
 
 .. code-block:: python
 
-    import spikeinterface.qualitymetrics as qm
+    import spikeinterface.qualitymetrics as sqm
 
-    d_prime = qm.lda_metrics(all_pcs, all_labels, 0)
+    d_prime = sqm.lda_metrics(all_pcs, all_labels, 0)
 
 
 Reference

doc/modules/qualitymetrics/drift.rst

@@ -40,11 +40,12 @@ Example code
 
 .. code-block:: python
 
-	import spikeinterface.qualitymetrics as qm
+	import spikeinterface.qualitymetrics as sqm
 
+	# Make recording, sorting and wvf_extractor object for your data.
 	# It is required to run `compute_spike_locations(wvf_extractor)`
 	# (if missing, values will be NaN)
-	drift_ptps, drift_stds, drift_mads = qm.compute_drift_metrics(wvf_extractor, peak_sign="neg")
+	drift_ptps, drift_stds, drift_mads = sqm.compute_drift_metrics(wvf_extractor, peak_sign="neg")
 	# drift_ptps, drift_stds, and drift_mads are dict containing the units' ID as keys,
 	# and their metrics as values.
 

doc/modules/qualitymetrics/firing_range.rst

@@ -0,0 +1,40 @@
+Firing range (:code:`firing_range`)
+===================================
+
+
+Calculation
+-----------
+
+The firing range indicates the dispersion of the firing rate of a unit across the recording. It is computed by
+taking the difference between the 95th percentile's firing rate and the 5th percentile's firing rate computed over short time bins (e.g. 10 s).
+
+
+
+Expectation and use
+-------------------
+
+Very high levels of firing ranges, outside of a physiological range, might indicate noise contamination.
+
+
+Example code
+------------
+
+.. code-block:: python
+
+    import spikeinterface.qualitymetrics as sqm
+
+    # Make recording, sorting and wvf_extractor object for your data.
+    firing_range = sqm.compute_firing_ranges(wvf_extractor)
+    # firing_range is a dict containing the unit IDs as keys,
+    # and their firing firing_range as values (in Hz).
+
+References
+----------
+
+.. autofunction:: spikeinterface.qualitymetrics.misc_metrics.compute_firing_ranges
+
+
+Literature
+----------
+
+Designed by Simon Musall and adapted to SpikeInterface by Alessio Buccino.

doc/modules/qualitymetrics/firing_rate.rst

@@ -37,11 +37,11 @@ With SpikeInterface:
 
 .. code-block:: python
 
-    import spikeinterface.qualitymetrics as qm
+    import spikeinterface.qualitymetrics as sqm
 
     # Make recording, sorting and wvf_extractor object for your data.
-    firing_rate = qm.compute_firing_rates(wvf_extractor)
-    # firing_rate is a dict containing the units' IDs as keys,
+    firing_rate = sqm.compute_firing_rates(wvf_extractor)
+    # firing_rate is a dict containing the unit IDs as keys,
     # and their firing rates across segments as values (in Hz).
 
 References

doc/modules/qualitymetrics/isi_violations.rst

@@ -77,11 +77,11 @@ With SpikeInterface:
 
 .. code-block:: python
 
-    import spikeinterface.qualitymetrics as qm
+    import spikeinterface.qualitymetrics as sqm
 
     # Make recording, sorting and wvf_extractor object for your data.
 
-    isi_violations_ratio, isi_violations_count = qm.compute_isi_violations(wvf_extractor, isi_threshold_ms=1.0)
+    isi_violations_ratio, isi_violations_count = sqm.compute_isi_violations(wvf_extractor, isi_threshold_ms=1.0)
 
 References
 ----------

doc/modules/qualitymetrics/presence_ratio.rst

@@ -23,12 +23,12 @@ Example code
 
 .. code-block:: python
 
-    import spikeinterface.qualitymetrics as qm
+    import spikeinterface.qualitymetrics as sqm
 
     # Make recording, sorting and wvf_extractor object for your data.
 
-    presence_ratio = qm.compute_presence_ratios(wvf_extractor)
-    # presence_ratio is a dict containing the units' IDs as keys
+    presence_ratio = sqm.compute_presence_ratios(wvf_extractor)
+    # presence_ratio is a dict containing the unit IDs as keys
     # and their presence ratio (between 0 and 1) as values.
 
 Links to original implementations

doc/modules/qualitymetrics/sliding_rp_violations.rst

@@ -27,11 +27,11 @@ With SpikeInterface:
 
 .. code-block:: python
 
-    import spikeinterface.qualitymetrics as qm
+    import spikeinterface.qualitymetrics as sqm
 
     # Make recording, sorting and wvf_extractor object for your data.
 
-    contamination = qm.compute_sliding_rp_violations(wvf_extractor, bin_size_ms=0.25)
+    contamination = sqm.compute_sliding_rp_violations(wvf_extractor, bin_size_ms=0.25)
 
 References
 ----------

doc/modules/qualitymetrics/snr.rst

@@ -41,12 +41,12 @@ With SpikeInterface:
 
 .. code-block:: python
 
-    import spikeinterface.qualitymetrics as qm
+    import spikeinterface.qualitymetrics as sqm
 
     # Make recording, sorting and wvf_extractor object for your data.
 
-    SNRs = qm.compute_snrs(wvf_extractor)
-    # SNRs is a dict containing the units' IDs as keys and their SNRs as values.
+    SNRs = sqm.compute_snrs(wvf_extractor)
+    # SNRs is a dict containing the unit IDs as keys and their SNRs as values.
 
 Links to original implementations
 ---------------------------------

doc/modules/qualitymetrics/synchrony.rst

@@ -27,9 +27,9 @@ Example code
 
 .. code-block:: python
 
-    import spikeinterface.qualitymetrics as qm
+    import spikeinterface.qualitymetrics as sqm
     # Make recording, sorting and wvf_extractor object for your data.
-    synchrony = qm.compute_synchrony_metrics(wvf_extractor, synchrony_sizes=(2, 4, 8))
+    synchrony = sqm.compute_synchrony_metrics(wvf_extractor, synchrony_sizes=(2, 4, 8))
     # synchrony is a tuple of dicts with the synchrony metrics for each unit