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])
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. ?? object is modified in place??

Parameters

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

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

Returns

Return type

None

set_channels(values)

Resets values in the stimulation parameters DataFrame. Updates ‘channel’, ‘polarity’, ‘anode’ and ‘cathode’ columns. ?? 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.

Returns

Return type

None

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

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. ?? object is modified in place??

Parameters

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

Returns

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.

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