Skip to content

Correlograms

pynapple.process.correlograms

Cross-correlograms

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
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 type(group) is nap.TsGroup:
        if isinstance(ep, nap.IntervalSet):
            newgroup = group.restrict(ep)
        else:
            newgroup = group
    else:
        raise RuntimeError("Unknown format for 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'). 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:

Type Description
DataFrame

_

Raises:

Type Description
RuntimeError

group must be TsGroup or tuple/list of two TsGroups

Source code in pynapple/process/correlograms.py
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, nap.TsGroup):
        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

    elif (
        isinstance(group, (tuple, list))
        and len(group) == 2
        and all(map(lambda g: isinstance(g, nap.TsGroup), group))
    ):
        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:
        raise RuntimeError("Unknown format for group")

    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
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

    if type(group) is nap.TsGroup:
        newgroup = group.restrict(ep)
    else:
        raise RuntimeError("Unknown format for group")

    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")