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 byfilepath
.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 theis_protocol_file
argument to eitherTrue
orFalse
.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 settingchannel
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 useatf_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
tofilename
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/