hepconvert

1.4.0 verified Fri May 01 auth: no python

High Energy Physics file conversion package (ROOT, Parquet, etc.). Current version 1.4.0, requires Python >=3.9. Active development, monthly releases.

pip install hepconvert

Common errors

error ModuleNotFoundError: No module named 'hepconvert' ↓

cause Package not installed or installed in wrong environment.

fix

Run: pip install hepconvert

error ValueError: The truth value of an array with more than one element is ambiguous ↓

cause Using hepconvert functions with Awkward arrays that require flattening due to jagged branches.

fix

Ensure input data is flat or use awkward.flatten() before passing to hepconvert.

error KeyError: 'branch_name' ↓

cause Specified branch does not exist in the ROOT file.

fix

Check branch names with: uproot.open('file.root').keys()

Warnings

gotcha convert_root_to_parquet by default converts all branches; this can be slow for large files. Always specify 'branches' to slim selection. ↓

fix Explicitly pass branches=[...] to select only what you need.

gotcha merge_root can silently lose 100 entries when using entry-number size selection (fixed in 1.3.8). If using 1.3.6 or earlier, upgrade. ↓

fix Upgrade to >=1.3.8 with: pip install --upgrade hepconvert

deprecated Python 3.8 support dropped in 1.4.0. The package now requires Python >=3.9. ↓

fix Use Python 3.9 or later.

gotcha CLI arguments for options like '--size' are case-sensitive and must match exactly. Mixing types (e.g., passing a string for an integer option) fails with unclear error in <1.4.0. ↓

fix Upgrade to >=1.4.0 or use Python API with correct types.

Install

conda install -c conda-forge hepconvert

Imports

convert_root_to_parquet

wrong

import hepconvert; hepconvert.convert_root_to_parquet()

correct

from hepconvert import convert_root_to_parquet

hepconvert exposes functions at top level; no submodule needed.

convert_parquet_to_root

from hepconvert import convert_parquet_to_root

merge_root
```
from hepconvert import merge_root
```
merge_parquet
```
from hepconvert import merge_parquet
```

Quickstart

Quickly convert a ROOT file to Parquet, selecting specific branches.

from hepconvert import convert_root_to_parquet
convert_root_to_parquet("input.root", "output.parquet", branches=["branch1", "branch2"])