PyIconeus

PyIconeus is Iconeus' open-source Python library for reading Iconeus data formats. It exposes the Scan, Bps, Roi and Raw models through a single file-opening entry point.

Supported formats:

• .scan (legacy HDF5 and binary scan files)
• .bps (HDF5 and binary Brain-to-Lab transforms)
• .bri (HDF5 and binary ROI meshes)
• .raw with its associated .hraw header (IQ data)

Table of Contents

• Installation
• Usage
• Contributing
• Citation
• License

Installation

1. Set up a virtual environment

The use of a python virtual environment is recommended to avoid conflicts with other Python packages.

You can create a virtual environment using uv:

uv venv
.venv/Scripts/activate       # Windows
source .venv/bin/activate    # Linux/macOS

2. Install PyIconeus

With Uv:

uv pip install pyiconeus

With pip:

python -m pip install pyiconeus

Or with the sources:

uv pip install -e .

3. Install other dependencies

Dependencies to run the tests:

uv pip install -e ".[test]"

To run the examples:

uv pip install -e ".[example]"

To build the doc:

uv pip install -e ".[doc]"

Documentation

You can build the documentation using Sphinx from the docs folder.

make html

Testing

Run the test suite with coverage locally:

coverage run -m pytest tests
coverage combine
coverage report --fail-under=90

Alternatively, you can use this command if you have hatch installed:

hatch test -c

The build requires at least 90% total coverage.

Usage

from pyiconeus import open_path

scan = open_path("acquisition.scan")
bps = open_path("positioning.bps")
scan.bps = bps

# RAW data requires both files. blockStart and blockEnd are one-based and
# inclusive; their defaults load the first block only.
raw = open_path("acquisition.raw", "acquisition.hraw", blockStart=1, blockEnd=1)

See the examples notebooks for more complete examples.

open_path determines the model from the lowercase filename extension. It raises FileNotFoundError for missing paths, ValueError for unsupported extensions or invalid RAW arguments, and may raise OSError when a file is not readable or has invalid content.

Contributing

Development setup, validation commands, branch policy, and pull request guidance are available in CONTRIBUTING.md.

Requirements

Python 3.10 or newer is supported. Runtime dependencies are NumPy, pytz, h5py and transforms3d.

To install all optional dependencies, run the following:

uv pip install -e ".[test,doc,example,dev]"

Citation

If you use PyIconeus in your research, please cite it. Citation metadata is available in CITATION.cff, and GitHub's "Cite this repository" button generates the entry for you in several formats.

@software{iconeus_pyiconeus,
  author  = {{Iconeus}},
  title   = {PyIconeus},
  url     = {https://github.com/Iconeus/PyIconeus},
  license = {BSD-3-Clause}
}

License

pyiconeus is distributed under the terms of the BSD-3-Clause license.