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 to w-1 in the x-direction, and 0 to h-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 width w, and a 0d time series vector containing a sequence of n times.

One-dimensional time series can be added to the block, provided the data also contains n instances of w 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 to t[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 to t[1], etc.

Constructor info:

w: Each 1d block should have dimension w by 1.
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 as pcolor and pcolormesh.

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 that x represents time and y represents space. To reverse this (and use the order used internally in the datablocks), set transpose=False.

The returned format is a tuple (x, y, z) where x, y and z are all 2d numpy arrays. Here, x (time) and y (space) describe the x and y-coordinates of rectangles, with a color (data value) given by z.

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 by z[i, j].

As a result, for a block of width w (e.g., w cells) containing n logged time points, the method returns arrays x and y of shape (w + 1, n + 1) and an array z of shape (w, n).

See image_grid() for a method where x, y and z 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) where x, y and z are all 2d numpy arrays. Here, x and y describe the time and space-coordinates of the logged points respectively, and z describes the corresponding data value. For a block of width w (e.g., w cells) containing n 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 the y coordinates become space. Use transpose=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 as progress. 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 entry
nx 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 line
1 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 string name.

The data must be specified as a sequence of length n, where n is the first value returned by DataBlock1d.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 string name.

The data must be specified as a numpy array with shape (n, w), where (n, w) is the value returned by DataBlock1d.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 to False.

trace(variable, x)¶: Returns a 0d time series of the value variable, corresponding to the cell at position x. 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 width w and height h, and a 0d time series vector containing a sequence of n times.

Two-dimensional time series can be added to the block, provided the data also contains n instances of w by h 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 to t[1], etc.

A “zero-dimensional time-series” is a series of single values where the first corresponds to a time t[0], the second to t[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 of W*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 by multiplier 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 of map2d.

Positions for the datablocks can be specified as pos1 and pos2, 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)), where w1 and w2 are the widths of block1 and block2 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 in block1, old_name_2 is the name of a 2d variable in block2 and padding_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) or new_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, where w1 is the width of block1.

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 format ARGB32.

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.

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 entry
ny the height of each 2d block
nx 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 line
2 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 frame frame will be stored in filename row by row. Each column is separated by delimx (by default a space) and rows are separated by delimy (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 string name.

The data must be specified as a sequence of length n, where n is the first value returned by DataBlock2d.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 string name.

The data must be specified as a numpy array with shape (n, w), where (n, w) is the value returned by DataBlock2d.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 to False.

trace(variable, x, y)¶: Returns a 0d time series of the value variable, corresponding to the cell at position x, 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 and upper 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 and upper 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 order 0xARGB, to False to return the order 0xBGRA or to None to let the system’s endianness determine the correct order. In the last case, big-endian systems will return 0xARGB while little-endian systems use the order 0xBGRA.

A 1-dimensional array of n floating point numbers will be converted to a 1-dimensional array of 4n uints, or 3n 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 by name. The image dimensions can be set using x and y.

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.

Myokit :: API and User Guide

Search

Data blocks¶