"""
Spike train statistics plots
----------------------------

.. autosummary::
    :toctree: toctree/statistics/

    plot_isi_histogram
    plot_time_histogram
    plot_instantaneous_rates_colormesh

"""
# Copyright 2017-2022 by the Viziphant team, see `doc/authors.rst`.
# License: Modified BSD, see LICENSE.txt.txt for details.

import matplotlib.pyplot as plt
import neo
import numpy as np
import quantities as pq

from elephant import statistics
from viziphant.utils import check_same_units


def plot_isi_histogram(spiketrains, axes=None, bin_size=3 * pq.ms, cutoff=None,
                       title='ISI distribution', legend=None, histtype='step'):
    """
    Create a simple histogram plot to visualise an inter-spike interval (ISI)
    distribution of spike trains.

    Input spike trains are sorted in time prior to computing the ISI.

    If the input is a list of list of spike trains, as in the Example 3, the
    ISI of a population is concatenated from all neuron spike trains.

    Parameters
    ----------
    spiketrains : neo.SpikeTrain or pq.Quantity or list
        A spike train or a list of spike trains the ISI to be computed from.
    axes : matplotlib.axes.Axes or None, optional
        Matplotlib axes handle. If set to None, new axes are created and
        returned.
        Default: None
    bin_size : pq.Quantity, optional
        The bin size for the histogram.
        Default: 3 ms
    cutoff : pq.Quantity or None, optional
        The largest ISI to consider. Otherwise, if set to None, all range of
        values are plotted. Typical cutoff values are ~250 ms.
        Default: None
    title : str, optional
        The axes title.
        Default: 'ISI distribution'
    legend : str or list of str or None, optional
        The axes legend labels.
        Default: None
    histtype : str
        Histogram type passed to matplotlib `hist` function.
        Default: 'step'

    Returns
    -------
    axes : matplotlib.axes.Axes

    Examples
    --------
    1. Basic ISI histogram plot.

    .. plot::
        :include-source:

        import quantities as pq
        import matplotlib.pyplot as plt
        from elephant.spike_train_generation import homogeneous_poisson_process
        from viziphant.statistics import plot_isi_histogram
        np.random.seed(12)

        spiketrain = homogeneous_poisson_process(rate=10*pq.Hz, t_stop=50*pq.s)
        plot_isi_histogram(spiketrain, cutoff=250*pq.ms, histtype='bar')
        plt.show()

    2. ISI histogram of multiple spike trains.

    .. plot::
        :include-source:

        import quantities as pq
        import matplotlib.pyplot as plt
        from elephant.spike_train_generation import homogeneous_poisson_process
        from viziphant.statistics import plot_isi_histogram
        np.random.seed(12)
        rates = [5, 10, 15] * pq.Hz
        spiketrains = [homogeneous_poisson_process(rate=r,
                       t_stop=100 * pq.s) for r in rates]