pulse2percept.stimuli.MonophasicPulse

class pulse2percept.stimuli.MonophasicPulse(amp, phase_dur, delay_dur=0, stim_dur=None, electrode=None)[source]

Monophasic pulse

A simple stimulus consisting of a single monophasic pulse (either cathodic/negative or anodic/positive).

Added in version 0.6.

Changed in version 0.10.0: The pulse retains the parameters that define it, and generates its sampled waveform only when one is asked for.

Parameters:

amp (float) – Current amplitude (uA). Negative currents: cathodic, positive: anodic.
phase_dur (float) – Duration (ms) of the cathodic or anodic phase.
delay_dur (float) – Delay duration (ms). Zeros will be inserted at the beginning of the stimulus to deliver the pulse after delay_dur ms.
stim_dur (float, optional) – Total stimulus duration (ms). Zeros will be inserted at the end of the stimulus to make the stimulus last stim_dur ms overall.
electrode ({ int | string }, optional) – Optionally, you can provide your own electrode name.

Notes

The sign of amp will determine whether the pulse is cathodic (negative current) or anodic (positive current).
A regular monophasic pulse is not considered “charge-balanced”. However, if amp is small enough, the pulse can be considered “charge-balanced” if its net current is smaller than 10 picoamps.
Arguments may be given as plain numbers in the units documented above, or as unitful quantities (e.g. 0.05 * mA, 450 * us), which are converted to those units. See pulse2percept.units.
The parameters above are read-only. A pulse with different parameters is a different pulse; build another one.

Examples

A single cathodic pulse (1ms phase duration at 20uA) delivered after 2ms and embedded in a stimulus that lasts 10ms overall:

>>> from pulse2percept.stimuli import MonophasicPulse
>>> pulse = MonophasicPulse(-20, 1, delay_dur=2, stim_dur=10)

__init__(amp, phase_dur, delay_dur=0, stim_dur=None, electrode=None)[source]

Methods

`__init__`(amp, phase_dur[, delay_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

`amp`	Current amplitude (uA); negative is cathodic
`cathodic`	Whether the pulse delivers a negative current
`data`	Stimulus data container
`delay_dur`	Delay (ms) before the pulse is delivered
`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.
`is_charge_balanced`	Flag indicating whether the stimulus is charge-balanced
`is_compressed`	Flag indicating whether the stimulus has been compressed
`metadata`
`phase_dur`	Duration (ms) of the cathodic or anodic phase
`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 amp: Current amplitude (uA); negative is cathodic

property phase_dur: Duration (ms) of the cathodic or anodic phase

property delay_dur: Delay (ms) before the pulse is delivered

property stim_dur: Total stimulus duration (ms)

property duration

Stimulus duration (ms)

The waveform is built to end exactly at stim_dur, so this is known without generating one.

property cathodic: Whether the pulse delivers a negative current

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)