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 laststim_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 thecathodic_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.
-
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.
- 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
-
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 laststim_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.
-
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.
- amp (float) – Current amplitude (uA). Negative currents: cathodic, positive: anodic.
The sign will be converted automatically depending on
-
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.
-
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.