perievent

Functions:

perievent_traces(data_timestamps, data_vals, ...)	Get peri-event traces of data.
perievent_events(discrete_timestamps, ...[, ...])	Get nested list of discrete times that fall within each peri-event window.
event_times_from_train(data_train, ...[, ...])	Return onset (or offset) times for when some boolean timeseries becomes (or stops being) True.
chunk_events(event_times, block_min_spacing, ...)	Return only the event times (and corresponding vals) that are more than block_min_spacing apart.
event_epochs(data_train, data_timestamps[, ...])	Quantifies characteristics (onset, offset, duration, value) of event epochs in a boolean timeseries.
map_values(data_timestamps, data_vals, ...)	Map values of data to event times.

timewizard.perievent.perievent_traces(data_timestamps, data_vals, event_timestamps, time_window, fs=None, ts_err_behav='error')

Get peri-event traces of data. TODO: allow interpolation.

Parameters:

• data_timestamps (array of shape (N,...)) – Timestamps of the data. Must be sorted along the time (0th) axis!

• data_vals (array of shape (N,...)) – The data corresponding to the timestamps.

• event_timestamps (array of shape (M,)) – Times to which to align the data. The output will be sorted in the same order as event_timestamps.

• time_window (tuple (start_offset, end_offset), in the same time base as the data.) – For example, (-2,5) with times in seconds will use a window from 2 seconds before to 5 seconds after each event timestamp.

• fs (int, default=None) – The sampling rate of the data, in Hz. If None, data are not assumed to be regularly sampled, and things are handled more carefully (eg traces will be a nested list instead of a matrix).

• ts_err_behav (str, default="error") – Throw an error if fs but timestamps diffs not all equal. Else if “warn”, report a warning but keep going. # TODO: replace this and other similar arguments with global settings that dictate how much double-checking tw should do of the user’s inputs # This global setting can also obv be overridden with kwargs to specific functions.

Returns:

• times (array of shape (fs * (time_window[1] - time_window[0]),)) – The timestamps for the peri-event traces. If fs is None, this is a nested list of timestamps for each event.

• traces (array of shape (M, fs * (time_window[1] - time_window[0]), …)) – The aligned peri-event data. If fs is None, this is a list of arrays with data for each event

Raises:

ValueError: – If size of data_timestamps and data_vals don’t match.

timewizard.perievent.perievent_events(discrete_timestamps, event_timestamps, time_window, zeroed=True, also_return_indices=False)

Get nested list of discrete times that fall within each peri-event window.

For example, if you have a list of lick times (discrete_timestamps) and a list of trial start times (event_timestamps), you could use this function to get a list of lick times around the start of each trial.

Parameters:

• discrete_timestamps (array of shape (N,)) – Discrete timestamps (i.e. events like licks, spikes, rears, etc.) to be windowed. Must be sorted!

• event_timestamps (array of shape (M,)) – Times to which to align the data. The output will be sorted in the same order as event_timestamps.

• time_window (tuple (start_offset, end_offset), in the same time base as the data.) – For example, (-2,5) with times in seconds will use a window from 2 seconds before to 5 seconds after each event timestamp.

• zeroed (bool, default=True) – If True, returns peri-stimulus timestamps, i.e. t=0 at event onset. If False, returns the un-aligned timestamp.

• also_return_indices (bool, default=False) – If True, return both the times and their indices.

Returns:

• times (list of np.arrays) – List of arrays with times for each peri-stimulus window.

• idxs (list of lists, optional) – List of indices corresponding to the times, returned only if also_return_indices is True.

timewizard.perievent.event_times_from_train(data_train, data_timestamps, mode='raw', kind='onsets', block_min_spacing=None)

Return onset (or offset) times for when some boolean timeseries becomes (or stops being) True.

Parameters:

• data_boolean (array of size (N,) and type bool or signed integers.) – Array of 0s/1s indicating stimulus state (0: OFF, 1: ON). Also acceptable: array with runs of any integer values, interspersed with zeros: [0,0,1,1,1,0,0,0,3,3,3,0,0,0,…] Not acceptable: mixing values within a run: ~[0,0,0,1,2,3,0,0,0,…]~

• data_timestamps (array-like of size (N,)) – Array of timestamps for the data.

• mode (str, default="raw") – Either ‘raw’ for every onset or ‘initial_onset’ for onsets with a gap defined by block_min_spacing.

• kind (str, default="onsets") – Either ‘onsets’ or ‘offsets’.

• block_min_spacing (int, default=None) – Time unit gap required between events if mode is ‘initial_onset’.

Returns:

Indices and timestamps for the onsets.

Return type:

tuple of np.array

timewizard.perievent.chunk_events(event_times, block_min_spacing, *args, kind='onsets')

Return only the event times (and corresponding vals) that are more than block_min_spacing apart.

Parameters:

• event_times (np.array of shape (M,)) – Vector of event times.

• block_min_spacing (int) – Minimum time difference between two events.

• *args (np.arrays of shape (M,)) – Other arrays that will be chunked in the same way as onset_times.

• kind (str, default="onsets") – Specifies if we’re working with “onsets” or “offsets”.

Returns:

Filtered onset times that are more than block_min_spacing apart.

Return type:

np.array

timewizard.perievent.event_epochs(data_train, data_timestamps, mode='raw', block_min_spacing=None)

Quantifies characteristics (onset, offset, duration, value) of event epochs in a boolean timeseries.

Parameters:

data_trainnp.array of shape (N,)

Boolean or integer time series representing the presence (1/True) or absence (0/False) of events.

data_timestampsnp.array of shape (N,)

Timestamps corresponding to the data_train.

modestr, optional (default = “raw”)

Specifies the event quantification mode: - “raw”: Extracts all onsets and offsets as they occur. - “initial_onset”: Consolidates events that are spaced closer than block_min_spacing.

block_min_spacingfloat, optional

Minimum spacing between event epochs. Only relevant if mode is “initial_onset”.

Returns:

dfpd.DataFrame of len N

DataFrame containing the following columns: - ‘onset_index’: Index of event onset in data_train. - ‘onset_time’: Timestamp of event onset. - ‘offset_index’: Index of event offset in data_train. - ‘offset_time’: Timestamp of event offset. - ‘duration’: Duration of the event. - ‘value’: Value of the event at the onset (usually 1 for boolean series).

Raises:

ValueError, TypeError, AssertionError

Various input checks to ensure data integrity.

timewizard.perievent.map_values(data_timestamps, data_vals, event_timestamps, interpolate=False)

Map values of data to event times. If interpolating, thin wrapper around scipy’s interp1d.

Parameters:

• data_timestamps (array of shape (N,...)) – Timestamps of the data. Must be sorted along the time (0th) axis!

• data_vals (array of shape (N,...)) – The data corresponding to the timestamps.

• event_timestamps (array of shape (M,)) – Times to which to align the data. The output will be sorted in the same order as event_timestamps.

• interpolate (bool, default=False) – If False, use the value at the nearest timestamp. If True, use interp1d to interpolate between timestamps.

Returns:

vals – The signal value at each event time.

Return type:

array of shape (M, …)

Raises:

ValueError: – If size of data_timestamps and data_vals don’t match.