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
time-series for the membrane potential of cell (x,y)
is stored in one list
and the time-series 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 time-series 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
tow-1
in the x-direction, and0
toh-1
in the y-direction.
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 time-series of 1d rectangular data arrays.
Each
DataBlock1d
has a fixed widthw
, and a 0d time series vector containing a sequence ofn
times.One-dimensional 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)
.Zero-dimensional time series can be added, provided they have length
n
.A “one-dimensional time-series” 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 “zero-dimensional time-series” 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 1e-3.
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
from_DataLog
(log)¶ Deprecated alias of
from_log()
.
-
static
from_log
(log)¶ Creates a DataBlock1d from a
myokit.DataLog
.
-
get0d
(name)¶ Returns the 0d time-series identified by
name
. The data is returned directly, no copy is made.
-
get1d
(name)¶ Returns the 1d time-series 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 data-values 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 y-coordinates 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 space-coordinates 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 data-values 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.
-
remove0d
(name)¶ Removes the 0d time-series identified by
name
.
-
remove1d
(name)¶ Removes the 1d time-series identified by
name
.
-
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 little-endian:- The
nt
time values - All 0d entries
- All 1d entries, reshaped using numpy order=’C’
-
set0d
(name, data, copy=True)¶ Adds or updates a zero-dimensional 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 one-dimensional 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.
-
to_log
(copy=True)¶ Returns a
myokit.DataLog
containing the same information as this block.The data will be copied, unless
copy
is set toFalse
.
-
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 time-series of 2d rectangular data arrays.
Each
DataBlock2d
has a fixed widthw
and heighth
, and a 0d time series vector containing a sequence ofn
times.Two-dimensional 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)
.Zero-dimensional time series can be added, provided they have length
n
.A “two-dimensional time-series” 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 “zero-dimensional time-series” 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, multiplier=1)¶ Converts the 2d series indicated by
name
into a list ofW*H*RGB
arrays, with each entry represented as an 8 bit unsigned integer.Arguments:
name
- The 2d variable to create arrays for.
colormap
- The colormap to use when converting to RGB.
lower
- An optional lower bound on the data (anything below this will become the lowest index in the colormap).
upper
- An optional upper bound on the data (anything above this will become the highest index in the colormap).
multiplier
- An optional integer greater than zero. If given, every point in the
data set will be represented as a square of
multiplier
bymultiplier
pixels.
-
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
from_DataLog
(log)¶ Deprecated alias of
from_log()
.
-
static
from_log
(log)¶ Creates a DataBlock2d from a
myokit.DataLog
.
-
get0d
(name)¶ Returns the 0d time-series identified by
name
. The data is returned directly, no copy is made.
-
get2d
(name)¶ Returns the 2d time-series 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 row-strided 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.
-
remove0d
(name)¶ Removes the 0d time-series identified by
name
.
-
remove2d
(name)¶ Removes the 2d time-series identified by
name
.
-
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 little-endian:- 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 zero-dimensional 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 two-dimensional 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.
-
to_log
(copy=True)¶ Returns a
myokit.DataLog
containing the same information as this block.The data will be copied, unless
copy
is set toFalse
.
-
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 1-dimensional 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, big-endian systems will return0xARGB
while little-endian systems use the order0xBGRA
.
A 1-dimensional array of
n
floating point numbers will be converted to a 1-dimensional 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].
-
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, upper)¶ Normalizes the given float data based on the specified lower and upper bounds.