pulse2percept.stimuli.pulses

MonophasicPulse, BiphasicPulse, AsymmetricBiphasicPulse

Classes

AsymmetricBiphasicPulse(amp1, amp2, ...[, ...])

Asymmetric biphasic pulse

BiphasicPulse(amp, phase_dur[, ...])

Symmetric biphasic pulse

MonophasicPulse(amp, phase_dur[, delay_dur, ...])

Monophasic pulse
class pulse2percept.stimuli.pulses.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.

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.

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)
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

Returns:

compressed

Return type:

Stimulus

property 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.

property dt

Sampling time step (ms)

Defines the duration of the signal edge transitions.

Added in version 0.7.

property duration

Stimulus duration (ms)

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.

Returns None if the stimulus is not a current at all: the gray levels of an ImageStimulus integrate to a number like any others, but that number is not a charge and asking whether it is zero answers nothing. Note that this is “not applicable”, not “unbalanced” – it is safe_mode that turns the question into an error, since a safety system genuinely cannot do its job on a stimulus that is not electrical.

Changed in version 0.10.0: Returns None for a stimulus that is not measured in units of current (was: integrated the values anyway).

property is_compressed

Flag indicating whether the stimulus has been compressed

Read-only: the flag is maintained by compress. Assigning to it raises an AttributeError.

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

Plot the stimulus

Added in version 0.7.

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.

  • ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.

Returns:

axes – Returns one matplotlib.axes.Axes per electrode

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

property time

Time steps A list of time steps, corresponding to 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 (milliseconds)

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

Microamps for an electrical stimulus, dimensionless for the gray levels of an ImageStimulus or VideoStimulus.

Read-only. The canonical storage unit is fixed so that models, safety checks and Cython kernels can rely on it; ask for another unit with values().

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. This is the boundary a numerical implementation should take its data across.

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)
class pulse2percept.stimuli.pulses.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.

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.

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)
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

Returns:

compressed

Return type:

Stimulus

property 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.

property dt

Sampling time step (ms)

Defines the duration of the signal edge transitions.

Added in version 0.7.

property duration

Stimulus duration (ms)

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.

Returns None if the stimulus is not a current at all: the gray levels of an ImageStimulus integrate to a number like any others, but that number is not a charge and asking whether it is zero answers nothing. Note that this is “not applicable”, not “unbalanced” – it is safe_mode that turns the question into an error, since a safety system genuinely cannot do its job on a stimulus that is not electrical.

Changed in version 0.10.0: Returns None for a stimulus that is not measured in units of current (was: integrated the values anyway).

property is_compressed

Flag indicating whether the stimulus has been compressed

Read-only: the flag is maintained by compress. Assigning to it raises an AttributeError.

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

Plot the stimulus

Added in version 0.7.

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.

  • ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.

Returns:

axes – Returns one matplotlib.axes.Axes per electrode

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

property time

Time steps A list of time steps, corresponding to 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 (milliseconds)

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

Microamps for an electrical stimulus, dimensionless for the gray levels of an ImageStimulus or VideoStimulus.

Read-only. The canonical storage unit is fixed so that models, safety checks and Cython kernels can rely on it; ask for another unit with values().

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. This is the boundary a numerical implementation should take its data across.

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)
class pulse2percept.stimuli.pulses.AsymmetricBiphasicPulse(amp1, amp2, phase_dur1, phase_dur2, interphase_dur=0, delay_dur=0, stim_dur=None, cathodic_first=True, electrode=None)[source]

Asymmetric biphasic pulse

A simple stimulus consisting of a single biphasic pulse: a cathodic and an anodic phase, optionally separated by an interphase gap. The two pulse phases can have different amplitudes and duration (“asymmetric”).

Added in version 0.6.

Parameters:

  • amp1 (float) – Current amplitude (uA) of the first and second pulse phases. Negative currents: cathodic, positive: anodic. The signs will be converted automatically depending on cathodic_first.

  • amp2 (float) – Current amplitude (uA) of the first and second pulse phases. Negative currents: cathodic, positive: anodic. The signs will be converted automatically depending on cathodic_first.

  • phase_dur1 (float) – Duration (ms) of the first and second pulse phases.

  • phase_dur2 (float) – Duration (ms) of the first and second pulse phases.

  • 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.

  • The sign of amp will be automatically adjusted depending on the cathodic_first flag.

  • A pulse 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.

Examples

An asymmetric cathodic-first pulse (first phase: -40uA, 1ms; second phase: 10uA, 4ms; 1ms interphase-gap) delivered after 2ms and embedded in a stimulus that lasts 15ms overall:

>>> from pulse2percept.stimuli import AsymmetricBiphasicPulse
>>> pulse = AsymmetricBiphasicPulse(-40, 10, 1, 4, interphase_dur=1,
...                                 delay_dur=2, stim_dur=15)
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

Returns:

compressed

Return type:

Stimulus

property 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.

property dt

Sampling time step (ms)

Defines the duration of the signal edge transitions.

Added in version 0.7.

property duration

Stimulus duration (ms)

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.

Returns None if the stimulus is not a current at all: the gray levels of an ImageStimulus integrate to a number like any others, but that number is not a charge and asking whether it is zero answers nothing. Note that this is “not applicable”, not “unbalanced” – it is safe_mode that turns the question into an error, since a safety system genuinely cannot do its job on a stimulus that is not electrical.

Changed in version 0.10.0: Returns None for a stimulus that is not measured in units of current (was: integrated the values anyway).

property is_compressed

Flag indicating whether the stimulus has been compressed

Read-only: the flag is maintained by compress. Assigning to it raises an AttributeError.

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

Plot the stimulus

Added in version 0.7.

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.

  • ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.

Returns:

axes – Returns one matplotlib.axes.Axes per electrode

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

property time

Time steps A list of time steps, corresponding to 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 (milliseconds)

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

Microamps for an electrical stimulus, dimensionless for the gray levels of an ImageStimulus or VideoStimulus.

Read-only. The canonical storage unit is fixed so that models, safety checks and Cython kernels can rely on it; ask for another unit with values().

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. This is the boundary a numerical implementation should take its data across.

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)