Metadata-Version: 2.4
Name: pyheka
Version: 1.0.1
Summary: Heka Dat File Reader
Author-email: Igor Delvendahl <igor.delvendahl@physiologie.uni-freiburg.de>
Project-URL: Homepage, https://github.com/delvendahl/pyHEKA
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Dynamic: license-file

# pyHEKA

[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org)
[![License: GNU AGPL](https://img.shields.io/badge/License-GNU-yellow.svg)](LICENSE)

`pyHEKA` (**py**thon **H**andling and **E**xtraction **K**it for .dat file **A**nalysis) 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 &rarr; Series &rarr; Sweep &rarr; Trace.
- **NumPy Integration:** Directly access electrophysiology traces as standard NumPy arrays.

---

## Installation

### From PyPI

The pyheka package is available on [PyPI](https://pypi.org/project/pyheka/).

```bash
pip install pyheka
```

### From Source

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

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

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

```bash
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

```python
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:

```python
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:

```python
# 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:

```python
# 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:

> [!NOTE]
>Note that data is loaded using Python indices, which are zero-based, while HEKA uses one-based indices.


```python
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:

```python
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:

```bash
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](LICENSE) file for details.
