pyHEKA

pyHEKA (python Handling and Extraction Kit for .dat file Analysis) is a lightweight, efficient, and easy-to-use Python library for parsing and reading bundled .dat files created by HEKA Patchmaster or Patchmaster Next software. It supports several HEKA file versions including v9, v1000, and v2000 formats.

The library allows neuroscience researchers and electrophysiologists to load complex electrophysiology data tree structures directly into Python, access metadata, and read raw traces as NumPy arrays.

---

Features

• Multi-version Support: Automatically detects and reads v9, v1000, and v2000 Patchmaster file versions.
• Efficient Memory Footprint: Built on highly optimized data structures (e.g., using StructArray with indexed slicing for $O(N)$ parsing, and direct attribute lookup instead of bulky internal dictionary storage).
• Comprehensive Metadata Access: Easily extract stimulation protocols, group/series/sweep labels, recording modes, and amplifier configurations.
• Hierarchical Access: Reflects HEKA's internal structure: Group → Series → Sweep → Trace.
• NumPy Integration: Directly access electrophysiology traces as standard NumPy arrays.

---

Installation

From PyPI

The pyheka package is available on PyPI.

pip install pyheka

From Source

Ensure you have Python 3.9+ and numpy installed. You can install pyHeka from source using pip:

git clone https://github.com/delvendahl/pyheka.git
cd pyheka
pip install .

For development work, you can install it in editable mode:

pip install -e .

---

Example Usage

Here is a quick overview of how to use pyHeka to load and inspect your .dat files. We recommend using a context manager when reading files:

1. Load a .dat Bundle

import pyheka

# Load your HEKA .dat file
with pyheka.Bundle("path/to/your/file.dat") as bundle:
    # Print basic info about the bundle format and metadata
    print(bundle)

For legacy support, you can also load a .DAT bundle without a context manager:

from pyheka import Bundle

# Load your HEKA .dat file
bundle = Bundle("path/to/your/file.dat")

# Print basic info about the bundle format and metadata
print(bundle)

2. Print a Summary of the Bundle

You can quickly get a brief or a detailed summary of the file content, including groups, series, sweeps, and stimulus protocols:

# Print brief summary
bundle.summary()

# Print detailed summary with recording modes and sweep counts
bundle.summary(detailed=True)

3. Navigate the HEKA Tree Hierarchy

HEKA's pulsed tree maps to standard Python indices:

# Access the pulsed tree
pul = bundle.pul

# Iterate over groups and series
for group in pul.children:
    print(f"Group: {group.Label}")
    for series in group.children:
        print(f"  Series: {series.Label}, Sweeps: {len(series)}")

4. Fetch Raw Electrophysiological Data

You can load the actual raw trace data into NumPy arrays using the .data property:

group_idx = 0
series_idx = 0
sweep_idx = 0
trace_idx = 0

# Retrieve data for the specific trace as a NumPy array
trace_data = bundle.data[group_idx, series_idx, sweep_idx, trace_idx]

print("Shape of trace data array:", trace_data.shape)
print("Trace sample values:", trace_data[:10])

There are convenience methods to fetch entire series or sweeps, with options to concatenate or average sweeps. The following example shows how to fetch series #0 from group #0 without concatenating or averaging sweeps:

with pyheka.Bundle('path/to/your/file.dat') as bundle:
    series_data = bundle.get_series(group_index=0, series_index=0, concatenate_sweeps=False, average_sweeps=False)

plt.plot(series_data.x, series_data.y[0])  # Plotting the first sweep
plt.xlabel(f'Time ({series_data.x_unit})')
plt.ylabel(f'Data ({series_data.y_unit})')
plt.title(f'Series {series_data.series_idx} data from {series_data.filename}')
plt.show()

---

Development & Testing

To run the unit tests, run:

python3 -m unittest discover -s tests -p "test_*.py"

Acknowledgements

The code is based on work by Luke Campagnola (https://github.com/campagnola/heka_reader). Additional contributions and improvements have been made to enhance performance, usability, and compatibility with different .dat file versions.

Note: "Heka" in the package name refers to HEKA Elektronik (now part of Harvard Bioscience), the manufacturer of the Patchmaster software and amplifiers this package supports. The backronym above is just a fun reinterpretation for the README — not an official expansion.

License

This project is licensed under the GNU AGPL License. See the LICENSE file for details.