pulse2percept.stimuli.pulse_trains¶
PulseTrain
, BiphasicPulseTrain
, AsymmetricBiphasicPulseTrain
Classes
AsymmetricBiphasicPulseTrain (freq, amp1, …) |
Asymmetric biphasic pulse |
BiphasicPulseTrain (freq, amp, phase_dur[, …]) |
Symmetric biphasic pulse train |
BiphasicTripletTrain (freq, amp, phase_dur[, …]) |
Biphasic pulse triplets |
PulseTrain (freq, pulse[, n_pulses, …]) |
Generic pulse train |
-
class
pulse2percept.stimuli.pulse_trains.
AsymmetricBiphasicPulseTrain
(freq, amp1, amp2, phase_dur1, phase_dur2, interphase_dur=0, delay_dur=0, n_pulses=None, stim_dur=1000.0, cathodic_first=True, electrode=None, metadata=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”). The order of the two phases is given by the
cathodic_first
flag.New in version 0.6.
Parameters: - freq (float) – Pulse train frequency (Hz).
- 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. - 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). Zeros will be inserted at the end of the
stimulus to make the 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
-
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.
-
class
pulse2percept.stimuli.pulse_trains.
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)[source]¶ Symmetric biphasic pulse train
A train of symmetric biphasic pulses.
New 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
. - 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
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.
-
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.
-
class
pulse2percept.stimuli.pulse_trains.
BiphasicTripletTrain
(freq, amp, phase_dur, interphase_dur=0, interpulse_dur=0, delay_dur=0, n_pulses=None, stim_dur=1000.0, cathodic_first=True, electrode=None, metadata=None)[source]¶ Biphasic pulse triplets
A train of symmetric biphasic pulse triplets.
New 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
. - 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. - interpulse_dur (float, optional, default: 0) – Delay duration (ms) between each biphasic pulse within the train. Note, this delay is also applied after the third biphasic pulse
- 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
Notes
- Each cycle (“window”) of the pulse train consists of three biphasic
pulses, 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.
-
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.
-
class
pulse2percept.stimuli.pulse_trains.
PulseTrain
(freq, pulse, n_pulses=None, stim_dur=1000.0, electrode=None, metadata=None)[source]¶ Generic pulse train
Can be used to concatenate single pulses into a pulse train.
New in version 0.6.
Parameters: - freq (float) – Pulse train frequency (Hz).
- pulse (
Stimulus
) – A Stimulus object containing a single pulse that will be concatenated. - 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) – Total stimulus duration (ms). The pulse train will be trimmed to make
the stimulus last
stim_dur
ms overall. - electrode ({ int | string }, optional) – Optionally, you can provide your own electrode name.
- metadata (dict) – A dictionary of meta-data
Notes
- If the pulse train frequency does not exactly divide
stim_dur
, the number of pulses will be rounded down. For example, when trying to fit a 11 Hz pulse train into a 100 ms window, there will be 9 pulses.
-
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.