跳转到主要内容

纯Python和NumPy的ROOT I/O。

项目描述

PyPI version Conda-Forge Python 3.8‒3.12 BSD-3 Clause License Continuous integration tests

Scikit-HEP NSF-1836650 DOI 10.5281/zenodo.4340632 Documentation Gitter

Uproot是一个用于在纯Python和NumPy中读取和写入ROOT文件的库。

与标准的C++ ROOT实现不同,Uproot仅是一个I/O库,主要用于将数据流式传输到Python机器学习库。与PyROOT和root_numpy不同,Uproot不依赖于C++ ROOT。相反,它使用Numpy将ROOT文件中的数据块转换为NumPy数组。

安装

Uproot 可以使用 pip 从 PyPI(https://pypi.ac.cn/project/uproot)安装。

pip install uproot

Uproot 还可以通过 conda 获取。

conda install -c conda-forge uproot

如果您已经添加了 conda-forge 作为频道,则不需要 -c conda-forge。添加频道是推荐的,因为它确保所有包都使用兼容的版本(见 conda-forge 文档

conda config --add channels conda-forge
conda update --all

获取帮助

教程和参考文档 开始。

  • GitHub Issues 上报告错误、请求功能,并请求更多文档。
  • 如果您有 "我该如何..." 的问题,请以 "Q&A" 类别在 GitHub Discussion 中开始讨论。
  • 或者,在带有 [uproot] 标签的 StackOverflow 上提问。请确保包括您使用的任何其他库的标签,例如 Pandas 或 PyTorch。
  • 要实时提问,请尝试 Gitter Scikit-HEP/uproot 聊天室。

开发者安装

Uproot 是一个普通的 Python 库;您可以使用

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

获取代码副本,并在存储库目录中通过调用 pip install -e . 本地安装它。

如果您还需要开发 Awkward Array,请参阅其 开发者安装说明

依赖项

Uproot 的唯一严格依赖项是 NumPy 和打包。 严格依赖项将由 pip(或 conda)自动安装。

Awkward Array 非常推荐,并且将由 pip(或 conda)自动安装,尽管在没有它的前提下也可以使用 Uproot。如果您需要最小化安装,请将 --no-deps 传递给 pip,并将每个数组获取函数的 library="np" 传递,或者全局设置 uproot.default_library 以获取 NumPy 数组而不是 Awkward 数组。

  • awkward:Uproot 5.x 需要 Awkward 2.x。

以下库与 Uproot 一起使用也很有用,但不是必需的。如果您调用需要其中一个的函数,系统会提示您安装它。(Conda 会自动安装其中大部分。)

对于以不同方式压缩的 ROOT 文件

  • lz4xxhash:如果读取被 LZ4 压缩的 ROOT 文件。
  • zstandard:如果读取被 ZSTD 压缩的 ROOT 文件。
  • ZLIB 和 LZMA 已内置(Python 标准库)。

对于访问远程文件

  • minio:如果读取以 s3:// URI 读取的文件。
  • xrootd:如果读取以 root:// URI 读取的文件。
  • HTTP/S 访问已内置(Python 标准库)。

对于与 Dask 一起进行分布式计算

  • dask:请参阅 uproot.dask
  • dask-awkward:对于具有不规则结构("jagged" 数组)的数据,请参阅 dask-awkward

对于将 TTrees 导出为 Pandas

  • pandas:如果 library="pd"
  • awkward-pandas:如果 library="pd" 并且数据具有不规则结构("jagged" 数组),请参阅 awkward-pandas

对于导出直方图

  • boost-histogram:如果使用 histogram.to_boost() 将直方图转换为 boost-histogram
  • hist:如果使用 histogram.to_hist() 将直方图转换为 hist

致谢

本工作的支持由NSF合作协议提供,包括OAC-1836650PHY-2323298(IRIS-HEP)、赠款OAC-1450377(DIANA/HEP)以及PHY-2121686(US-CMS LHC Ops)。

特别感谢Uproot贡献者的热情帮助(包括原始仓库)。

Jim Pivarski
Jim Pivarski

💻 📖 🚇 🚧
Pratyush Das
Pratyush Das

💻 🚇
Chris Burr
Chris Burr

💻 🚇
Dmitri Smirnov
Dmitri Smirnov

💻
Matthew Feickert
Matthew Feickert

🚇
Tamas Gal
Tamas Gal

💻
Luke Kreczko
Luke Kreczko

💻 ⚠️
Nicholas Smith
Nicholas Smith

💻
Noah Biederbeck
Noah Biederbeck

💻
Oksana Shadura
Oksana Shadura

💻 🚇
Henry Schreiner
Henry Schreiner

💻 🚇 ⚠️
Mason Proffitt
Mason Proffitt

💻 ⚠️
Jonas Rembser
Jonas Rembser

💻
benkrikler
benkrikler

💻
Hans Dembinski
Hans Dembinski

📖
Marcel R.
Marcel R.

💻
Ruggero Turra
Ruggero Turra

💻
Jonas Rübenach
Jonas Rübenach

💻
bfis
bfis

💻
Raymond Ehlers
Raymond Ehlers

💻
Andrzej Novak
Andrzej Novak

💻
Josh Bendavid
Josh Bendavid

💻
Doug Davis
Doug Davis

💻
Chao Gu
Chao Gu

💻
Lukas Koch
Lukas Koch

💻
Michele Peresano
Michele Peresano

💻
Edoardo
Edoardo

💻
JMSchoeffmann
JMSchoeffmann

💻
alexander-held
alexander-held

💻
Giordon Stark
Giordon Stark

💻
Ryunosuke O'Neil
Ryunosuke O'Neil

💻
ChristopheRappold
ChristopheRappold

📖
Cosmin Deaconu
Cosmin Deaconu

⚠️ 💻
Carlos Pegueros
Carlos Pegueros

📖 💡 ⚠️
Benjamin Tovar
Benjamin Tovar

💻
Duncan Macleod
Duncan Macleod

🚇
mpad
mpad

💻
Peter Fackeldey
Peter Fackeldey

💻
Kush Kothari
Kush Kothari

💻
Aryan Roy
Aryan Roy

💻
Jerry Ling
Jerry Ling

💻
kakwok
kakwok

💻
Dmitry Kalinkin
Dmitry Kalinkin

💻 🚇
Nikolai Hartmann
Nikolai Hartmann

💻
Kilian Lieret
Kilian Lieret

📖
Daniel Cervenkov
Daniel Cervenkov

💻
Beojan Stanislaus
Beojan Stanislaus

💻
Angus Hollands
Angus Hollands

💻 🚧
Luis Antonio Obis Aparicio
Luis Antonio Obis Aparicio

💻
renyhp
renyhp

💻
Lindsey Gray
Lindsey Gray

💻
ioanaif
ioanaif

💻
OTABI Tomoya
OTABI Tomoya

⚠️
Jost Migenda
Jost Migenda

📖
Gaétan Lepage
Gaétan Lepage

⚠️
HaarigerHarald
HaarigerHarald

💻
Ben Greiner
Ben Greiner

⚠️
Robin Sonnabend
Robin Sonnabend

💻
Bo Johnson
Bo Johnson

💻
Miles
Miles

💻
djw9497
djw9497

💻
Piotr Sobczyński
Piotr Sobczyński

💻
Giedrius Juškevičius
Giedrius Juškevičius

💻

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

由...