Respond to review

doc/modules/qualitymetrics/isi_violations.rst

@@ -16,14 +16,16 @@ A correlation will lead to an overestimation of the contamination, whereas an an
 
 Different formulas have been developed, but all require:
 
-- :math:`T` the duration of the recording.
+- :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.
+- :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>`_.
+
 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
@@ -39,8 +41,8 @@ Calculation from the [Llobet]_ paper
 ------------------------------------
 
 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
+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
 
 .. math::
 

src/spikeinterface/qualitymetrics/misc_metrics.py

@@ -272,9 +272,14 @@ def compute_isi_violations(sorting_analyzer, isi_threshold_ms=1.5, min_isi_ms=0,
     becomes worse as it grows. In cases of highly contaminated units, the ISI  violations
     ratio can sometimes be greater than 1.
 
+    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
+    spikes which have been violated.  This is is contrast to `compute_refrac_period_violations`,
+    which counts the number of violations.
+
     References
     ----------
-    Based on metrics originally implemented in [UMS]_
+    Based on metrics originally implemented in Ultra Mega Sort [UMS]_.
 
     This implementation is based on one written in Matlab by Nick Steinmetz
     (https://github.com/cortex-lab/sortingQuality) and converted to Python by Daniel Denman.
@@ -325,7 +330,6 @@ def compute_refrac_period_violations(
     Calculate the number of refractory period violations.
 
     This is similar (but slightly different) to the ISI violations.
-    The key differences being that the violations are not only computed on consecutive spikes.
 
     This is required for some formulas (e.g. the ones from Llobet & Wyngaard 2022).
 
@@ -352,6 +356,12 @@ def compute_refrac_period_violations(
     -----
     Requires "numba" package
 
+    This method counts the number of violations which occur during the refactory period.
+    If there are three spikes within `refractory_period_ms`, the second and third spikes
+    violate the first spikes and the third spike violates the second spike. Hence there
+    are three violations. This is in contrast to `compute_isi_violations`, which
+    computes the number of spikes which have been violated.
+
     References
     ----------
     Based on metrics described in [Llobet]_