From d1ea2158dc8bd2de5f2d69b69ed0c1b0ed8adc87 Mon Sep 17 00:00:00 2001
From: chrishalcrow <57948917+chrishalcrow@users.noreply.github.com>
Date: Tue, 2 Jul 2024 09:50:34 +0100
Subject: [PATCH] Respond to review

---
 doc/modules/qualitymetrics/isi_violations.rst     | 9 ++++++---
 doc/references.rst                                | 3 ++-
 src/spikeinterface/qualitymetrics/misc_metrics.py | 9 +++++----
 3 files changed, 13 insertions(+), 8 deletions(-)

diff --git a/doc/modules/qualitymetrics/isi_violations.rst b/doc/modules/qualitymetrics/isi_violations.rst
index 2002ec6582..4527cdffe9 100644
--- a/doc/modules/qualitymetrics/isi_violations.rst
+++ b/doc/modules/qualitymetrics/isi_violations.rst
@@ -19,13 +19,14 @@ Different formulas have been developed, but all require:
 - :math:`T` the duration of the recording in seconds.
 - :math:`N` the number of spikes in the unit's spike train.
 - :math:`t_r` the duration of the unit's refractory period in seconds.
-- :math:`n_v` the number of violations of the refractory period.
 
 Calculation from the [UMS]_ package
 -----------------------------------
 
 Originally implemented in the `rpv_contamination` calculation of the UltraMegaSort2000 package: `<https://github.com/danamics/UMS2K/blob/master/quality_measures/rpv_contamination.m>`_.
 
+In this method the number of spikes whose refractory period are violated, denoted :math:`n_v`, is used.
+
 Here, the refactory period :math:`t_r` is adjusted to take account of the data recording system's minimum possible refactory
 period. E.g. if a system has a sampling rate of :math:`f \text{ Hz}`, the closest that two spikes from the same unit can possibly
 be is :math:`1/f \, \text{s}`. Hence the refactory period :math:`t_r` is the expected biological threshold minus this minimum possible
@@ -40,6 +41,8 @@ The contamination rate is calculated to be
 Calculation from the [Llobet]_ paper
 ------------------------------------
 
+In this method the number spikes which violate other spikes' refractory periods, denoted :math:`\tilde{n}_v`, is used.
+
 The estimated contamination :math:`C` is calculated in 2 extreme scenarios. In the first, the contaminant spikes
 are completely random (or come from an infinite number of other neurons). In the second, the contaminant spikes
 come from a single other neuron. In these scenarios, the contamination rate is
@@ -47,8 +50,8 @@ come from a single other neuron. In these scenarios, the contamination rate is
 .. math::
 
     C = \frac{FP}{TP + FP} \approx \begin{cases}
-        1 - \sqrt{1 - \frac{n_v T}{N^2 t_r}} \text{ for the case of random contamination} \\
-        \frac{1}{2} \left( 1 - \sqrt{1 - \frac{2 n_v T}{N^2 t_r}} \right) \text{ for the case of 1 contaminant neuron}
+        1 - \sqrt{1 - \frac{\tilde{n}_v T}{N^2 t_r}} \text{ for the case of random contamination} \\
+        \frac{1}{2} \left( 1 - \sqrt{1 - \frac{2 \tilde{n}_v T}{N^2 t_r}} \right) \text{ for the case of 1 contaminant neuron}
     \end{cases}
 
 Where :math:`TP` is the number of true positives (detected spikes that come from the neuron) and :math:`FP` is the number of false positives (detected spikes that don't come from the neuron).
diff --git a/doc/references.rst b/doc/references.rst
index 48b7cd44f6..5fbcbecb63 100644
--- a/doc/references.rst
+++ b/doc/references.rst
@@ -51,7 +51,8 @@ or :code:`compute_quality_metrics()` methods, please include the citations for t
 important for your research:
 
 - :code:`amplitude_cutoff` [Hill]_
-- :code:`amplitude_median` or :code:`sliding_rp_violation` [IBL]_
+- :code:`amplitude_median` [IBL]_
+- :code:`sliding_rp_violation` [IBL]_
 - :code:`drift` [Siegle]_
 - :code:`isi_violation` [UMS]_
 - :code:`rp_violation` [Llobet]_
diff --git a/src/spikeinterface/qualitymetrics/misc_metrics.py b/src/spikeinterface/qualitymetrics/misc_metrics.py
index 9e4685b5bd..31a3efb2b6 100644
--- a/src/spikeinterface/qualitymetrics/misc_metrics.py
+++ b/src/spikeinterface/qualitymetrics/misc_metrics.py
@@ -267,10 +267,11 @@ def compute_isi_violations(sorting_analyzer, isi_threshold_ms=1.5, min_isi_ms=0,
 
     Notes
     -----
-    The returned ISI violations ratio measures the approximate fraction of spikes in each
-    unit which are contaminted. This interpretation is good when the ratio is small, and
-    becomes worse as it grows. In cases of highly contaminated units, the ISI  violations
-    ratio can sometimes be greater than 1.
+    The returned ISI violations ratio approximates the fraction of spikes in each
+    unit which are contaminted. The formulation assumes that the contaminating spikes
+    are statistically independent from the other spikes in that cluster. This
+    approximation can break down in reality, especially for highly contaminated units.
+    See the discussion in Section 4.1 of [Llobet]_ for more details.
 
     This method counts the number of spikes whose isi is violated. If there are three
     spikes within `isi_threshold_ms`, the first and second are violated. Hence there are two