ROOT I/O in pure Python and Numpy.
.. image:: https://raw.githubusercontent.com/scikit-hep/uproot3/master/docs/source/logo-300px.png :alt: uproot :target: https://github.com/scikit-hep/uproot3
.. inclusion-marker-1-5-do-not-remove
uproot (originally μproot, for "micro-Python ROOT") is a reader and a writer of the ROOT file format <https://root.cern/>
__ 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).
.. image:: https://raw.githubusercontent.com/scikit-hep/uproot3/master/docs/root-none-muon.png :width: 350 px .. image:: https://raw.githubusercontent.com/scikit-hep/uproot3/master/docs/rootnumpy-none-muon.png :width: 350 px
uproot is not maintained by the ROOT project team, so post bug reports here as GitHub issues <https://github.com/scikit-hep/uproot3/issues>
__, not on a ROOT forum. Thanks!
.. inclusion-marker-2-do-not-remove
Install uproot like any other Python package:
.. code-block:: bash
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).
numpy <https://scipy.org/install.html>
__ (1.13.1+)Awkward Array 0.x <https://github.com/scikit-hep/awkward-0.x>
__uproot3-methods <https://github.com/scikit-hep/uproot3-methods>
__cachetools <https://pypi.org/project/cachetools>
__lz4 <https://pypi.org/project/lz4>
__ to read/write lz4-compressed ROOT filesxxhash <https://pypi.org/project/xxhash/>
__ to read/write lz4-compressed ROOT fileslzma <https://pypi.org/project/backports.lzma>
__ to read/write lzma-compressed ROOT files in Python 2xrootd <https://anaconda.org/conda-forge/xrootd>
__ to access remote files through XRootDrequests <https://pypi.org/project/requests>
__ to access remote files through HTTPpandas <https://pandas.pydata.org>
__ to fill Pandas DataFrames instead of Numpy arraysReminder: you do not need C++ ROOT to run uproot.
See the project homepage <https://github.com/scikit-hep/uproot3>
__ for a tutorial <https://github.com/scikit-hep/uproot3#tutorial>
__.
Run that tutorial <https://mybinder.org/v2/gh/scikit-hep/uproot3/master?urlpath=lab/tree/binder%2Ftutorial.ipynb>
__ on Binder.
Tutorial contents:
Introduction <https://github.com/scikit-hep/uproot3#introduction>
__
What is Uproot? <https://github.com/scikit-hep/uproot3#what-is-uproot>
__
Exploring a file <https://github.com/scikit-hep/uproot3#exploring-a-file>
__
Compressed objects in ROOT files <https://github.com/scikit-hep/uproot3#compressed-objects-in-root-files>
__Exploring a TTree <https://github.com/scikit-hep/uproot3#exploring-a-ttree>
__Some terminology <https://github.com/scikit-hep/uproot3#some-terminology>
__Reading arrays from a TTree <https://github.com/scikit-hep/uproot3#reading-arrays-from-a-ttree>
__
Caching data <https://github.com/scikit-hep/uproot3#caching-data>
__
Automatically managed caches <https://github.com/scikit-hep/uproot3#automatically-managed-caches>
__Caching at all levels of abstraction <https://github.com/scikit-hep/uproot3#caching-at-all-levels-of-abstraction>
__Lazy arrays <https://github.com/scikit-hep/uproot3#lazy-arrays>
__
Lazy array of many files <https://github.com/scikit-hep/uproot3#lazy-array-of-many-files>
__Lazy arrays with caching <https://github.com/scikit-hep/uproot3#lazy-arrays-with-caching>
__Lazy arrays as lightweight skims <https://github.com/scikit-hep/uproot3#lazy-arrays-as-lightweight-skims>
__Lazy arrays in Dask <https://github.com/scikit-hep/uproot3#lazy-arrays-in-dask>
__Iteration <https://github.com/scikit-hep/uproot3#iteration>
__
Filenames and entry numbers while iterating <https://github.com/scikit-hep/uproot3#filenames-and-entry-numbers-while-iterating>
__Limiting the number of entries to be read <https://github.com/scikit-hep/uproot3#limiting-the-number-of-entries-to-be-read>
__Controlling lazy chunk and iteration step sizes <https://github.com/scikit-hep/uproot3#controlling-lazy-chunk-and-iteration-step-sizes>
__Caching and iteration <https://github.com/scikit-hep/uproot3#caching-and-iteration>
__Changing the output container type <https://github.com/scikit-hep/uproot3#changing-the-output-container-type>
__
Filling Pandas DataFrames <https://github.com/scikit-hep/uproot3#filling-pandas-dataframes>
__
Selecting and interpreting branches <https://github.com/scikit-hep/uproot3#selecting-and-interpreting-branches>
__
TBranch interpretations <https://github.com/scikit-hep/uproot3#tbranch-interpretations>
__Reading data into a preexisting array <https://github.com/scikit-hep/uproot3#reading-data-into-a-preexisting-array>
__Passing many new interpretations in one call <https://github.com/scikit-hep/uproot3#passing-many-new-interpretations-in-one-call>
__Multiple values per event: fixed size arrays <https://github.com/scikit-hep/uproot3#multiple-values-per-event-fixed-size-arrays>
__Multiple values per event: leaf-lists <https://github.com/scikit-hep/uproot3#multiple-values-per-event-leaf-lists>
__Multiple values per event: jagged arrays <https://github.com/scikit-hep/uproot3#multiple-values-per-event-jagged-arrays>
__Jagged array performance <https://github.com/scikit-hep/uproot3#jagged-array-performance>
__Special physics objects: Lorentz vectors <https://github.com/scikit-hep/uproot3#special-physics-objects-lorentz-vectors>
__Variable-width values: strings <https://github.com/scikit-hep/uproot3#variable-width-values-strings>
__Arbitrary objects in TTrees <https://github.com/scikit-hep/uproot3#arbitrary-objects-in-ttrees>
__Doubly nested jagged arrays (i.e. std::vector<std::vector<T>>) <https://github.com/scikit-hep/uproot3#doubly-nested-jagged-arrays-ie-stdvectorstdvectort>
__Parallel array reading <https://github.com/scikit-hep/uproot3#parallel-array-reading>
__
Histograms, TProfiles, TGraphs, and others <https://github.com/scikit-hep/uproot3#histograms-tprofiles-tgraphs-and-others>
__
Creating and writing data to ROOT files <https://github.com/scikit-hep/uproot3#creating-and-writing-data-to-root-files>
__
Writing histograms <https://github.com/scikit-hep/uproot3#writing-histograms>
__Writing TTrees <https://github.com/scikit-hep/uproot3#writing-ttrees>
__