Data blocks¶
Data blocks provide a useful representation for data logged in rectangular 1d
or 2d simulations. They can be created from DataLog
objects containing
data in a suitable form.
In DataLogs
, the data is stored per variable, per cell. That means the
timeseries for the membrane potential of cell (x,y)
is stored in one list
and the timeseries for the same variable of cell (u,v)
is stored in
another. In some cases, it can be beneficial to have a reshaped view of the
data, where the membrane potential has a single timeseries of 2d (or 1d)
values. This representation is provided by the DataBlock
classes.
An additional feature of data blocks is that they make strong assumptions about the stored data:
 Each 1d or 2d series has the same dimensions
(w)
or(w, h)
.  The data represents a rectangular grid of cells.
 The cell indices run from
0
tow1
in the xdirection, and0
toh1
in the ydirection.
By contrast, the DataLog
class only assumes that each time series it
contains has the same length.
The class
DataBlockViewer
provides
a GUI for visualising DataBlock1d
and DataBlock2d
objects.

class
myokit.
DataBlock1d
(w, time, copy=True)¶ Container for timeseries of 1d rectangular data arrays.
Each
DataBlock1d
has a fixed widthw
, and a 0d time series vector containing a sequence ofn
times.Onedimensional time series can be added to the block, provided the data also contains
n
instances ofw
data points. The data should be passed in as a numpy array with shape(n, w)
.Zerodimensional time series can be added, provided they have length
n
.A “onedimensional timeseries” is a series of equally sized 1d arrays (sequences), such that the first corresponds to a time
t[0]
, the second tot[1]
, etc. Each array has shape(n, w)
.A “zerodimensional timeseries” is a series of single values where the first corresponds to a time
t[0]
, the second tot[1]
, etc.Constructor info:
w
 Each 1d block should have dimension
w
by1
. time
 A sequence of
n
times. copy
 By default, a copy of the given time sequence will be stored. To
prevent this copy, set
copy=False
.

block2d
()¶ Returns a
myokit.DataBlock2d
based on this 1d data block.

cv
(name, threshold=30, length=0.01, time_multiplier=0.001, border=None)¶ Calculates conduction velocity (CV) in a cable.
Accepts the following arguments:
name
 The name (as string) of the membrane potential variable. This should be a 1d variable in this datablock.
threshold
 The start of an action potential is determined as the first time the membrane potential crosses this threshold (default=30mV) and has a positive direction.
length
 The length of a single cell in cm, in the direction of the cable.
The default is
length=0.01cm
. time_multiplier
 A multiplier used to convert the used time units to seconds. Most simulations use milliseconds, so the default value is 1e3.
border
 The number of cells to exclude from the analysis on each end of the cable to avoid boundary effects. If not given, 1/3 of the number of cells will be used, with a maximum of 50 cells on each side.
Returns the approximate conduction velocity in cm/s. If no cv can be

static
fromDataLog
(log)¶ Creates a DataBlock1d from a
myokit.DataLog
.

get0d
(name)¶ Returns the 0d timeseries identified by
name
. The data is returned directly, no copy is made.

get1d
(name)¶ Returns the 1d timeseries identified by
name
. The data is returned directly, no copy is made.The returned data is a 2d array of the shape given by
shape()
.

grid
(name, transpose=True)¶ Returns a 2d grid representation suitable for plotting color maps or contours with
matplotlib.pyplot
methods such aspcolor
andpcolormesh
.When used for example with
pyplot.pcolormesh(*block.grid('membrane.V'))
this will create a 2d plot where the horizontal axis shows time and the vertical axis shows the cell index.Arguments:
name
 The name identifying the 1d datavalues to return.
transpose
 By default (
transpose=True
) the data is returned so thatx
represents time andy
represents space. To reverse this (and use the order used internally in the datablocks), settranspose=False
.
The returned format is a tuple
(x, y, z)
wherex
,y
andz
are all 2d numpy arrays. Here,x
(time) andy
(space) describe the x and ycoordinates of rectangles, with a color (data value) given byz
.In particular, each rectangle
(x[i, j], y[i, j])
,(x[i + 1, j], y[i + 1, j])
,(x[i, j + 1], y[i, j + 1])
,(x[i + 1,j + 1], y[i + 1,j + 1])
, has a color given byz[i, j]
.As a result, for a block of width
w
(e.g.,w
cells) containingn
logged time points, the method returns arraysx
andy
of shape(w + 1, n + 1)
and an arrayz
of shape(w, n)
.See
image_grid()
for a method wherex
,y
andz
all have shape(w, n)
.

image_grid
(name, transpose=True)¶ Returns a 2d grid representation of the data.
The returned format is a tuple
(x, y, z)
wherex
,y
andz
are all 2d numpy arrays. Here,x
andy
describe the time and spacecoordinates of the logged points respectively, andz
describes the corresponding data value. For a block of widthw
(e.g.,w
cells) containingn
logged time points, each returned array has the shape(w, n)
.Arguments:
name
 The name identifying the 1d datavalues to return.
transpose
 By default, the data is transposed so that the
x
coordinates become time and they
coordinates become space. Usetranspose=False
to return untransposed results.

keys0d
()¶ Returns an iterator over this block’s 0d time series.

keys1d
()¶ Returns an iterator over this block’s 1d time series.

len0d
()¶ Returns the number of 0d time series in this block.

len1d
()¶ Returns the number of 1d time series in this block.

static
load
(filename, progress=None, msg='Loading DataBlock1d')¶ Loads a
DataBlock1d
from the specified file.To obtain feedback on the simulation progress, an object implementing the
myokit.ProgressReporter
interface can be passed in. passed in asprogress
. An optional description of the current simulation to use in the ProgressReporter can be passed in as msg.

save
(filename)¶ Writes this
DataBlock1d
to a binary file.The resulting file will be a zip file with the following entries:
header_block1d.txt
: A header file containing the following information (line by line):nt
the number of points in time in each entrynx
the length of each 1d block"dtype"
the used datatype (either “d” or “f”)"name"
the names of all 0d entries, each on its own line1
the indication that the 1d entries are starting"name"
the names of all 1d entries, each on its own line
data.bin
: A binary file containing the following data, in the data type specified by the header, and littleendian: The
nt
time values  All 0d entries
 All 1d entries, reshaped using numpy order=’C’

set0d
(name, data, copy=True)¶ Adds or updates a zerodimensional time series
data
for the variable named by the stringname
.The
data
must be specified as a sequence of lengthn
, wheren
is the first value returned byDataBlock1d.shape()
.By default, a copy of the given data will be stored. To prevent this and store a reference instead, set
copy=False
.

set1d
(name, data, copy=True)¶ Adds or updates a onedimensional time series
data
for the variable named by the stringname
.The
data
must be specified as a numpy array with shape(n, w)
, where(n, w)
is the value returned byDataBlock1d.shape()
.By default, a copy of the given data will be stored. To prevent this and store a reference instead, set
copy=False
.

shape
()¶ Returns the required shape for 1d data passed to this data block. Zero dimensional series passed in must have length
shape()[0]
.

time
()¶ Returns the time data for this datablock. The data is returned directly, no copy is made.

trace
(variable, x)¶ Returns a 0d time series of the value
variable
, corresponding to the cell at positionx
. The data is returned directly, no copy is made.

class
myokit.
DataBlock2d
(w, h, time, copy=True)¶ Container for timeseries of 2d rectangular data arrays.
Each
DataBlock2d
has a fixed widthw
and heighth
, and a 0d time series vector containing a sequence ofn
times.Twodimensional time series can be added to the block, provided the data also contains
n
instances ofw
byh
data points. The data should be passed in as a numpy array with shape(n, h, w)
.Zerodimensional time series can be added, provided they have length
n
.A “twodimensional timeseries” is a series of equally sized 2d arrays (sequences), such that the first corresponds to a time
t[0]
, the second tot[1]
, etc.A “zerodimensional timeseries” is a series of single values where the first corresponds to a time
t[0]
, the second tot[1]
, etc.Constructor info:
w
 The width of a 2d block. Each block should have shape (n, h, w)
h
 The height of a 2d block. Each block should have shape (n, h, w)
time
 A sequence of
n
times. copy
 By default, a copy of the given time sequence will be stored. To
prevent this copy, set
copy=False
.

colors
(name, colormap='traditional', lower=None, upper=None)¶ Converts the 2d series indicated by
name
into a list ofW*H*RGB
arrays, with each entry represented as an 8 bit unsigned integer.

static
combine
(block1, block2, map2d, map0d=None, pos1=None, pos2=None)¶ Combines two blocks, containing information about different areas, into a single
DataBlock2d
.Both blocks must contain data from the same points in time.
A mapping from old to new variables must be passed in as a dictionary
map2d
. The blocks can have different sizes but must have the same time vector. If any empty space is created it is padded with a value taken from one of the data blocks or a padding value specified as part ofmap2d
.Positions for the datablocks can be specified as
pos1
andpos2
, the new datablock will have indices ranging from(0, 0)
to(max(pos1[0] + w1, pos2[0] + w2), max(pos1[0] + w1, pos2[0] + w2))
, wherew1
andw2
are the widths ofblock1
andblock2
respectively. Negative indices are not supported and the blocks are not allowed to overlap.Arguments:
block1
 The first DataBlock2d
block2
 The second DataBlock2d. This must have the same time vector as the first.
map2d
 A dictionary object showing how to map 2d variables from both
blocks into the newly created datablock. The format must be:
new_name : (old_name_1, old_name_2, padding_value)
. Here,new_name
is the name of the new 2d variable,old_name_1
is the name of a 2d variable inblock1
,old_name_2
is the name of a 2d variable inblock2
andpadding_value
is an optional value indicating the value to use for undefined spaces in the new block. map0d=None
, A dictionary object showing how to map 0d variables from both
blocks into the newly created datablock. Each entry must take the
format:
new_name : (old_name_1, None)
ornew_name : (None, old_name_2)
. pos1=None
 Optional value indicating the position
(x, y)
of the first datablock. By default(0, 0)
is used. pos2=None
 Optional value indicating the position
(x, y)
of the first datablock. By default(w1, 0)
is used, wherew1
is the width ofblock1
.

dominant_eigenvalues
(name)¶ Takes the 2d data specified by
name
and computes the dominant eigenvalue for each point in time. This only works for datablocks with a square 2d grid.The “dominant eigenvalue” is defined as the eigenvalue with the largest magnitude (
sqrt(a + bi)
).The returned data is a 1d numpy array.

eigenvalues
(name)¶ Takes the 2d data specified as
name
and computes the eigenvalues of its data matrix at every point in time. This only works for datablocks with a square 2d grid.The returned data is a 2d numpy array where the first axis is time and the second axis is the index of each eigenvalue.

static
fromDataLog
(log)¶ Creates a DataBlock2d from a
myokit.DataLog
.

get0d
(name)¶ Returns the 0d timeseries identified by
name
. The data is returned directly, no copy is made.

get2d
(name)¶ Returns the 2d timeseries identified by
name
. The data is returned directly, no copy is made.

images
(name, colormap='traditional', lower=None, upper=None)¶ Converts the 2d series indicated by
name
into a list of 1d arrays in a rowstrided image formatARGB32
.

is_square
()¶ Returns True if this data block’s grid is square.

items0d
()¶ Returns an iterator over
(name, value)
pairs for the 0d series stored in this block. The given values are references! No copy of the data is made.

items2d
()¶ Returns an iterator over
(name, value)
pairs for the 2d series stored in this block. The given values are references! No copy of the data is made.

keys0d
()¶ Returns an iterator over this block’s 0d time series.

keys2d
()¶ Returns an iterator over this block’s 2d time series.

largest_eigenvalues
(name)¶ Takes the 2d data specified by
name
and computes the largest eigenvalue for each point in time. This only works for datablocks with a square 2d grid.The “largest eigenvalue” is defined as the eigenvalue with the most positive real part. Note that the returned values may be complex.
The returned data is a 1d numpy array.

len0d
()¶ Returns the number of 0d time series in this block.

len2d
()¶ Returns the number of 2d time series in this block.

static
load
(filename, progress=None, msg='Loading DataBlock2d')¶ Loads a
DataBlock2d
from the specified file.To obtain feedback on the simulation progress, an object implementing the
myokit.ProgressReporter
interface can be passed in. passed in asprogress
. An optional description of the current simulation to use in the ProgressReporter can be passed in as msg.If the given file contains a
DataBlock1d
this is read and converted to a 2d block without warning.

save
(filename)¶ Writes this
DataBlock2d
to a binary file.The resulting file will be a zip file with the following entries:
header_block2d.txt
: A header file containing the following information (line by line):nt
the number of points in time in each entryny
the height of each 2d blocknx
the width of each 2d block"dtype"
the used datatype (either “d” or “f”)"name"
the names of all 0d entries, each on its own line2
the indication that the 2d entries are starting"name"
the names of all 2d entries, each on its own line
data.bin
: A binary file containing the following data, in the data type specified by the header, and littleendian: The
nt
time values  All 0d entries
 All 2d entries, reshaped using numpy order=’C’

save_frame_csv
(filename, name, frame, xname='x', yname='y', zname='value')¶ Stores a single 2d variable’s data at a single point in time to disk, using a csv format where each point in the frame is stored on a separate line as a tuple
x, y, value
.

save_frame_grid
(filename, name, frame, delimx=' ', delimy='\n')¶ Stores a single 2d variable’s data at a single point in time to disk, using a simple 2d format where each row of the resulting data file represents a row of the frame.
Data from 2d variable
name
at frameframe
will be stored infilename
row by row. Each column is separated bydelimx
(by default a space) and rows are separated bydelimy
(by default this will be a newline character).

set0d
(name, data, copy=True)¶ Adds or updates a zerodimensional time series
data
for the variable named by the stringname
.The
data
must be specified as a sequence of lengthn
, wheren
is the first value returned byDataBlock2d.shape()
.By default, a copy of the given data will be stored. To prevent this and store a reference instead, set
copy=False
.

set2d
(name, data, copy=True)¶ Adds or updates a twodimensional time series
data
for the variable named by the stringname
.The
data
must be specified as a numpy array with shape(n, w)
, where(n, w)
is the value returned byDataBlock2d.shape()
.By default, a copy of the given data will be stored. To prevent this and store a reference instead, set
copy=False
.

shape
()¶ Returns the required shape for 2d data passed to this data block. Zero dimensional series passed in must have length
shape()[0]
.

time
()¶ Returns the time data for this datablock. The data is returned directly, no copy is made.

trace
(variable, x, y)¶ Returns a 0d time series of the value
variable
, corresponding to the cell at positionx
,y
. The data is returned directly, no copy is made.

class
myokit.
ColorMap
¶ Abstract class
Applies colormap transformations to floating point data and returns RGB data.
ColorMaps
are callable objects and take the following arguments:floats
 A 1dimensional numpy array of floating point numbers.
lower=None
 A lower bound for the floats in the input. The
lower
andupper
values are used to normalize the input before applying the colormap. If this bound is omitted the lowest value in the input data is used. upper=None
 An upper bound for the floats in the input. The
lower
andupper
values are used to normalize the input before applying the colormap. If this bound is omitted the highest value in the input data is used. alpha=True
 Set to
False
to omit an alpha channel from the output. rgb=None
 Set to
True
to return bytes in the order0xARGB
, toFalse
to return the order0xBGRA
or toNone
to let the system’s endianness determine the correct order. In the last case, bigendian systems will return0xARGB
while littleendian systems use the order0xBGRA
.
A 1dimensional array of
n
floating point numbers will be converted to a 1dimensional array of4n
uints
, or3n
if the alpha channel is disabled. The array will be ordered sequentially: the first four (or three) bytes describe the first float, the next four (or three) describe the second float and so on.
static
exists
(name)¶ Returns True if the given name corresponds to a colormap.

static
get
(name)¶ Returns the colormap method indicated by the given name.

static
hsv_to_rgb
(h, s, v)¶ Converts hsv values in the range [0,1] to rgb values in the range [0,255]. Adapted from Matplotlib.

static
image
(name, x, y)¶ Returns image data (such as returned by
DataBlock2d.images()
) representing the colormap specified byname
. The image dimensions can be set usingx
andy
.

static
names
()¶ Returns an iterator over the names of all available colormaps.

static
normalize
(floats, lower=None, upper=None)¶ Normalizes the given float data based on the specified lower and upper bounds. If no bounds are set, the scaling is deduced from the data.