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

New in version 0.6.

Parameters:
  • amp2 (amp1,) – 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_dur2 (phase_dur1,) – 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.

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.

New in version 0.7.

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

Compress the source data

Returns:compressed (Stimulus)
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.

dt

Sampling time step (ms)

Defines the duration of the signal edge transitions.

New in version 0.7.

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

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.

is_compressed

Flag indicating whether the stimulus has been compressed

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

Plot the stimulus

New 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 (matplotlib.axes.Axes or np.ndarray of them) – Returns one matplotlib.axes.Axes per electrode

remove(electrodes)[source]

Remove electrode(s)

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

New 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.
shape

Data container shape

time

Time steps A list of time steps, corresponding to the columns in the data container.

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

New 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”.

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.

New in version 0.7.

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

Compress the source data

Returns:compressed (Stimulus)
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.

dt

Sampling time step (ms)

Defines the duration of the signal edge transitions.

New in version 0.7.

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

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.

is_compressed

Flag indicating whether the stimulus has been compressed

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

Plot the stimulus

New 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 (matplotlib.axes.Axes or np.ndarray of them) – Returns one matplotlib.axes.Axes per electrode

remove(electrodes)[source]

Remove electrode(s)

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

New 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.
shape

Data container shape

time

Time steps A list of time steps, corresponding to the columns in the data container.

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

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

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.

New in version 0.7.

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

Compress the source data

Returns:compressed (Stimulus)
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.

dt

Sampling time step (ms)

Defines the duration of the signal edge transitions.

New in version 0.7.

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

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.

is_compressed

Flag indicating whether the stimulus has been compressed

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

Plot the stimulus

New 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 (matplotlib.axes.Axes or np.ndarray of them) – Returns one matplotlib.axes.Axes per electrode

remove(electrodes)[source]

Remove electrode(s)

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

New 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.
shape

Data container shape

time

Time steps A list of time steps, corresponding to the columns in the data container.