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().

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.

The “data” in an AbfFile is recorded (analog-to-digital) data. Any output signals from the amplifier to the cell (digital-to-analog) are termed the “protocol”.

Data in AbfFiles is recorded in episodes called “sweeps”. Each sweep contains the data from all recorded channels. The number of channels is constant: channel 1 in sweep 1 contains data recorded from the same source as channel 1 in sweep 10.

The data in an AbfFile can be read by iterating over it:

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

Similarly, protocol data can be accessed using:

for sweep in f.protocol():
    for channel in sweep:
        plt.plot(channel.times(), channel.values())

Note that the number of output (“protocol”) channels need not equal the number of input (“data”) channels.

Because each channel can have a different sampling rate, AbfFile data is not one-on-one compatible with myokit Simulation logs. To obtain a myokit.DataLog version of the file’s data, use:meth:myokit_log.

In some cases, a myokit protocol can be created from a stored stimulus protocol. To do this, use the method:meth:myokit_protocol.

data_channels()

Returns the number of channels in this file’s sweeps.

extract_channel(channel=0, join=False)

Extracts a selected data channel and returns its data in a tuple containing:

A numpy array representing time
A numpy array representing the first sweep
A numpy array representing the second sweep
...

An optional argument join=True can be set to join all sweeps together and return just two arrays, one for time and one for data.

If no data is available, None is returned.

extract_channel_as_myokit_log(channel=0)

Extracts the given data channel and returns it as a myokit DataLog.

The log will contain an entry “time” that contains the time vector. Each sweep will be in an entry “0.sweep”, “1.sweep”, “2.sweep” etc.

filename()

Returns this AbfFile’s filename.

info(show_header=False)

Returns a string with lots of info on this file.

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

matplotlib_figure()

Creates and returns a matplotlib figure of this abf file’s contents.

myokit_log()

Converts the data in this ABF file to a:class:myokit.DataLog with an entry for every channel. All sweeps will be joined together into a single time series.

The log will contain an entry “time” that contains the time vector. Channels will be stored using “0.ad”, “1.ad” etc. for the recorded (analog-to-digital) channels and “0.da”, “1.da” etc. for the output (digital-to-analog) channels.

myokit_protocol(channel=None, ms=True)

Returns a single channel from an embedded protocol as a myokit.Protocol. The channel to return is specified by setting channel to the correct index.

Only works for episodic stimulation, without user lists.

By default, all times are converted to milliseconds. To disable this function, set ms=False.

protocol()

Returns an interator over the protocol data.

protocol_channels()

Returns the number of channels in this file’s protocol.

protocol_holding_level(channel=0)

Returns the holding level used by the requested output channel of the embedded protocol.

protocol_steps(channel=0)

For a stepped protocol, this function returns a tuple of lists of the successive values (not including the holding value).

For example, for a protocol that has holding value -120mV and performs steps to -100mV, -80mV, and -40mV the returned output will be:

([-100, -80, -40])

For a more complicated protocol, where each step is followed by a step down to -140mV, the output would be:

([-100, -80, -40], [-140, -140, -140])
class myokit.formats.axon.Sweep(n)

Represents a single sweep (also called an ‘episode’)

A sweep is represented as a fixed-size list of channels.

class myokit.formats.axon.Channel(parent_file)

Represents an analog signal for a single channel.

To obtain this channel’s formatted data, use times() and trace()

name()

Returns the name set for this channel.

number()

Returns the channel index used by pClamp. Note that this does not necessarily equal its index in the python sweep data!

times()

Returns a copy of the values on the time axis.

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 the header/meta data found in this file.

items()

Iterates over all key-value pairs in this ATF file’s data.

keys()

Iterates over all keys in this ATF file’s data.

myokit_log()

Returns this file’s time series data as a myokit.DataLog.

values()

Iterates over all values in this ATF file’s data.

version()

Returns the file type version of this ATF file (as a string).

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=None)

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/