pulse2percept.stimuli.PulseTrain

class pulse2percept.stimuli.PulseTrain(freq, pulse, n_pulses=None, stim_dur=1000.0, electrode=None, metadata=None)[source]

Generic pulse train

Can be used to concatenate single pulses into a pulse train.

See also

Added in version 0.6.

Parameters:

freq (float) – Pulse train frequency (Hz).
pulse (Stimulus) – A Stimulus object containing a single pulse that will be concatenated.
n_pulses (int) – Number of pulses requested in the pulse train. If None, the entire stimulation window (stim_dur) is filled.
stim_dur (float, optional) – Total stimulus duration (ms). The pulse train will be trimmed to make the stimulus last stim_dur ms overall.
electrode ({ int | string }, optional) – Optionally, you can provide your own electrode name.
metadata (dict) – A dictionary of meta-data

Notes

Only pulses that fit whole are delivered. If the pulse train frequency does not exactly divide stim_dur, the number of pulses is therefore rounded down: a 30 Hz train in a 33.37 ms window has one pulse, not one and a fraction of a second. A partial pulse would leave the train with a net current.
A frequency slower than 1000 / stim_dur cannot be realized, since the window still holds one pulse. Pass freq=0 for a silent train.
Arguments may be given as plain numbers in the units documented above, or as unitful quantities (e.g. 0.02 * kHz, 1 * s), which are converted to those units. See pulse2percept.units.
The train is measured in whatever pulse was measured in: tiling an electrical pulse gives a train in microamps, and tiling a dimensionless one gives a dimensionless train.

__init__(freq, pulse, n_pulses=None, stim_dur=1000.0, electrode=None, metadata=None)[source]

Methods

`__init__`(freq, pulse[, n_pulses, stim_dur, ...])
`append`(other)	Append another stimulus
`compress`()	Compress the source data in place
`pad`(duration)	Pad the stimulus with zeros up to a given time.
`plot`([electrodes, time, fmt, ax, kind])	Plot the stimulus
`remove`(electrodes)	Remove electrode(s)
`shift`(dt)	Shift the stimulus in time.
`times`([unit])	The stimulus time axis, expressed in `unit`
`values`([unit])	The stimulus data, expressed in `unit`

Attributes

`data`	Stimulus data container
`dt`	Sampling time step (duration of signal edge transitions)
`duration`	Stimulus duration (ms)
`electrodes`	Electrode names A list of electrode names, corresponding to the rows in the data container.
`freq`	Pulse train frequency (Hz)
`is_charge_balanced`	Flag indicating whether the stimulus is charge-balanced
`is_compressed`	Flag indicating whether the stimulus has been compressed
`metadata`
`n_pulses`	Number of pulses delivered
`pulse`	The single pulse this train repeats
`pulse_type`	Name of the class the repeated pulse came from
`quantity`	The stimulus data, with its unit attached
`shape`	Data container shape
`stim_dur`	Total stimulus duration (ms)
`time`	A list of time steps (i.e., the columns in the data container)
`time_quantity`	The stimulus time axis with its unit attached, or None
`time_unit`	The unit `time` is expressed in
`unit`	The unit `data` is expressed in

property freq: Pulse train frequency (Hz)

property pulse: The single pulse this train repeats

property n_pulses: Number of pulses delivered

property stim_dur: Total stimulus duration (ms)

property pulse_type: Name of the class the repeated pulse came from

property duration: Stimulus duration (ms)

append(other)[source]

Append another stimulus

This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.

Added in version 0.7.

Parameters:: other (Stimulus) – Another stimulus with matching electrodes.
Returns:: comb – A combined stimulus with the same number of electrodes and new stimulus duration equal to the sum of the two individual stimuli.
Return type:: Stimulus

compress()[source]: Compress the source data in place

property data

Stimulus data container

A read-only 2-D NumPy array that contains the sampled waveform, where the rows denote electrodes and the columns denote points in time.

property dt: Sampling time step (duration of signal edge transitions)

Added in version 0.7.

property electrodes: Electrode names A list of electrode names, corresponding to the rows in the data container.

property is_charge_balanced

Flag indicating whether the stimulus is charge-balanced

A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.

Changed in version 0.10.0: Returns None for a stimulus that is not measured in units of current.

property is_compressed: Flag indicating whether the stimulus has been compressed

pad(duration)[source]

Pad the stimulus with zeros up to a given time.

Adds zero-valued endpoints at t=0 and t=duration as needed. duration specifies the final time, not the amount of padding to add.

Added in version 0.10.0.

Parameters:: duration (float or Quantity) – Final time of the padded stimulus. Bare values are interpreted in the stimulus’ time unit.
Returns:: padded – Padded copy of the stimulus.
Return type:: Stimulus

Notes

Padding requires existing boundary values to be zero; otherwise interpolation would create a ramp. It never truncates the stimulus or removes negative time points.

plot(electrodes=None, time=None, fmt='k-', ax=None, kind=None)[source]

Plot the stimulus

Added in version 0.7.

Changed in version 0.10.0: Added kind: a whole multi-electrode stimulus is now drawn as an electrode-by-time heatmap rather than as one subplot per electrode.

Parameters:

electrodes (int, string, or list thereof; optional, default: None) – The electrodes for which to plot the stimulus. If None, all electrodes are plotted.
time ((t_min, t_max) tuple, slice, or list of exact time points) – The time points at which to plot the stimulus. Specify a range of time points with a tuple or a slice, or specify the exact time points to interpolate. If None, all time points are plotted.
fmt (str, optional, default: 'k-') – A Matplotlib format string; e.g., ‘ro’ for red circles to use when kind='traces'.
ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object. kind='traces' also accepts a list thereof (one per electrode to plot); kind='heatmap' draws into a single Axes. If None, a new Axes object will be created.
kind ({'traces', 'heatmap'}, optional, default: None) –
What to draw:
- ’traces’: the waveform of each electrode, one Axes per electrode. Good for a handful of electrodes.
- ’heatmap’: an electrode-by-time image in a single Axes. Good for a whole implant’s worth of electrodes.
If None, a whole stimulus of more than one electrode is drawn as a heatmap and everything else as traces.

Returns:

ax – One Axes per electrode for kind='traces', a single Axes for kind='heatmap'.

Return type:

matplotlib.axes.Axes or np.ndarray of them

property quantity

The stimulus data, with its unit attached

Added in version 0.10.0.

Examples

>>> from pulse2percept.stimuli import Stimulus
>>> from pulse2percept.units import uA
>>> Stimulus([500, 1000] * uA).quantity
[[ 500.]
 [1000.]] uA

remove(electrodes)[source]

Remove electrode(s)

Removes the stimulus of a certain electrode or list of electrodes.

Added in version 0.8.

Parameters:: electrodes (int, string, or list of int/str) – The item(s) to remove from the stimulus. Can either be an electrode index, electrode name, or a list thereof.

property shape: Data container shape

shift(dt)[source]

Shift the stimulus in time.

Added in version 0.10.0.

Parameters:: dt (float or Quantity) – Time shift. May be positive or negative. Bare values are interpreted in the stimulus’ time unit.
Returns:: shifted – Shifted copy of the stimulus.
Return type:: Stimulus

Notes

stim >> dt and stim << dt are shorthand for stim.shift(dt) and stim.shift(-dt).

property time: A list of time steps (i.e., the columns in the data container)

property time_quantity: The stimulus time axis with its unit attached, or None

Added in version 0.10.0.

property time_unit: The unit time is expressed in

Added in version 0.10.0.

times(unit=None)[source]

The stimulus time axis, expressed in unit

Added in version 0.10.0.

Parameters:: unit (Unit, optional) – The unit to express the time axis in. If None, time is returned as it is stored (milliseconds).
Returns:: times – An ordinary NumPy array, or None if the stimulus has no time component.
Return type:: np.ndarray or None

property unit: The unit data is expressed in

Added in version 0.10.0.

values(unit=None)[source]

The stimulus data, expressed in unit

Added in version 0.10.0.

Parameters:: unit (Unit, optional) – The unit to express the data in. Must be compatible with unit. If None, the stimulus’ own unit is used and data is returned as it is stored.
Returns:: values – An ordinary NumPy array, never a Quantity.
Return type:: np.ndarray

Examples

>>> from pulse2percept.stimuli import Stimulus
>>> from pulse2percept.units import uA, mA
>>> Stimulus([500, 1000] * uA).values(mA)
array([[0.5],
       [1. ]], dtype=float32)