h1. Libraries for reading BIOPAC files

These utilities are for reading the files produced by BIOPAC's AcqKnowledge software. Much of the information is based on  "Application Note 156":http://www.biopac.com/Manuals/app_pdf/app156.pdf from BIOPAC; however, newer file formats were decoded through the tireless efforts of John Ollinger and Nate Vack.

This library is mostly concerned with getting you the data, and less so with interpreting UI-related header values.

h2. Status

As far as I know, this should read any AcqKnowledge file you throw at it. Windows, Mac, compressed, not, old, new... it should happily read 'em all. If you have trouble with a file, I'd love to get a copy and make bioread work with it.

h2. Installation

We're up in "pypi":http://pypi.python.org/pypi, so installing should be as simple as:

<pre>
easy_install bioread
</pre>

Note that bioread requires the excellent "NumPy":http://numpy.scipy.org/ package, and writing Matlab files requires "SciPy":http://scipy.org/.

h2. Command-line usage:

h3. acq2mat 

This program creates a Matlab (version 5) file from an AcqKnowledge file. On the back-end, it uses "scipy.io.savemat":http://docs.scipy.org/doc/scipy/reference/generated/scipy.io.savemat.html. Channels are named "n1" through "nN"

<pre>
Usage: acq2mat [options] ACQ_FILE MAT_FILE

Options:
  -h, --help      show this help message and exit
  -c, --compress  Save compressed Matlab file
</pre>

h3. acq_info

acq_info prints out some simple debugging information about an AcqKnowledge file. It'll do its best to print something out even for damaged files.

<pre>
Usage: acq_info [options] ACQ_FILE

Options:
  -h, --help   show this help message and exit
  -d, --debug  Print lots of debugging data
</pre>

h2. API usage:

If you want to process the data as NumPy arrays instead, there's an easy API to work with it:

<pre>
>>> from bioread.readers import AcqReader
>>> data = AcqReader.read_file("myfile.acq")
>>> data.file_revision
84
>>> len(data.channels)
2
>>> data.channels[0].samples_per_second
1000.0
>>> len(data.channels[0].data)
10002
>>> data.channels[1].samples_per_second
500.0
>>> len(data.channels[1].data) 
5001
>>> len(data.channels[1].upsampled_data)
10002
>>> data.channels[0].data[0]
1.23
>>> data.channels[0].raw_data[0] # ints are not scaled
13
>>> data.channels[0].name
'CO2'
>>> data.named_channels['CO2'].data[0]
1.23
>>> from bioread.writers import MatlabWriter
>>> MatlabWriter.write_file(data, "myfile.mat") # Creates a matlab file.
</pre>

h2. Notes

The two areas I'm not certain about are very old (version 2.x) files, and old-ish (3.8.1) compressed files. I suspect the old compressed files were stored compressed and interleaved, but I don't have a way to generate one to test. Got one you're willing to send my way?

Also, the channel order I read is not the one displayed in the AcqKnowledge interface. Neither the order of the data nor any channel header value I can find seems to entirely control that. I'm gonna just assume it's not a very big deal.

h2. Copyright & Disclaimers

bioread is distributed under Version 2 of the GNU Public License. For more details, see LICENSE.

BIOPAC is a trademark of BIOPAC Systems, Inc. The authors of this software have no affiliation with BIOPAC Systems, Inc, and that company does not support or endorse this software package.