@verbose
def plot_events(events, sfreq=None, first_samp=0, color=None, event_id=None, axes=None, equal_spacing=True, show=True, on_missing='raise', verbose=None):
    "Plot events to get a visual display of the paradigm.\n\n    Parameters\n    ----------\n    events : array, shape (n_events, 3)\n        The events.\n    sfreq : float | None\n        The sample frequency. If None, data will be displayed in samples (not\n        seconds).\n    first_samp : int\n        The index of the first sample. Recordings made on Neuromag systems\n        number samples relative to the system start (not relative to the\n        beginning of the recording). In such cases the ``raw.first_samp``\n        attribute can be passed here. Default is 0.\n    color : dict | None\n        Dictionary of event_id integers as keys and colors as values. If None,\n        colors are automatically drawn from a default list (cycled through if\n        number of events longer than list of default colors). Color can be any\n        valid :doc:`matplotlib color <tutorials/colors/colors>`.\n    event_id : dict | None\n        Dictionary of event labels (e.g. 'aud_l') as keys and their associated\n        event_id values. Labels are used to plot a legend. If None, no legend\n        is drawn.\n    axes : instance of Axes\n       The subplot handle.\n    equal_spacing : bool\n        Use equal spacing between events in y-axis.\n    show : bool\n        Show figure if True.\n    %(on_missing_events)s\n    %(verbose)s\n\n    Returns\n    -------\n    fig : matplotlib.figure.Figure\n        The figure object containing the plot.\n\n    Notes\n    -----\n    .. versionadded:: 0.9.0\n    "
    if (sfreq is None):
        sfreq = 1.0
        xlabel = 'Samples'
    else:
        xlabel = 'Time (s)'
    events = np.asarray(events)
    if (len(events) == 0):
        raise ValueError('No events in events array, cannot plot.')
    unique_events = np.unique(events[:, 2])
    if (event_id is not None):
        event_id_rev = {v: k for (k, v) in event_id.items()}
        (conditions, unique_events_id) = zip(*sorted(event_id.items(), key=(lambda x: x[1])))
        keep = np.ones(len(unique_events_id), bool)
        for (ii, this_event) in enumerate(unique_events_id):
            if (this_event not in unique_events):
                msg = f'{this_event} from event_id is not present in events.'
                _on_missing(on_missing, msg)
                keep[ii] = False
        conditions = [cond for (cond, k) in zip(conditions, keep) if k]
        unique_events_id = [id_ for (id_, k) in zip(unique_events_id, keep) if k]
        if (len(unique_events_id) == 0):
            raise RuntimeError('No usable event IDs found')
        for this_event in unique_events:
            if (this_event not in unique_events_id):
                warn(('event %s missing from event_id will be ignored' % this_event))
    else:
        unique_events_id = unique_events
    color = _handle_event_colors(color, unique_events, event_id)
    import matplotlib.pyplot as plt
    fig = None
    if (axes is None):
        fig = plt.figure()
    ax = (axes if axes else plt.gca())
    unique_events_id = np.array(unique_events_id)
    min_event = np.min(unique_events_id)
    max_event = np.max(unique_events_id)
    max_x = ((events[(np.in1d(events[:, 2], unique_events_id), 0)].max() - first_samp) / sfreq)
    (handles, labels) = (list(), list())
    for (idx, ev) in enumerate(unique_events_id):
        ev_mask = (events[:, 2] == ev)
        count = ev_mask.sum()
        if (count == 0):
            continue
        y = np.full(count, ((idx + 1) if equal_spacing else events[(ev_mask, 2)][0]))
        if (event_id is not None):
            event_label = ('%s (%s)' % (event_id_rev[ev], count))
        else:
            event_label = ('N=%d' % (count,))
        labels.append(event_label)
        kwargs = {}
        if (ev in color):
            kwargs['color'] = color[ev]
        handles.append(ax.plot(((events[(ev_mask, 0)] - first_samp) / sfreq), y, '.', clip_on=False, **kwargs)[0])
    if equal_spacing:
        ax.set_ylim(0, (unique_events_id.size + 1))
        ax.set_yticks((1 + np.arange(unique_events_id.size)))
        ax.set_yticklabels(unique_events_id)
    else:
        ax.set_ylim([(min_event - 1), (max_event + 1)])
    ax.set(xlabel=xlabel, ylabel='Events id', xlim=[0, max_x])
    ax.grid(True)
    fig = (fig if (fig is not None) else plt.gcf())
    (handles, labels) = (handles[::(- 1)], labels[::(- 1)])
    box = ax.get_position()
    factor = (0.8 if (event_id is not None) else 0.9)
    ax.set_position([box.x0, box.y0, (box.width * factor), box.height])
    ax.legend(handles, labels, loc='center left', bbox_to_anchor=(1, 0.5), fontsize='small')
    fig.canvas.draw()
    plt_show(show)
    return fig
Plot events to get a visual display of the paradigm.

Parameters
----------
events : array, shape (n_events, 3)
    The events.
sfreq : float | None
    The sample frequency. If None, data will be displayed in samples (not
    seconds).
first_samp : int
    The index of the first sample. Recordings made on Neuromag systems
    number samples relative to the system start (not relative to the
    beginning of the recording). In such cases the ``raw.first_samp``
    attribute can be passed here. Default is 0.
color : dict | None
    Dictionary of event_id integers as keys and colors as values. If None,
    colors are automatically drawn from a default list (cycled through if
    number of events longer than list of default colors). Color can be any
    valid :doc:`matplotlib color <tutorials/colors/colors>`.
event_id : dict | None
    Dictionary of event labels (e.g. 'aud_l') as keys and their associated
    event_id values. Labels are used to plot a legend. If None, no legend
    is drawn.
axes : instance of Axes
   The subplot handle.
equal_spacing : bool
    Use equal spacing between events in y-axis.
show : bool
    Show figure if True.
%(on_missing_events)s
%(verbose)s

Returns
-------
fig : matplotlib.figure.Figure
    The figure object containing the plot.

Notes
-----
.. versionadded:: 0.9.0
@verbose
def plot_events(events, sfreq=None, first_samp=0, color=None, event_id=None, axes=None, equal_spacing=True, show=True, on_missing='raise', verbose=None):
    "Plot events to get a visual display of the paradigm.\n\n    Parameters\n    ----------\n    events : array, shape (n_events, 3)\n        The events.\n    sfreq : float | None\n        The sample frequency. If None, data will be displayed in samples (not\n        seconds).\n    first_samp : int\n        The index of the first sample. Recordings made on Neuromag systems\n        number samples relative to the system start (not relative to the\n        beginning of the recording). In such cases the ``raw.first_samp``\n        attribute can be passed here. Default is 0.\n    color : dict | None\n        Dictionary of event_id integers as keys and colors as values. If None,\n        colors are automatically drawn from a default list (cycled through if\n        number of events longer than list of default colors). Color can be any\n        valid :doc:`matplotlib color <tutorials/colors/colors>`.\n    event_id : dict | None\n        Dictionary of event labels (e.g. 'aud_l') as keys and their associated\n        event_id values. Labels are used to plot a legend. If None, no legend\n        is drawn.\n    axes : instance of Axes\n       The subplot handle.\n    equal_spacing : bool\n        Use equal spacing between events in y-axis.\n    show : bool\n        Show figure if True.\n    %(on_missing_events)s\n    %(verbose)s\n\n    Returns\n    -------\n    fig : matplotlib.figure.Figure\n        The figure object containing the plot.\n\n    Notes\n    -----\n    .. versionadded:: 0.9.0\n    "
    if (sfreq is None):
        sfreq = 1.0
        xlabel = 'Samples'
    else:
        xlabel = 'Time (s)'
    events = np.asarray(events)
    if (len(events) == 0):
        raise ValueError('No events in events array, cannot plot.')
    unique_events = np.unique(events[:, 2])
    if (event_id is not None):
        event_id_rev = {v: k for (k, v) in event_id.items()}
        (conditions, unique_events_id) = zip(*sorted(event_id.items(), key=(lambda x: x[1])))
        keep = np.ones(len(unique_events_id), bool)
        for (ii, this_event) in enumerate(unique_events_id):
            if (this_event not in unique_events):
                msg = f'{this_event} from event_id is not present in events.'
                _on_missing(on_missing, msg)
                keep[ii] = False
        conditions = [cond for (cond, k) in zip(conditions, keep) if k]
        unique_events_id = [id_ for (id_, k) in zip(unique_events_id, keep) if k]
        if (len(unique_events_id) == 0):
            raise RuntimeError('No usable event IDs found')
        for this_event in unique_events:
            if (this_event not in unique_events_id):
                warn(('event %s missing from event_id will be ignored' % this_event))
    else:
        unique_events_id = unique_events
    color = _handle_event_colors(color, unique_events, event_id)
    import matplotlib.pyplot as plt
    fig = None
    if (axes is None):
        fig = plt.figure()
    ax = (axes if axes else plt.gca())
    unique_events_id = np.array(unique_events_id)
    min_event = np.min(unique_events_id)
    max_event = np.max(unique_events_id)
    max_x = ((events[(np.in1d(events[:, 2], unique_events_id), 0)].max() - first_samp) / sfreq)
    (handles, labels) = (list(), list())
    for (idx, ev) in enumerate(unique_events_id):
        ev_mask = (events[:, 2] == ev)
        count = ev_mask.sum()
        if (count == 0):
            continue
        y = np.full(count, ((idx + 1) if equal_spacing else events[(ev_mask, 2)][0]))
        if (event_id is not None):
            event_label = ('%s (%s)' % (event_id_rev[ev], count))
        else:
            event_label = ('N=%d' % (count,))
        labels.append(event_label)
        kwargs = {}
        if (ev in color):
            kwargs['color'] = color[ev]
        handles.append(ax.plot(((events[(ev_mask, 0)] - first_samp) / sfreq), y, '.', clip_on=False, **kwargs)[0])
    if equal_spacing:
        ax.set_ylim(0, (unique_events_id.size + 1))
        ax.set_yticks((1 + np.arange(unique_events_id.size)))
        ax.set_yticklabels(unique_events_id)
    else:
        ax.set_ylim([(min_event - 1), (max_event + 1)])
    ax.set(xlabel=xlabel, ylabel='Events id', xlim=[0, max_x])
    ax.grid(True)
    fig = (fig if (fig is not None) else plt.gcf())
    (handles, labels) = (handles[::(- 1)], labels[::(- 1)])
    box = ax.get_position()
    factor = (0.8 if (event_id is not None) else 0.9)
    ax.set_position([box.x0, box.y0, (box.width * factor), box.height])
    ax.legend(handles, labels, loc='center left', bbox_to_anchor=(1, 0.5), fontsize='small')
    fig.canvas.draw()
    plt_show(show)
    return fig