pulse2percept.stimuli.BiphasicPulse

class pulse2percept.stimuli.BiphasicPulse(amp, phase_dur, interphase_dur=0, delay_dur=0, stim_dur=None, cathodic_first=True, electrode=None)[source]

Symmetric biphasic pulse

A simple stimulus consisting of a single biphasic pulse: a cathodic and an anodic phase, optionally separated by an interphase gap. Both cathodic and anodic phases have the same duration (“symmetric”).

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. The sign will be converted automatically depending on cathodic_first.
phase_dur (float) – Duration (ms) of the cathodic/anodic phase.
interphase_dur (float, optional, default: 0) – Duration (ms) of the gap between cathodic and anodic phases.
delay_dur (float) – Delay duration (ms). Zeros will be inserted at the beginning of the stimulus to deliver the first pulse phase after delay_dur ms.
stim_dur (float, optional, default:) – 2*phase_dur+interphase_dur+delay_dur Total stimulus duration (ms). Zeros will be inserted at the end of the stimulus to make the stimulus last stim_dur ms overall.
cathodic_first (bool, optional, default: True) – If True, will deliver the cathodic pulse phase before the anodic one.
electrode ({ int | string }, optional, default: 0) – Optionally, you can provide your own electrode name.

Notes

The order of the two phases is given by the cathodic_first flag.
A biphasic pulse created with this class will always be considered “charge-balanced”.
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.
amp reads back as a magnitude, because that is all of it that reaches the waveform: the constructor takes np.abs(amp) and gets the polarity from cathodic_first.

Examples

A cathodic-first pulse (1ms phase duration at 20uA, no interphase gap) delivered after 2ms and embedded in a stimulus that lasts 10ms overall:

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

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

Methods

`__init__`(amp, phase_dur[, interphase_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`	Magnitude (uA) of both pulse phases
`cathodic_first`	Whether the cathodic phase is delivered first
`data`	Stimulus data container
`delay_dur`	Delay (ms) before the first phase 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.
`interphase_dur`	Duration (ms) of the gap between the two phases
`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/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: Magnitude (uA) of both pulse phases

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

property interphase_dur: Duration (ms) of the gap between the two phases

property delay_dur: Delay (ms) before the first phase 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_first: Whether the cathodic phase is delivered first

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)