ROOT I/O in pure Python and NumPy.
Project description
Uproot is a library for reading and writing ROOT files in pure 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.
Installation
Uproot can be installed from PyPI using pip. Awkward Array is optional but highly recommended:
pip install uproot awkward
Uproot is also available using conda (in this case, Awkward Array is automatically installed):
conda install -c conda-forge uproot
If you have already added conda-forge
as a channel, the -c conda-forge
is unnecessary. Adding the channel is recommended because it ensures that all of your packages use compatible versions (see conda-forge docs):
conda config --add channels conda-forge
conda update --all
Getting help
Start with the tutorials and reference documentation.
- Report bugs, request features, and ask for additional documentation on GitHub Issues.
- If you have a "How do I...?" question, start a GitHub Discussion with category "Q&A".
- Alternatively, ask about it on StackOverflow with the [uproot] tag. Be sure to include tags for any other libraries that you use, such as Pandas or PyTorch.
- To ask questions in real time, try the Gitter Scikit-HEP/uproot chat room.
Installation for developers
Uproot is an ordinary Python library; you can get a copy of the code with
git clone https://github.com/scikit-hep/uproot4.git
and install it locally by calling pip install .
in the repository directory.
If you need to develop Awkward Array as well, see its installation for developers.
Dependencies
Uproot's only strict dependencies are NumPy and packaging. You'll also need importlib_metadata
if you are on Python 3.7. These will be automatically installed when you install uproot.
Awkward Array is highly recommended. It is not a strict dependency, but is included in the dependencies to help most users; install without dependencies (--no-deps
with pip) if you want to avoid awkward
. If you're using Uproot without Awkward Array, you'll have to use the library="np"
option or globally set uproot.default_library
to return arrays as NumPy arrays (see documentation).
awkward
: be sure to use Awkward Array 2.x.
The following libraries are also useful in conjunction with Uproot, but are not necessary. If you call a function that needs one, you'll be prompted to install it. (Conda installs most of these automatically.)
For ROOT files, compressed different ways:
lz4
andxxhash
: only if reading ROOT files that have been LZ4-compressed.zstandard
: only if reading ROOT files that have been ZSTD-compressed.
For remote data:
xrootd
: only if reading files withroot://
URLs.
For exporting data to other libraries:
pandas
: only iflibrary="pd"
.cupy
: only iflibrary="cp"
(reads arrays onto GPUs).boost-histogram
: only if converting histograms to boost-histogram withhistogram.to_boost()
.hist
: only if converting histograms to hist withhistogram.to_hist()
.
Acknowledgements
Support for this work was provided by NSF cooperative agreement OAC-1836650 (IRIS-HEP), grant OAC-1450377 (DIANA/HEP) and PHY-1520942 (US-CMS LHC Ops).
Thanks especially to the gracious help of Uproot contributors (including the original repository).
๐ป: code, ๐: documentation, ๐: infrastructure, ๐ง: maintainance, โ : tests/feedback, ๐ค: foundational ideas.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for uproot-5.0.0rc5-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 99da150a9fae2a11c63dec300496c1e4f797a5ebe32635ef64309bbc524af5c1 |
|
MD5 | fc3c33b1fb2564b9a63ed1058280779d |
|
BLAKE2b-256 | a686a5db4a7a24010cb1c96f3e2bff6b0b762b9ddb86c61c9a2440e50d1fbd36 |