Ephys

The Ephys class provides several ways to work with electrophysiology data. An Ephys object is usually instantiated with only a path name to a ripple file or TDT tank or a list of path names.

class pyeCAP.ephys.Ephys(data, *args, stores=None, order=True, rz_sample_rate=None, si_sample_rate=None, sample_delay=None, **kwargs)

Class for working with Ephys objects.

__init__(data, *args, stores=None, order=True, rz_sample_rate=None, si_sample_rate=None, sample_delay=None, **kwargs)

Ephys constructor.

Parameters

  • data (str, list) – path name or list of pathnames for a directory of TDT data

  • args (*) – Arguments to be passed to _TsData (parent class) constructor.

  • stores (None, list, tuple) – Sequence of tdt store names to include in the object, or None to include all stores.

  • order (bool) – Set to True to order data sets by start time. Since data from the same file is read in chronological order, this will only have an effect when reading in data from multiple files.

  • rz_sample_rate (int) – Sample rate (in kHz) of the rz processor of a TDT system.

  • si_sample_rate (int) – Sample rate (in kHz) of the PZ5 processor of a TDT system.

  • sample_delay (int, list) – Int to add one sample delay to all channels, or a list to add individual sample delays. The list must be the same length as the number of channels and each sample in the list matches the channels by order. Specify offsets as positive to show

  • kwargs (**) – Keyword arguments to be passed to _TsData (parent class) constructor.

Examples

>>> pyeCAP.Ephys(pathname1)   # replace pathnames with paths to data      

>>> pyeCAP.Ephys([pathname1, pathname2, pathname3])

Sample Delays

TDT recording devices are sometimes configured in a way that creates delays between different Ephys channels or between a stimulation channel and Ephys channels. The delay is expressed in terms of number of samples and can depend on sample rate and gizmo configuration. More information can be found at https://www.tdt.com/files/fastfacts/IODelays.pdf

In order to take these delays into account, the rz_sample_rate, si_sample_rate, and sample_delay parameters are passed into the Ephys constructor. The rz and si sample rate parameters refer to the table found at https://www.tdt.com/files/fastfacts/IODelays.pdf . Inputting these parameters will correct for uniform delays for each channel by removing samples from the start of each data set in order to line up stimulation timing with Ephys data timing. Additional sample delays can be specified with the sample_delay parameter. Input sample delays as an integer to apply the sample delay to all channels or as a list (with same length as number of channels) to specify a sample delay for individual channels. Specify sample delays as positive to chop off samples from the start of the data set. Although negative sample delays will not cause the code to crash, no samples will be eliminated and the data will be treated as if no sample delays were entered.

_TsData (parent class)

The Ephys and Phys classes inherit the majority of methods from the _TsData class. There are several categories of methods including:

  • Plotting Methods:

    Methods for plotting raw or processed data and experiment times.

  • Channel Methods:

    Methods that set channel names, types, or re-reference channels by creating a new class instance with different channels.

  • Filtering Methods:

    These methods are used to filter time series data. They are useful for eliminating noise and unwanted frequencies from the data. These methods return a new class instance with filtered data.

  • Utility Methods:

    These methods are mainly used by other _TsData methods. However, they can be used to process the data at a lower level with a greater degree of control.

  • Property Methods:

    Getter Methods using the @property decorator. These contain important metadata or ways to work with the time series data as an array.

class pyeCAP.base.ts_data._TsData(data, metadata, chunks=None, daskify=True, thread_safe=True, fancy_index=True, order=True, ch_offsets=None)

Class for time series data. Contains many of the methods for the pyCAP.Ephys child class.

__init__(data, metadata, chunks=None, daskify=True, thread_safe=True, fancy_index=True, order=True, ch_offsets=None)

Constructor for time series data objects.

Parameters

  • data (list) – List of arrays of input data.

  • metadata (list) – List of experiment metadata dictionaries.

  • chunks (None, list) – Dask chunks of the input data, or None to pull the chunks from the input data.

  • daskify (bool) – Set to True to convert input data into a dask array.

  • thread_safe (bool) – Set to True to create a lock if daskify is True.

  • fancy_index (bool) – Set to True to support fancy indexing if daskify is True.

  • order (bool) – Set to True to order data sets by start time. Since data from the same file is read in chronological order, this will only have an effect when reading in data from multiple files.

  • ch_offsets (None, list) – List of the same length as the number of channels. Each number corresponds to a channel offset in units of samples. This corrects for errors in timing between channels in TDT systems. Channel offsets are negative, and delete the first samples of the corresponding channel in order to change the timing difference between channels. Set to None to ignore any channel offsets.

Plotting methods

plot(axis=None, channels=None, events=None, x_lim=None, y_lim='auto', ch_labels=None, colors=sns.color_palette(), fig_size=(10, 6), down_sample=True, show=True)

Method for plotting time series data.

Method for plotting time series data using matplotlib. Also allows for interactive plots within a jupyter notebook, or jupyter lab based on ipython widgets. If show is set to ‘notebook’ this method will display an interactive plot in a jupyter notebook (only works within a jupyter notebook). If show is True a plot will be diplayed. If show is False then a plot will not be displayed but a matplotlib axis will be returned.

Parameters

  • axis (None, matplotlib.axis.Axis) – Either None to use a new axis or matplotlib axis to plot on.

  • channels (int, str, list, tuple, np.ndarray) – Channels to plot. Can be a boolean numpy array with the same length as the number of channels, an integer array, or and array of strings containing channel names.

  • events (_DioData, _EventData, or subclass) – Event data to plot alongside time series data.

  • x_lim (None, list, tuple, np.ndarray) – None to plot the entire data set. Otherwise tuple, list, or numpy array of length 2 containing the start of end times for data to plot.

  • y_lim (None, str, list, tuple, np.ndarray) – None or ‘auto’ to automatically calculate reasonable bounds based on standard deviation of data. ‘max’ to plot y axis limits encompassing all accessible data. Otherwise tuple, list, or numpy array of length 2 containing limits for the y axis.

  • ch_labels (list, tuple, np.ndarray) – Stings to use as channel labels in the plot. Must match length of channels being displayed.

  • colors (list) – Color palette or list of colors to use for channels.

  • fig_size (list, tuple, np.ndarray) – The size of the matplotlib figure to plot axis on if axis=None.

  • down_sample (bool) – Down sample data to optimize display speed. WARNING: This changes the frequency components of the plot. Defaults to True.

  • show (str, bool) – String ‘notebook’ to plot interactively in a jupyter notebook or boolean value indicating if the plot should be displayed.

  • remove_gaps (bool) – Set to False to plot gaps in the data

Returns

If show is ‘notebook’ returns an ipython app. Otherwise returns a matplotlib axis.

Return type

matplotlib.axis.Axis, ipywidgets.widgets.widget_templates.AppLayout

Examples

>>> ephys_data.plot()       # plots data with default settings      

>>> # plots data with x limit and stimulation data
>>> ephys_data.plot(events=stim_data, x_lim=(0,5), y_lim=(0,1))
plot_times(*args, axis=None, events=None, x_lim=None, fig_size=(10, 2), show=True, **kwargs)

Plots the times when experiments represented by the data sets were conducted. Useful for visualizing experiment duration and experiment timing relative to other experiments.

Parameters

  • args (*) – y_min, y_max are possible arguments. Float from 0-1 representing the height of the time bar relative to the height of the plot.

  • axis (None, matplotlib.axis.Axis) – Either None to use a new axis or matplotlib axis to plot on.

  • events (_DioData, _EventData, or subclass) – Event data to plot alongside time series data.

  • x_lim (None, list, tuple, np.ndarray) – None to plot the entire data set. Otherwise tuple, list, or numpy array of length 2 containing the start of end times for data to plot.

  • fig_size (list, tuple, np.ndarray) – The size of the matplotlib figure to plot axis on if axis=None.

  • show (bool) – Set to True to display the plot and return nothing, set to False to return the plotting axis and display nothing.

  • kwargs (**) – See mpl.axes.Axes.axvspan and mpl.axes.Axes.axvline for details on plot customization.

Returns

  • # Todo (check return)

  • matplotlib.axis.Axis, None – If show is False, returns a matplotlib axis. Otherwise, plots the figure and returns None.

Examples

>>> ephys_data.plot_times()
plot_psd(axis=None, x_lim=None, y_lim=None, show=True, *args, fig_size=(10, 3), nperseg=None, colors=sns.color_palette(), **kwargs)

Plots Power Spectral Density (PSD) (V**2/Hz) vs. Frequency (Hz) using the Welch method and 50 percent overlap.

Parameters

  • axis (None, matplotlib.axis.Axis) – Either None to use a new axis or matplotlib axis to plot on.

  • x_lim (None, list, tuple, np.ndarray) – None to plot the entire data set. Otherwise tuple, list, or numpy array of length 2 containing the start of end times for data to plot.

  • y_lim (None, list, tuple, np.ndarray) – Use None to have the y axis span the entire distribution. Otherwise, use a tuple or other two element sequence to specify limits for the y axis. This function plots the y-axis on a log scale.

  • show (bool) – Set to True to display the plot and return nothing, set to False to return the plotting axis and display nothing.

  • args (*) – See scipy.signal.welch for more information.

  • fig_size (list, tuple, np.ndarray) – The size of the matplotlib figure to plot axis on if axis=None.

  • nperseg (None, int) – The segment length. Sample rate is used if not specified.

  • colors (list) – Color palette or list of colors to use for channels.

  • kwargs (**) –

    See scipy.signal.welch for more information.

Returns

If show is False, returns a matplotlib axis. Otherwise, plots the figure and returns None.

Return type

matplotlib.axis.Axis, None

Channel Methods

set_ch_names(ch_names)

Method for renaming channels.

Parameters

ch_names (list) – List of channel names.

Returns

New class instance with renamed channels.

Return type

_TsData or subclass

See also

ch_names

Examples

>>> new_channels = ["LIFE1", "LIFE2", "LIFE3", "LIFE4", "EMG1", "EMG2", "EMG3", "EMG4", "T1", "T2", "T3", "T4", "E1", "E2", "E3", "E4"]
>>> renamed_data = ephys_data.set_ch_names(new_channels)
>>> renamed_data.ch_names
['LIFE1', 'LIFE2', 'LIFE3', 'LIFE4', 'EMG1', 'EMG2', 'EMG3', 'EMG4', 'T1', 'T2', 'T3', 'T4', 'E1', 'E2', 'E3', 'E4']
set_ch_types(ch_types)

Method for setting the type of each channel.

Parameters

ch_types (list) – List of channel types

Returns

New class instance with channel types reset.

Return type

_TsData or subclass

Examples

>>> ephys_data.set_ch_types(['L','L','L','L','E','E','E','E','L','L','L','L','E','E','E','E'])

See also

ch_types

remove_ch(channels, invert=False)

Method for removing channels from time series data objects.

Parameters

  • channels (int, str, list) – Name of a channel in the form of a string or index of the channel list from property method ch_names. This method will also accept a list of channel names or indices.

  • invert (bool) – Default false will remove the specified channels. Invert = True will remove all channels except the ones specified in the channels parameter.

Returns

New class instance with specified channel names removed.

Return type

_TsData or subclass

Examples

>>> ephys_data.remove_ch("RawE 1")
channel_reference(channel, ch_type=None)

Creates a new object with specified channel types re-referenced to the specified channel.

Parameters

  • channel (int, str) – Name or index of the channel to be used as the reference channel.

  • ch_type (str, list) – Specifies channel type or list of types to apply the channel reference to. Use ‘None’ to re-reference all channels.

Returns

Class instance with channels referenced to specified channel.

Return type

_TsData or subclass

Examples

>>> ephys_data.channel_reference(channel = 'RawE 1')
common_reference(ch_type=None, method='mean')

Creates a new object with specified channel types re-referenced to a common mean or median.

Parameters

  • ch_type (None, str, list) – Channel type or list of types that the common reference will be applied to. Use ‘None’ to re-reference all channels.

  • method (str) – Enter in ‘mean’ use a mean common reference and ‘median’ to use a median common reference.

Returns

Class instance with channels referenced to mean or median.

Return type

_TsData or subclass

Examples

>>> ephys_data.common_reference(method = 'mean')

Filtering Methods

filter_fir(cutoff, width=None, filter_length='auto', window='hamming', pass_zero=True)

Filters the frequencies specified in the ‘cutoff’ parameter with a finite impulse response (fir) filter.

Parameters

  • cutoff (float, list, tuple) – Cutoff frequency or increasing sequence specifying band edge frequencies (Hz). Frequencies must be between 0 and self.sample_rate/2.

  • width (None, float) – Width of the transition region in Hz.

  • filter_length (str) –

    ??

  • window (str, tuple) – Window type. See scipy.signal.get_window documentation for more information. for more information.

  • pass_zero (bool, str) – If True, gain at 0 is 1, if False, the gain is 0.

Returns

New class instance of the same type as self which contains the filtered data.

Return type

_TsData or subclass

filter_iir(Wn, rp=None, rs=None, btype='band', order=1, ftype='butter')

Filters the data with an infinite impulse response (iir) filter with the scipy.signal.iirfilter method.

Parameters

  • Wn (list, tuple) – Sequence with 2 elements containing critical frequencies.

  • rp (None, float) – Maximum ripple in the passband in decibels for Chebyshev and ellipitic filters.

  • rs (None, float) – Minimum attenuation in the stop band for Chebyshev and ellipitic filters.

  • btype (str) – Use ‘band’, ‘bandpass’, ‘lowpass’, ‘highpass’, or ‘bandstop’ to specify type of filter.

  • order (int) – Order of the filter. Default is 1.

  • ftype (str) – Use ‘butter’ for Butterworth filter, ‘cheby1’ for Chebyshev I filter, ‘cheby2’ for Chebyshev II filter, ‘ellip’ for elliptic filter, ‘bessel’ for Bessel filter.

Returns

New class instance of the same type as self which contains the filtered data.

Return type

_TsData or subclass

filter_median(kernel_size=201, btype='lowpass')

Filters the channels using a median filter. The median filter slides across the data set and replaces each data point with the median of surrounding entries using the scipy.ndimage.median_filter method. The median filter is a nonlinear filter useful for noise and spike elimination.

Parameters

  • kernel_size (int) – The size of the ‘window’ used in the median filter.

  • btype (str) – Use ‘lowpass’ or ‘low’ to attenuate high frequency signals. Use ‘highpass’ or ‘high to attenuate low frequency signals.

Returns

New class instance of the same type as self which contains the filtered data.

Return type

_TsData or subclass

filter_gaussian(Wn, btype='lowpass', order=0, truncate=4.0)

Filters the channels using a gaussian filter using the scipy.ndimage.guassian_filter1d method.

Parameters

  • Wn (int, float) – Corner frequency

  • btype (str) – Use ‘lowpass’ or ‘low’ to attenuate high frequency signals. Use ‘highpass’ or ‘high to attenuate low frequency signals.

  • order (int) – The order of the kernel. 0 corresponds to a filter with a Gaussian kernel. 1 corresponds to the derivative, ect.

  • truncate (float) – Number of standard deviations to include in Gaussian filter kernel

Returns

New class instance of the same type as self which contains the filtered data.

Return type

_TsData or subclass

filter_powerline(frequencies=[60, 120, 180], notch_width=None, trans_bandwidth=1.0)

Filter powerline noise from time series data.

This function filters data with a series of notch filters at defined frequencies. Filtering frequencies default to 60, 120, and 180 Hz, which are appropriate for 60Hz line noise common in the United States. A fir filter is constructed with a hamming window and filter design is performed with scipy.signal.firwin. Filtering is performed with self.filter_fir. This function is set up with similar default parameters to mne.notch_filter from the mne-python toolkit.

Parameters

  • frequencies (list, tuple, np.ndarray, int, float) – Frequencies at which to filter in Hz. Defaults to 60, 120, and 180 Hz.

  • notch_width (list, tuple, np.ndarray, int, float) – Width of notch at each filter frequency. Defaults to freq / 200 if set to None.

  • trans_bandwidth (int, float) – Width of transition band in Hz.

Returns

New class instance of the same type as self which contains the filtered data.

Return type

_TsData or subclass

See also

filter_fir, filter_iir

Utility Methods

_time_to_index(time, units='seconds', remove_gaps=True)

Converts an elapsed time into an index. This index corresponds to the array index of the data point at the specified time.

Parameters

  • time (int, str) – Elapsed time.

  • units (str) – Units of the ‘time’ parameter. Enter ‘seconds’, ‘milliseconds’, or ‘microseconds’.

  • remove_gaps (bool) – Set to False to take into account time gaps in the data.

Returns

Array index corresponding to the data at the time input.

Return type

int

Examples

>>> ephys_data._time_to_index(5)
122070
_time_lim_validate(x_lim, remove_gaps=True)

Checks whether a time limit with a start and end time is valid. Returns a tuple of the input time limit or raises an error. Useful for checking x-limits in plotting functions.

Parameters

  • x_lim (None, list, tuple) – Range of times in seconds. Use None to calculate the time limit for the entire data set. Use an iterable such as a list or tuple to input start and end times.

  • remove_gaps (bool) – Set to False to take gaps in the data into account.

Returns

Valid time limit containing start and end time.

Return type

tuple

_ch_to_index(ch)

Returns a boolean array with indices corresponding to the self.ch_names property. A value in the array will be ‘True’ if the channel name is present in the ‘ch’ argument, otherwise the value will be ‘False’.

Parameters

ch (str, list) – Channel name or names for the method to search for.

Returns

A numpy array of boolean values.

Return type

numpy.ndarray

See also

ch_names

_ch_type_to_index(ch_type)

Returns a boolean array with indices matching the self.ch_names property and values indicating whether the channel is of the type specified in the ch_type argument.

Parameters

ch_type (str) – Channel type for the method to search for.

Returns

A numpy array of boolean values.

Return type

numpy.ndarray

See also

ch_names

_to_plt_line_collection(x_lim, channels, d_l, down_sample=True, remove_gaps=True)

Converts raw data into an array that can be used to create a matplotlib line collection. With gaps removed, the list this method returns will be one element. Otherwise, each tuple in the list will correspond to a chunk of data without any gaps.

Parameters

  • x_lim (list, tuple, numpy.ndarray) – Sequence containing the start and end times of the plot (in seconds).

  • channels (int, slice) – Channel index or slice of indices.

  • d_l (int ??) –

    ??

  • down_sample (bool) – Down sample to plot fewer points if True.

Returns

List containging tuples of line collection arrays and boolean indicators.

Return type

list

_to_mne_raw()

Loads raw data set into an array. This method is very computationally and memory intensive.

Returns

Mne array of the raw data set.

Return type

mne.io.array.array.RawArray

Property Methods

property array

Property getter method for a dask array of the raw data for all data sets. All data sets are concatenated into one array by channel.

Returns

Array of the class instance data sets.

Return type

dask.array.core.Array

Examples

>>> ephys_data.array
property shape

Property getter method for the dimensions of the raw data array. Shows number of channels as the first dimension and number of data points as the second dimension.

Returns

Dimensions of the array.

Return type

tuple

See also

array

Examples

>>> ephys_data.shape
(16, 155648)
property ndim

Property getter method for the number of dimensions in the raw data array.

Returns

Number of dimensions in the array.

Return type

int

See also

array

Examples

>>> ephys_data.ndim
2
property dtype

Property getter method for the data type of each element in the raw data array.

Returns

Type of data present in the array.

Return type

numpy.dtpye

See also

array

Examples

>>> ephys_data.dtype
dtype('float32')
property size

Property getter method for the total number of elements in the raw data array.

Returns

Total size of the array.

Return type

int

See also

array

Examples

>>> ephys_data.size
2490368
property itemsize

Property getter method for the storage taken up by a single element in the raw data array.

Returns

Size of each element in bytes.

Return type

int

See also

array

Examples

>>> ephys_data.itemsize
4
property shapes

Property getter method for the dimensions of each data set.

Returns

List of tuples, with each tuple corresponding to the shape property for each data set.

Return type

list

See also

shape

Examples

>>> ephys_data.shapes
[(16, 155648)]
property ch_names

Property getter method for channel names.

Returns

A list of the channel names.

Return type

list

Examples

>>> ephys_data.ch_names
['RawE 1', 'RawE 2', 'RawE 3', 'RawE 4', 'RawG 1', 'RawG 2', 'RawG 3', 'RawG 4', 'LIFt 1', 'LIFt 2', 'LIFt 3', 'LIFt 4', 'EMGt 1', 'EMGt 2', 'EMGt 3', 'EMGt 4']
property ch_types

Property getter method for channel types.

Returns

List of channel types without duplicates.

Return type

list

Examples

>>> ephys_data = ephys_data.set_ch_types(['L','L','L','L','E','E','E','E','L','L','L','L','E','E','E','E'])
>>> sorted(ephys_data.ch_types)     # sort this list to ensure the order is always the same
['E', 'L']
property sample_rate

Property getter method for the sampling rate of the data set.

Returns

Sample rate of the experiment in Hz.

Return type

float

Examples

>>> ephys_data.sample_rate
24414.0625
property start_times

Property getter method for start times of each data set.

Returns

List of start times for each data set in seconds since epoch.

Return type

list

Examples

>>> ephys_data.start_times
[1576541104.999999]
property start_indices

Property getter method for array indices that represent the start of each data set within the dask array. Using these indices allows the raw data in the array property to be divided by data set.

Returns

Array containing the start indices of each data set.

Return type

numpy.ndarray

See also

array

Examples

>>> ephys_data.start_indices
array([0])

# Example code to split the array back into component data sets >>> import numpy as np # doctest: +SKIP >>> np.split(ephys_data.array.compute(), ephys_data.start_indices[1:], axis = 1) # doctest: +SKIP

property end_times

Property getter method for the end time of each data set in seconds since the epoch.

Returns

List containing end times of each data set.

Return type

list

Examples

>>> ephys_data.end_times
[1576541111.3753412]
property ndata

Property getter method for the the number of data sets included.

Returns

Number of data sets in the class instance.

Return type

int

Examples

>>> ephys_data.ndata
1
time(remove_gaps=True)

Property getter method for a dask array of time points for each data set starting at 0 seconds. Each point in the time array corresponds to a point in the raw data array. Times are derived from the sample rate.

Parameters

remove_gaps (bool) – Set to False to take gaps between data sets into account.

Returns

Array of time points.

Return type

dask.array.core.Array

Examples

>>> ephys_data.time