Axon Instruments Formats¶

Support is provided for reading data and protocols from Axon Binary Files (ABF versions 1 and 2) and for reading and writing data in the Axon Text File (ATF) format.

Time series and meta data can be read using the classes AbfFile and AtfFile. Stored protocol data can also be retrieved from ABF files. A DataLog can be stored in ATF format using save_atf().

The AbfFile class implements Myokit’s shared myokit.formats.SweepSource interface.

class myokit.formats.axon.AbfFile(filepath, is_protocol_file=None)¶

Represents a read-only Axon Binary Format file (.abf), stored at the location pointed to by filepath.

Files in the “ABF” format and the newer “ABF2” format can be read. If the given filepath ends in .pro a protocol file is assumed. This assumption can be overruled by setting the is_protocol_file argument to either True or False.

Data in ABF files is recorded in sweeps, where each sweep contains one or more channels with recorded (A/D) data. In addition, zero or more output waveforms may be defined (also called “protocol” or D/A channels). Where possible, the :class`AbfFile` class will convert these embedded protocols to time series and include them as additional channels.

For example:

abf = AbfFile('some_file.abf')
for sweep in abf:
    for channel in sweep:
        print(channel.name())
    break

might show

IN 0 10xVm Cmd 0

where the first two channels are recorded A/D channels and the final one is a reconstructed D/A output channel.

Sweeps and channels are represented by Sweep and Channel objects respectively, and these can be used to obtain the data from a file:

abf = AbfFile('some_file.abf')
for sweep in abf:
    for channel in sweep:
        plot(channel.times(), channel.values())

In addition the AbfFile class implements the :class`myokit.formats.SweepSource` interface. Note that this interface treats A/D and D/A as separate things, so channel_count() returns the number of A/D channels, not the total number of channels in a Sweep object (which can include D/A channels).

Support notes:

Protocol (D/A) conversion is only supported for “episodic stimulation” with constant valued steps (so e.g. no ramps) and without “user lists”.
Protocols with more than one sampling rate are not supported.
The publicly available information on the ABF format is not great, so there will be several other issues and shortcomings.

When an AbfFile is created, the file at filepath is read in its entirety and the file handle is closed. No try-catch or with statements are required.

Arguments:

filepath: The path to load the data from. Data will be read into memory immediately upon construction.
is_protocol_file: If set to True, no attempt to read A/D data will be made and only D/A “protocol” information will be read. If left at its default value of None files with the extension .pro will be recognized as protocol files.

channel(channel_id, join_sweeps=False)¶

Returns the data for a single channel, identified by integer or string channel_id.

With join_sweeps=False, the data is returned as a tuple (times, sweeps) where times and sweeps are 2d numpy arrays indexed so that times[i][j] is the j-th time point for sweep i.

If join_sweeps=True the sweeps are joined together, and a tuple (times, values) is returned times and values are 1d arrays.

channel_count()¶: Returns the number of channels.

channel_names(index=None)¶: Returns the names of all channels or the name of a specific channel index.

channel_units(index=None)¶: Returns the units (as myokit.Unit) of all channels or the units of a specific channel index.

da(output_id, join_sweeps=False)¶: Like channel(), but returns reconstructed D/A signals.

da_count()¶

Returns the available number of reconstructed D/A output channels.

This should return 0 if D/A channels are not supported.

da_names(index=None)¶

Returns the names of all reconstructed D/A output channels or the name of a specific output channel index.

This will raise a NotImplementedError if D/A channels are not supported.

da_protocol(output_id=None, tu='ms', vu='mV', cu='pA', n_digits=9, include_initial_holding=False)¶

See myokit.formats.SweepSource.da_protocol().

This implementation adds a keyword argument include_initial_holding that lets you switch between the declared protocol (False) and the protocol as actually implemented (True). In the latter case, a short holding time is added before the first epoch in every sweep.

da_units(index=None)¶

Returns the units (as myokit.Unit) of all reconstructed D/A output channels or the units of a specific output channel index.

This will raise a NotImplementedError if D/A channels are not supported.

equal_length_sweeps()¶: Returns True only if each sweep in this source has the same length.

filename()¶: Returns this ABF file’s filename.

log(join_sweeps=False, use_names=False, include_da=True)¶

Returns a myokit.DataLog containing the data from all channels.

The log will have a single entry time corresponding to the time of the first sweep if join_sweeps is False, or the time of all points when join_sweeps is True.

Names will have a systematic form i_sweep.i_channel.label, for example 0.1.channel for sweep 0 of recorded channel 1, or 3.0.da for sweep 3 of reconstructed D/A output 0. These can also be accessed using the syntax log['channel', 1, 0] and log['da', 0, 3].

To obtain a log with the user-specified names from the source instead, set use_names to True. This will result in names such as 0.IN 1 or 3.Cmd 0.

To exclude D/A signal reconstructions, set include_da to False.

A call with join_sweeps=False on a source where equal_length_sweeps() returns False will raise a ValueError.

matplotlib_figure()¶: Creates and returns a matplotlib figure with this file’s data.

meta_str(show_header=False)¶

Returns a multi-line string with meta data about this file.

The optional argument show_header can be used to add the full header contents to the output.

path()¶: Returns the path to the underlying ABF file.

sweep_count()¶

Returns the number of sweeps.

Note that a source with zero recorded channels may still report a non-zero number of sweeps if it can provide D/A outputs.

Similarly, formats like WCP can report zero sweeps but have a non-zero channel count (if no data was recorded).

time_unit()¶: Returns the time unit used in this source.

version()¶: Returns a string representation of this file’s version number.

class myokit.formats.axon.Sweep¶

Represents a single sweep (also called an episode).

Each sweep contains a fixed number of channels.

class myokit.formats.axon.Channel(parent_file)¶

Represents a signal for a single channel.

To obtain its data, use times() and values().

index()¶: Returns the index set for this channel.

name()¶: Returns the name set for this channel.

times()¶: Returns a copy of the values on the time axis.

unit()¶: Returns the units this channel is in.

values()¶: Returns a copy of the values on the data axis.

class myokit.formats.axon.AtfFile(filename)¶

Represents an Axon Text File (ATF) stored on disk.

This method provides access to the data stored in the ATF as well as any meta data stored in the header.

Access to the data is provided using a dict-like interface: to iterate over the file’s keys use iterkeys(), to select a value use atf_file['key']. All iterators return the keys stored in the order they were listed in the ATF file.

filename()¶: Returns this ATF’s filename.

info()¶: Returns this ATF’s header/meta data.

items()¶: Returns an iterator over all (key, value) pairs.

keys()¶: Returns an iterator over all keys in this ATF.

log()¶: Returns this file’s time series data as a myokit.DataLog.

meta_str(verbose=True)¶

Returns this ATF’s header data as an unstructured multi-line string.

Note that the verbose argument doesn’t do anything, but provides compatibility with similar methods in other files.

myokit_log()¶: Deprecated alias of log().

path()¶: Returns the path to this ATF file.

values()¶: Returns an iterator over all values in this ATF.

version()¶: Returns a string representation of this file’s version number.

myokit.formats.axon.load_atf(filename)¶: Reads an ATF file and returns its data as a myokit.DataLog.

myokit.formats.axon.save_atf(log, filename, fields=None)¶

Saves the myokit.DataLog log to filename in ATF format.

ATF requires that the times in the log be regularly spaced.

The first column in an ATF file should always be time. Remaining fields will be written in a random order. To indicate an order or make a selection of fields, pass in a sequence fields containing the field names.

Protocols can be read from ABF files using the standard interface:

myokit.formats.axon.importers()¶: Returns a dict of all importers available in this module.

class myokit.formats.axon.AbfImporter¶

This Importer can import protocols from files in Axon Binary Format.

protocol(filename, channel=0)¶

Attempts to load the protocol from the file at filename.

If specified, the channel index channel will be used to select which channel in the AbfFile to convert to a protocol

supports_protocol()¶: Returns a bool indicating if protocol import is supported.

Licensing (ABF)¶

The standard myokit license applies to this file. However, it should be noted that the AbfFile class is in part derived from code found in the Neo package for representing electrophysiology data, specifically from a python module authored by sgarcia and jnowacki. Neo can be found at: http://neuralensemble.org/trac/neo

The Neo package is licensed using the following BSD License:

Copyright (c) 2010-2012, Neo authors and contributors
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice,
  this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice,
  this list of conditions and the following disclaimer in the documentation
  and/or other materials provided with the distribution.
Neither the names of the copyright holders nor the names of the
contributors may be used to endorse or promote products derived from this
software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

The code used in Neo is itself derived from the publicly contributed matlab script abf2load, again licensed under BSD. The original notice follows:

Copyright (c) 2009, Forrest Collman
Copyright (c) 2004, Harald Hentschke
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice,
  this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice,
  this list of conditions and the following disclaimer in the documentation
  and/or other materials provided with the distribution

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

The abf2load script is available from: http://www.mathworks.com/matlabcentral/fileexchange/22114-abf2load

Information (but no direct code) from the matlab script get_abf_header.m was also used: http://neurodata.hg.sourceforge.net/hgweb/neurodata/neurodata/

Myokit :: API and User Guide

Search

Axon Instruments Formats¶

Licensing (ABF)¶