vidyasagarv.com
Python bindings to oxyroot. Makes reading .root files blazing fast 🚀
Populate some documentation
+97
README.md
+97
README.md
···
1
+
# Python bindings for oxyroot
2
+
3
+
[](https://github.com/vvsagar/py-oxyroot/actions/workflows/CI.yml)
4
+
[](https://opensource.org/licenses/MIT)
5
+
6
+
> **Warning**
7
+
> This project is an early prototype and is not yet recommended for production use. For a mature and well-tested alternative, please consider using [uproot](https://github.com/scikit-hep/uproot5).
8
+
9
+
A fast, Rust-powered Python reader for CERN ROOT files.
10
+
11
+
This package provides a simple and Pythonic interface bindings to `oxyroot`, a rust package, to read data from `.root` files, inspired by libraries like `uproot`. It leverages the speed of Rust for high-performance data extraction and integrates with the scientific Python ecosystem by providing data as NumPy arrays.
12
+
13
+
## Features
14
+
15
+
- **High-Performance**: Core logic is written in Rust for maximum speed.
16
+
- **Parquet Conversion**: Convert TTrees directly to Apache Parquet files with a single command.
17
+
- **NumPy Integration**: Get branch data directly as NumPy arrays.
18
+
- **Simple, Pythonic API**: Easy to learn and use, and similar to `uproot`
19
+
20
+
## Quick Start
21
+
22
+
Here's how to open a ROOT file, access a TTree, and read a TBranch into a NumPy array.
23
+
24
+
```python
25
+
import oxyroot
26
+
import numpy as np
27
+
28
+
# Open the ROOT file
29
+
file = oxyroot.open("ntuples.root")
30
+
31
+
# Get a TTree
32
+
tree = file["mu_mc"]
33
+
34
+
# List branches in the tree
35
+
print(f"Branches: {tree.branches()}")
36
+
37
+
# Get a specific branch and its data as a NumPy array
38
+
branch = tree["mu_pt"]
39
+
data = branch.array()
40
+
41
+
print(f"Read branch '{branch.name}' into a {type(data)}")
42
+
print(f"Mean value: {np.nanmean(data):.2f}")
43
+
```
44
+
45
+
## Converting to Parquet
46
+
47
+
You can easily convert all (or a subset of) branches in a TTree to a Parquet file.
48
+
49
+
```python
50
+
# Convert the entire tree to a Parquet file
51
+
tree.to_parquet("output.parquet")
52
+
53
+
# Convert specific columns to a Parquet file with ZSTD compression
54
+
tree.to_parquet(
55
+
"output_subset.parquet",
56
+
columns=["mu_pt", "mu_eta"],
57
+
compression="zstd"
58
+
)
59
+
```
60
+
61
+
## Performance
62
+
63
+
`oxyroot` is designed to be fast. Here is a simple benchmark comparing the time taken to read all branches of a TTree with `uproot` and `oxyroot`.
64
+
65
+
```python
66
+
import oxyroot
67
+
import uproot
68
+
import time
69
+
70
+
file_name = "ntuples.root"
71
+
tree_name = 'mu_mc'
72
+
73
+
# Time uproot
74
+
start_time = time.time()
75
+
up_tree = uproot.open(file_name)[tree_name]
76
+
for branch in up_tree:
77
+
if branch.typename != "std::string":
78
+
branch.array(library="np")
79
+
end_time = time.time()
80
+
print(f"Uproot took: {end_time - start_time:.3f}s")
81
+
82
+
# Time oxyroot
83
+
start_time = time.time()
84
+
oxy_tree = oxyroot.open(file_name)[tree_name]
85
+
for branch in oxy_tree:
86
+
branch.array()
87
+
end_time = time.time()
88
+
print(f"Oxyroot took: {end_time - start_time:.3f}s")
89
+
```
90
+
91
+
## License
92
+
93
+
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
94
+
95
+
## Contributing
96
+
97
+
Contributions are welcome! Please feel free to submit a pull request or open an issue.
+41
-3
pyproject.toml
+41
-3
pyproject.toml
···
4
4
5
5
[project]
6
6
name = "oxyroot"
7
-
requires-python = ">=3.8"
7
+
requires-python = ">=3.8,<3.14"
8
+
authors = [
9
+
{name = "Vidya Sagar Vobbilisetti", email = "mail@vidyasagarv.com"},
10
+
]
11
+
description = "A .root file reader, backed by rust"
12
+
readme = "README.md"
13
+
license = "MIT"
8
14
classifiers = [
9
-
"Programming Language :: Rust",
10
-
"Programming Language :: Python :: Implementation :: CPython",
15
+
'Development Status :: 3 - Alpha',
16
+
'Intended Audience :: Science/Research',
17
+
'License :: OSI Approved :: MIT License',
18
+
'Programming Language :: Rust',
19
+
'Programming Language :: Python',
20
+
'Programming Language :: Python :: 3',
21
+
'Programming Language :: Python :: 3.8',
22
+
'Programming Language :: Python :: 3.9',
23
+
'Programming Language :: Python :: 3.10',
24
+
'Programming Language :: Python :: 3.11',
25
+
'Programming Language :: Python :: 3.12',
26
+
'Programming Language :: Python :: 3.13',
27
+
'Programming Language :: Python :: 3 :: Only',
28
+
'Programming Language :: Python :: Implementation :: CPython',
11
29
"Programming Language :: Python :: Implementation :: PyPy",
30
+
'Topic :: Software Development',
31
+
'Topic :: Scientific/Engineering',
32
+
'Typing :: Typed',
33
+
'Operating System :: Microsoft :: Windows',
34
+
'Operating System :: Unix',
35
+
'Operating System :: MacOS',
12
36
]
13
37
dynamic = ["version"]
38
+
39
+
[project.urls]
40
+
Homepage = "https://github.com/vvsagar/py-oxyroot"
41
+
Repository = "https://github.com/vvsagar/py-oxyroot.git"
42
+
14
43
[project.optional-dependencies]
15
44
tests = [
16
45
"pytest",
17
46
"numpy",
18
47
"uproot",
19
48
]
49
+
dev = [
50
+
"ruff",
51
+
]
52
+
20
53
[tool.maturin]
21
54
python-source = "python"
22
55
features = ["pyo3/extension-module"]
56
+
module-name = "oxyroot"
57
+
include = [
58
+
"python/oxyroot/oxyroot.pyi",
59
+
"python/oxyroot/py.typed",
60
+
]