UnROOT

UnROOT: an I/O library for the CERN ROOT file format written in Julia - Published in JOSS (2022)

https://github.com/juliahep/unroot.jl

Science Score: 100.0%

This score indicates how likely this project is to be science-related based on various indicators:

✓
CITATION.cff file
Found CITATION.cff file
✓
codemeta.json file
Found codemeta.json file
✓
.zenodo.json file
Found .zenodo.json file
✓
DOI references
Found 1 DOI reference(s) in JOSS metadata
✓
Academic publication links
Links to: joss.theoj.org
✓
Committers with academic emails
3 of 15 committers (20.0%) from academic institutions
○
Institutional organization owner
✓
JOSS paper metadata
Published in Journal of Open Source Software

Keywords

cern-root hacktober hep high-energy-physics julia particle-physics

Keywords from Contributors

pde standardization interpretability simulations meshing pypy climate ode eeg sensitivity-analysis

Last synced: 6 months ago · JSON representation ·

Repository

Native Julia I/O package to work with CERN ROOT files objects (TTree and RNTuple)

Basic Info

Host: GitHub
Owner: JuliaHEP
License: mit
Language: Julia
Default Branch: main
Homepage: https://juliahep.github.io/UnROOT.jl/
Size: 17.5 MB

Statistics

Stars: 110
Watchers: 7
Forks: 20
Open Issues: 35
Releases: 106

Topics

cern-root hacktober hep high-energy-physics julia particle-physics

Created almost 6 years ago · Last pushed 6 months ago

Metadata Files

Readme Contributing License Code of conduct Citation

README.md

UnROOT.jl Logo

UnROOT.jl is a reader for the CERN ROOT file format written entirely in Julia, without any dependence on ROOT or Python.

Important API changes in v0.9.0

Click to expand example for RNTuple

We decided to alter the behaviour of `getindex(f::ROOTfile, s::AbstractString)` which is essentially the method called called when `f["foo/bar"]` is used. Before `v0.9.0`, `UnROOT` tried to do a best guess and return a tree/branch or even fully parsed data. This lead to two bigger issues. 1. Errors prevented any further exploration once `UnROOT` bumped into something it could not interpret, although it might not even be requested by the user (e.g. the interpretation of a single branch in a tree, while others would work fine) 2. Unpredictable behaviour (type instability): the path dictates which type of data is returned. Starting from `v0.9.0` we introduce an interface where `f["..."]` always returns genuine ROOT datatypes (or custom ones if you provide interpretations) and only performs the actual parsing when explicitly requested by the user via helper methods like `LazyBranch(f, "...")`. Long story short, the following pattern can be used to fix your code when upgrading to `v0.9.0`: f("foo/bar") => LazyBranch(f, "foo/bar") The `f["foo/bar"]` accessor should now work on almost all files and is a handy utility to explore the ROOT data structures. See [PR199](https://github.com/JuliaHEP/UnROOT.jl/pull/199) for more details.

Installation Guide

Download the latest Julia release
Open up Julia REPL (hit ] once to enter Pkg mode, hit backspace to exit it) julia julia>] (v1.8) pkg> add UnROOT ## Quick Start (see docs for more)

TTree

```julia julia> using UnROOT

julia> f = ROOTFile("test/samples/NanoAODv5sample.root") ROOTFile with 2 entries and 21 streamers. test/samples/NanoAODv5sample.root ├─ Events (TTree) │ ├─ "run" │ ├─ "luminosityBlock" │ ├─ "event" │ ├─ "⋮" │ ├─ "L1UnpairedBunchBptxPlus" │ ├─ "L1ZeroBias" │ └─ "L1ZeroBiascopy" └─ untagged (TObjString)

julia> mytree = LazyTree(f, "Events", ["Electrondxy", "nMuon", r"Muon(pt|eta)$"]) Row │ Electrondxy nMuon Muonpt Muon_eta
│ SubArray{Float3 UInt32 SubArray{Float3 SubArray{Float3 ─────┼──────────────────────────────────────────────────────────────────────────── 1 │ [0.000371] 0 [] [] 2 │ [-0.00982] 2 [19.9, 15.3] [0.53, 0.229] 3 │ [] 0 [] [] 4 │ [-0.00157] 0 [] [] 5 │ [] 0 [] [] 6 │ [-0.00126] 0 [] [] 7 │ [0.0612, 0.000642] 2 [22.2, 4.43] [-1.13, 1.98] 8 │ [0.00587, 0.000549, -0.00617] 0 [] [] ⋮ │ ⋮ ⋮ ⋮ ⋮ 992 rows omitted ```

RNTuple

Click to expand example for RNTuple

```julia julia> using UnROOT julia> f = ROOTFile("./test/samples/RNTuple/test_ntuple_stl_containers.root"); julia> f["ntuple"] UnROOT.RNTuple with 5 rows, 13 fields, and metadata: header: name: "ntuple" ntuple_description: "" writer_identifier: "ROOT v6.29/01" schema: RNTupleSchema with 13 top fields ├─ :lorentz_vector ⇒ Struct ├─ :vector_tuple_int32_string ⇒ Vector ├─ :string ⇒ String ├─ :vector_string ⇒ Vector ├─ :vector_vector_int32 ⇒ Vector ├─ :vector_variant_int64_string ⇒ Vector ├─ :vector_vector_string ⇒ Vector ├─ :variant_int32_string ⇒ Union ├─ :array_float ⇒ StdArray{3} ├─ :tuple_int32_string ⇒ Struct ├─ :array_lv ⇒ StdArray{3} ├─ :pair_int32_string ⇒ Struct └─ :vector_int32 ⇒ Vector footer: cluster_summaries: UnROOT.ClusterSummary[ClusterSummary(num_first_entry=0, num_entries=5)] julia> LazyTree(f, "ntuple") Row │ string vector_int32 array_float vector_vector_i vector_string vector_vector_s variant_int32_s vector_variant_ ⋯ │ String Vector{Int32} StaticArraysCor Vector{Vector{I Vector{String} Vector{Vector{S Union{Int32, St Vector{Union{In ⋯ ─────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── 1 │ one [1] [1.0, 1.0, 1.0] Vector{Int32}[Int3 ["one"] [["one"]] 1 Union{Int64, Strin ⋯ 2 │ two [1, 2] [2.0, 2.0, 2.0] Vector{Int32}[Int3 ["one", "two"] [["one"], ["two"]] two Union{Int64, Strin ⋯ 3 │ three [1, 2, 3] [3.0, 3.0, 3.0] Vector{Int32}[Int3 ["one", "two", "th [["one"], ["two"], three Union{Int64, Strin ⋯ 4 │ four [1, 2, 3, 4] [4.0, 4.0, 4.0] Vector{Int32}[Int3 ["one", "two", "th [["one"], ["two"], 4 Union{Int64, Strin ⋯ 5 │ five [1, 2, 3, 4, 5] [5.0, 5.0, 5.0] Vector{Int32}[Int3 ["one", "two", "th [["one"], ["two"], 5 Union{Int64, Strin ⋯ 5 columns omitted ```

LazyTree as unified table / iteration interface

You can iterate through a LazyTree: ```julia julia> for event in mytree @show event.Electrondxy break end event.Electrondxy = Float32[0.00037050247]

julia> Threads.@threads :static for event in mytree # multi-threading ... end ```

Only one basket per branch will be cached so you don't have to worry about running out of RAM. At the same time, event inside the for-loop is not materialized until a field is accessed. This means you should avoid double-access, see performance tips

XRootD is also supported, depending on the protocol: - the "url" has to start with http:// or https://: - (1.6+ only) or the "url" has to start with root:// and have another // to separate server and file path ```julia julia> r = ROOTFile("https://scikit-hep.org/uproot3/examples/Zmumu.root") ROOTFile with 1 entry and 18 streamers. https://scikit-hep.org/uproot3/examples/Zmumu.root └─ events (TTree) ├─ "Type" ├─ "Run" ├─ "Event" ├─ "⋮" ├─ "phi2" ├─ "Q2" └─ "M"

julia> r = ROOTFile("root://eospublic.cern.ch//eos/root-eos/cmsopendata2012nanoaod/Run2012BDoubleMuParked.root") ROOTFile with 1 entry and 19 streamers. root://eospublic.cern.ch//eos/root-eos/cmsopendata2012nanoaod/Run2012BDoubleMuParked.root └─ Events (TTree) ├─ "run" ├─ "luminosityBlock" ├─ "event" ├─ "⋮" ├─ "ElectrondxyErr" ├─ "Electrondz" └─ "Electron_dzErr"

```

TBranch of custom struct

We provide an experimental interface for hooking up UnROOT with your custom types that only takes 2 steps, as explained in the docs. As a show case for this functionality, the TLorentzVector support in UnROOT is implemented with the said plug-in system.

Support & Contributiing

Use Github issues for any bug reporting or feature request; feel free to make PRs, bug fixing, feature tuning, quality of life, docs, examples etc.
See CONTRIBUTING.md for more information and recommended workflows in contributing to this package.

Acknowledgements

Special thanks to Jim Pivarski (@jpivarski) from the Scikit-HEP project, who is the main author of uproot, a native Python library to read and write ROOT files, which was and is a great source of inspiration and information for reverse engineering the ROOT binary structures.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

_{Tamas Gal} 💻 📖 🚇 🔣 ⚠️	_{Jerry Ling} 💻 ⚠️ 🔣 📖	_{Johannes Schumann} 💻 ⚠️ 🔣	_{Nick Amin} 💻 ⚠️ 🔣	_{Mosè Giordano} 🚇	_{Oliver Schulz} 🤔	_{Misha Mikhasenko} 🔣
_{Yuan-Ru Lin} ⚠️

This project follows the all-contributors specification. Contributions of any kind welcome!

Owner

Name: JuliaHEP
Login: JuliaHEP
Kind: organization

Repositories: 18
Profile: https://github.com/JuliaHEP

JOSS Publication

UnROOT: an I/O library for the CERN ROOT file format written in Julia

Published

August 18, 2022

DOI

10.21105/joss.04452

Volume 7, Issue 76, Page 4452

Authors

Tamás Gál

Erlangen Centre for Astroparticle Physics, Friedrich-Alexander-Universität Erlangen-Nürnberg

Jerry (Jiahong) Ling

Harvard University

Nick Amin

University of California, Santa Barbara

Editor

Daniel S. Katz

Citation (CITATION.bib)

@article{
    UnROOT-2022,
    doi = {10.21105/joss.04452},
    url = {https://doi.org/10.21105/joss.04452},
    year = {2022},
    publisher = {The Open Journal},
    volume = {7},
    number = {76},
    pages = {4452},
    author = {Tamás Gál and Jerry (Jiahong) Ling and Nick Amin},
    title = {UnROOT: an I/O library for the CERN ROOT file format written in Julia},
    journal = {Journal of Open Source Software}
}

GitHub Events

Total

Create event: 23
Commit comment event: 10
Release event: 5
Issues event: 18
Watch event: 12
Delete event: 17
Issue comment event: 65
Push event: 108
Pull request review event: 4
Pull request review comment event: 3
Pull request event: 25
Fork event: 2

Last Year

Create event: 23
Commit comment event: 10
Release event: 5
Issues event: 18
Watch event: 12
Delete event: 17
Issue comment event: 65
Push event: 108
Pull request review event: 4
Pull request review comment event: 3
Pull request event: 25
Fork event: 2

Committers

Last synced: 7 months ago

All Time

Total Commits: 612
Total Committers: 15
Avg Commits per committer: 40.8
Development Distribution Score (DDS): 0.57

Past Year

Commits: 48
Committers: 4
Avg Commits per committer: 12.0
Development Distribution Score (DDS): 0.229

Top Committers

Name	Email	Commits
Tamas Gal	t**l@k**e	263
Jerry Ling	p**n@j**v	260
Nick Amin	a**j@g**m	49
allcontributors[bot]	4****]	11
Johannes Schumann	j**n@f**e	10
Oliver Schulz	o**z@m**e	5
CompatHelper Julia	c**y@j**g	4
Pere Mato	p****o	2
Yuan-Ru Lin	y**n@g**m	2
Daniel S. Katz	d**z@i**g	1
Frank Gaede	g**e@d**e	1
Mosè Giordano	m**e@g**g	1
Philippe Gras	p**s@c**h	1
dependabot[bot]	4****]	1
github-actions[bot]	4****]	1

Committer Domains (Top 20 + Academic)

cern.ch: 1 gnu.org: 1 desy.de: 1 ieee.org: 1 julialang.org: 1 mpp.mpg.de: 1 fau.de: 1 jling.dev: 1 km3net.de: 1

Issues and Pull Requests

Last synced: 6 months ago

All Time

Total issues: 78
Total pull requests: 164
Average time to close issues: 3 months
Average time to close pull requests: 13 days
Total issue authors: 18
Total pull request authors: 14
Average comments per issue: 6.19
Average comments per pull request: 2.8
Merged pull requests: 137
Bot issues: 0
Bot pull requests: 18

Past Year

Issues: 14
Pull requests: 30
Average time to close issues: 10 days
Average time to close pull requests: 18 days
Issue authors: 7
Pull request authors: 4
Average comments per issue: 3.14
Average comments per pull request: 1.3
Merged pull requests: 22
Bot issues: 0
Bot pull requests: 9

View more stats

Top Authors

Issue Authors

Moelf (38)
tamasgal (12)
peremato (7)
Yuan-Ru-Lin (4)
aminnj (3)
jpata (2)
MarcoRiggirello (2)
oschulz (2)
JuliaTagBot (1)
TheFibonacciEffect (1)
silverweed (1)
pranphy (1)
AnthonyAportela (1)
PerilousApricot (1)
karuboniru (1)

Pull Request Authors

Moelf (112)
tamasgal (53)
github-actions[bot] (14)
dependabot[bot] (10)
Yuan-Ru-Lin (3)
grasph (2)
peremato (2)
aminnj (2)
8me (2)
oschulz (1)
allcontributors[bot] (1)
gaede (1)
danielskatz (1)
briederer (1)

Top Labels

Issue Labels

bug (10) good first issue (8) help wanted (6) performance (4) future (4) discussion (4) enhancement (3) question (3) documentation (1) wontfix (1) hacktoberfest (1) upstream (1)

Pull Request Labels

dependencies (10) performance (1) future (1)

Packages

Total packages: 1
Total downloads:
- julia 33 total

Total dependent packages: 2
Total dependent repositories: 0
Total versions: 106

juliahub.com: UnROOT

Native Julia I/O package to work with CERN ROOT files objects (TTree and RNTuple)

Homepage: https://juliahep.github.io/UnROOT.jl/
Documentation: https://docs.juliahub.com/General/UnROOT/stable/
License: MIT
Latest release: 0.10.37
published 9 months ago

Versions: 106
Dependent Packages: 2
Dependent Repositories: 0
Downloads: 33 Total

Rankings

Dependent repos count: 9.9%

Stargazers count: 10.1%

Forks count: 13.7%

Average: 14.2%

Dependent packages count: 23.0%

Last synced: 6 months ago

Dependencies

.github/workflows/CompatHelper.yml actions

julia-actions/setup-julia v1 composite

.github/workflows/TagBot.yml actions

JuliaRegistries/TagBot v1 composite

.github/workflows/ci.yml actions

actions/checkout v2 composite
codecov/codecov-action v1 composite
julia-actions/cache v1 composite
julia-actions/julia-buildpkg v1 composite
julia-actions/julia-buildpkg latest composite
julia-actions/julia-docdeploy latest composite
julia-actions/julia-processcoverage v1 composite
julia-actions/julia-runtest v1 composite
julia-actions/setup-julia v1 composite

.github/workflows/draft-pdf.yml actions

actions/checkout v2 composite
actions/upload-artifact v1 composite
openjournals/openjournals-draft-action master composite

UnROOT

Science Score: 100.0%

Keywords

Keywords from Contributors

Repository

Basic Info

Statistics

Topics

Metadata Files

README.md

Important API changes in v0.9.0

Installation Guide

TTree

RNTuple

LazyTree as unified table / iteration interface

TBranch of custom struct

Support & Contributiing

Acknowledgements

Contributors ✨

Owner

JOSS Publication

UnROOT: an I/O library for the CERN ROOT file format written in Julia

Authors

Editor

Tags

Citation (CITATION.bib)

GitHub Events

Total

Last Year

Committers

All Time

Past Year

Top Committers

Committer Domains (Top 20 + Academic)

Issues and Pull Requests

All Time

Past Year

Top Authors

Issue Authors

Pull Request Authors

Top Labels

Issue Labels

Pull Request Labels

Packages

juliahub.com: UnROOT

Rankings

Dependencies