PhysResponse¶

The PhysResponse class combines physiological and stimulation data into an object that can access physiological data across a stimulation parameter easily. The PhysResponse is very similar to the ECAP class, except that data is accessed across an entire parameter instead of one stimulation pulse. This is more suitable for analyzing physiological data such as heart rate and blood pressure because the changes often occur over a longer period of time. An explanation of stimulation parameters can be found in the documentation for the ECAP class.

Instantiating a PhysResponse object can be done with a Phys object, a Stim object, and the name of a trigger channel.

class pyeCAP.phys_response.PhysResponse(phys_data, stim_data, trigger_channel, threshold=1, time_difference=0, search=1, **kwargs)¶

Class for indexing physiological data with stimulation parameters and viewing the response to stimulation.

__init__(phys_data, stim_data, trigger_channel, threshold=1, time_difference=0, search=1, **kwargs)¶

Constructor for the PhysResponse class.

Parameters

phys_data (_TsData or subclass) – Phys object containing the raw data.
stim_data (Stim or PhysStim object) – Object containing stimulation data.
trigger_channel (str, None) – Channel that contains data for stimulation trigger pulses. Used to sync the Phys and Stim data times. Use None to create an object without a trigger channel (not recommended).
threshold (float) – Minimum value to register as a stimulation pulse
time_difference (float) – Time difference in seconds between the clocks of the computers that recorded the stimulation and physiological data. A time_difference of 3600 would correct an error where the time of the phys_data leads the stim_data by 1 hour.
search (float) – Maximum time difference to search for a pulse in the trigger channel in seconds. With a search of 1, pyeCAP will search all data points between 1 second before and after the time given by the stimulation data.
kwargs (**) – See _DioEpoch for more information

Examples

>>> # Set up a PhysResponse object with trigger as "Channel 6" and default parameters.
>>> response_data = pyeCAP.PhysResponse(phys_data, stim_data, "Channel 6")    

Timing Synchronization¶

The purpose of timing synchronization is to take stimulation parameter start/stop times and convert them to times that can be used to access the physiological data. The basic approach of pyeCAP is to take start times from stimulation data, convert them to a unix timestamp, match them with the closest trigger pulse in the physiological data, then convert the timestamp of the trigger pulse into an elapsed time since the start of the physiological data. Physiological data from ADInstruments and stimulation data from TDT or Ripple are often collected on different machines. The internal timing of these machines is separate, so synchronizing the timing is extremely important in order to ensure accurate results from data analysis. pyeCAP provides several methods of time synchronization. The following are parameters of the PhysResponse constructor and their roles in time synchronization:

trigger_channel :
A trigger channel is used to register changes in stimulation amplitude which indicate the start of a stimulation parameter. The TDT or Ripple machine can be set up to send a pulse to the ADInstruments machine whenever this occurs. By setting up a channel to register these pulses, small errors in timing between the two machines can be eliminated. pyeCAP is built to find these trigger pulses in the physiological data and use them as start times for a stimulation parameter as opposed to using the times from the stimulation data. The stimulation data provides an approximate time to search for a pulse but not the exact time. If the trigger channel is passed in as None, pyeCAP will use the timing of the stimulation data and neglect trigger pulses when determining stimulation start/end times.
threshold :
This is the value used to detect changes in stimulation amplitude. pyeCAP iterates over values in the trigger channel and any values greater than the threshold are registered as possible stimulation parameters.
search :
This parameter is used to specify the time period to search for a pulse on the trigger channel. pyeCAP pulls an approximate parameter start time from the stimulation data. Setting search to 1 would search the time from 1 second before to 1 second after the start time of the stimulation data. The pulse which is closest to the start time from the stimulation data is used. NOTE: search treats gap times between data sets as non-existent.
time_difference :
This parameter is only necessary when there is a large time difference between the computer times of the physiological and stimulation data. An example of this would be if one computer had changed its time because of daylight savings but the other computer had not. A time difference of 3600 would correct an error where the physiology data leads the stimulation data by 3600 seconds.

When instantiating a PhysResponse object, pyeCAP will automatically search for stimulation pulses for every parameter and generate warnings when no stimulation pulse is found. Since it can be time consuming to search for pulses in data with a high sample rate or wide search window, all of the results are stored as trigger offsets. A trigger offset is the time difference between the pulse found in the physiological data and the pulse time recorded in the stimulation data after taking into account any system-wide time difference. A positive trigger offset indicates that the physiological data leads the stimulation data. If no pulse is found on the trigger channel, the trigger offset will become NaN. When the parameter is used, a warning will be generated and the trigger offset will be neglected. The get_trigger_offsets, and set_trigger_offsets methods shown below can be used to view and customize the trigger offsets.

The following diagram shows how pyeCAP uses system-wide time difference and trigger offsets to determine the start of a stimulation parameter:

Customizing Trigger offsets¶

It is possible to analyze data with pyeCAP with custom trigger offsets or without using trigger offsets at all. If ignoring trigger offsets, set the trigger_channel parameter to None when instantiating an object or pass the compute=False argument to the PhysResponse constructor. All trigger offsets will be initialized as 0, meaning that the only variables used to calculate the stimulation stop and start times are stimulation data and the time_difference parameter. Warnings about trigger pulses not being found will not appear. To pass in custom trigger offsets, create a dictionary with keys as stimulation parameters and values as trigger offsets. Pass this dictionary to the PhysResponse constructor with the trigger_offsets keyword argument. Be sure to set compute=False, otherwise trigger offsets will automatically be computed based on other parameters.

Warnings¶

pyeCAP will warn users of data that may not be properly synchronized or is interrupted by other stimulation parameters or block starting and ending times. The following are PhysResponse warnings:

“No trigger pulse found for stimulation parameter {}”
“Stimulation period interrupted by start/end of block at parameter {}”
“block start/end period during baseline”
“Other Stimulation period occurs during baseline”

Warnings about trigger pulse are generated when a Phys object is created. Other warnings can be generated by calling the verify_parameters method. It is recommended to call this method on all parameters that will be used in data analysis to ensure proper timing synchronization.

_DioEpoch¶

The _DioEpoch class is the parent class of PhysResponse. All methods for the PhysResponse class are inherited from _DioEpoch. The class contains getter/setter methods for each of the parameters relating to time synchronization. The class also contains methods to access, plot, and determine change from baseline over a stimulation parameter.

class pyeCAP.base.dio_epoch._DioEpoch(ts_data, dio_data, trigger_channel, parameter_data=None, threshold=1, time_difference=0, search=1, compute=True, trigger_offsets=None)¶

Class for analyzing data based on stimulation onset and offset times

__init__(ts_data, dio_data, trigger_channel, parameter_data=None, threshold=1, time_difference=0, search=1, compute=True, trigger_offsets=None)¶

Constructor for the _DioEpoch class.

Parameters

ts_data (_TsData or subclass) – Time series data such as Phys or Ephys data.
dio_data (_DioData or subclass) – Data referencing stimulation start and stop times.
trigger_channel (str) – Channel that contains data for stimulation trigger pulses. Used to sync the Phys and Stim data times.
parameter_data (_ParameterData or subclass, None) – Data referencing stimulation parameters. Use None if dio_data and parameter_data reference the same object.
threshold (float) – Minimum value to register as a stimulation pulse.
time_difference (float) – Time difference in seconds between the clocks of the computers that recorded the stimulation and physiological data. A time_difference of 3600 would correct an error where the time of the phys_data leads the stim_data by 1 hour.
search (float) – Maximum time difference to search for a pulse in the trigger channel in seconds. With a search of 1, pyCAP will search all data points between 1 second before and after the time given by the stimulation data.
compute (bool) – True to compute trigger offsets for each pulse when instantiating, False to ignore trigger offsets, or pass in custom trigger offsets
trigger_offsets (dict) – Dictionary matching parameter with trigger offset. Only used if compute is False or trigger_channel is None.

get_ts_data()¶

Getter method for the time series data.

Returns: Time series data.
Return type: _TsData or subclass

Examples

>>> response_data.get_ts_data()     

get_stim_data()¶

Getter Method for stimulation data. Specifically returns the dio_data used to create the object.

Returns: Stimulation data.
Return type: _DioData or subclass

get_parameter_data()¶

Getter method for stimulation parameter data in DataFrame format.

Returns: Pandas DataFrame containing stimulation parameters.
Return type: pandas.core.frame.DataFrame

get_time_difference()¶

Getter method for the user-specified time difference between the Physiological and Stimulation data sets.

Returns: Time difference in seconds
Return type: int, float

get_trigger_channel()¶

Getter method for the user-specified stimulation trigger channel.

Returns: Channel name.
Return type: str

get_threshold()¶

Getter method for the user-specified threshold to define a stimulation pulse.

Returns: Stimulation threshold.
Return type: int, float

get_trigger_offsets(parameters=None)¶

Getter method for stimulation trigger offsets (in seconds). Trigger offsets are defined as the time difference between the detected pulse in the trigger channel and the stimulation data. A trigger offset of 0.5 means that that the detected pulse leads the stimulation data by 0.5 seconds.

Parameters: parameters (None, list) – List of parameters to get the trigger offsets for, or None to get the trigger offsets of all parameters.
Returns: Python dictionary with keys as parameters and values as trigger offsets.
Return type: dict

get_search()¶

Getter method for the user-specified search window for stimulation trigger pulses.

Returns: Maximum time difference to search for a pulse in the trigger channel in seconds.
Return type: int, float

set_trigger_channel(new_channel)¶

Resets the trigger channel to new_channel. Warning : This will re-compute the trigger offsets which may be time consuming and will reset any user-specified trigger offsets.

Parameters: new_channel (str) – Channel from the physiological data to search for
Returns: New class instance with a different trigger_channel and recomputed trigger offsets.
Return type: _DioEpoch or subclass

set_threshold(new_threshold)¶

Resets the threshold for stimulation detection to new_threshold. Warning : This will re-compute the trigger offsets which may be time consuming and will reset any user-specified trigger offsets.

Parameters: new_threshold (int, float) – New Threshold to detect stimulation pulses.
Returns: New class instance with a different threshold and recomputed trigger offsets.
Return type: _DioEpoch or subclass

Examples

>>> # create a new object with a threshold of 3.
>>> new_response_data = response_data.set_threshold(3)      

set_time_difference(new_time_difference)¶

Resets time difference between the physiological and stimulation data sets. Warning : This will re-compute the trigger offsets which may be time consuming and will reset any user-specified trigger offsets.

Parameters: new_time_difference (int, float) – New time difference to reset the time difference.
Returns: New class instance with a different time_difference and recomputed trigger offsets.
Return type: _DioEpoch or subclass

set_trigger_offsets(parameters, offsets)¶

Resets trigger offsets for the specified parameters with the specified offsets. Parameters and offsets must line up by index in order for them to be matched properly.

Parameters

parameters (list) – List of parameters to reset trigger offsets for.
offsets (list) – List of offsets to use when resetting the parameters.

Returns

New class instance with the specified trigger offsets changed.

Return type

_DioEpoch or subclass

Examples

>>> # create a new object with trigger offsets reset to 0.5s for parameters (0,0), (0,1), and (0,2).
>>> new_response_data = response_data.set_trigger_offsets([(0,0), (0,1), (0,2)], [0.5, 0.5, 0.5])      

set_search(new_window)¶

Resets search window to new_window. The search window is defined as the maximum time difference relative to the stimulation data to search for a trigger pulse. Warning : This will re-compute the trigger offsets which may be time consuming and will reset any user-specified trigger offsets.

Parameters: new_window (int, float) – New search window.
Returns: New class instance with a different search and recomputed trigger offsets.
Return type: _DioEpoch or subclass

parameter_time(parameter)¶

Finds the start and end time of the given parameter. Times are in seconds relative to the start time of the physiological data.

Parameters: parameter (tuple) – Stimulation parameter. Composed of index for the data set and index for the stimulation.
Returns: Start time followed by end time in a python tuple.
Return type: tuple

Examples

>>> # get start time and end time of the parameter (0,0)
>>> start_time, end_time = response_data.parameter_time((0,0))      

array(parameter, onset=0, offset=0, channels=None, delayed=False)¶

Generates an array of raw physiological data from the specified parameter with the specified onset and offset.

Parameters

parameter (tuple) – Stimulation parameter. Composed of index for the data set and index for the stimulation.
onset (int, float) – Time to include before the stimulation start time (-2.0 will include 2.0 seconds of data before stimulation onset).
offset (int, float) – Time to include after the stimulation end time (2.0 will include 2.0 seconds of data after the stimulation ending).
channels (str, list) – Channel name or list of channel names to include in the data array

Returns

Array of raw time series data.

Return type

dask.array.core.Array

Examples

>>> # return array of raw data for the parameter (0,0) across all channels and include 5 seconds of data before
>>> # the start time of the parameter.
>>> response_data.array((0,0), onset=-5, offset=0)      

time(parameter, onset=0, offset=0)¶

Creates an array of points representing time where each point corresponds to a data point in the raw data array.

Parameters

parameter (tuple) – Stimulation parameter. Composed of index for the data set and index for the stimulation.
onset (int, float) – Time to include before the stimulation start time (-2.0 will include 2.0 seconds of data before stimulation onset).
offset (int, float) – Time to include after the stimulation end time (2.0 will include 2.0 seconds of data after the stimulation ending).

Returns

Array of time points in seconds corresponding to each data point starting at the onset time.

Return type

numpy.ndarray

plot_parameter(parameter, channels=None, onset=- 1, offset=1, show=True, events=False, axis=None, fig_size=(10, 6), **kwargs)¶

Plots a parameter with the given channels and onset and offset times.

Parameters

parameter (tuple) – Stimulation parameter. Composed of index for the data set and index for the stimulation.
channels (str, list) – Channel name or list of channel names to plot.
onset (int, float) – Time to include before the stimulation start time (-2.0 will include 2.0 seconds of data before stimulation onset).
offset (int, float) – Time to include after the stimulation end time (2.0 will include 2.0 seconds of data after the stimulation ending).
show (bool) – Set to True to display the plot, False to return the axis and not display the plot.
events (bool) – Set to True to display stimulation event data alongside the parameter data, False to omit event data.
axis (None, matplotlib.axis.Axis) – Either None to use a new axis or matplotlib axis to plot on.
fig_size (list, tuple, np.ndarray) – The size of the matplotlib figure to plot axis on if axis=None.
**kwargs (KeywordArguments) – See _TsData (parent class) for more details.

Returns

Returns subplot and plots nothing, or returns nothing and displays the plot.

Return type

matplotlib.axes._subplots.AxesSubplot, None

Examples

>>> # plot the data for Channel 7 across parameter (0,0) with stimulation raster shown
>>> response_data.plot_parameter((0,0), channels=[0], events=True)        

baseline(parameter, channel, first_onset=- 3, second_onset=- 1)¶

Calculates baseline values for a parameter from the period before stimulation given the starting and ending onset times before stimulation occurs.

Parameters

parameter (tuple) – Stimulation parameter. Composed of index for the data set and index for the stimulation.
channel (str) – Channel name.
first_onset (int, float) – Time to start measuring baseline before stimulation onset (Negative numbers reference times before stimulation onset).
second_onset (int, float) – Time to finish measuring baseline before stimulation onset (Negative numbers reference times before stimulation onset).

Returns

Array of floats representing the baseline for each channel.

Return type

numpy.ndarray

Examples

>>> # get baseline for Channel 7 of parameter (0,0) for the time period 5 to 1 seconds prior to stimulation
>>> baseline = response_data.baseline((0,0), channel=0, first_onset=-5)       

delta(parameter, channel, first_onset=- 3, second_onset=0, offset=0, method=None)¶

Calculates changes in values at the specified channels due to stimulation. First calculates a baseline from the onset times, then compares the baseline to a maximum or minimum value across the stimulation period.

Parameters

parameter (tuple) – Stimulation parameter. Composed of index for the data set and index for the stimulation.
channel (str) – Channel name.
first_onset (int, float) –

Time to start measuring baseline before stimulation onset (Negative numbers reference times before
stimulation onset).
second_onset (int, float) –

Time to finish measuring baseline before stimulation onset (Negative numbers reference times before
stimulation onset).
offset (int, float) –

Time after stimulation period finishes to search for a maximum(positive numbers reference times after
stimulation ends).
method (None, str) – Use “maximum” to find the maximum and “minimum” to find the minimum. Default None will find the largest change which could be maximum or minimum.

Returns

Dictionary containing baseline, extreme value, and absolute change.

Return type

dict

Examples

>>> # get largest change from Channel 7 on parameter (0,0)
>>> delta_dict = response_data.baseline((0,0), "Channel 7", first_onset=-5)       
>>> change = delta_dict["absolute change"]      

verify_parameters(parameters=None, baseline=3, plot=False)¶

Method to verify that stimulation parameters are referring to the correct time in the physiological data set. This method will generate warnings for inadequate baseline, inability to find a trigger pulse, or interruptions by start and end time of blocks. This method will plot all of the parameters in the order specified to aid in debugging.

Parameters

parameters (list) – List of parameters to verify.
baseline (int, float) – Seconds of baseline to verify. A baseline of 3 will verify that there are 3 seconds of uninterrupted baseline before the parameter start time.
plot (bool) – Set to True to create plot figures for each parameter and store them in the output dictionary.

Returns

Dictionary containing verification information.

Return type

dict

Examples

>>> # check for any errors in the parameters (0,0) and (0,1) with a 5 second baseline period
>>> response_data.verify_parameters([(0,0), (0,1)], baseline=5)     

dio(channel)¶

Outputs an array containing starting and stopping times for stimulation periods for a given channel. Start/stop times are relative to the start of the time series data object with no gaps between data sets.

Parameters: channel (str) – Name of channel.
Returns: Array containing start and stop times of the stimulation data.
Return type: numpy.ndarray