Electrical Stimuli

The stimuli module provides a number of common electrical stimulus types, which can be assigned to electrodes of a ProsthesisSystem object:

Stimulus Description
MonophasicPulse single phase: cathodic or anodic
BiphasicPulse biphasic: cathodic + anodic
AsymmetricBiphasicPulse biphasic with unequal amplitude/duration
PulseTrain combine any Stimulus into a pulse train
BiphasicPulseTrain series of (symmetric) biphasic pulses
AsymmetricBiphasicPulseTrain series of asymmetric biphasic pulses
BiphasicTripletTrain series of biphasic pulse triplets

In addition, pulse2percept provides convenience functions to convert images and videos into Stimulus objects (see the io module).

Important

Stimuli specify electrical currents in microamps (uA) and time in milliseconds (ms). When in doubt, check the docstring of the function or class you are trying to use.

Understanding the Stimulus class

The Stimulus object defines a common interface for all electrical stimuli, consisting of a 2D data array with labeled axes, where rows denote electrodes and columns denote points in time.

A stimulus can be created from a variety of source types. The number of electrodes and time points will be automatically extracted from the source type:

Source type electrodes time
Scalar value 1 None
Nx1 NumPy array N None
NxM NumPy array N M

In addition, you can also pass a collection of source types (e.g., list, dictionary).

Note

Depending on the source type, a stimulus might have a time component or not.

Single-electrode stimuli

The easiest way to create a stimulus is to specify the current amplitude (uA) to be delivered to an electrode:

In [1]: from pulse2percept.stimuli import Stimulus

# Stimulate an unnamed electrode with -14uA:
In [2]: Stimulus(-14)
Out[2]: 
Stimulus(data=[[-14.]], dt=0.001, electrodes=[0], 
         is_charge_balanced=False, 
         metadata={'electrodes': {}, 'user': None}, 
         shape=(1, 1), time=None)

You can also specify the name of the electrode to be stimulated:

# Stimulate Electrode 'B7' with -14uA:
In [3]: Stimulus(-14, electrodes='B7')
Out[3]: 
Stimulus(data=[[-14.]], dt=0.001, electrodes=['B7'], 
         is_charge_balanced=False, 
         metadata={'electrodes': {}, 'user': None}, 
         shape=(1, 1), time=None)

By default, this stimulus will not have a time component (stim.time is None). Some models, such as ScoreboardModel, cannot handle stimuli in time.

To create stimuli in time, you can use one of the above mentioned stimulus types, such as MonophasicPulse or BiphasicPulseTrain:

# Stimulate Electrode 'A001' with a 20Hz pulse train lasting 0.5s
# (pulses: cathodic-first, 10uA amplitude, 0.45ms phase duration):
In [4]: from pulse2percept.stimuli import BiphasicPulseTrain

In [5]: pt = BiphasicPulseTrain(20, 10, 0.45, stim_dur=500)

In [6]: stim = Stimulus(pt)

In [7]: stim
Out[7]: 
Stimulus(data=[[  0. -10. -10. ...  10.   0.   0.]], 
         dt=0.001, electrodes=[0], 
         is_charge_balanced=False, metadata=dict, 
         shape=(1, 71), time=<(71,) np.ndarray>)

# This stimulus has a time component:
In [8]: stim.time
Out[8]: 
array([0.000e+00, 1.000e-03, 4.490e-01, ..., 4.509e+02, 4.509e+02,
       5.000e+02], dtype=float32)

You can specify not only the name of the electrode but also the time steps to be used:

# Stimulate Electrode 'C7' with int time steps:
In [9]: Stimulus(pt, electrodes='C7', time=np.arange(pt.shape[-1]))
Out[9]: 
Stimulus(data=[[  0. -10. -10. ...  10.   0.   0.]], 
         dt=0.001, electrodes=['C7'], 
         is_charge_balanced=True, metadata=dict, 
         shape=(1, 71), time=[ 0.  1.  2. ... 68. 69. 70.])

Creating multi-electrode stimuli

Stimuli can also be created from a list or dictionary of source types:

# Stimulate three unnamed electrodes with -2uA, 14uA, and -100uA,
# respectively:
In [10]: Stimulus([-2, 14, -100])
Out[10]: 
Stimulus(data=[[  -2.], [  14.], [-100.]], dt=0.001, 
         electrodes=[0 1 2], is_charge_balanced=False, 
         metadata={'electrodes': {}, 'user': None}, 
         shape=(3, 1), time=None)

Electrode names can be passed in a list:

In [11]: Stimulus([-2, 14, -100], electrodes=['A1', 'B1', 'C1'])
Out[11]: 
Stimulus(data=[[  -2.], [  14.], [-100.]], dt=0.001, 
         electrodes=['A1' 'B1' 'C1'], 
         is_charge_balanced=False, 
         metadata={'electrodes': {}, 'user': None}, 
         shape=(3, 1), time=None)

Alternatively, stimuli can be created from a dictionary:

# Equivalent to the previous one:
In [12]: Stimulus({'A1': -2, 'B1': 14, 'C1': -100})
Out[12]: 
Stimulus(data=[[  -2.], [  14.], [-100.]], dt=0.001, 
         electrodes=['A1' 'B1' 'C1'], 
         is_charge_balanced=False, 
         metadata={'electrodes': {}, 'user': None}, 
         shape=(3, 1), time=None)

The same is true for a dictionary of pulse trains:

In [13]: from pulse2percept.stimuli import BiphasicPulse

In [14]: Stimulus({'A1': BiphasicPulse(10, 0.45, stim_dur=100),
   ....:           'C9': BiphasicPulse(-30, 1, delay_dur=10, stim_dur=100)})
   ....: 
Out[14]: 
Stimulus(data=<(2, 15) np.ndarray>, dt=0.001, 
         electrodes=['A1' 'C9'], is_charge_balanced=True, 
         metadata=dict, shape=(2, 15), 
         time=<(15,) np.ndarray>)

Interacting with stimuli

Accessing individual data points

You can directly index into the Stimulus object to retrieve individual data points: stim[item]. item can be an integer, string, slice, or tuple.

For example, to retrieve all data points of the first electrode in a multi-electrode stimulus, use the following:

In [15]: stim = Stimulus(np.arange(10).reshape((2, 5)))

In [16]: stim[0]
Out[16]: array([0., 1., 2., 3., 4.], dtype=float32)

Here 0 is a valid electrode index, because we did not specify an electrode name. Analogously:

In [17]: stim = Stimulus(np.arange(10).reshape((2, 5)), electrodes=['B1', 'C2'])

In [18]: stim['B1']
Out[18]: array([0., 1., 2., 3., 4.], dtype=float32)

Similarly, you can retrieve all data points at a particular time:

In [19]: stim = Stimulus(np.arange(10).reshape((2, 5)))

In [20]: stim[:, 3]
Out[20]: 
array([[3.],
       [8.]])

Important

The second index or slice into stim is not a column index into stim.data, but an exact time specified in ms! For example, stim[:, 3] translates to “retrieve all data points at time = 3 ms”, not “retrieve stim.data[:, 3]”.

This works even when the specified time is not explicitly provided in the stimulus! In that case, the value is automatically interpolated (using SciPy’s interp1d):

# A single-electrode ramp stimulus:
In [21]: stim = Stimulus(np.arange(10).reshape((1, -1)))

In [22]: stim
Out[22]: 
Stimulus(data=[[0. 1. 2. ... 7. 8. 9.]], dt=0.001, 
         electrodes=[0], is_charge_balanced=False, 
         metadata={'electrodes': {}, 'user': None}, 
         shape=(1, 10), time=[0. 1. 2. ... 7. 8. 9.])

# Retrieve stimulus at t=3:
In [23]: stim[0, 3]
Out[23]: 3.0

# Time point 3.45 is not in the data provided above, but can be
# interpolated as follows:
In [24]: stim[0, 3.45]
Out[24]: 3.450000047683716

# This also works for multiple time points:
In [25]: stim[0, [3.45, 6.78]]
Out[25]: array([[3.45, 6.78]])

# Time points above the valid range will return the largest stored value:
In [26]: stim[0, 123.45]
Out[26]: 9.0

Accessing the raw data

The raw data is accessible as a 2D NumPy array (electrodes x time) stored in the data container of a Stimulus:

In [27]: stim = Stimulus(np.arange(10).reshape((2, 5)))

In [28]: stim.data
Out[28]: 
array([[0., 1., 2., 3., 4.],
       [5., 6., 7., 8., 9.]], dtype=float32)

You can index and slice the data container like any NumPy array.

Assigning new coordinates to an existing stimulus

You can change the coordinates of an existing Stimulus object, but retain all its data, by wrapping it in a second Stimulus object:

# Say you have a Stimulus object with unlabeled axes:
In [29]: stim = Stimulus(np.ones((2, 5)))

In [30]: stim
Out[30]: 
Stimulus(data=[[1. 1. 1. 1. 1.], [1. 1. 1. 1. 1.]], 
         dt=0.001, electrodes=[0 1], 
         is_charge_balanced=False, 
         metadata={'electrodes': {}, 'user': None}, 
         shape=(2, 5), time=[0. 1. 2. 3. 4.])

# You can create a new object from it with named electrodes:
In [31]: Stimulus(stim, electrodes=['A1', 'F10'])
Out[31]: 
Stimulus(data=[[1. 1. 1. 1. 1.], [1. 1. 1. 1. 1.]], 
         dt=0.001, electrodes=['A1' 'F10'], 
         is_charge_balanced=False, 
         metadata={'electrodes': {}, 'user': None}, 
         shape=(2, 5), time=[0. 1. 2. 3. 4.])

# Same goes for time points:
In [32]: Stimulus(stim, time=[0, 0.1, 0.2, 0.3, 0.4])
Out[32]: 
Stimulus(data=[[1. 1. 1. 1. 1.], [1. 1. 1. 1. 1.]], 
         dt=0.001, electrodes=[0 1], 
         is_charge_balanced=False, 
         metadata={'electrodes': {}, 'user': None}, 
         shape=(2, 5), time=[0.  0.1 0.2 0.3 0.4])

Compressing a stimulus

The compress method automatically compresses the data in two ways:

  • Removes electrodes with all-zero activation.
  • Retains only the time points at which the stimulus changes.

For example, only the signal edges of a pulse train are saved. That is, rather than saving the current amplitude at every 0.1ms time step, only the non-redundant values are retained. This drastically reduces the memory footprint of the stimulus. You can convince yourself of that by inspecting the size of a Stimulus object before and after compression:

# An uncompressed stimulus:
In [33]: stim = Stimulus([[0, 0, 0, 1, 2, 0, 0, 0]], time=[0, 1, 2, 3, 4, 5, 6, 7])

In [34]: stim
Out[34]: 
Stimulus(data=[[0. 0. 0. ... 0. 0. 0.]], dt=0.001, 
         electrodes=[0], is_charge_balanced=False, 
         metadata={'electrodes': {}, 'user': None}, 
         shape=(1, 8), time=[0. 1. 2. ... 5. 6. 7.])

# Now compress the data:
In [35]: stim.compress()

# Notice how the time axis have changed:
In [36]: stim
Out[36]: 
Stimulus(data=[[0. 0. 1. 2. 0. 0.]], dt=0.001, 
         electrodes=[0], is_charge_balanced=False, 
         metadata={'electrodes': {}, 'user': None}, 
         shape=(1, 6), time=[0. 2. 3. 4. 5. 7.])

Accessing stimulus metadata

Stimuli can store additional relevant information in the metadata dictionary. Users can also pass their own metadata, which will be stored in metadata["user"] Stimuli built from a collection of sources store the metadata for each source in metadata["electrodes"][electrode]["metadata"]:

# Accessing metadata
In [37]: stim = Stimulus([[0, 1, 2, 3]], metadata='user_metadata')

In [38]: stim.metadata
Out[38]: {'electrodes': {}, 'user': 'user_metadata'}

# Some objects store their own metadata
In [39]: stim = BiphasicPulseTrain(1,1,1, metadata='user_metadata')

In [40]: stim.metadata
Out[40]: {'freq': 1, 'amp': 1, 'phase_dur': 1, 'delay_dur': 0, 'user': 'user_metadata'}

# Multiple source metadata
In [41]: stim = Stimulus({'A1' : BiphasicPulseTrain(1,1,1, metadata='A1 metadata'),
   ....:                  'B2' : BiphasicPulseTrain(1,1,1, metadata='B2 metadata')},
   ....:                 metadata='stimulus metadata')
   ....: 

In [42]: stim.metadata
Out[42]: 
{'electrodes': {'A1': {'metadata': {'freq': 1,
    'amp': 1,
    'phase_dur': 1,
    'delay_dur': 0,
    'user': 'A1 metadata'},
   'type': pulse2percept.stimuli.pulse_trains.BiphasicPulseTrain},
  'B2': {'metadata': {'freq': 1,
    'amp': 1,
    'phase_dur': 1,
    'delay_dur': 0,
    'user': 'B2 metadata'},
   'type': pulse2percept.stimuli.pulse_trains.BiphasicPulseTrain}},
 'user': 'stimulus metadata'}