aind_ephys_utils.align module

Module to align two sorted temporal sequences (usually spike times and events).

aind_ephys_utils.align.align_to_events(times, events, interval, bin_size=None, event_labels=None, unit_ids=None, return_df=False, spike_times_key='spike_times')

Alias for to_events

aind_ephys_utils.align.events_to_dataset(events: DataArray) → Dataset

Convert a canonical events DataArray into a Dataset with a t variable.

Parameters:

events – Events DataArray with dims (trial, event, bound). The bound coord should include "start" and "end". The returned Dataset uses the "start" bound by default.

Returns:

Dataset with variable t containing event times.

Return type:

xr.Dataset

aind_ephys_utils.align.to_events(times, events, interval, bin_size=None, event_labels=None, unit_ids=None, return_df=False, spike_times_key='spike_times')

Aligns spikes times (sorted in ascending order) to a set of event times

Spike times can take the following formats: - 1-dimensional ndarray of times for one unit - list of 1-dimensional ndarrays of times for multiple units - dict of 1-dimensional ndarrays with unit IDs as keys - DataFrame indexed by unit IDs, with a “spike_times” column

If the optional bin_size argument is supplied, the spike times are binned.

If return_dataframe is set to True, the results will be returned as a pandas DataFrame (or xarray.DataArray if results are binned)

Parameters:

• times (ndarray, List[ndarrays], dict, or DataFrame) – 1-D sequence(s) of times to align (in seconds). Must be sorted in ascending order.

• events (ndarray) – 1-D sequence of reference times (in seconds).

• interval (tuple) – Start and end of the window around each event (in seconds).

• bin_size (float, optional) – Bin size (in seconds); if None, then individual times will be returned.

• unit_ids (List[int]) – Labels for each unit. If len(unit_ids) < len(times) and times is dict or DataFrame, then this argument will specify which units to align.

• event_labels (List[int] or List[str]) – Labels for each event (optional).

• return_df (bool, optional (default = False)) – If True, returns the results as a pandas DataFrame (or xarray.DataArray if binning is enabled).

• spike_times_key (str, optional (default = 'spike_times')) – If ‘times’ argument is a DataFrame, this specifies the name of the column containing the spike times.

Returns:

• if return_df = False and bin_size = None

• aligned_times (ndarray) – 1-D sequence of times relative to the events of interest.

• event_indices (ndarray) – 1-D sequence of associated event index for each time in aligned_times.

• unit_ids (list or ndarray) – 1-D sequence of unit IDs for each sequence of spike times

• if return_df = False and bin_size is not None

• bins (ndarray) – 1-D sequence of time bin left edges

• counts (ndarray) – 2-D or 3-D array of spike counts of size trials x bins (x units)

• unit_ids (ndarray) – 1-D sequence of unit IDs

• if return_df = True and bin_size = None

• df (pd.DataFrame with columns:) –

  • time : aligned times

  • event_index : event index for each time

  • event_label : event label for each time (optional)

  • unit_id : unit label for each time (optional)

• if return_df = True and bin_size is not None

• da (xr.DataArray with dimensions:) –

  • time : time relative to each event

  • event_index or event_label : label for each event

  • unit_id : label of each unit