stimuli

Functions for creating retinal implants

BiphasicPulse(ptype, pdur, tsample[, …])

Methods

MonophasicPulse(ptype, pdur, tsample[, …])

Methods

PulseTrain(tsample[, freq, amp, dur, delay, …])

Methods

Movie2Pulsetrain(rflum, tsample[, fps, …]) Deprecated function. Use p2p.stimuli.video2pulsetrain instead.
image2pulsetrain(img, implant[, coding, …]) Converts an image into a series of pulse trains
parse_pulse_trains(stim, implant) Parse input stimulus and convert to list of pulse trains
retinalmovie2electrodtimeseries(rf, movie) Deprecated function.
video2pulsetrain(filename, implant[, …]) Converts a video into a series of pulse trains

BiphasicPulse

class pulse2percept.stimuli.BiphasicPulse(ptype, pdur, tsample, interphase_dur=0)[source]

Bases: pulse2percept.utils.TimeSeries

Methods

append(other) Appends the data of another TimeSeries object (in time)
max() Returns the time and value of the largest data point
max_frame() Returns the time frame that contains the largest data point
resample(tsample_new) Returns data sampled according to new time step
__init__(ptype, pdur, tsample, interphase_dur=0)[source]

A charge-balanced pulse with a cathodic and anodic phase

A single biphasic pulse with duration pdur per phase, separated by interphase_dur is returned.

Parameters:

ptype : {‘cathodicfirst’, ‘anodicfirst’}

A cathodic-first pulse has the negative phase first, whereas an anodic-first pulse has the positive phase first.

pdur : float

Duration of single (positive or negative) pulse phase in seconds.

tsample : float

Sampling time step in seconds.

interphase_dur : float, optional

Duration of inter-phase interval (between positive and negative pulse) in seconds. Default: 0.

MonophasicPulse

class pulse2percept.stimuli.MonophasicPulse(ptype, pdur, tsample, delay_dur=0, stim_dur=None)[source]

Bases: pulse2percept.utils.TimeSeries

Methods

append(other) Appends the data of another TimeSeries object (in time)
max() Returns the time and value of the largest data point
max_frame() Returns the time frame that contains the largest data point
resample(tsample_new) Returns data sampled according to new time step
__init__(ptype, pdur, tsample, delay_dur=0, stim_dur=None)[source]

A pulse with a single phase

Parameters:

ptype : {‘anodic’, ‘cathodic’}

Pulse type. Anodic pulses have positive current amplitude, cathodic pulses have negative amplitude.

pdur : float

Pulse duration (s).

tsample : float

Sampling time step (s).

delay_dur : float, optional

Pulse delay (s). Pulse will be zero-padded (prepended) to deliver the pulse only after delay_dur milliseconds. Default: 0.

stim_dur : float, optional

Stimulus duration (ms). Pulse will be zero-padded (appended) to fit the stimulus duration. Default: No additional zero padding, stim_dur is pdur`+`delay_dur.

PulseTrain

class pulse2percept.stimuli.PulseTrain(tsample, freq=20, amp=20, dur=0.5, delay=0, pulse_dur=0.00045, interphase_dur=0.00045, pulsetype=’cathodicfirst’, pulseorder=’pulsefirst’)[source]

Bases: pulse2percept.utils.TimeSeries

Methods

append(other) Appends the data of another TimeSeries object (in time)
max() Returns the time and value of the largest data point
max_frame() Returns the time frame that contains the largest data point
resample(tsample_new) Returns data sampled according to new time step
__init__(tsample, freq=20, amp=20, dur=0.5, delay=0, pulse_dur=0.00045, interphase_dur=0.00045, pulsetype=’cathodicfirst’, pulseorder=’pulsefirst’)[source]

A train of biphasic pulses

Parameters:

tsample : float

Sampling time step (seconds).

freq : float, optional, default: 20 Hz

Frequency of the pulse envelope (Hz).

amp : float, optional, default: 20 uA

Max amplitude of the pulse train in micro-amps.

dur : float, optional, default: 0.5 seconds

Stimulus duration in seconds.

delay : float, optional, default: 0

Delay until stimulus on-set in seconds.

pulse_dur : float, optional, default: 0.45 ms

Single-pulse duration in seconds.

interphase_duration : float, optional, default: 0.45 ms

Single-pulse interphase duration (the time between the positive and negative phase) in seconds.

pulsetype : str, optional, default: ‘cathodicfirst’

Pulse type {‘cathodicfirst’ | ‘anodicfirst’}, where ‘cathodicfirst’ has the negative phase first.

pulseorder : str, optional, default: ‘pulsefirst’

Pulse order {‘gapfirst’ | ‘pulsefirst’}, where ‘pulsefirst’ has the pulse first, followed by the gap. ‘gapfirst’ has it the other way round.

Movie2Pulsetrain

pulse2percept.stimuli.Movie2Pulsetrain(rflum, tsample, fps=30.0, amp_transform=’linear’, amp_max=60, freq=20, pulse_dur=0.0005, interphase_dur=0.0005, pulsetype=’cathodicfirst’, stimtype=’pulsetrain’)[source]

Deprecated function. Use p2p.stimuli.video2pulsetrain instead.

Function Movie2Pulsetrain is deprecated, and will be removed in version 0.3. Use p2p.stimuli.video2pulsetrain instead.

Is used to create pulse-train stimulus based on luminance over time from
a movie

image2pulsetrain

pulse2percept.stimuli.image2pulsetrain(img, implant, coding=’amplitude’, valrange=[0, 50], max_contrast=False, const_val=20, invert=False, tsample=5e-06, dur=0.5, pulsedur=0.0005, interphasedur=0.0005, pulsetype=’cathodicfirst’)[source]

Converts an image into a series of pulse trains

This function creates an input stimulus from an RGB or grayscale image. The image is down-sampled to fit the spatial layout of the implant (currently supported are ArgusI and ArgusII arrays). Requires Scikit-Image.

Parameters:

img : str|array_like

An input image, either a valid filename (string) or a numpy array (row x col x channels).

implant : p2p.implants.ElectrodeArray

An ElectrodeArray object that describes the implant.

coding : {‘amplitude’, ‘frequency’}, optional

A string describing the coding scheme: - ‘amplitude’: Image intensity is linearly converted to a current

amplitude between valrange[0] and valrange[1]. Frequency is held constant at const_freq.

  • ‘frequency’: Image intensity is linearly converted to a pulse

    frequency between valrange[0] and valrange[1]. Amplitude is held constant at const_amp.

Default: ‘amplitude’

valrange : list, optional

Range of stimulation values to be used (If coding is ‘amplitude’, specifies min and max current; if coding is ‘frequency’, specifies min and max frequency). Default: [0, 50]

max_contrast : bool, optional

Flag wether to maximize image contrast (True) or not (False). Default: False

const_val : float, optional

For frequency coding: The constant amplitude value to be used for all pulse trains. For amplitude coding: The constant frequency value to be used for all pulse trains. Default: 20

invert : bool, optional

Flag whether to invert the grayscale values of the image (True) or not (False). Default: False

tsample : float, optional

Sampling time step (seconds). Default: 0.005 / 1000 seconds.

dur : float, optional

Stimulus duration (seconds). Default: 0.5 seconds.

pulsedur : float, optional

Duration of single (positive or negative) pulse phase in seconds.

interphasedur : float, optional

Duration of inter-phase interval (between positive and negative pulse) in seconds.

pulsetype : {‘cathodicfirst’, ‘anodicfirst’}, optional

A cathodic-first pulse has the negative phase first, whereas an anodic-first pulse has the positive phase first.

Returns:

pulses : list

A list of p2p.stimuli.PulseTrain objects, one for each electrode in the implant.

parse_pulse_trains

pulse2percept.stimuli.parse_pulse_trains(stim, implant)[source]

Parse input stimulus and convert to list of pulse trains

Parameters:

stim : utils.TimeSeries|list|dict

There are several ways to specify an input stimulus:

  • For a single-electrode array, pass a single pulse train; i.e., a single utils.TimeSeries object.
  • For a multi-electrode array, pass a list of pulse trains, where every pulse train is a utils.TimeSeries object; i.e., one pulse train per electrode.
  • For a multi-electrode array, specify all electrodes that should receive non-zero pulse trains by name in a dictionary. The key of each element is the electrode name, the value is a pulse train. Example: stim = {‘E1’: pt, ‘stim’: pt}, where ‘E1’ and ‘stim’ are electrode names, and pt is a utils.TimeSeries object.

implant : p2p.implants.ElectrodeArray

A p2p.implants.ElectrodeArray object that describes the implant.

Returns:

A list of pulse trains; one pulse train per electrode.

retinalmovie2electrodtimeseries

pulse2percept.stimuli.retinalmovie2electrodtimeseries(rf, movie)[source]

Deprecated function.

Function retinalmovie2electrodtimeseries is deprecated since version 0.2, and will be removed in version 0.3.

Calculates the luminance over time for each electrodes receptive field.

video2pulsetrain

pulse2percept.stimuli.video2pulsetrain(filename, implant, framerate=20, coding=’amplitude’, valrange=[0, 50], max_contrast=False, const_val=20, invert=False, tsample=5e-06, pulsedur=0.0005, interphasedur=0.0005, pulsetype=’cathodicfirst’, ffmpeg_path=None, libav_path=None)[source]

Converts a video into a series of pulse trains

This function creates an input stimulus from a video. Every frame of the video is passed to image2pulsetrain, where it is down-sampled to fit the spatial layout of the implant (currently supported are ArgusI and ArgusII arrays). In this mapping, rows of the image correspond to rows in the implant (top row, Argus I: A1 B1 C1 D1, Argus II: A1 A2 … A10).

Requires Scikit-Image and Scikit-Video.

Parameters:

img : str|array_like

An input image, either a valid filename (string) or a numpy array (row x col x channels).

implant : p2p.implants.ElectrodeArray

An ElectrodeArray object that describes the implant.

coding : {‘amplitude’, ‘frequency’}, optional

A string describing the coding scheme: - ‘amplitude’: Image intensity is linearly converted to a current

amplitude between valrange[0] and valrange[1]. Frequency is held constant at const_freq.

  • ‘frequency’: Image intensity is linearly converted to a pulse

    frequency between valrange[0] and valrange[1]. Amplitude is held constant at const_amp.

Default: ‘amplitude’

valrange : list, optional

Range of stimulation values to be used (If coding is ‘amplitude’, specifies min and max current; if coding is ‘frequency’, specifies min and max frequency). Default: [0, 50]

max_contrast : bool, optional

Flag wether to maximize image contrast (True) or not (False). Default: False

const_val : float, optional

For frequency coding: The constant amplitude value to be used for all pulse trains. For amplitude coding: The constant frequency value to be used for all pulse trains. Default: 20

invert : bool, optional

Flag whether to invert the grayscale values of the image (True) or not (False). Default: False

tsample : float, optional

Sampling time step (seconds). Default: 0.005 / 1000 seconds.

dur : float, optional

Stimulus duration (seconds). Default: 0.5 seconds.

pulsedur : float, optional

Duration of single (positive or negative) pulse phase in seconds.

interphasedur : float, optional

Duration of inter-phase interval (between positive and negative pulse) in seconds.

pulsetype : {‘cathodicfirst’, ‘anodicfirst’}, optional

A cathodic-first pulse has the negative phase first, whereas an anodic-first pulse has the positive phase first.

Returns:

pulses : list

A list of p2p.stimuli.PulseTrain objects, one for each electrode in the implant.