Uproot 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.
We are in the middle of a transition in which Uproot 3 is deprecated in favor of Uproot 4. Most features are available in Uproot 4 (the major exception being file-writing) and it's ready for new physics analyses. Interfaces differ slightly between Uproot 3 and 4, and the new one isn't properly documented yet.
This tutorial at PyHEP 2020 (video with interactive notebook on Binder) may be a good way to get started, though it's understandable if you want to wait for full documentation.
Both libraries can be used in the same Python process; just
pip install uproot # old
pip install uproot4 # new
and import them as uproot
and uproot4
, respectively. Later this year (2020), the two packages will shift to
pip install uproot # new
pip install uproot3 # old
Note that Uproot 3 returns old-style Awkward 0 arrays and Uproot 4 returns new-style Awkward 1 arrays. (The new version of Uproot was motivated by the new version of Awkward, to make a clear distinction.)
Usually, you'll want to install Uproot with Awkward Array <https://awkward-array.org>
__ because this is the default array format.
.. code-block:: bash
pip install uproot4 awkward1
But if you are working in a limited environment, Uproot can be installed without Awkward Array.
.. code-block:: bash
pip install uproot4
Just be sure to pass library="np"
to any function that returns arrays to specify that you want NumPy arrays, rather than Awkward arrays. Other array libraries include Pandas <https://pandas.pydata.org/>
__ and CuPy <https://cupy.dev/>
__, which, like Awkward, would need to be explicitly installed.
Uproot 4's only strict dependency is NumPy. (The pip command above will install it, if you don't have it.)
If you use any features that require more dependencies, you will be prompted with instructions to install them.
The full list is
awkward1
: highly recommended, but can be avoided by passinglibrary="np"
to any functions that read arrays.pandas
: only iflibrary="pd"
.cupy
: only iflibrary="cp"
(reads arrays onto GPUs).dask[array]
anddask[dataframe]
: experimental, for lazy arrays withlibrary="da"
.xrootd
: only if reading files withroot://
URLs.lz4
andxxhash
: only if reading ROOT files that have been LZ4-compressed.zstandard
: only if reading ROOT files that have been ZSTD-compressed.backports.lzma
: only if reading ROOT files that have been LZMA-compressed (in Python 2).boost-histogram
: only if converting histograms to Boost with.to_boost()
.hist
: only if converting histograms to hist with.to_hist()
.