uproot3 3.14.4

Description:

uproot3 3.14.4

uproot (originally μproot, for “micro-Python ROOT”) is a reader and 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 to cast blocks of data from the ROOT file as Numpy arrays.
Python does not necessarily mean slow. As long as the data blocks (“baskets”) are large, this “array at a time” approach can even be faster than “event at a time” C++. Below, the rate of reading data into arrays with uproot is shown to be faster than C++ ROOT (left) and root_numpy (right), as long as the baskets are tens of kilobytes or larger (for a variable number of muons per event in an ensemble of different physics samples; higher is better).


uproot is not maintained by the ROOT project team, so post bug reports here as GitHub issues, not on a ROOT forum. Thanks!

Installation
Install uproot like any other Python package:
pip install uproot3 # maybe with sudo or --user, or in virtualenv
The pip installer automatically installs strict dependencies; the conda installer also installs optional dependencies (except for Pandas).

Strict dependencies:

numpy (1.13.1+)
Awkward Array 0.x
uproot3-methods
cachetools



Optional dependencies:

lz4 to read/write lz4-compressed ROOT files
xxhash to read/write lz4-compressed ROOT files
lzma to read/write lzma-compressed ROOT files in Python 2
xrootd to access remote files through XRootD
requests to access remote files through HTTP
pandas to fill Pandas DataFrames instead of Numpy arrays

Reminder: you do not need C++ ROOT to run uproot.



Tutorial
See the project homepage for a tutorial.
Run that tutorial on Binder.
Tutorial contents:

Introduction
What is Uproot?
Exploring a file

Compressed objects in ROOT files
Exploring a TTree
Some terminology


Reading arrays from a TTree
Caching data

Automatically managed caches
Caching at all levels of abstraction


Lazy arrays

Lazy array of many files
Lazy arrays with caching
Lazy arrays as lightweight skims
Lazy arrays in Dask


Iteration

Filenames and entry numbers while iterating
Limiting the number of entries to be read
Controlling lazy chunk and iteration step sizes
Caching and iteration


Changing the output container type
Filling Pandas DataFrames
Selecting and interpreting branches

TBranch interpretations
Reading data into a preexisting array
Passing many new interpretations in one call
Multiple values per event: fixed size arrays
Multiple values per event: leaf-lists
Multiple values per event: jagged arrays
Jagged array performance
Special physics objects: Lorentz vectors
Variable-width values: strings
Arbitrary objects in TTrees
Doubly nested jagged arrays (i.e. std::vector<std::vector<T>>)


Parallel array reading
Histograms, TProfiles, TGraphs, and others
Creating and writing data to ROOT files

Writing histograms
Writing TTrees