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!
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 also installs optional dependencies (except for Pandas).
- 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.
Testing and development requirements
The packages need to run the test suite can be installed via pip install "uproot[testing]". Here is an example how to set up a development
git clone https://github.com/scikit-hep/uproot.git # alternatively your own fork cd uproot python -m venv venv # create a virtual environment in the folder venv . venv/bin/activate # activate the Python environment pip install -e ".[testing]" # installs uproot in editable mode with all packages required for testing pytest # run the test suite
Run that tutorial on Binder.
- What is uproot?
- Exploring a file
- Reading arrays from a TTree
- Caching data
- Lazy arrays
- 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
- Opening files
- ROOT I/O
- TTree Handling
- Parallel I/O
Release history Release notifications
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
|Filename, size||File type||Python version||Upload date||Hashes|
|Filename, size uproot-3.11.3-py2.py3-none-any.whl (114.5 kB)||File type Wheel||Python version py2.py3||Upload date||Hashes View hashes|
|Filename, size uproot-3.11.3.tar.gz (34.3 MB)||File type Source||Python version None||Upload date||Hashes View hashes|
Hashes for uproot-3.11.3-py2.py3-none-any.whl