Pacing protocols¶
-
class
myokit.
Protocol
¶ Represents a pacing protocol as a sequence of
events
.Every event represents a time span during which the stimulus is non-zero. All events specify a stimulus level, a starting time and a duration. The stimulus level is given as a dimensionless number where 0 is no stimulus and 1 is a “full” stimulus. No range is specified: 2 would indicate “twice the normal stimulus”.
Periodic events can be created by specifying their period. A period of 0 is used for non-periodic events. The number of times a periodic event occurs can be set using the multiplier value. For any non-zero value, the event will occur exactly this many times.
If an event starts while another event is already active, the new event will determine the pacing value and the old event will be deactivated.
Scheduling two events to occur at the same time will result in an error, as the resulting behavior would be undefined. When events are scheduled with the same starting time an error will be raised immediately. If the clash only happens when an event re-occurs, an error will be raised when using the protocol (for example during a simulation).
An event with start time
a
and durationb
will be active during the interval[a, b)
. In other words, timea
will be the first time it is active and timeb
will be the first time aftera
at which it is not.Protocols can be compared with
==
, which will check if thecode()
for both protocols is the same. Protocols can be serialized withpickle
.-
add_step
(level, duration)¶ Appends an event to the end of this protocol.
This method can be used to easily create voltage-step protocols. A call to
p.add_step(level, duration)
is equivalent top.schedule(level, p.characteristic_time(), duration, 0, 0)
.Arguments:
level
- The stimulus level. 1 Represents a full-sized stimulus. Only non-zero levels should be set.
duration
- The length of the stimulus.
-
characteristic_time
()¶ Returns the characteristic time associated with this protocol.
The characteristic time is defined as the maximum characteristic time of all events in the protocol (see
ProtocolEvent.characteristic_time()
). For a sequence of events, this is simply the protocol duration.Examples:
>>> import myokit >>> # A sequence of events >>> p = myokit.Protocol() >>> p.schedule(1, 0, 100) >>> p.schedule(1, 100, 100) >>> p.characteristic_time() 200.0
>>> # A finitely reoccurring event >>> p = myokit.Protocol() >>> p.schedule(1, 100, 0.5, 1000, 3) >>> p.characteristic_time() 3100.0
>>> # An indefinitely reoccurring event, method returns period >>> p = myokit.Protocol() >>> p.schedule(1, 100, 0.5, 1000, 0) >>> p.characteristic_time() 1000.0
-
clone
()¶ Returns a deep clone of this protocol.
-
code
()¶ Returns the
mmt
code representing this protocol and its events.
-
create_log_for_interval
(a, b, for_drawing=False)¶ Deprecated alias of
log_for_interval()
.
-
create_log_for_times
(times)¶ Deprecated alias of
log_for_times()
.
-
events
()¶ Returns a list of all events in this protocol.
-
head
()¶ Returns the first event in this protocol.
If the protocol is empty,
None
will be returned.
-
in_words
()¶ Returns a description of this protocol in words.
-
is_infinite
()¶ Returns True if (and only if) this protocol contains indefinitely recurring events.
-
is_sequence
()¶ Checks if this protocol is a sequence of non-periodic steps.
The following checks are performed:
- The protocol does not contain any periodic events
- The protocol does not contain any overlapping events
See also
is_sequence_exception()
.
-
is_sequence_exception
()¶ Like
is_sequence()
, but raises an exception if the protocol is not a sequence, providing some information about the check that failed.
-
is_unbroken_sequence
()¶ Checks if this protocol is an unbroken sequence of steps. Returns
True
only for an unbroken sequence.The following checks are performed:
- The protocol does not contain any periodic events
- The protocol does not contain any overlapping events
- Each new event starts where the last ended
See also
is_unbroken_sequence_exception()
.
-
is_unbroken_sequence_exception
()¶ Like
is_unbroken_sequence()
, but raises an exception if the protocol is not an unbroken sequence, providing some information about the check that failed.
-
levels
()¶ Returns the levels of the events scheduled in this protocol.
For unbroken sequences of events this will produce a list of the levels visited by the protocol. For sequences with gaps or protocols with periodic events the relationship between actual levels and this method’s output is more complicated.
-
log_for_interval
(a, b, for_drawing=False)¶ Returns a
myokit.DataLog
containing the entriestime
andpace
, representing the value of the pacing stimulus at each point on the interval[a, b]
.The time points in the log will be
a
andb
, and any time in between at which the pacing value changes.If
for_drawing
is set toTrue
each time value where the protocol changes will be listed twice, so that a vertical line can be drawn from the old to the new pacing value.Note that the points returned are from
a
tob
inclusive (the interval[a, b]
), and so ifb
coincides with the end of the protocol a point(b, 0)
will be included in the output (protocol steps are defined as half-open, so include their starting point but not their end point).
-
log_for_times
(times)¶ Returns a
myokit.DataLog
containing the entriestime
andpace
representing the value of the pacing stimulus at each point.The time entries
times
must be an non-descreasing series of non-negative points.
-
pop
()¶ Removes and returns the event at the head of the queue.
-
range
()¶ Returns the minimum and maximum levels set in this protocol. Will return
0, 0
for empty protocols.
-
schedule
(level, start, duration, period=0, multiplier=0)¶ Schedules a new event.
level
- The stimulus level. 1 Represents a full-sized stimulus. Only non-zero levels should be set.
start
- The time this event first occurs.
duration
- The length of the stimulus.
period (optional)
- This event’s period, or
0
if it is a one-off event. multiplier (optional)
- For periodic events, this indicates the number of times this event
occurs. Non-periodic events or periodic events that continue
indefinitely can use
0
here.
-
tail
()¶ Returns the last event in this protocol. Note that recurring events can be rescheduled, so that the event returned by this method is not necessarily the last event that would occur when running the protocol.
If the protocol is empty,
None
will be returned.
-
value_at_times
(times)¶ Returns a list containing the value of the pacing variable at each time listed in
times
.Arguments:
times
- A (non-decreasing) sequence of (non-negative) points in time.
-
-
class
myokit.
ProtocolEvent
(level, start, duration, period=0, multiplier=0)¶ Describes an event occurring as part of a protocol.
-
characteristic_time
()¶ Returns a characteristic time associated with this event.
The time is calculated as follows:
- Singular events
characteristic_time = start + duration
- Finitely recurring events
characteristic_time = start + multiplier * period
- Indefinitely recurring events, where
start + duration < period
characteristic_time = period
- Indefinitely recurring events, where
start + duration >= period
characteristic_time = start + period
Roughly, this means that for finite events the full duration is returned, while indefinitely recurring events return the time until the first period is completed.
-
clone
()¶ Returns a clone of this event.
Note that links to other events are not included in the copy!
-
code
()¶ Returns a consistently formatted string representing an event.
-
duration
()¶ Returns this even’t duration.
-
in_words
()¶ Returns a description of this event.
-
level
()¶ Returns this event’s pacing level.
-
multiplier
()¶ Returns the number of times this event recurs. Zero is returned for singular events and indefinitely recurring events.
-
next
()¶ If this event is part of a
myokit.Protocol
, this returns the next scheduled event.
-
period
()¶ Returns this event’s period (or zero if the event is singular).
-
start
()¶ Returns the time this event starts.
-
stop
()¶ Returns the time this event ends, i.e. start() + duration().
-
-
class
myokit.
PacingSystem
(protocol, initial_time=0)¶ This class uses a
myokit.Protocol
to update the value of a pacing variable over time.A pacing system is created by passing in a protocol:
import myokit p = myokit.load_protocol(‘example’) s = myokit.PacingSystem(p)The given protocol will be cloned internally before use.
Initially, all pacing systems are at time 0. Time can be updated (but never moved back!) by calling
advance(new_time)()
. The current time can be obtained withtime()
. The value of the pacing variable is obtained frompace()
. The next time the pacing variable will change can be obtained fromnext_time()
.A pacing system can be used to calculate the values of the pacing variable at different times:
>>> import myokit >>> p = myokit.load_protocol('example') >>> s = myokit.PacingSystem(p) >>> import numpy as np >>> time = np.linspace(0, 1000, 10001) >>> pace = np.array([s.advance(t) for t in time])
-
advance
(new_time)¶ Advances the time in the pacing system to
new_time
.Returns the current value of the pacing variable.
-
next_time
()¶ Returns the next time the pacing system will halt at.
-
pace
()¶ Returns the current value of the pacing variable.
-
time
()¶ Returns the current time in the pacing system.
-
-
class
myokit.
TimeSeriesProtocol
(times, values, method=None)¶ Represents a pacing protocol as a sequence of time value pairs and an interpolation method (currently only linear interpolation is supported).
A 1D time-series should be given as input. During the simulation, the value of the pacing variable will be determined by interpolating between the two nearest points in the series. If the simulation time is outside the bounds of the time-series, the first or last value in the series will be used.
Protocols can be compared with
==
, which will check if the sequence of time value pairs is the same, and the interpolation method is the same. Protocols can be serialized withpickle
.-
clone
()¶ Returns a clone of this protocol.
-
pace
(t)¶ Returns the value of the pacing variable at time
t
.
-
times
()¶ Returns a list of the times in this protocol.
-
values
()¶ Returns a list of the values in this protocol.
-
Protocol factory¶
The myokit.pacing
module provides a factory methods to facilitate the
creation of Protocol
objects directly from python.
This module is imported automatically when import myokit
is run.
Periodic pacing¶
-
myokit.pacing.
bpm2bcl
(bpm, m=0.001)¶ Converts a beats-per-minute number to a basic cycle length in ms. For example a bpm of 60 equals a bcl of 1000ms.
>>> import myokit >>> print(myokit.pacing.bpm2bcl(60)) 1000.0
To use a different unit scaling, change the optional parameter
m
. For example, with m set to 1 the returned units are seconds:>>> print(myokit.pacing.bpm2bcl(120, 1)) 0.5
-
myokit.pacing.
blocktrain
(period, duration, offset=0, level=1.0, limit=0)¶ Creates a train of block pulses.
Each pulse lasts
duration
time units and a pulse is initiated everyperiod
time units.An optional offset to the first pulse can be specified using
offset
and the level of each pulse can be set usinglevel
. To limit the number of pulses generated set limit to a non-zero value.
Step protocols¶
-
myokit.pacing.
constant
(level)¶ Creates a very simple protocol where the pacing variable is held constant at a given level specified by the argument
level
.
-
myokit.pacing.
steptrain
(vsteps, vhold, tpre, tstep, tpost=0)¶ Creates a series of increasing or decreasing steps away from the fixed holding potential
vhold
, towards the voltages listed invsteps
.- For the first
tpre
time units, the pacing variable is held at the value given byvhold
. - For the next
tstep
time units, the pacing variable is held at a value fromvsteps
- For the next
tpost
time units, the pacing variable is held atvhold
again.
These three steps are repeated for each value in the
vsteps
.- For the first
-
myokit.pacing.
steptrain_linear
(vstart, vend, dv, vhold, tpre, tstep, tpost=0)¶ Creates a series of increasing or decreasing steps away from a holding value (typically a holding potential). This type of protocol is commonly used to measure activation or inactivation in ion channel models.
- For the first
tpre
time units, the pacing variable is held at the value given byvhold
. - For the next
tstep
time units, the pacing variable is held at a value ranging from vstart to vend, with increments dv. - For the next
tpost
time units, the pacing variable is held at the valuevhold
again.
These three steps are repeated for each value in the range from
vstart
up to (but not including)vend
, with an increment specified asdv
.- For the first