pulse2percept.stimuli.BiphasicPulseTrain

class pulse2percept.stimuli.BiphasicPulseTrain(freq, amp, phase_dur, interphase_dur=0, delay_dur=0, n_pulses=None, stim_dur=1000.0, cathodic_first=True, electrode=None, metadata=None, threshold_amp=None)[source]

Symmetric biphasic pulse train

A train of symmetric biphasic pulses.

Added in version 0.6.

Parameters:

freq (float) – Pulse train frequency (Hz).
amp (float) –
Current amplitude (uA). Negative currents: cathodic, positive: anodic. The sign will be converted automatically depending on cathodic_first.

May also be given as a multiple of perceptual threshold, e.g. 2 * xTh (see xTh). The current that realizes it is amp * threshold_amp, so without a threshold the train stays measured in xTh.
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.
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, default: 1000 ms) – Total stimulus duration (ms). The pulse train will be trimmed 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.
metadata (dict) – A dictionary of meta-data
threshold_amp (float, optional) –
Perceptual threshold (uA) of the electrode this train drives. It is what converts between amp_factor and a current, in either direction.

Added in version 0.10.0.

Notes

Each cycle (“window”) of the pulse train consists of a symmetric biphasic pulse, created with BiphasicPulse.
The order and sign of the two phases (cathodic/anodic) of each pulse in the train is automatically adjusted depending on the cathodic_first flag.
A pulse train will 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.
A train holds a current or a multiple of threshold, and unit says which. Converting between them takes a threshold, so an xTh train without one stays measured in xTh – and is not yet something an implant can deliver.

Examples

Twice threshold, on an electrode whose threshold has been measured:

>>> from pulse2percept.stimuli import BiphasicPulseTrain
>>> from pulse2percept.units import uA, xTh
>>> pt = BiphasicPulseTrain(20, 2 * xTh, 0.45, threshold_amp=80 * uA)
>>> pt.amp, pt.amp_factor
(160.0, 2.0)

The same stimulation, expressed as the current it delivers:

>>> pt = BiphasicPulseTrain(20, 160.0 * uA, 0.45, threshold_amp=80 * uA)
>>> pt.amp, pt.amp_factor
(160.0, 2.0)

With no threshold it is still 2xTh, but it is no longer a current:

>>> pt = BiphasicPulseTrain(20, 2.0 * xTh, 0.45)
>>> pt.amp_factor, pt.unit, pt.threshold_amp
(2.0, xTh, None)

__init__(freq, amp, phase_dur, interphase_dur=0, delay_dur=0, n_pulses=None, stim_dur=1000.0, cathodic_first=True, electrode=None, metadata=None, threshold_amp=None)[source]

Methods

`__init__`(freq, amp, phase_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 of both phases of each pulse, in `unit`
`amp_factor`	Amplitude as a multiple of `threshold_amp`
`cathodic_first`	Whether the cathodic phase is delivered first
`data`	Stimulus data container
`delay_dur`	Delay (ms) before the first phase of each pulse
`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)
`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`
`n_pulses`	Number of pulses delivered
`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)
`threshold_amp`	Perceptual threshold (uA) this train's amplitude is relative to
`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 n_pulses: Number of pulses delivered

property stim_dur: Total stimulus duration (ms)

property duration: Stimulus duration (ms)

property amp: Magnitude of both phases of each pulse, in unit

property threshold_amp

Perceptual threshold (uA) this train’s amplitude is relative to

The implant calibration in force, else the threshold this train was built with, else None.

Added in version 0.10.0.

property amp_factor

Amplitude as a multiple of threshold_amp

None only for a current with no threshold to measure it against: an xTh amplitude is the multiple, threshold or no threshold.

Added in version 0.10.0.

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 of each pulse

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)