ROOT I/O in pure Python and Numpy.
Project description
uproot (originally μproot, for “micro-Python ROOT”) is a reader and (someday) a writer of the ROOT file format using only Python and Numpy. Unlike the standard C++ ROOT implementation, uproot is only an I/O library, primarily intended to stream data into machine learning libraries in Python. Unlike PyROOT and root_numpy, uproot does not depend on C++ ROOT. Instead, it uses Numpy calls to rapidly cast data blocks in the ROOT file as Numpy arrays.
It is important to note that uproot is not maintained by the ROOT project team, so post bug reports as uproot GitHub issues, not on any ROOT forum.
Installation
Install uproot like any other Python package:
pip install uproot --useror similar (use sudo, virtualenv, or conda if you wish).
Strict dependencies:
Recommended dependencies:
Optional dependencies:
XRootD to access remote files
futures for parallel processing; this is part of the Python 3 standard library, so only install for Python 2
Reminder: you do not need C++ ROOT to run uproot.
Getting started
Download a Z → μμ flat ntuple and a H → ZZ → eeμμ structured TTree.
wget http://scikit-hep.org/uproot/examples/Zmumu.root
wget http://scikit-hep.org/uproot/examples/HZZ.rootOpen each of the files; uproot presents them as dict-like objects with ROOT names and objects as keys and values. (The “cycle number” after the semicolon can usually be ignored.)
>>> import uproot
>>> uproot.open("Zmumu.root").keys()
[b'events;1']
>>> uproot.open("HZZ.root").keys()
[b'events;1']Since the file acts as a dict, access the TTrees with square brackets. TTrees are also dict-like objects, with branch names and branches as keys and values. (Hint: allkeys() lists branches recursively, if they’re nested.)
>>> zmumu = uproot.open("Zmumu.root")["events"]
>>> hzz = uproot.open("HZZ.root")["events"]
>>> zmumu.keys()
[b'Type', b'Run', b'Event', b'E1', b'px1', b'py1', b'pz1', b'pt1', b'eta1', b'phi1',
b'Q1', b'E2', b'px2', b'py2', b'pz2', b'pt2', b'eta2', b'phi2', b'Q2', b'M']
>>> hzz.keys()
[b'NJet', b'Jet_Px', b'Jet_Py', b'Jet_Pz', b'Jet_E', b'Jet_btag', b'Jet_ID', b'NMuon',
b'Muon_Px', b'Muon_Py', b'Muon_Pz', b'Muon_E', b'Muon_Charge', b'Muon_Iso', b'NElectron',
b'Electron_Px', b'Electron_Py', b'Electron_Pz', b'Electron_E', b'Electron_Charge',
...You can turn a chosen set of branches into Numpy arrays with the arrays method. Each array represents the values of a single attribute for all events, just as they’re stored in a split ROOT file.
>>> zmumu.arrays(["px1", "py1", "pz1"])
{b'px1': array([-41.19528764, 35.11804977, ..., 32.37749196, 32.48539387]),
b'py1': array([ 17.4332439 , -16.57036233, ..., 1.19940578, 1.2013503 ]),
b'pz1': array([-68.96496181, -48.77524654, ..., -74.53243061, -74.80837247])}If the number of items per entry is not constant, such as the number of jets in an event, they can’t be expressed as flat Numpy arrays. Instead, uproot loads them into jagged arrays.
>>> hzz.array("Jet_E")
jaggedarray([[],
[44.137363],
[],
...,
[55.95058],
[229.57799 33.92035],
[]])A jagged array behaves like an array of unequal-length arrays,
>>> for jetenergies in hzz.array("Jet_E"):
... print("event")
... for jetenergy in jetenergies:
... print(jetenergy)
...
event
event
44.137363
event
event
230.34601
101.35884
60.08414But it’s built out of regular Numpy arrays, for use in libraries that accept Numpy.
>>> jaggedarray.content
array([ 44.137363, 230.34601 , 101.35884 , ..., 55.95058 , 229.57799 ,
33.92035 ], dtype=float32)
>>> jaggedarray.starts
array([ 0, 0, 1, ..., 2770, 2771, 2773])
>>> jaggedarray.stops
array([ 0, 1, 1, ..., 2771, 2773, 2773])Reference documentation
The complete reference documentation is available on uproot.readthedocs.io. These are exhaustive descriptions of each function and its parameters, also available as Python help strings.
Introductory tutorials
Reference documentation is not the place to start learning about a topic. Introductory tutorials are provided below.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
File details
Details for the file uproot-2.8.4.tar.gz.
File metadata
- Download URL: uproot-2.8.4.tar.gz
- Upload date:
- Size: 5.4 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 2c8e347168e22243a0ba8bdec9ee57da824d7988239287795b9be3b6df46ec83 |
|
| MD5 | fb1b7fdaf01fa9350c88f75c874f45c2 |
|
| BLAKE2b-256 | d5400c7f38342154ad01e3f2a290379328260091ed2b0676d7c8fe1339403427 |
