Stim

The Stim class along with parent classes handle stimulation metadata, parameters, and times of stimulation events. This data can be used to view times at which stimulation occurred, stimulation amplitudes, stimulation frequencies, and more. The Stim class uses pandas DataFrames to view these parameters. Similar to the Ephys class, there are plotting methods as well as methods for working with channels.

class pyeCAP.stim.Stim(file_path, io=None, events=None, event_indicators=None, dio=None, dio_indicators=None, parameters=None, metadata=None)

Class for working with stimulation data.

__init__(file_path, io=None, events=None, event_indicators=None, dio=None, dio_indicators=None, parameters=None, metadata=None)

Constructor for stimulation data objects.

Parameters:

  • file_path (str, list) – Directory or list of directories containing TDT data sets.

  • io (None, list) – List of pyeCAP io objects to read ripple/tdt data for each experiment.

  • events (None, list) – List of dictionaries containing name and an array with stimulation event times.

  • event_indicators (None, list) – List of dictionaries containing channel name and a pandas integer array relating each stimulation event to the stimulation parameter.

  • dio (None, list) – List of dictionaries containing channel name and stimulation start/stop times in an array.

  • dio_indicators (None, list) – List of dictionaries containing channel name and pandas integer array that relates the stimulation parameter to the starting and stopping times.

  • parameters (None, list) – List of pandas DataFrames containing stimulation parameter data.

  • metadata (None, list) – List of dictionaries containing stimulation experiment metadata.

Examples

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

>>> pyeCAP.Stim([pathname1, pathname2, pathname3])
property raw_stores

Returns data for raw stimulation waveforms (‘eS1r’ stores) and raw voltage monitoring data (‘MonA’ stores) if they exist (TDT only).

Returns:

list of dictionaries that contain the raw data structs.

Return type:

list

plot_dio(*args, **kwargs)

Creates a plot of stimulation data showing the time periods with and without stimulation in raster format. See the _DioData.plot_raster method for more detail.

Parameters:

  • *args (Arguments) – Arguments to be passed to the _DioData.plot_raster method.

  • **kwargs (KeywordArguments) – Keyword arguments to be passed to the _DioData.plot_raster method.

Returns:

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

Return type:

matplotlib.axis.Axis, None

See also

_DioData.plot_raster

Examples

>>> stim_data.plot_dio()
plot_events(*args, **kwargs)

Creates a plot of stimulation data showing the time periods with and without stimulation in raster format. See the _EventData.plot_raster method for more detail.

Parameters:

  • *args (Arguments) – Arguments to be passed to the _EventData.plot_raster method.

  • **kwargs (KeywordArguments) – Keyword arguments to be passed to the _EventData.plot_raster method.

Returns:

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

Return type:

matplotlib.axis.Axis, None

See also

_EventData.plot_raster

set_parameters(parameter, values)

Resets the values of the ‘channel’ and ‘polarity’ parameters in the stimulation parameters DataFrame. Warning: Object is modified in place.

Parameters:

  • parameter (str) – Potential parameters are ‘polarity’ and ‘channel’.

  • values (list) – List of values to reset the parameters.

Return type:

None

set_channels(values)

Resets values in the stimulation parameters DataFrame. Updates ‘channel’, ‘polarity’, ‘anode’ and ‘cathode’ columns. Warning: Object is modified in place.

Parameters:

values (list, int) – Values to use in the stimulation parameters DataFrame. Use a list of integers equal to the number of data sets to reset the channels for each data set. Use a list of sequences of length 2 to reset ‘anode’ and ‘cathode’ values for bipolar stimulation.

Return type:

None

add_series(num_condition, series_to_add: <MagicMock id='140556032833744'>)

Used to add series to stimulation parameters. commonly used with: Channel, Condition, Stimulation Type

append(new_data)

Adds new data to a Stim class instance. Warning: Object is modified in place.

Parameters:

new_data (Stim) – New data to be added to the Stim class instance.

Return type:

None

Stim parent classes

The Stim class has three parent classes to handle stimulation: events, parameters, and Dio data. The inheritance order for Stim objects is _EventData first, _DioData second, and _ParameterData third. The event data class keeps track of the time of each individual stimulation pulse. The Digital I/O (Dio) class keeps track of the start and stop time of a group of pulses. The parameter data class keeps track of stimulation parameters such as pulse amplitude and pulse count.

Event Data class

class pyeCAP.base.event_data._EventData(events, metadata, indicators=None)

Class for stimulation event data.

property metadata

Property getter method for metadata for the data sets including start and stop time, channel names, number of stimulation times, and more.

Returns:

list of metadata dictionaries for each stimulation data set.

Return type:

list

property ch_names

Property getter method for viewing channel names.

Returns:

List of channel names.

Return type:

list

property start_times

Property getter method for experiment start times of stimulation data sets.

Returns:

List of start times in seconds since epoch.

Return type:

list

events(channel, start_times=None, reference=None, remove_gaps=False)

Outputs a one dimensional array of elapsed times corresponding to stimulation pulses from the specified channel. Times are in seconds and the first recorded data set is assumed to start at 0 seconds while other data sets start times are specified with the start_times argument.

Parameters:

  • channel (str) – Channel name.

  • start_times (None, list) – Specify a list of start times or specify None to use the start_times property method default.

  • reference (None, pyCAP.base.ts_data._TsData or subclass) – If start_times is None, specify a reference object to match start times. This is useful when removing gaps between data sets.

  • remove_gaps (bool) – Uses the object specified in the ‘reference’ parameter to take gaps in the data into account. Set to True to remove time gaps in the data.

Returns:

Array of elapsed times.

Return type:

numpy.ndarray

event_indicators(channel)

Outputs a numpy array of stimulation parameters for each pulse given a channel name.

Parameters:

channel (str) – Channel name.

Returns:

Two dimensional array of integers.

Return type:

numpy.ndarray

plot_raster(axis=None, start_times=None, reference=None, remove_gaps=False, x_lim=None, fig_size=(10, 1.5), show=True, lw=1, **kwargs)

Plots stimulation data showing the time periods with and without stimulation in raster format.

Parameters:

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

  • start_times (None, list) – List of start times for each data set in timestamp format (seconds since epoch). Leaving this as None will default to start times stored in the metadata.

  • reference (None, pyCAP.base.ts_data._TsData or subclass) – If start_times is None, specify a reference object to match start times. This is useful when removing gaps between data sets.

  • remove_gaps (bool) – Uses the object specified in the ‘reference’ parameter to take gaps in the data into account. Set to True to remove time gaps in the 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.

  • lw (int) – Line width.

  • **kwargs (KeywordArguments) – See mpl.axes.Axes.vlines 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

append(new_data)

Creates a new class instance with new data added to the original data.

Parameters:

new_data (_EventData or subclass) – New data to be added.

Returns:

Class instance with new data included.

Return type:

_EventData or subclass

Dio Data class

class pyeCAP.base.dio_data._DioData(dio, metadata, indicators=None)

Class for stimulation start/stop data.

property metadata

Property getter method for metadata including experiment start and stop times, channel names, and stimulation starting times.

Returns:

List of dictionaries containing metadata for each data set.

Return type:

list

property ch_names

Property getter method for channel names.

Returns:

List of channel names.

Return type:

list

property start_times

Property getter method for the experiment start time of each data set.

Returns:

List of start times in seconds since epoch.

Return type:

list

dio(channel, start_times=None, reference=None, remove_gaps=False)

Outputs an array containing starting and stopping times for stimulation periods for a given channel.

Parameters:

  • channel (str) – Name of channel.

  • start_times (None, list) – Specify a list of start times or specify None to use the start_times property default.

  • reference (None, pyCAP.base.ts_data._TsData or subclass) – If start_times is None, specify a reference object to match start times. This is useful when removing gaps between data sets.

  • remove_gaps (bool) – Uses the object specified in the ‘reference’ parameter to take gaps in the data into account. Set to True to remove time gaps in the data.

Returns:

Array containing start and stop times of the stimulation data.

Return type:

numpy.ndarray

dio_indicators(channel)

Returns an array of indicators that link stimulation start/stop times to stimulation parameters for a given channel.

Parameters:

channel (str) – Channel name.

Returns:

Pandas integer index.

Return type:

pandas.core.indexes.numeric.Int64Index

plot_raster(*args, axis=None, start_times=None, reference=None, remove_gaps=False, ch_names=None, x_lim=None, fig_size=(10, 1.5), display='span', show=True, dio=None, **kwargs)

Plots electrical stimulation time periods in a raster format.

Parameters:

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

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

  • start_times (None, list) – List of start times for each experiment or ‘None’ to use start times in metadata.

  • reference (None, pyCAP.base.ts_data._TsData or subclass) – If start_times is None, specify a reference object to match start times. This is useful when removing gaps between data sets.

  • remove_gaps (bool) – Uses the object specified in the ‘reference’ parameter to take gaps in the data into account. Set to True to remove time gaps in the data.

  • ch_names (None, list) – Names of channels to plot, or None to plot all channels.

  • 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.

  • display (str) – Use ‘span’ or ‘lines’ to specify the type of raster plot to create.

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

  • dio (None, dict) – Use None to use the dio data stored in the object, or replace with custom data in the same format.

  • kwargs (**) –

    See mpl.axes.Axes.axvspan and mpl.axes.Axes.axvline for details on plot customization.

Returns:

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

Return type:

matplotlib.axis.Axis, None

append(new_data)

Creates a class instance with new data added to the original data.

Parameters:

new_data (_DioData or subclass) – New data to be added to the original data.

Returns:

New class instance with new data.

Return type:

_DioData or subclass

Parameter Data class

class pyeCAP.base.parameter_data._ParameterData(parameters, metadata)

Class representing stimulation parameter data.

property parameters

Property getter method for information about stimulation time periods, pulses, frequencies, and more.

Returns:

Pandas DataFrame containing stimulation parameters.

Return type:

pandas.core.frame.DataFrame

append(new_data)

Creates a new class instance with new parameter data added to the original parameter data.

Parameters:

new_data (_ParameterData or subclass) – New data

Returns:

Class instance containing original data with new data.

Return type:

_ParameterData or subclass