pynapple.process.randomize#

Functions to shuffle timestamps to create surrogate datasets.

Functions

jitter_timestamps(ts[, max_jitter, ...])

Jitters each time stamp independently of random amounts uniformly drawn between -max_jitter and max_jitter.

resample_timestamps(ts)

Resamples the timestamps in the time support, with uniform distribution.

shift_timestamps(data[, min_shift, ...])

Shifts all the time stamps of a random amount between a minimum and maximum shift, wrapping the end of the time support to the beginning.

shuffle_ts_intervals(ts)

Randomizes the timestamps by shuffling the intervals between them.
pynapple.process.randomize.jitter_timestamps(ts, max_jitter=None, keep_tsupport=False)[source]#

Jitters each time stamp independently of random amounts uniformly drawn between -max_jitter and max_jitter.

Parameters:

  • ts (Ts or TsGroup) – The timestamps to jitter. If TsGroup, jitter is applied to each element of the group.

  • max_jitter (float) – maximum jitter

  • keep_tsupport (bool, optional) – If True, keep time support of the input. The number of timestamps will not be conserved. If False, the time support is inferred from the jittered timestamps. The number of tmestamps is conserved. (default: False)

Returns:

The jittered timestamps

Return type:

Ts or TsGroup

pynapple.process.randomize.resample_timestamps(ts)[source]#

Resamples the timestamps in the time support, with uniform distribution.

Parameters:

ts (Ts or TsGroup) – The timestamps to resample. If TsGroup, each Ts object in the group is independently resampled, in the time support of the whole group.

Returns:

The resampled timestamps

Return type:

Ts or TsGroup

pynapple.process.randomize.shift_timestamps(data, min_shift=0.0, max_shift=None, mode='drop')[source]#

Shifts all the time stamps of a random amount between a minimum and maximum shift, wrapping the end of the time support to the beginning.

Notes

If the time support of the input has multiple epochs, some timepoints will fall outside of those epochs after shifting. In mode='drop', those timepoints are dropped. In mode='wrap', timestamps are wrapped circularly using the full time support. However, if there are multiple epochs and mode='wrap', timepoints falling outside the epochs in the middle are still dropped.

Parameters:

  • data (Ts, TsGroup) – The timeseries object whose timestamps to shift. If TsGroup, shifts all objects in the group independently.

  • min_shift (float, optional) – minimum shift (default: 0)

  • max_shift (float, optional) – maximum shift, (default: length of time support)

  • mode ('drop' or 'wrap', optional) –

    How to handle timestamps that fall outside the time support after shifting.

    • 'drop': (default): drop those timestamps

    • 'wrap': circularly wrap timestamps within the time support

Returns:

The randomly shifted timestamps

Return type:

Ts or TsGroup

Examples

Fixed shift with default mode='drop':

>>> import pynapple as nap
>>> ts = nap.Ts([25, 27, 33.3, 34.5])
>>> shifted_ts = nap.shift_timestamps(ts, min_shift=1, max_shift=1, mode="drop")
>>> shifted_ts
Time (s)
26.0
28.0
34.3
shape: 4

The last timepoint falls outside the time support, so it is dropped.

With multiple epochs, timestamps falling outside the support anywhere are dropped:

>>> epochs = nap.IntervalSet(start=[25, 30], end=[27, 34.5])
>>> ts = nap.Ts([25, 27, 33.3, 34.5], time_support=epochs)
>>> shifted_ts = nap.shift_timestamps(ts, min_shift=1, max_shift=1, mode="drop")
>>> shifted_ts
Time (s)
26.0
34.3
shape: 3

Using mode='wrap' to circularly wrap timestamps within the full time support:

>>> epochs = nap.IntervalSet(start=0, end=40)
>>> ts = nap.Ts([38, 39.5], time_support=epochs)
>>> shifted_ts = nap.shift_timestamps(ts, min_shift=5, max_shift=5, mode="wrap")
>>> shifted_ts
Time (s)
3.0
4.5
shape: 2

When mode='wrap' and there are multiple epochs, the start and end are circular, but everything in between is not:

>>> import pynapple as nap
>>> epochs = nap.IntervalSet(start=[25, 30], end=[27, 34.5])
>>> ts = nap.Ts([25, 27, 33.3, 34.5], time_support=epochs)
>>> shifted_ts = nap.shift_timestamps(ts, min_shift=1, max_shift=1, mode="wrap")
>>> shifted_ts
Time (s)
26.0
26.0
34.3
shape: 3
pynapple.process.randomize.shuffle_ts_intervals(ts)[source]#

Randomizes the timestamps by shuffling the intervals between them.

Parameters:

ts (Ts or TsGroup) – The timestamps to randomize. If TsGroup, randomizes all Ts in the group independently.

Returns:

The randomized timestamps, with shuffled intervals

Return type:

Ts or TsGroup