Correlograms

pynapple.process.correlograms

This module holds the functions to compute discrete cross-correlogram for timestamps data (i.e. spike times).

Function	Description
nap.compute_autocorrelogram	Autocorrelograms from a TsGroup object
nap.compute_crosscorrelogram	Crosscorrelogram from a TsGroup object
nap.compute_eventcorrelogram	Crosscorrelogram between a TsGroup object and a Ts object

compute_autocorrelogram

compute_autocorrelogram(
    group,
    binsize,
    windowsize,
    ep=None,
    norm=True,
    time_units="s",
)

Computes the autocorrelogram of a group of Ts/Tsd objects. The group can be passed directly as a TsGroup object.

Parameters:

Name	Type	Description	Default
group	TsGroup	The group of Ts/Tsd objects to auto-correlate	required
binsize	float	The bin size. Default is second. If different, specify with the parameter time_units ('s' [default], 'ms', 'us').	required
windowsize	float	The window size. Default is second. If different, specify with the parameter time_units ('s' [default], 'ms', 'us').	required
ep	IntervalSet	The epoch on which auto-corrs are computed. If None, the epoch is the time support of the group.	None
norm	bool	If True, autocorrelograms are normalized to baseline (i.e. divided by the average rate) If False, autoorrelograms are returned as the rate (Hz) of the time series (relative to itself)	True
time_units	str	The time units of the parameters. They have to be consistent for binsize and windowsize. ('s' [default], 'ms', 'us').	's'

Returns:

Type	Description
DataFrame	_

Raises:

Type	Description
RuntimeError	group must be TsGroup

Source code in pynapple/process/correlograms.py

@_validate_correlograms_inputs
def compute_autocorrelogram(
    group, binsize, windowsize, ep=None, norm=True, time_units="s"
):
    """
    Computes the autocorrelogram of a group of Ts/Tsd objects.
    The group can be passed directly as a TsGroup object.

    Parameters
    ----------
    group : TsGroup
        The group of Ts/Tsd objects to auto-correlate
    binsize : float
        The bin size. Default is second.
        If different, specify with the parameter time_units ('s' [default], 'ms', 'us').
    windowsize : float
        The window size. Default is second.
        If different, specify with the parameter time_units ('s' [default], 'ms', 'us').
    ep : IntervalSet
        The epoch on which auto-corrs are computed.
        If None, the epoch is the time support of the group.
    norm : bool, optional
         If True, autocorrelograms are normalized to baseline (i.e. divided by the average rate)
         If False, autoorrelograms are returned as the rate (Hz) of the time series (relative to itself)
    time_units : str, optional
        The time units of the parameters. They have to be consistent for binsize and windowsize.
        ('s' [default], 'ms', 'us').

    Returns
    -------
    pandas.DataFrame
        _

    Raises
    ------
    RuntimeError
        group must be TsGroup
    """
    if isinstance(ep, nap.IntervalSet):
        newgroup = group.restrict(ep)
    else:
        newgroup = group

    autocorrs = {}

    binsize = nap.TsIndex.format_timestamps(
        np.array([binsize], dtype=np.float64), time_units
    )[0]
    windowsize = nap.TsIndex.format_timestamps(
        np.array([windowsize], dtype=np.float64), time_units
    )[0]

    for n in newgroup.keys():
        spk_time = newgroup[n].index
        auc, times = _cross_correlogram(spk_time, spk_time, binsize, windowsize)
        autocorrs[n] = pd.Series(index=np.round(times, 6), data=auc, dtype="float")

    autocorrs = pd.DataFrame.from_dict(autocorrs)

    if norm:
        autocorrs = autocorrs / newgroup.get_info("rate")

    # Bug here
    if 0 in autocorrs.index:
        autocorrs.loc[0] = 0.0

    return autocorrs.astype("float")

compute_crosscorrelogram

compute_crosscorrelogram(
    group,
    binsize,
    windowsize,
    ep=None,
    norm=True,
    time_units="s",
    reverse=False,
)

Computes all the pairwise cross-correlograms for TsGroup or list/tuple of two TsGroup.

If input is TsGroup only, the reference Ts/Tsd and target are chosen based on the builtin itertools.combinations function. For example if indexes are [0,1,2], the function computes cross-correlograms for the pairs (0,1), (0, 2), and (1, 2). The left index gives the reference time series. To reverse the order, set reverse=True.

If input is tuple/list of TsGroup, for example group=(group1, group2), the reference for each pairs comes from group1.

Parameters:

Name	Type	Description	Default
group	TsGroup or tuple/list of two TsGroups		required
binsize	float	The bin size. Default is second. If different, specify with the parameter time_units ('s' [default], 'ms', 'us').	required
windowsize	float	The window size. Default is second. If different, specify with the parameter time_units ('s' [default], 'ms', 'us').	required
ep	IntervalSet	The epoch on which cross-corrs are computed. If None, the epoch is the time support of the group.	None
norm	bool	If True (default), cross-correlograms are normalized to baseline (i.e. divided by the average rate of the target time series) If False, cross-orrelograms are returned as the rate (Hz) of the target time series ((relative to the reference time series)	True
time_units	str	The time units of the parameters. They have to be consistent for binsize and windowsize. ('s' [default], 'ms', 'us').	's'
reverse	bool	To reverse the pair order if input is TsGroup	False

Returns:

Type	Description
DataFrame	_

Raises:

Type	Description
RuntimeError	group must be TsGroup or tuple/list of two TsGroups

Source code in pynapple/process/correlograms.py

@_validate_correlograms_inputs
def compute_crosscorrelogram(
    group, binsize, windowsize, ep=None, norm=True, time_units="s", reverse=False
):
    """
    Computes all the pairwise cross-correlograms for TsGroup or list/tuple of two TsGroup.

    If input is TsGroup only, the reference Ts/Tsd and target are chosen based on the builtin itertools.combinations function.
    For example if indexes are [0,1,2], the function computes cross-correlograms
    for the pairs (0,1), (0, 2), and (1, 2). The left index gives the reference time series.
    To reverse the order, set reverse=True.

    If input is tuple/list of TsGroup, for example group=(group1, group2), the reference for each pairs comes from group1.

    Parameters
    ----------
    group : TsGroup or tuple/list of two TsGroups

    binsize : float
        The bin size. Default is second.
        If different, specify with the parameter time_units ('s' [default], 'ms', 'us').
    windowsize : float
        The window size. Default is second.
        If different, specify with the parameter time_units ('s' [default], 'ms', 'us').
    ep : IntervalSet
        The epoch on which cross-corrs are computed.
        If None, the epoch is the time support of the group.
    norm : bool, optional
        If True (default), cross-correlograms are normalized to baseline (i.e. divided by the average rate of the target time series)
        If False, cross-orrelograms are returned as the rate (Hz) of the target time series ((relative to the reference time series)
    time_units : str, optional
        The time units of the parameters. They have to be consistent for binsize and windowsize.
        ('s' [default], 'ms', 'us').
    reverse : bool, optional
        To reverse the pair order if input is TsGroup

    Returns
    -------
    pandas.DataFrame
        _

    Raises
    ------
    RuntimeError
        group must be TsGroup or tuple/list of two TsGroups

    """
    crosscorrs = {}

    binsize = nap.TsIndex.format_timestamps(
        np.array([binsize], dtype=np.float64), time_units
    )[0]
    windowsize = nap.TsIndex.format_timestamps(
        np.array([windowsize], dtype=np.float64), time_units
    )[0]

    if isinstance(group, tuple):
        if isinstance(ep, nap.IntervalSet):
            newgroup = [group[i].restrict(ep) for i in range(2)]
        else:
            newgroup = group

        pairs = product(list(newgroup[0].keys()), list(newgroup[1].keys()))

        for i, j in pairs:
            spk1 = newgroup[0][i].index
            spk2 = newgroup[1][j].index
            auc, times = _cross_correlogram(spk1, spk2, binsize, windowsize)
            if norm:
                auc /= newgroup[1][j].rate
            crosscorrs[(i, j)] = pd.Series(index=times, data=auc, dtype="float")

        crosscorrs = pd.DataFrame.from_dict(crosscorrs)
    else:
        if isinstance(ep, nap.IntervalSet):
            newgroup = group.restrict(ep)
        else:
            newgroup = group
        neurons = list(newgroup.keys())
        pairs = list(combinations(neurons, 2))
        if reverse:
            pairs = list(map(lambda n: (n[1], n[0]), pairs))

        for i, j in pairs:
            spk1 = newgroup[i].index
            spk2 = newgroup[j].index
            auc, times = _cross_correlogram(spk1, spk2, binsize, windowsize)
            crosscorrs[(i, j)] = pd.Series(index=times, data=auc, dtype="float")

        crosscorrs = pd.DataFrame.from_dict(crosscorrs)

        if norm:
            freq = newgroup.get_info("rate")
            freq2 = pd.Series(
                index=pairs, data=list(map(lambda n: freq.loc[n[1]], pairs))
            )
            crosscorrs = crosscorrs / freq2

    return crosscorrs.astype("float")

compute_eventcorrelogram

compute_eventcorrelogram(
    group,
    event,
    binsize,
    windowsize,
    ep=None,
    norm=True,
    time_units="s",
)

Computes the correlograms of a group of Ts/Tsd objects with another single Ts/Tsd object The time of reference is the event times.

Parameters:

Name	Type	Description	Default
group	TsGroup	The group of Ts/Tsd objects to correlate with the event	required
event	Ts / Tsd	The event to correlate the each of the time series in the group with.	required
binsize	float	The bin size. Default is second. If different, specify with the parameter time_units ('s' [default], 'ms', 'us').	required
windowsize	float	The window size. Default is second. If different, specify with the parameter time_units ('s' [default], 'ms', 'us').	required
ep	IntervalSet	The epoch on which cross-corrs are computed. If None, the epoch is the time support of the event.	None
norm	bool	If True (default), cross-correlograms are normalized to baseline (i.e. divided by the average rate of the target time series) If False, cross-orrelograms are returned as the rate (Hz) of the target time series (relative to the event time series)	True
time_units	str	The time units of the parameters. They have to be consistent for binsize and windowsize. ('s' [default], 'ms', 'us').	's'

Returns:

Type	Description
DataFrame	_

Raises:

Type	Description
RuntimeError	group must be TsGroup

Source code in pynapple/process/correlograms.py

@_validate_correlograms_inputs
def compute_eventcorrelogram(
    group, event, binsize, windowsize, ep=None, norm=True, time_units="s"
):
    """
    Computes the correlograms of a group of Ts/Tsd objects with another single Ts/Tsd object
    The time of reference is the event times.

    Parameters
    ----------
    group : TsGroup
        The group of Ts/Tsd objects to correlate with the event
    event : Ts/Tsd
        The event to correlate the each of the time series in the group with.
    binsize : float
        The bin size. Default is second.
        If different, specify with the parameter time_units ('s' [default], 'ms', 'us').
    windowsize : float
        The window size. Default is second.
        If different, specify with the parameter time_units ('s' [default], 'ms', 'us').
    ep : IntervalSet
        The epoch on which cross-corrs are computed.
        If None, the epoch is the time support of the event.
    norm : bool, optional
        If True (default), cross-correlograms are normalized to baseline (i.e. divided by the average rate of the target time series)
        If False, cross-orrelograms are returned as the rate (Hz) of the target time series (relative to the event time series)
    time_units : str, optional
        The time units of the parameters. They have to be consistent for binsize and windowsize.
        ('s' [default], 'ms', 'us').

    Returns
    -------
    pandas.DataFrame
        _

    Raises
    ------
    RuntimeError
        group must be TsGroup

    """
    if ep is None:
        ep = event.time_support
        tsd1 = event.index
    else:
        tsd1 = event.restrict(ep).index

    newgroup = group.restrict(ep)

    crosscorrs = {}

    binsize = nap.TsIndex.format_timestamps(
        np.array([binsize], dtype=np.float64), time_units
    )[0]
    windowsize = nap.TsIndex.format_timestamps(
        np.array([windowsize], dtype=np.float64), time_units
    )[0]

    for n in newgroup.keys():
        spk_time = newgroup[n].index
        auc, times = _cross_correlogram(tsd1, spk_time, binsize, windowsize)
        crosscorrs[n] = pd.Series(index=times, data=auc, dtype="float")

    crosscorrs = pd.DataFrame.from_dict(crosscorrs)

    if norm:
        crosscorrs = crosscorrs / newgroup.get_info("rate")

    return crosscorrs.astype("float")