doc: update statistics documentation page

docs/api/_toctree/StatisticsAPI/miv.statistics.firing_rates.rst

@@ -0,0 +1,6 @@
+miv.statistics.firing\_rates
+============================
+
+.. currentmodule:: miv.statistics
+
+.. autofunction:: firing_rates

docs/api/_toctree/StatisticsAPI/miv.statistics.inter_spike_intervals.rst

@@ -0,0 +1,6 @@
+miv.statistics.inter\_spike\_intervals
+======================================
+
+.. currentmodule:: miv.statistics
+
+.. autofunction:: inter_spike_intervals

docs/api/_toctree/StatisticsAPI/miv.statistics.signal_to_noise.rst

@@ -0,0 +1,6 @@
+miv.statistics.signal\_to\_noise
+================================
+
+.. currentmodule:: miv.statistics
+
+.. autofunction:: signal_to_noise

docs/api/statistics.rst

@@ -2,4 +2,50 @@
 Statistics Modules
 ******************
 
-.. automodule:: miv.statistics.summarizer
+Statistics Tools
+================
+
+.. currentmodule:: miv.statistics
+
+Signals
+-------
+
+.. autosummary::
+  :nosignatures:
+  :toctree: _toctree/StatisticsAPI
+
+  signal_to_noise
+
+Spikestamps Statistics
+----------------------
+
+.. autosummary::
+  :nosignatures:
+  :toctree: _toctree/StatisticsAPI
+
+  firing_rates
+  inter_spike_intervals
+
+Useful External Packages
+========================
+
+Here are few external `python` packages that can be used for further statistical analysis.
+
+scipy statistics
+----------------
+
+`scipy <https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.describe.html>`_
+
+.. autosummary::
+
+   scipy.stats.describe
+
+elephant.statistics
+-------------------
+
+`elephant documentation: <https://elephant.readthedocs.io/en/latest/reference/statistics.html>`_
+
+.. autosummary::
+
+   elephant.statistics.mean_firing_rate
+   elephant.statistics.instantaneous_rate

miv/statistics/__init__.py

@@ -1,2 +1,2 @@
-from miv.statistics.summarizer import *
-from miv.statistics.utility import *
+from miv.statistics.signal_statistics import *
+from miv.statistics.spiketrain_statistics import *

miv/statistics/utility.py → miv/statistics/signal_statistics.py

@@ -6,7 +6,8 @@
 
 
 def signal_to_noise(signal: SignalType, axis: int = 0, ddof: int = 0):
-    """signal_to_noise.
+    """
+    Compute signal-to-noise ratio of raw signal.
 
     Parameters
     ----------

miv/statistics/summarizer.py → miv/statistics/spiketrain_statistics.py

@@ -1,85 +1,74 @@
-__doc__ = """
-
-Statistics Tools
-================
-
-Spikestamps
------------
-
-.. currentmodule:: miv.statistics
-
-.. autosummary::
-  :nosignatures:
-  :toctree: _toctree/StatisticsAPI
-
-  spikestamps_statistics
-
-Useful External Packages
-========================
-
-Here are few external `python` packages that can be used for further statistical analysis.
-
-scipy statistics
-----------------
-
-`scipy <https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.describe.html>`_
-
-.. autosummary::
-
-   scipy.stats.describe
-
-elephant.statistics
--------------------
-
-`elephant documentation: <https://elephant.readthedocs.io/en/latest/reference/statistics.html>`_
-
-.. autosummary::
-
-   elephant.statistics.mean_firing_rate
-   elephant.statistics.instantaneous_rate
-"""
-__all__ = ["spikestamps_statistics"]
-
-from typing import Any, Dict, Iterable, Optional, Union
-
-import datetime
-
-import elephant.statistics
-import matplotlib.pyplot as plt
-import neo
-import numpy as np
-import quantities as pq
-import scipy
-import scipy.signal
-
-
-# FIXME: For now, we provide the free function for simple usage. For more
-# advanced statistical analysis, we should have a module wrapper.
-def spikestamps_statistics(
-    spiketrains: Union[pq.Quantity, Iterable[neo.core.SpikeTrain]],
-    # t_start: Optional[float] = None,
-    # t_stop: Optional[float] = None,
-) -> Dict[str, Any]:
-    """
-    Process basic spiketrains statistics: rates, mean, variance.
-
-    Parameters
-    ----------
-    spiketrains : Iterable[neo.core.SpikeTrain]
-
-    Returns
-    -------
-    Iterable[Any]
-
-    """
-    rates = [
-        float(elephant.statistics.mean_firing_rate(spikestamp).magnitude)
-        for spikestamp in spiketrains
-    ]
-    rates_mean_over_channel = np.mean(rates)
-    rates_variance_over_channel = np.var(rates)
-    return {
-        "rates": rates,
-        "mean": rates_mean_over_channel,
-        "variance": rates_variance_over_channel,
-    }
+__all__ = ["firing_rates", "inter_spike_intervals"]
+
+from typing import Any, Dict, Iterable, Optional, Union
+
+import datetime
+
+import elephant.statistics
+import matplotlib.pyplot as plt
+import neo
+import numpy as np
+import quantities as pq
+import scipy
+import scipy.signal
+
+from miv.typing import SpikestampsType
+
+
+# FIXME: For now, we provide the free function for simple usage. For more
+# advanced statistical analysis, we should have a module wrapper.
+def firing_rates(
+    spiketrains: Union[pq.Quantity, Iterable[neo.core.SpikeTrain]],
+    # t_start: Optional[float] = None,
+    # t_stop: Optional[float] = None,
+) -> Dict[str, Any]:
+    """
+    Process basic spiketrains statistics: rates, mean, variance.
+
+    Parameters
+    ----------
+    spiketrains : Iterable[neo.core.SpikeTrain]
+
+    Returns
+    -------
+    Iterable[Any]
+
+    """
+    rates = [
+        float(elephant.statistics.mean_firing_rate(spikestamp).magnitude)
+        for spikestamp in spiketrains
+    ]
+    rates_mean_over_channel = np.mean(rates)
+    rates_variance_over_channel = np.var(rates)
+    return {
+        "rates": rates,
+        "mean": rates_mean_over_channel,
+        "variance": rates_variance_over_channel,
+    }
+
+
+def inter_spike_intervals(spikes):
+    """
+    Compute the inter-spike intervals of the given spike train.
+
+    Examples
+    --------
+
+    How to draw Inter-spike interval histogram (ISIH)
+
+        >>> from miv.statistics import inter_spike_intervals
+        >>> import matplotlib.pyplot as plt
+        >>> interval = inter_spike_intervals(spikestamps)
+        >>> plt.hist(interval)
+
+    Parameters
+    ----------
+    spikes : SpikestampsType
+
+    Returns
+    -------
+        numpy.ndarray
+
+    """
+
+    return np.diff(spikes)

tests/statistics/test_spikestamps_statistics.py

@@ -3,7 +3,7 @@
 import quantities as pq
 from neo.core import SpikeTrain
 
-from miv.statistics import spikestamps_statistics
+from miv.statistics import firing_rates
 
 SpikestampsTestSet = [
     [pq.Quantity([1, 2, 3], "s")],
@@ -15,7 +15,7 @@
 
 @pytest.mark.parametrize("spikestamps, true_rate", zip(SpikestampsTestSet, TrueRates))
 def test_spikestamps_statistics_base_function(spikestamps, true_rate):
-    result = spikestamps_statistics(spikestamps)
+    result = firing_rates(spikestamps)
     np.testing.assert_allclose(result["rates"], true_rate)
     assert np.isclose(result["mean"], np.mean(true_rate))
     assert np.isclose(result["variance"], np.var(true_rate))