Install & Compatibility
Where this runs
tested against v0.10.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 91.6MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 4.0s · import 0.000s · 88MB
91MB installed
● package 91MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
TLorentzVector
✓ from uproot3_methods import TLorentzVector
✗ from uproot3_methods.classes.TLorentzVector import TLorentzVector
This quickstart demonstrates how `uproot3-methods` extends `uproot3`'s capabilities. When `uproot3-methods` is installed, it implicitly adds methods (like `pt`, `eta`, `phi` for four-vectors or `integral` for histograms) to arrays loaded by `uproot3` or created as `awkward0` arrays. The example creates a dummy ROOT file, loads four-vector branches, and then explicitly creates `TLorentzVector` objects using data from the file to showcase the extended methods.
import uproot3
import numpy as np
# Installing uproot3-methods automatically adds methods to uproot3 arrays.
# No explicit import of uproot3_methods is needed for the methods to be available on arrays.
# Example: Create a dummy ROOT file with four-vectors using uproot3
with uproot3.recreate('test_tree.root') as file:
file['tree'] = {
'px': np.array([10.0, 20.0, 30.0]),
'py': np.array([5.0, 10.0, 15.0]),
'pz': np.array([1.0, 2.0, 3.0]),
'energy': np.array([11.22, 22.45, 33.67])
}
# Open the file and access the branches as a 'Momentum4D' object
with uproot3.open('test_tree.root') as file:
tree = file['tree']
# uproot3-methods automatically provides a 'Momentum4D' accessor
# if the 'px', 'py', 'pz', 'energy' branches are present.
# This assumes 'Momentum4D' is enabled by default or via configuration.
# For a direct example, let's load specific branches and construct.
vectors = uproot3.allbranches(file, filter_name=['px', 'py', 'pz', 'energy'])
# Assuming uproot3-methods is installed, it enhances the awkward0 array with methods
# You might need to explicitly wrap or configure, but typically it's auto-applied.
# For direct usage or clarity, we can use the class directly.
from uproot3_methods.vector.lorentz import TLorentzVector
# Example: create TLorentzVector objects from numpy arrays
p4_vectors = TLorentzVector.from_pxyzm(
vectors['px'], vectors['py'], vectors['pz'], np.zeros_like(vectors['px']) # mass=0 for simplicity
)
print(f"First vector pt: {p4_vectors.pt[0]:.2f}")
print(f"All vectors eta: {p4_vectors.eta}")
# Example for histograms
# from uproot3_methods.hist import TH1F
# hist = TH1F(bins=np.array([0, 1, 2, 3]), values=np.array([10, 20, 30]))
# print(f"Histogram integral: {hist.integral}")
Debug
Known issues
breakingThe package name was changed from `uproot-methods` to `uproot3-methods` starting from version 0.10.0. Older installations or `import` statements will fail.fixUninstall `uproot-methods` if present (`pip uninstall uproot-methods`) and install the new package (`pip install uproot3-methods`). Update all `import` statements from `uproot_methods` to `uproot3_methods`.
affects: 0.10.0 and later
gotchauproot3-methods is strictly designed for `uproot3` and `awkward0`. It is incompatible with `uproot` versions 4 or later, and `awkward` versions 1 or later.fixEnsure your environment uses `uproot3` and `awkward0`. If you need to work with newer `uproot` or `awkward` versions, use `uproot-methods` (no '3' in the name, e.g., `pip install uproot-methods`) which is compatible with `uproot` 4+ and `awkward` 1+.
affects: All versions
gotchaHistogram `fSumw2` calculation was corrected for NumPy arrays (which have values without errors). Previously, `fSumw2` was incorrectly set to the square of values; it should be equal to the values.fixUpdate to `uproot3-methods` version 0.10.1 or later (`pip install --upgrade uproot3-methods`) to ensure correct histogram error calculations from NumPy arrays.
affects: Prior to 0.10.1
Upgrade
Version history
0.10.1latest on PyPI · released Mar 18, 2021
Audit
Dependencies
uproot3requiredProvides the core ROOT file I/O objects that uproot3-methods extends.
awkward0requireduproot3-methods adds methods to Awkward 0.x arrays; incompatible with Awkward 1.x or 2.x.