Pythonic Mix-ins for ROOT classes (uproot3-methods)

0.10.1 · maintenance · verified Thu Apr 16

uproot3-methods provides Pythonic mix-ins that extend the functionality of `uproot3` and `awkward0` arrays, adding common methods found in ROOT's C++ classes like TLorentzVector, TVector2, TVector3, and histogram types. It is specifically designed for the `uproot3` and `awkward0` ecosystems. The current version is 0.10.1 and it is primarily in maintenance mode, supporting the older `uproot3` branch.

Common errors

```
ModuleNotFoundError: No module named 'uproot_methods'
```
cause Attempting to import from the old package name after updating uproot3-methods (or its dependencies) or installing an environment with the new name.

fix Change your import statements from `uproot_methods` to `uproot3_methods`. If you still have the old package installed, uninstall it: `pip uninstall uproot-methods`.
```
AttributeError: 'JaggedArray' object has no attribute 'pt'
```
cause This error typically occurs when `uproot3-methods` is not installed, or when you are trying to use it with an incompatible version of `awkward` (e.g., Awkward 1.x or 2.x instead of Awkward 0.x).

fix Ensure `uproot3-methods` is installed (`pip install uproot3-methods`) and that your environment uses `awkward0` (`pip install 'awkward<1'`). If you intend to use `uproot` v4+ and `awkward` v1+, you should install `uproot-methods` instead (without the '3').
```
RuntimeWarning: A mix-in for an Awkward 0.x Array could not be found...
```
cause This warning indicates that `uproot3-methods` is installed, but it couldn't properly apply its mix-ins to the `awkward` arrays because the loaded `awkward` version is not `awkward0`.

fix Verify your `awkward` installation. For `uproot3-methods`, you must use `awkward0` (e.g., `pip install 'awkward<1'`). If you need a newer `awkward` version, use `uproot-methods` (compatible with Awkward 1+) instead of `uproot3-methods`.

Warnings

breaking The package name was changed from `uproot-methods` to `uproot3-methods` starting from version 0.10.0. Older installations or `import` statements will fail.
Fix: Uninstall `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`.
gotcha uproot3-methods is strictly designed for `uproot3` and `awkward0`. It is incompatible with `uproot` versions 4 or later, and `awkward` versions 1 or later.
Fix: Ensure 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+.
gotcha Histogram `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.
Fix: Update to `uproot3-methods` version 0.10.1 or later (`pip install --upgrade uproot3-methods`) to ensure correct histogram error calculations from NumPy arrays.

Install

pip install uproot3-methods Install stable version

Imports

TLorentzVector
wrong:
```
from uproot_methods.vector.lorentz import TLorentzVector
```
correct:
```
from uproot3_methods.vector.lorentz import TLorentzVector
```
The package name changed from 'uproot-methods' to 'uproot3-methods' in version 0.10.0.
TH1F
wrong:
```
from uproot_methods.hist import TH1F
```
correct:
```
from uproot3_methods.hist import TH1F
```
The package name changed from 'uproot-methods' to 'uproot3-methods' in version 0.10.0.

Quickstart

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}")

view raw JSON →