uproot 3.5.0rc1

ROOT I/O in pure Python and Numpy.

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 uproot                        # maybe with sudo or --user, or in virtualenv

or install with conda:

conda config --add channels conda-forge   # if you haven't added conda-forge already
conda install uproot

The pip installer automatically installs strict dependencies; the conda installer installs optional dependencies, too.

Strict dependencies:

• numpy (1.13.1+)

• awkward-array (0.9.0+)

• uproot-methods (0.5.0+)

• cachetools

Optional dependencies:

• lz4 to read lz4-compressed ROOT files

• lzma to read lzma-compressed ROOT files in Python 2

• xrootd to access remote files through XRootD

• requests to access remote files through HTTP

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

Tutorial

See the project homepage for a tutorial.

Run that tutorial on Binder.

Reference documentation

• Opening files

  • uproot.open

  • uproot.xrootd

  • uproot.iterate

• ROOT I/O

  • uproot.rootio.ROOTDirectory

  • uproot.rootio.ROOTObject

  • uproot.rootio.ROOTStreamedObject

• TTree Handling

  • uproot.tree.TTreeMethods

  • uproot.tree.TBranchMethods

• Interpretation

• Caches

• Parallel I/O