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.

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

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

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