pulse2percept.stimuli

This module provides a number of stimuli.

base
pulse_trains
class pulse2percept.stimuli.BiphasicPulse(ptype, pdur, tsample, interphase_dur=0)[source]

A charge-balanced pulse with a cathodic and anodic phase

A single biphasic pulse with duration pdur per phase, separated by interphase_dur is returned.

Parameters:
  • ptype ({'cathodicfirst', 'anodicfirst'}) – A cathodic-first pulse has the negative phase first, whereas an anodic-first pulse has the positive phase first.
  • pdur (float) – Duration of single (positive or negative) pulse phase in seconds.
  • tsample (float) – Sampling time step in seconds.
  • interphase_dur (float, optional) – Duration of inter-phase interval (between positive and negative pulse) in seconds. Default: 0.
append(other)[source]

Appends the data of another TimeSeries object (in time)

This function concatenates the data of another TimeSeries object to the current object, along the last dimension (time). To make this work, all but the last dimension of the two objects must be the same.

If the two objects have different time sampling steps, the other object is resampled to fit the current tsample.

Parameters:other (TimeSeries) – A TimeSeries object whose content should be appended.

Examples

>>> from pulse2percept import stimuli
>>> pt = stimuli.TimeSeries(1.0, np.zeros((2, 2, 10)))
>>> num_frames = pt.shape[-1]
>>> pt.append(pt)
>>> pt.shape[-1] == 2 * num_frames
True
max()[source]

Returns the time and value of the largest data point

This function returns the the largest value in the TimeSeries data, as well as the time at which it occurred.

Returns:
  • t (float) – time (s) at which max occurred
  • val (float) – max value
max_frame()[source]

Returns the time frame that contains the largest data point

This function returns the time frame in the TimeSeries data that contains the largest data point, as well as the time at which it occurred.

Returns:
  • t (float) – time (s) at which max occurred
  • frame (TimeSeries) – A TimeSeries object.
resample(tsample_new)[source]

Returns data sampled according to new time step

This function returns a TimeSeries object whose data points were resampled according to a new time step tsample_new. New values are found using linear interpolation.

Parameters:tsample_new (float) – New sampling time step (s)
Returns:TimeSeries object
class pulse2percept.stimuli.MonophasicPulse(ptype, pdur, tsample, delay_dur=0, stim_dur=None)[source]

A pulse with a single phase

Parameters:
  • ptype ({'anodic', 'cathodic'}) – Pulse type. Anodic pulses have positive current amplitude, cathodic pulses have negative amplitude.
  • pdur (float) – Pulse duration (s).
  • tsample (float) – Sampling time step (s).
  • delay_dur (float, optional) – Pulse delay (s). Pulse will be zero-padded (prepended) to deliver the pulse only after delay_dur milliseconds. Default: 0.
  • stim_dur (float, optional) – Stimulus duration (ms). Pulse will be zero-padded (appended) to fit the stimulus duration. Default: No additional zero padding, stim_dur is pdur + delay_dur.
append(other)[source]

Appends the data of another TimeSeries object (in time)

This function concatenates the data of another TimeSeries object to the current object, along the last dimension (time). To make this work, all but the last dimension of the two objects must be the same.

If the two objects have different time sampling steps, the other object is resampled to fit the current tsample.

Parameters:other (TimeSeries) – A TimeSeries object whose content should be appended.

Examples

>>> from pulse2percept import stimuli
>>> pt = stimuli.TimeSeries(1.0, np.zeros((2, 2, 10)))
>>> num_frames = pt.shape[-1]
>>> pt.append(pt)
>>> pt.shape[-1] == 2 * num_frames
True
max()[source]

Returns the time and value of the largest data point

This function returns the the largest value in the TimeSeries data, as well as the time at which it occurred.

Returns:
  • t (float) – time (s) at which max occurred
  • val (float) – max value
max_frame()[source]

Returns the time frame that contains the largest data point

This function returns the time frame in the TimeSeries data that contains the largest data point, as well as the time at which it occurred.

Returns:
  • t (float) – time (s) at which max occurred
  • frame (TimeSeries) – A TimeSeries object.
resample(tsample_new)[source]

Returns data sampled according to new time step

This function returns a TimeSeries object whose data points were resampled according to a new time step tsample_new. New values are found using linear interpolation.

Parameters:tsample_new (float) – New sampling time step (s)
Returns:TimeSeries object
class pulse2percept.stimuli.PulseTrain(tsample, freq=20, amp=20, dur=0.5, delay=0, pulse_dur=0.00045, interphase_dur=0.00045, pulsetype='cathodicfirst', pulseorder='pulsefirst')[source]

A train of biphasic pulses

Parameters:
  • tsample (float) – Sampling time step (seconds).
  • freq (float, optional, default: 20 Hz) – Frequency of the pulse envelope (Hz).
  • amp (float, optional, default: 20 uA) – Max amplitude of the pulse train in micro-amps.
  • dur (float, optional, default: 0.5 seconds) – Stimulus duration in seconds.
  • delay (float, optional, default: 0) – Delay until stimulus on-set in seconds.
  • pulse_dur (float, optional, default: 0.45 ms) – Single-pulse duration in seconds.
  • interphase_duration (float, optional, default: 0.45 ms) – Single-pulse interphase duration (the time between the positive and negative phase) in seconds.
  • pulsetype (str, optional, default: 'cathodicfirst') – Pulse type {‘cathodicfirst’ | ‘anodicfirst’}, where ‘cathodicfirst’ has the negative phase first.
  • pulseorder (str, optional, default: 'pulsefirst') – Pulse order {‘gapfirst’ | ‘pulsefirst’}, where ‘pulsefirst’ has the pulse first, followed by the gap. ‘gapfirst’ has it the other way round.
append(other)[source]

Appends the data of another TimeSeries object (in time)

This function concatenates the data of another TimeSeries object to the current object, along the last dimension (time). To make this work, all but the last dimension of the two objects must be the same.

If the two objects have different time sampling steps, the other object is resampled to fit the current tsample.

Parameters:other (TimeSeries) – A TimeSeries object whose content should be appended.

Examples

>>> from pulse2percept import stimuli
>>> pt = stimuli.TimeSeries(1.0, np.zeros((2, 2, 10)))
>>> num_frames = pt.shape[-1]
>>> pt.append(pt)
>>> pt.shape[-1] == 2 * num_frames
True
max()[source]

Returns the time and value of the largest data point

This function returns the the largest value in the TimeSeries data, as well as the time at which it occurred.

Returns:
  • t (float) – time (s) at which max occurred
  • val (float) – max value
max_frame()[source]

Returns the time frame that contains the largest data point

This function returns the time frame in the TimeSeries data that contains the largest data point, as well as the time at which it occurred.

Returns:
  • t (float) – time (s) at which max occurred
  • frame (TimeSeries) – A TimeSeries object.
resample(tsample_new)[source]

Returns data sampled according to new time step

This function returns a TimeSeries object whose data points were resampled according to a new time step tsample_new. New values are found using linear interpolation.

Parameters:tsample_new (float) – New sampling time step (s)
Returns:TimeSeries object
class pulse2percept.stimuli.Stimulus(source, electrodes=None, time=None, metadata=None, compress=False, interp_method='linear', extrapolate=False)[source]

New in version 0.6.

A stimulus is comprised of a labeled 2-D NumPy array that contains the data, where the rows denote electrodes and the columns denote points in time.

A stimulus can be created from a variety of source types (see below), including lists and dictionaries. Depending on the source type, a stimulus might have a time component or not.

Parameters:
  • source (source type) –

    A valid source type is one of the following:

    • Scalar value: interpreted as the current amplitude delivered to a single electrode (no time component).
    • NumPy array:
      • Nx1 array: interpreted as N current amplitudes delivered to N electrodes (no time component).
      • NxM array: interpreted as N electrodes each receiving M current amplitudes in time.
    • TimeSeries: interpreted as the stimulus in time for a single electrode (e.g., BiphasicPulse, PulseTrain).

    In addition, you can also pass a collection of source types. Each element must be a valid source type for a single electrode (e.g., scalar, 1-D array, TimeSeries).

    • List or tuple: List elements will be assigned to electrodes in order.
    • Dictionary: Dictionary keys are used to address electrodes by name.
  • electrodes (int, string or list thereof; optional, default: None) –

    Optionally, you can provide your own electrode names. If none are given, electrode names will be extracted from the source type (e.g., the keys from a dictionary). If a scalar or NumPy array is passed, electrode names will be numbered 0..N.

    Note

    The number of electrode names provided must match the number of electrodes extracted from the source type (i.e., N).

  • time (int, float or list thereof; optional, default: None) –

    Optionally, you can provide the time points of the source data. If none are given, time steps will be numbered 0..M.

    Note

    The number of time points provided must match the number of time points extracted from the source type (i.e., M).

    Stimuli created from scalars or 1-D NumPy arrays will have no time componenet, in which case you cannot provide your own time points.

  • metadata (dict, optional, default: None) – Additional stimulus metadata can be stored in a dictionary.
  • compress (bool, optional, default: False) – If True, will compress the source data in two ways: * Remove electrodes with all-zero activation. * Retain only the time points at which the stimulus changes. For example, in a pulse train, only the signal edges are saved. This drastically reduces the memory footprint of the stimulus.
  • interp_method (str or int, optional, default: 'linear') – For SciPy’s interp1 method, specifies the kind of interpolation as a string (‘linear’, ‘nearest’, ‘zero’, ‘slinear’, ‘quadratic’, ‘cubic’, ‘previous’, ‘next’) or as an integer specifying the order of the spline interpolator to use. Here, ‘zero’, ‘slinear’, ‘quadratic’ and ‘cubic’ refer to a spline interpolation of zeroth, first, second or third order; ‘previous’ and ‘next’ simply return the previous or next value of the point.
  • extrapolate (bool, optional, default: False) – Whether to extrapolate data points outside the given range.

Examples

Stimulate a single electrode with -13uA:

>>> from pulse2percept.stimuli import Stimulus
>>> stim = Stimulus(-13)

Stimulate Electrode ‘B9’ with a 10Hz cathodic-first pulse train lasting 0.2 seconds, with 0.45ms pulse duration, 40uA current amplitude, and the time series resolved at 0.1ms resolution:

>>> from pulse2percept.stimuli import Stimulus, PulseTrain
>>> stim = Stimulus({'B9': PulseTrain(0.0001, freq=10, amp=40, dur=0.2)})

Compress an existing Stimulus:

>>> from pulse2percept.stimuli import Stimulus, PulseTrain
>>> stim = Stimulus({'B9': PulseTrain(0.0001, freq=10, amp=40, dur=0.5)})
>>> stim.shape
(1, 5000)
>>> stim.compress()
>>> stim.shape
(1, 40)

Stimulate ten electrodes with 0uA:

>>> from pulse2percept.stimuli import Stimulus
>>> stim = Stimulus(np.zeros(10))

Provide new electrode names for an existing Stimulus object:

>>> from pulse2percept.stimuli import Stimulus
>>> old_stim = Stimulus([3, 5])
>>> new_stim = Stimulus(old_stim, electrodes=['new0', 'new1'])

Interpolate the stimulus value at some point in time. Here, the stimulus is a single-electrode ramp stimulus (stimulus value == point in time):

>>> from pulse2percept.stimuli import Stimulus
>>> stim = Stimulus(np.arange(10).reshape((1, -1)))
>>> stim[:, 3.45] # doctest: +ELLIPSIS
3.45...
compress()[source]

Compress the source data

Returns:compressed (Stimulus)
data

Stimulus data container

A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.

electrodes

Electrode names

A list of electrode names, corresponding to the rows in the data container.

get_params()[source]

Return a dictionary of class attributes

shape

Data container shape

time

Time steps

A list of time steps, corresponding to the columns in the data container.

class pulse2percept.stimuli.TimeSeries(tsample, data)[source]

Container for time series data

Provides a container for time series data. Every time series has a sampling step tsample, and some data sampled at that rate.

Parameters:
  • tsample (float) – Sampling time step (seconds).
  • data (array_like) – Time series data sampled at every tsample seconds.
append(other)[source]

Appends the data of another TimeSeries object (in time)

This function concatenates the data of another TimeSeries object to the current object, along the last dimension (time). To make this work, all but the last dimension of the two objects must be the same.

If the two objects have different time sampling steps, the other object is resampled to fit the current tsample.

Parameters:other (TimeSeries) – A TimeSeries object whose content should be appended.

Examples

>>> from pulse2percept import stimuli
>>> pt = stimuli.TimeSeries(1.0, np.zeros((2, 2, 10)))
>>> num_frames = pt.shape[-1]
>>> pt.append(pt)
>>> pt.shape[-1] == 2 * num_frames
True
max()[source]

Returns the time and value of the largest data point

This function returns the the largest value in the TimeSeries data, as well as the time at which it occurred.

Returns:
  • t (float) – time (s) at which max occurred
  • val (float) – max value
max_frame()[source]

Returns the time frame that contains the largest data point

This function returns the time frame in the TimeSeries data that contains the largest data point, as well as the time at which it occurred.

Returns:
  • t (float) – time (s) at which max occurred
  • frame (TimeSeries) – A TimeSeries object.
resample(tsample_new)[source]

Returns data sampled according to new time step

This function returns a TimeSeries object whose data points were resampled according to a new time step tsample_new. New values are found using linear interpolation.

Parameters:tsample_new (float) – New sampling time step (s)
Returns:TimeSeries object