pulse2percept.stimuli.PulseEncoder

class pulse2percept.stimuli.PulseEncoder(implant=None, phase_dur=0.46, interphase_dur=0, cathodic_first=True, pulse=None, clock=None, n_levels=None, frame_dur=None, stretch=False)

Abstract base class for electrical pulse-train encoders.

Maps image or video gray levels onto the parameters of repeated electrical pulses. If the encoder has an implant, the source is sampled at its electrode locations and scheduled using its raster pattern.

Subclasses implement _modulate(), which maps gray levels to pulse amplitude and frequency.

Added in version 0.10.0.

Changed in version 0.11.0: Renamed from StimulusEncoder. The implant is passed to the constructor rather than to encode().

Parameters:

• implant (Implant, optional) – The implant to encode for. Its electrode locations are used to sample images and videos, its electrode names label the result, and its raster decides which electrodes may pulse when. If None, every pixel of the source is its own electrode and every electrode fires on the same schedule.

• phase_dur (float, optional) – Duration of each pulse phase (ms).

• interphase_dur (float, optional) – Gap between cathodic and anodic phases (ms).

• cathodic_first (bool, optional) – If True, deliver the cathodic phase first.

• pulse (Stimulus, optional) – Pulse shape to repeat. Its amplitude is normalized away.

• clock (float, optional) – Stimulator clock period (ms). Pulse periods and raster offsets are rounded to whole clock cycles.

• n_levels (int, optional) – Number of gray levels used before modulation.

• frame_dur (float, optional) – Frame duration (ms). If None, infer it from the source.

• stretch (bool, optional) – If True, stretch source gray levels to [0, 1].

Notes

Plain numbers use the units documented above; unitful values are converted automatically. See pulse2percept.units.

__init__(implant=None, phase_dur=0.46, interphase_dur=0, cathodic_first=True, pulse=None, clock=None, n_levels=None, frame_dur=None, stretch=False)

Methods

__init__([implant, phase_dur, ...])
encode(source)	Encode an image or a video as a train of electrical pulses

Attributes

phase_dur
interphase_dur
cathodic_first
pulse
clock
n_levels
frame_dur
stretch
amp_unit	Unit of amplitudes returned by _modulate
implant	The implant this encoder is bound to, or None (read-only)

amp_unit = uA

Unit of amplitudes returned by _modulate

encode(source)

Encode an image or a video as a train of electrical pulses

Parameters:

source (Stimulus) – The image or video to encode. Gray levels are expected in [0, 1], which is what ImageStimulus and VideoStimulus produce. It must be dimensionless: this method is the boundary at which a picture becomes stimulation, so an electrical stimulus is not a valid source for it.

Returns:

stim – The encoded stimulus, ready for the implant to deliver. Its amplitudes are in microamps, or in threshold multiples (xTh) if the encoder’s amplitude parameters were, and its time axis is in milliseconds, whatever units the encoder’s own parameters were given in.

Return type:

Stimulus

Raises:

DimensionMismatchError – If source is not dimensionless.

property implant

The implant this encoder is bound to, or None (read-only)