F9 Columnar
A PyTorch-based library for processing event data in high energy physics for ML applications.
Project description
F9Columnar is a Python library designed to streamline the processing of physics datasets (ROOT, HDF5, parquet) for machine learning. It is built on top of PyTorch, Uproot and Awkward Arrays. It provides a modular framework for efficient data loading, transformation, and analysis in high-energy physics research.
The library bridges the gap between traditional high-energy physics data formats and modern machine learning workflows. It enables physicists and data scientists to:
- Process large datasets in many formats using PyTorch DataLoaders
- Apply event selections, calculate variables, and create histograms
- Convert data to piles, HDF5 files with events prepared for fast random-access reads during ML training
The library is designed to be modular and extensible, allowing users to easily add new processors and functionality as needed. A common workflow is illustrated in the diagram below:
Check out the PyHEP 2025 talk for a good overview of what the library can do.
Setup
The library comes without any PyTorch dependencies by default to allow flexible installations. You can install it with or without PyTorch GPU support depending on your needs.
Install with PyTorch for GPU
pip install f9columnar
pip install torch
Install with PyTorch for CPU
pip install f9columnar
pip install torch --index-url https://download.pytorch.org/whl/cpu
Install for development
git clone https://gitlab.cern.ch/ijs-f9-ljubljana/F9Columnar.git
cd F9Columnar
uv sync
Run the tests with uv run pytest.
Getting started
The examples folder walks through the library step by step. The examples are self-contained, you do not need real data. Example 1 generates dummy ROOT files that the other examples use. The last example is the exception, it shows the grid workflow and needs a grid environment to run.
- Making dummy ROOT inputs
- Basic data loading and histogramming with awkward arrays
- Data loading and processing with a processor graph
- Converting ROOT files into HDF5 piles used for ML training
- One ML training loader from two sources
- A Lightning training loop over partitioned ROOT files and over HDF5 piles
- Inference on the trained model with the inference server
- Feature scaling with fitted scalers as torch modules
- Rucio ntuples and batch processing on the Vega HPC with aCT
Projects using F9Columnar
- SeeSawML: multi-dataset, multi-modal and multi-task ML training framework.
Citation
If you found F9Columnar useful, please consider citing its Zenodo record 10.5281/zenodo.19312298.
You can find an example bibtex entry below.
@software{F9Columnar,
author = {Gavranovic, Jan},
title = {F9Columnar: A PyTorch-Based Library for High Energy Physics Data Processing and Analysis},
year = {2026},
publisher = {Zenodo},
doi = {10.5281/zenodo.19312298},
url = {https://doi.org/10.5281/zenodo.19312298},
}
1 maintainer
Metadata
1 maintainer
Release files for f9columnar 0.8.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| f9columnar-0.8.2.tar.gz | 235.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| f9columnar-0.8.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 499.5 kB
Release files / f9columnar-0.8.2.tar.gz
| Download URL | f9columnar-0.8.2.tar.gz |
|---|---|
| Size | 235.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1440244b915bbb84f087e90fe47f450e3901f7d63582fc474c9441de57a53a9d
|
|
BLAKE2b-256 checksum How to use checksums |
2d1447cdf392766b141e5353d82ea02754e591d46398e6bf779ac0c0eec3ecf0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.9 {"installer":{"name":"uv","version":"0.12.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / f9columnar-0.8.2-py3-none-any.whl
| Download URL | f9columnar-0.8.2-py3-none-any.whl |
|---|---|
| Size | 264.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c306d1b0b90c75e784d825b1efc55a8404684d0bec1f716431b18c6fc1e20f01
|
|
BLAKE2b-256 checksum How to use checksums |
c0f857cad2ca97dc08a02b6874295f184a3947229959c7456ef3b96eca75c489
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.9 {"installer":{"name":"uv","version":"0.12.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
