读取 BIOPAC AcqKnowledge 文件的实用程序
项目描述
用于读取 BIOPAC 文件的库
这些实用程序用于读取由 BIOPAC 的 AcqKnowledge 软件生成的文件。大部分信息基于BIOPAC 的应用说明 156；然而，通过 John Ollinger 和 Nate Vack 的不懈努力，较新的文件格式得以解码。
这个库主要关注的是获取数据，而不是解释与 UI 相关的标头值。
地位
据我所知，这应该读取您扔给它的任何 AcqKnowledge 文件。Windows、Mac、未压缩的、压缩的、旧的、新的……它应该愉快地阅读它们。如果您在处理文件时遇到问题，我很想得到一份副本并让 bioread 使用它。
安装
我们在pypi中，所以安装应该很简单：
pip install bioread
bioread 的一些可选部分依赖于外部库。acq2hdf5依赖于h5py并且acq2mat依赖于scipy，但由于它们都不是 bioread 的核心部分（并且在某些系统上工作可能很麻烦），因此默认情况下不会安装它们。要获得它们，请执行以下操作：
# Just h5py
pip install bioread[hdf5]
# Just scipy
pip install bioread[mat]
# The whole shebang
pip install bioread[all]
从 2020 年 5 月（第 2 版）开始，我们现在需要 Python 3.6 或更高版本。1.0.4 及以下版本应适用于 Python 2.7 及更高版本。
API 用法：
命令行用法：
acq2hdf5
如果您想从 AcqKnowledge 转换文件，这可能就是您想要使用的——Matlab 可以开箱即用地读取这些文件，并且有 R 等库。这将转换文件，将通道存储为数据集，其名称为 like/channels/channel_0和属性中的元数据。事件标记存储在/event_markers/marker_X
Convert an AcqKnowledge file to an HDF5 file.
Usage:
acq2hdf5 [options] <acq_file> <hdf5_file>
acq2hdf5 -h | --help
acq2hdf5 --version
Options:
--values-as=<type> Save raw measurement values, stored as integers in the
base file, as either 'raw' or 'scaled'. If stored as
raw, you can convert to scaled using the scale and
offset attributes on the channel. If storing scaled
values, scale and offset will be 1 and 0.
[default: scaled]
--compress=<method> How to compress data. Options are gzip, lzf, none.
[default: gzip]
--data-only Only save data and required headers -- do not save
journal or marker information.
-v, --verbose Print extra messages for debugging.
注意这不需要将整个数据集读入内存，所以如果你有一个 2G 的数据集，这会很好用。
要获取您在 AcqKnowledge 中看到的值，请将--values-as选项保留为默认值（“缩放”）。为了获得更快的性能、更少的内存使用和更小的文件，您可以使用“原始”并稍后（如果您关心）使用比例和偏移属性转换通道。
一般来说，gzip 压缩似乎工作得很好，但如果你正在制作非常大的东西，你可能想要使用 lzf（更糟糕的压缩，更快）。
您将在文件中找到：
根级属性：
file_revision内部 AckKnowledge 文件版本号samples_per_second文件的基本采样率byte_order原始文件的字节顺序journal文件的日志数据。
频道级属性：
scale原始数据的比例因子（对于浮点型数据，将为 1）offset原始数据的偏移量（对于浮点型数据，将为 0）frequency_divider此通道的采样率分频器samples_per_second通道的采样率name频道名称units通道的单位channel_number通道的显示编号（用于标记）
标记
label频道的文本标签type此标记类型的描述type_code一个简短的 4 个字符的类型代码global_sample_index此标记的索引，以主采样率为单位channel指向指定频道的硬链接（仅适用于非全局事件）channel_number通道的显示编号（仅适用于非全局事件）channel_sample_index该标记所属的通道数据中的 （仅适用于非全局事件）
acq2mat
注意：我建议acq2hdf5导出到 Matlab。这个程序仍然存在，因为嘿：它有效。
该程序从 AcqKnowledge 文件创建一个 Matlab（版本 5）文件。在后端，它使用scipy.io.savemat。通道存储在一个名为“通道”的元胞数组中。
Convert an AcqKnowledge file to a MATLAB file.
Usage:
acq2mat [options] <acq_file> <mat_file>
acq2mat -h | --help
acq2mat --version
Options:
-c, --compress Save compressed Matlab file
--data-only Only save data and required header information -- do not
save event markers.
Note: scipy is required for this program.
如果您已将文件另存为myfile.mat，则可以在 Matlab 中：
>> data = load('myfile.mat')
data =
channels: {1x2 cell}
markers: {1x3 cell}
headers: [1x1 struct]
samples_per_second: 1000
>> data.channels{1}
ans =
units: 'Percent'
frequency_divider: 1
samples_per_second: 1000
data: [1x10002 double]
name: 'CO2'
>> plot(data.channels{1}.data)
(Plots the data)
>> data.markers{1}
ans =
style: 'apnd'
sample_index: 0
label: 'Segment 1'
channel: Global
acq2txt
acq2txt 将获取 AcqKnowledge 文件中的数据并将其写入制表符分隔的文本文件。默认情况下，将写入所有通道（加上时间索引）。
Write the data from an AcqKnowledge file channel to a text file.
Usage:
acq2txt [options] <acq_file>
acq2txt -h | --help
acq2txt --version
Options:
--version Show program's version number and exit.
-h, --help Show this help message and exit.
--channel-indexes=<indexes> The indexes of the channels to extract.
Separate numbers with commas. Default is to
extract all channels.
-o, --outfile=<file> Write to a file instead of standard out.
--missing-as=<val> What value to write where a channel is not
sampled. [default: ]
The first column will always be time in seconds. Channel raw values are
converted with scale and offset into native units.
acq_info
acq_info 打印出一些关于 AcqKnowledge 文件的简单调试信息。即使是损坏的文件，它也会尽最大努力打印出来。
Print some information about an AcqKnowledge file.
Usage:
acq_info [options] <acq_file>
acq_info -h | --help
acq_info --version
Options:
-d, --debug print lots of debugging data
Note: Using - for <acq_file> reads from stdin.
如使用说明中所述，acq_info 将从标准输入读取，因此如果您的文件被 gzip 压缩，您可以说：
zcat myfile.acq.gz | acq_info -
acq_markers
将 AcqKnowlege 文件中的所有标记打印为制表符分隔的格式，打印到标准输出或指定文件。字段是：
filename time (s) label channel style
Print the event markers from an AcqKnowledge file.
Usage:
acq_markers [options] <file>...
acq_markers -h | --help
acq_markers --version
Options:
-o <file> Write to a file instead of standard output.
请注意，这不是从标准输入读取的；在这种情况下，从大量文件中打印标记比从其他文件中获取更重要zcat。
笔记
我已经测试了我能想到和找到的所有不同年份的文件，除了非常旧的（AcqKnowledge 2.x）文件。
另外，我阅读的频道顺序不是AcqKnowledge界面中显示的。数据的顺序和我能找到的任何通道标头值似乎都不能完全控制它。我只是假设这不是什么大不了的事。
文件格式文档
虽然无法替代代码潜水来了解事情的真正运作方式，但我已经编写了一些文件格式的快速文档。
此外，开发人员 Mike Davison 出色地找出了额外的 .acq 文件格式信息（远远超过 bioread 中实现的信息！）；他的贡献在 notes/acqknowledge_file_structure.pdf
学分
这段代码几乎都是由 Nate Vack njvack@wisc.edu编写的，并由 John Ollinger 完成了大量的初步研究。
版权和免责声明
bioread 在 MIT 许可下分发。有关更多详细信息，请参阅许可证。
BIOPAC 和 AcqKnowledge 是 BIOPAC Systems, Inc. 的商标。该软件的作者与 BIOPAC Systems, Inc 没有任何关系，该公司既不支持也不认可该软件包。
