hepconvert

What it is and what it does

hepconvert is a Python library that simplifies conversion between columnar data formats used in high-energy physics. It currently bridges ROOT (the standard HEP data format) and Parquet, with HDF5 support planned. The library wraps the complexity of multi-step format conversions into single-line Python functions or command-line commands, handling both tree-based data (via merge_root) and histogram aggregation (via add_histograms). It includes built-in features for managing large datasets and controlling compression, making it useful for data pipeline automation and batch processing in physics workflows.

The package depends on uproot for ROOT file I/O, click for CLI scaffolding, and click-default-group for command organization. It targets Python 3.9+ and is actively maintained, though still in early planning stages (Development Status 1). With low install friction and no known vulnerabilities, it's straightforward to add to existing analysis environments.

Use it for:

• Merge multiple ROOT files containing TTrees into a single consolidated file for downstream analysis.
• Combine histograms across multiple ROOT files and write the aggregated results to a new ROOT file.
• Convert ROOT data to Parquet format for use in data science workflows outside the HEP ecosystem.
• Automate batch conversion of large physics datasets as part of a data processing pipeline.
• Simplify one-off file format conversions from the command line without writing custom Python scripts.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

hepconvert converts between columnar file formats—currently ROOT and Parquet, with HDF5 planned—replacing multi-step conversion workflows with single-line Python calls or CLI commands, with built-in support for large datasets and compression control.

Yes, if you work with ROOT files and need straightforward conversion or merging. Low install friction, active maintenance, permissive license, and no security issues make it a safe addition. The early development status (Planning) means the API or feature set may change, so pin the version if you rely on it in production. Best suited for exploratory analysis or pipeline automation rather than mission-critical workflows until it reaches a stable release milestone.

Install

hepconvert on PyPI

pip install hepconvert

uv add hepconvert

poetry add hepconvert

Installing hepconvert

Before you install

Low friction: pure Python wheel with three lightweight runtime dependencies (click, click-default-group, uproot). Active maintenance with recent releases; last commit 2026-07-20. Early-stage project (Development Status 1 - Planning) but functional and regularly updated.

License in practice

Permissive license (BSD) means you can use, modify, and distribute the package with minimal restrictions, typical for scientific software.

Quickstart

pip install hepconvert

import hepconvert

# Merge ROOT files with TTrees
hepconvert.merge_root("output.root", ["input1.root", "input2.root"])

# Or from CLI:
# hepconvert merge-root [options] output.root input1.root input2.root

Requires Python 3.9 or later; uproot (a runtime dependency) requires compiled C++ bindings for ROOT file I/O, which may need a working C++ build environment on some systems.

Verify before relying

• Whether HDF5 support is currently available or still planned—description says 'soon will include' but no timeline or release notes confirm implementation status.
• Performance characteristics and memory efficiency for datasets larger than typical RAM—documentation mentions 'managing large datasets' but specifics are not in the fact sheet.
• Compression algorithm options and their trade-offs beyond 'choosing compression levels'.

Package facts

Evidence: hepconvert-1.4.0-py3-none-any.whl

Tags

More Scientific/Engineering packages