Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/scikit-hep/uproot5

ROOT I/O in pure Python and NumPy.
https://github.com/scikit-hep/uproot5

analysis big-data bigdata file-format hep hep-ex hep-py numpy python root root-cern scikit-hep

Last synced: about 15 hours ago
JSON representation

ROOT I/O in pure Python and NumPy.

Host: GitHub
URL: https://github.com/scikit-hep/uproot5
Owner: scikit-hep
License: bsd-3-clause
Created: 2020-05-08T20:30:09.000Z (over 4 years ago)
Default Branch: main
Last Pushed: 2025-01-24T17:28:46.000Z (9 days ago)
Last Synced: 2025-01-25T14:01:42.735Z (8 days ago)
Topics: analysis, big-data, bigdata, file-format, hep, hep-ex, hep-py, numpy, python, root, root-cern, scikit-hep
Language: Python
Homepage: https://uproot.readthedocs.io
Size: 4.08 MB
Stars: 241
Watchers: 20
Forks: 76
Open Issues: 70
Metadata Files:
- Readme: README.md
- License: LICENSE
- Citation: CITATION.cff

Awesome Lists containing this project

README

        

[![PyPI version](https://badge.fury.io/py/uproot.svg)](https://pypi.org/project/uproot)

[![Conda-Forge](https://img.shields.io/conda/vn/conda-forge/uproot)](https://github.com/conda-forge/uproot-feedstock)

[![Python 3.9‒3.13](https://img.shields.io/badge/python-3.9%E2%80%923.13-blue)](https://www.python.org)

[![BSD-3 Clause License](https://img.shields.io/badge/license-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)

[![Continuous integration tests](https://github.com/scikit-hep/uproot5/actions/workflows/build-test.yml/badge.svg)](https://github.com/scikit-hep/uproot5/actions)

[![Scikit-HEP](https://scikit-hep.org/assets/images/Scikit--HEP-Project-blue.svg)](https://scikit-hep.org/)

[![NSF-1836650](https://img.shields.io/badge/NSF-1836650-blue.svg)](https://nsf.gov/awardsearch/showAward?AWD_ID=1836650)

[![DOI 10.5281/zenodo.4340632](https://zenodo.org/badge/DOI/10.5281/zenodo.4340632.svg)](https://doi.org/10.5281/zenodo.4340632)

[![Documentation](https://img.shields.io/badge/docs-online-success)](https://uproot.readthedocs.io/)

[![Gitter](https://img.shields.io/badge/chat-online-success)](https://gitter.im/Scikit-HEP/uproot)

Uproot is a library for reading and writing [ROOT files](https://root.cern/) 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](https://pypi.org/project/uproot) using pip.

```bash

pip install uproot

```

Uproot is also available using [conda](https://anaconda.org/conda-forge/uproot).

```bash

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](https://conda-forge.org/docs/user/introduction.html#how-can-i-install-packages-from-conda-forge)):

```bash

conda config --add channels conda-forge

conda update --all

```

## Getting help

**Start with the [tutorials and reference documentation](https://uproot.readthedocs.io/).**

   * Report bugs, request features, and ask for additional documentation on [GitHub Issues](https://github.com/scikit-hep/uproot5/issues).

   * If you have a "How do I...?" question, start a [GitHub Discussion](https://github.com/scikit-hep/uproot5/discussions) with category "Q&A".

   * Alternatively, ask about it on [StackOverflow with the [uproot] tag](https://stackoverflow.com/questions/tagged/uproot). 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](https://gitter.im/Scikit-HEP/uproot) chat room.

## Installation for developers

Uproot is an ordinary Python library; you can get a copy of the code with

```bash

git clone https://github.com/scikit-hep/uproot5.git

```

and install it locally by calling `pip install -e .` in the repository directory.

If you need to develop Awkward Array as well, see its [installation for developers](https://github.com/scikit-hep/awkward-1.0#installation-for-developers).

# Dependencies

**Uproot's only strict dependencies are NumPy and packaging.** Strict dependencies are automatically installed by pip (or conda).

**[Awkward Array](https://anaconda.org/conda-forge/awkward) is highly recommended** and is automatically installed by pip (or conda), though it is _possible_ to use Uproot without it. If you need a minimal installation, pass `--no-deps` to pip and pass `library="np"` to every array-fetching function, or globally set `uproot.default_library` to get NumPy arrays instead of Awkward Arrays.

   * `awkward`: Uproot 5.x requires Awkward 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` and `xxhash`: if reading ROOT files that have been LZ4-compressed.

   * `zstandard`: if reading ROOT files that have been ZSTD-compressed.

   * ZLIB and LZMA are built in (Python standard library).

**For accessing remote files:**

   * `minio`: if reading files with `s3://` URIs.

   * `xrootd`: if reading files with `root://` URIs.

   * HTTP/S access is built in (Python standard library).

**For distributed computing with [Dask](https://www.dask.org/):**

   * `dask`: see [uproot.dask](https://uproot.readthedocs.io/en/latest/uproot._dask.dask.html).

   * `dask-awkward`: for data with irregular structure ("jagged" arrays), see [dask-awkward](https://github.com/dask-contrib/dask-awkward).

**For exporting TTrees to [Pandas](https://pandas.pydata.org/):**

   * `pandas`: if `library="pd"`.

   * `awkward-pandas`: if `library="pd"` and the data have irregular structure ("jagged" arrays), see [awkward-pandas](https://github.com/intake/awkward-pandas).

**For exporting histograms:**

   * `boost-histogram`: if converting histograms to [boost-histogram](https://github.com/scikit-hep/boost-histogram) with `histogram.to_boost()`.

   * `hist`: if converting histograms to [hist](https://github.com/scikit-hep/hist) with `histogram.to_hist()`.

# Acknowledgements

Support for this work was provided by NSF cooperative agreements [OAC-1836650](https://www.nsf.gov/awardsearch/showAward?AWD_ID=1836650) and [PHY-2323298](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2323298) (IRIS-HEP), grant [OAC-1450377](https://nsf.gov/awardsearch/showAward?AWD_ID=1450377) (DIANA/HEP), and [PHY-2121686](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2121686) (US-CMS LHC Ops).

Thanks especially to the gracious help of Uproot contributors (including the [original repository](https://github.com/scikit-hep/uproot)).

  

    

      
_{Jim Pivarski}
💻 📖 🚇 🚧

      
_{Pratyush Das}
💻 🚇

      
_{Chris Burr}
💻 🚇

      
_{Dmitri Smirnov}
💻

      
_{Matthew Feickert}
🚇

      
_{Tamas Gal}
💻

      
_{Luke Kreczko}
💻 ⚠️

    

    

      
_{Nicholas Smith}
💻

      
_{Noah Biederbeck}
💻

      
_{Oksana Shadura}
💻 🚇

      
_{Henry Schreiner}
💻 🚇 ⚠️

      
_{Mason Proffitt}
💻 ⚠️

      
_{Jonas Rembser}
💻

      
_benkrikler
💻

    

    

      
_{Hans Dembinski}
📖

      
_{Marcel R.}
💻

      
_{Ruggero Turra}
💻

      
_{Jonas Rübenach}
💻

      
_bfis
💻

      
_{Raymond Ehlers}
💻

      
_{Andrzej Novak}
💻

    

    

      
_{Josh Bendavid}
💻

      
_{Doug Davis}
💻

      
_{Chao Gu}
💻

      
_{Lukas Koch}
💻

      
_{Michele Peresano}
💻

      
_Edoardo
💻

      
_{JMSchoeffmann}
💻

    

    

      
_{alexander-held}
💻

      
_{Giordon Stark}
💻

      
_{Ryunosuke O'Neil}
💻

      
_{ChristopheRappold}
📖

      
_{Cosmin Deaconu}
⚠️ 💻

      
_{Carlos Pegueros}
📖 💡 ⚠️ ✅

      
_{Benjamin Tovar}
💻

    

    

      
_{Duncan Macleod}
🚇

      
_mpad
💻

      
_{Peter Fackeldey}
💻

      
_{Kush Kothari}
💻

      
_{Aryan Roy}
💻

      
_{Jerry Ling}
💻

      
_kakwok
💻

    

    

      
_{Dmitry Kalinkin}
💻 🚇

      
_{Nikolai Hartmann}
💻

      
_{Kilian Lieret}
📖

      
_{Daniel Cervenkov}
💻

      
_{Beojan Stanislaus}
💻

      
_{Angus Hollands}
💻 🚧

      
_{Luis Antonio Obis Aparicio}
💻

    

    

      
_renyhp
💻

      
_{Lindsey Gray}
💻

      
_ioanaif
💻

      
_{OTABI Tomoya}
⚠️

      
_{Jost Migenda}
📖

      
_{Gaétan Lepage}
⚠️

      
_{HaarigerHarald}
💻

    

    

      
_{Ben Greiner}
⚠️

      
_{Robin Sonnabend}
💻

      
_{Bo Johnson}
💻

      
_Miles
💻

      
_djw9497
💻

      
_{Piotr Sobczyński}
💻

      
_{Giedrius Juškevičius}
💻

    

    

      
_MatousVozak
💻

      
_{Andrea Serafini}
💻

      
_{Andres Rios Tascon}
💻

    

  

💻: code, 📖: documentation, 🚇: infrastructure, 🚧: maintainance, ⚠: tests/feedback, 🤔: foundational ideas.