Common experiments

The module myokit.lib.common is deprecated: it will be removed in future versions of Myokit.

The module myokit.lib.common contains implementations of some common experiments.

Step protocol experiments

class myokit.lib.common.Activation(model, var, vvar=None)

Runs a step protocol and measures during the step. Can be used to create activation curves and I-V curves.

The protocol is defined as follows: Initially, the membrane potential is held at a holding potential vhold for the duration of thold time units. Then, the voltage is changed to vstep and held there for vstep time units. During this step, the cell’s response is logged. The experiment is repeated for vstep values ranging linearly from vmin to vmax with an increment of dv.

.               +--- vstep ---+
.               +-------------+
.               +-------------+
.               |             |
.  vhold -------+             +-
.  t=0          t=thold       t=thold+tstep
.  no current   current!

Accepts the following input arguments:

model
The model for which to run the simulations
var
A variable or a list of variables to log and use in calculations
vvar
The membrane potential variable or its qname. If not given, the method will search for a variable labelled membrane_potential.

Depending on the experiment being run, var could be a conductance or a current variable (or a list of conductances or currents).

The experiment is not performed until a call to one of the post-processing methods is made. After this, the raw data will be cached. Any change to the protocol variables after this point will delete the cached data.

convert_g2i(vrev=60, gmax=1)

Converts any data logged during this experiment from conductances to currents by multiplying each step’s data by:

gmax * (v - vrev)

This can be useful to obtain the original current traces when a conductance value was logged or when creating an IV protocol.

Calling this method will override any previously set conversion factor.

convert_i2g(vrev=60, gmax=1)

Converts any data logged during this experiment from currents to conductance by multiplying each step’s data by:

1 / (gmax * (v - vrev))

This can be useful to obtain an activation or inactivation curve from logged current data. However, since this leads to numerical issues around v == vrev its better to run these experiments directly on a conductance variable.

Calling this method will override any previously set conversion factor.

disable_conversion()

Disables any previously set conversion factor.

fit_boltzmann(var=None)

Attempts to fit a Boltzmann curve to a voltage-peaks dataset.

The variable whose peaks to use can be specified as var. If no variable is given the first value specified in the constructor is used. The fitted curve is given by:

g = gmin + (gmax - gmin) / (1 + np.exp((v - v_half) / k))

Note: This method requires a scipy installation providing the method scipy.optimize.curve_fit

peaks(normalize=False)

Returns a myokit.DataLog containing the tested step voltages and the peak values of the logged variable(s).

The names used in the simulation log correspond to those used in the model. For example, when doing an experiment on a Sodium channel the simulation log might have entries membrane.v and ina.g where membrane.v contains the used voltage steps while ina.g contains the peak values measured at those voltages.

If normalize is set to True, the peak data returned will be normalized by dividing all values by the largest (most positive) peak in the list. If no positive, non-zero values are found no normalization will be applied.

If any conversion factor was specified the data will be converted before normalization.

set_constant(var, value)

Changes the value of a constant in the used model.

set_holding_potential(vhold=-140, thold=1800)

Sets the holding potential and the time to hold. During the experiment, the cell will be held at vhold for thold time units before every voltage step.

set_max_step_size(dtmax=None)

Can be used to set a maximum step size to use in the logged parts of the simulation. Use dtmax==None to let the solver chose any size it likes.

set_step_potential(vmin=-100, vmax=50, dv=1, tstep=200)

Sets the step potentials and the step duration. Each experiment will step linearly from vmin to vmax with steps of size dv. The cell is held at each step for tstep time units.

steps()

Returns the list of steps this protocol will use.

times()

Returns a myokit.DataLog containing the time-to-peak for each logged variable at each voltage step.

traces()

Returns the logged traces for each variable as an ordered list of tuples (v, DataLog).

If any conversion factor was specified the data will be converted before returning.

class myokit.lib.common.Inactivation(model, var, vvar=None)

Can run an inactivation step protocol on a model and calculate various entities using the results.

The protocol starts by holding the membrane potential at a high value, causing the channels to fully activate and then inactivate. Next, the potential is stepped to a lower value, causing the inactivation to go away while the activation stays close to full. Current is measured after the step, when the cell is at the holding potential.

.  --- vstep ---+
.  -------------+
.  -------------+
.               |
.               +--- vhold ---+-
.  t=0          t=tstep       t=tstep+thold

Accepts the following input arguments:

model
The model for which to run the simulations
var
A variable or a list of variables to log and use in calculations
vvar
The membrane potential variable or its qname. If not given, the method will search for a variable labelled membrane_potential.

Depending on the experiment being run, var could be a conductance or a current variable (or a list of conductances or currents).

The experiment is not performed until a call to one of the post-processing methods is made. After this, the raw data will be cached. Any change to the protocol variables after this point will delete the cached data.

convert_g2i(vrev=60, gmax=1)

Converts any data logged during this experiment from conductances to currents by multiplying each step’s data by:

gmax * (v - vrev)

This can be useful to obtain the original current traces when a conductance value was logged or when creating an IV protocol.

Calling this method will override any previously set conversion factor.

convert_i2g(vrev=60, gmax=1)

Converts any data logged during this experiment from currents to conductance by multiplying each step’s data by:

1 / (gmax * (v - vrev))

This can be useful to obtain an activation or inactivation curve from logged current data. However, since this leads to numerical issues around v == vrev its better to run these experiments directly on a conductance variable.

Calling this method will override any previously set conversion factor.

disable_conversion()

Disables any previously set conversion factor.

fit_boltzmann(var=None)

Attempts to fit a Boltzmann curve to a voltage-peaks dataset.

The variable whose peaks to use can be specified as var. If no variable is given the first value specified in the constructor is used. The fitted curve is given by:

g = gmin + (gmax - gmin) / (1 + np.exp((v - v_half) / k))

Note: This method requires a scipy installation providing the method scipy.optimize.curve_fit

peaks(normalize=False)

Returns a myokit.DataLog containing the tested step voltages and the peak values of the logged variable(s).

The names used in the simulation log correspond to those used in the model. For example, when doing an experiment on a Sodium channel the simulation log might have entries membrane.v and ina.g where membrane.v contains the used voltage steps while ina.g contains the peak values measured at those voltages.

If normalize is set to True, the peak data returned will be normalized by dividing all values by the largest (most positive) peak in the list. If no positive, non-zero values are found no normalization will be applied.

If any conversion factor was specified the data will be converted before normalization.

set_constant(var, value)

Changes the value of a constant in the used model.

set_holding_potential(vhold=-20, thold=50)

Sets the holding potential and the time to hold. During the experiment, the cell will be held at vhold for thold time units before every voltage step.

set_max_step_size(dtmax=None)

Can be used to set a maximum step size to use in the logged parts of the simulation. Use dtmax==None to let the solver chose any size it likes.

set_step_potential(vmin=-100, vmax=-40, dv=1, tstep=1000)

Sets the step potentials and the step duration. Each experiment will step linearly from vmin to vmax with steps of size dv. The cell is held at each step for tstep time units.

steps()

Returns the list of steps this protocol will use.

times()

Returns a myokit.DataLog containing the time-to-peak for each logged variable at each voltage step.

traces()

Returns the logged traces for each variable as an ordered list of tuples (v, DataLog).

If any conversion factor was specified the data will be converted before returning.

class myokit.lib.common.Recovery(model, var, vvar=None)

Can run a two-pulse recovery from inactivation experiment and process the results.

The experiment proceeds as follows: first, the cell is held at a low holding potential vhold for thold time units. This causes the channels to fully deactivate (activation=0) and fully recover from inactivation (inactivation=1). Next, the membrane is stepped up to a voltage vstep and kept there for tstep1 time units. This causes the channels to activate (activation=1) and then inactivate (inactivation=0). The model then steps back down to vhold for twait time units, during which partial recovery from inactivation is expected. After this short recovery period, the cell is stepped back to vstep for another tstep2 time units. The recovery from inactivation can then be judged by comparing the peak current during step2 with the peak current during step1. By varying the time between steps twait a plot of recovery characteristics can be made.

.                +--- vstep ---+         +- vstep -+
.                |             |  twait  |         |
.                |             | <-----> |         |
.                |             |         |         |
.  +--- vhold ---+             +- vhold -+         +---
.  t=0           t=thold       t+=tstep1 t+=twait  t+=tstep2

Accepts the following input arguments:

model
The model for which to run the simulations
var
A conductance variable (or a list of variables) to record during the experiment. Variables can be specified using Variable objects or through their fully qualified names.
vvar
The membrane potential variable or its qname. If not given, the method will search for a variable labelled membrane_potential.

The argument var expects conduction variables, not currents. In other words, it expects the name of a variable g such that I = Gmax * g * (V - E). Using conductance in this test rather than current avoids the numerical problems incurred by dividing I through (V-E).

ratio()

Returns the ratios of the peak conductances (p1 / p2) for step 1 and step 2.

The returned value is a myokit.DataLog with entries corresponding to the given variable names.

set_holding_potential(vhold=-120, thold=2000)

Sets the holding potential and the time to hold. During the experiment, the cell will be held at vhold for thold time units before every voltage step.

set_pause_duration(tmin=0.5, tmax=1000, nt=50)

Sets the duration of the pauses between the steps.

tmin
The shortest time between steps
tmax
The longest time between steps
nt
The number of times to test
set_step_potential(vstep=-20, tstep1=500, tstep2=25)

Sets the step potential and the step durations.

vstep
The potential used during the steps
tstep1
The duration of the first pulse
tstep2
The duration of the second pulse

Others

class myokit.lib.common.Restitution(model, vvar=None)

Can run a restitution experiment and return the values needed to make a plot.

Accepts the following input arguments:

model
The model for which to run the simulations
vvar
The variable or variable name representing membrane potential. If not given, the method will look for the label membrane_potential, if that’s not found an exception is raised.
run()

Returns a DataLog containing the tested cycle lengths as cl and the measured action potential durations as apd. The diastolic intervals are given as di.

Each cycle length is repeated beats number of times, where beats is the number of beats specified in the constructor.

set_beats(beats=2, pre=50)

Sets the number of beats each cycle length is tested for.

beats
The number of beats during which apd is measured
pre
The number of pre-pacing beats done at each cycle length before the measurement.
set_max_step_size(dtmax=None)

Sets an (optional) maximum step size for the solver. To let the solver pick any step size it likes, use dtmax=None.

This method can be useful to avoid “CVODES flag 22” errors.

set_stimulus(duration=2.0, level=1)

Sets the stimulus used to pace the model.

stim_duration
The duration of the pacing stimulus.
stim_level
The level of the dimensionless pacing stimulus.
set_threshold(threshold=-70)

Sets the APD threshold, specified as a fixed membrane potential.

set_times(clmin=300, clmax=1200, dcl=20)

Sets the pacing cycle lengths tested in this experiment.

clmin
The shortest cycle length tested.
clmax
The longest cycle length tested.
dcl
The size of the steps from clmin to clmax
class myokit.lib.common.StrengthDuration(model, ivar, vvar=None)

For a range of durations, this experiment checks the stimulus size needed to excite a cell.

Accepts the following input arguments:

model
The model to run the experiment with.
ivar
A variable that can be used as the stimulus current. It’s value will be set as pace * amplitude where pace is a variable bound to the pacing signal and amplitude is varied by the method.
vvar
A variable that indicates the membrane potential. If not specified (or given as None), the method will search for a variable labeled as membrane_potential.
run(debug=False)

Runs the experiment, returning a myokit.DataLog with the entries duration and strength, where each strenght is the minimum required to create a depolarisation at the corresponding duration.

set_currents(imin=-250, imax=0)

Sets the range of current levels tested.

imin
The lowest (or most negative) current amplitude to test.
imax
The greatest (or least negative) current amplitude to test.
set_precision(precision=10)

Sets the number of different amplitudes tried. This is done using a bisection algorithm, so low values of precision can still produce a good result.

set_threshold(threshold=10)

Sets the level above which the membrane potential must rise to count as a depolarization.

set_times(tmin=0.2, tmax=2.0, dt=0.1, twait=50)

Sets the tested stimulus durations.

tmin
The smallest stimulus time tested.
tmax
The largest stimulus time tested.
dt
The step size when going from tmin to tmax.
twait
The duration of the experiment that tries to measure a depolarization.

Base classes

class myokit.lib.common.StepProtocol(model, var, vvar=None)

An abstract base class for step protocol experiments.

_run()

Should run the simulation and save the current traces in self._logs

convert_g2i(vrev=60, gmax=1)

Converts any data logged during this experiment from conductances to currents by multiplying each step’s data by:

gmax * (v - vrev)

This can be useful to obtain the original current traces when a conductance value was logged or when creating an IV protocol.

Calling this method will override any previously set conversion factor.

convert_i2g(vrev=60, gmax=1)

Converts any data logged during this experiment from currents to conductance by multiplying each step’s data by:

1 / (gmax * (v - vrev))

This can be useful to obtain an activation or inactivation curve from logged current data. However, since this leads to numerical issues around v == vrev its better to run these experiments directly on a conductance variable.

Calling this method will override any previously set conversion factor.

disable_conversion()

Disables any previously set conversion factor.

fit_boltzmann(var=None)

Attempts to fit a Boltzmann curve to a voltage-peaks dataset.

The variable whose peaks to use can be specified as var. If no variable is given the first value specified in the constructor is used. The fitted curve is given by:

g = gmin + (gmax - gmin) / (1 + np.exp((v - v_half) / k))

Note: This method requires a scipy installation providing the method scipy.optimize.curve_fit

peaks(normalize=False)

Returns a myokit.DataLog containing the tested step voltages and the peak values of the logged variable(s).

The names used in the simulation log correspond to those used in the model. For example, when doing an experiment on a Sodium channel the simulation log might have entries membrane.v and ina.g where membrane.v contains the used voltage steps while ina.g contains the peak values measured at those voltages.

If normalize is set to True, the peak data returned will be normalized by dividing all values by the largest (most positive) peak in the list. If no positive, non-zero values are found no normalization will be applied.

If any conversion factor was specified the data will be converted before normalization.

set_constant(var, value)

Changes the value of a constant in the used model.

set_holding_potential(vhold=-140, thold=1800)

Sets the holding potential and the time to hold. During the experiment, the cell will be held at vhold for thold time units before every voltage step.

set_max_step_size(dtmax=None)

Can be used to set a maximum step size to use in the logged parts of the simulation. Use dtmax==None to let the solver chose any size it likes.

set_step_potential(vmin=-100, vmax=50, dv=1, tstep=200)

Sets the step potentials and the step duration. Each experiment will step linearly from vmin to vmax with steps of size dv. The cell is held at each step for tstep time units.

steps()

Returns the list of steps this protocol will use.

times()

Returns a myokit.DataLog containing the time-to-peak for each logged variable at each voltage step.

traces()

Returns the logged traces for each variable as an ordered list of tuples (v, DataLog).

If any conversion factor was specified the data will be converted before returning.