Uproot

Uproot uses two internal caches to streamline interactive use and improve performance:

1. object_cache: Stores objects like TDirectories, histograms, and TTrees. This allows repeated access to the same object via different names or paths without re-instantiating it.
2. array_cache: Stores array outputs (up to a maximum number of bytes). It relies on the array having an nbytes or memory_usage attribute (supported by NumPy, Awkward Array, and Pandas).

Default Settings:

• object_cache: 100 objects.
• array_cache: 100 MB.

Customization: You can override these by passing object_cache or array_cache arguments to uproot.open() or by setting the object_cache and array_cache properties on the ReadOnlyFile object. To disable caching, set these to None. Any MutableMapping (like a standard dict) can be used as a cache.

# Example of object cache behavior
file = uproot.open("https://scikit-hep.org/uproot3/examples/hepdata-example.root")
histogram = file["hpx"]
# Both references point to the exact same object in memory
print(histogram, file["hpx"])

The object returned by uproot.open represents a ReadOnlyDirectory (the root directory /). This object behaves like a Python Mapping (dictionary-like).

Listing contents

Use .keys() to see the available objects and paths in the file.

Accessing objects

Use square brackets [] to extract objects. You can access nested objects using slashes (/) or by chaining brackets. Note that objects are not read from disk until they are explicitly requested via square brackets or mapping methods like .values() or .items().

Cycle numbers (e.g., ;1) can be included in the key or omitted.

Inspecting class names

To see the class types of objects without actually reading the data from disk, use .classnames().

Shortcut: Open a specific object directly

You can jump straight to a specific object by appending a colon (:) followed by the object path to the file path string.

Note: If your filename contains a colon, wrap the path in a pathlib.Path object to avoid ambiguity.

import uproot

# Open a file
file = uproot.open("https://scikit-hep.org/uproot3/examples/nesteddirs.root")

# List keys
print(file.keys())
# Output: ['one;1', 'one/two;1', 'one/two/tree;1', 'one/tree;1', 'three;1', 'three/tree;1']

# Access nested objects
dir = file["one"]
dir_two = file["one/two"]
tree = file["one/two/tree"]

# Get class names without reading data
print(file.classnames())

# Shortcut: Open a specific TTree directly
events = uproot.open("https://scikit-hep.org/uproot3/examples/Zmumu.root:events")

The Reader interface acts as a node in a 'data tree' that mirrors the structure of an awkward array. The process of converting custom classes to awkward.Array follows five distinct procedures:

1. Tree Configuration Generation (Python): Recursively traverses streamer information to create a nested dict (the 'tree configuration') describing the structure. Each node in the dict contains a reader type, a name, and necessary metadata (like ctype for CTypeReader or sub_readers for ObjectReader).
2. Reader Tree Building (Python): Instantiates a tree of Reader objects based on the configuration. Children readers are instantiated first and passed to parent readers.
3. Data Reading (C++): A BinaryParser is used to read data from the binary stream. The root reader's read method is called for every event, recursively calling children readers.
4. Raw Data Retrieval (C++): The get_data method is called on the root reader. Leaf readers return numpy arrays; internal/wrapper readers return tuples packaging their own data with their children's data.
5. Array Reconstruction (Python): The reconstruct_array method uses the original tree configuration and the retrieved raw data to build the final awkward.Array. It uses operations like awkward.unflatten (for sequences) or awkward.zip (for objects) to reconstruct the structure.

---
title: How Reader Works
---

flowchart TD
  Z[(All Streamers Information)] -.-> A[Tree Configuration Generating]
    A --> B[(Tree Configuration)]
    A --> C[Reader Tree Building]
    B -.-> C
    C --> D[Data Reading]
    D --> E[Get Raw Data]
    E --> F[Array Reconstruction]
    E --> G[(Raw Data)]
     F -.-> H[(awkward.Array)]
    G -.-> F
    B -.-> F

Both TTree and TBranch objects implement the Mapping protocol. You can navigate the hierarchy using standard dictionary-like methods:

• .keys(): Returns branch names.
• .values(): Returns branch objects.
• .items(): Returns (name, branch) pairs.
• .typenames(recursive=True, ...): Returns a mapping of branch names to their C++ type strings.

Filtering options for .keys(), .values(), .items(), and .typenames():

• recursive=True (default): Searches directories recursively.
• filter_name: Select branches by name using a string, glob, regex (e.g., "/pattern/i"), or a function str -> bool.
• filter_typename: Select branches by their C++ type using the same options as filter_name.
• filter_branch: Select branches using a function TBranch -> bool (e.g., to filter by compression_ratio).

>>> tree.keys()
['evt', 'evt/Beg', 'evt/I16', ...]
>>> tree["evt"].keys()
['Beg', 'I16', 'I32', ...]

# Filtering examples
>>> events.keys(filter_name="px*")
['px1', 'px2']
>>> events.keys(filter_name="/p[xyz][0-9]/i")
['px1', 'py1', 'pz1', ...]
>>> events.keys(filter_branch=lambda b: b.compression_ratio > 10)
['Run', 'Q1', 'Q2']

A TTree in Uproot behaves like a Mapping, where keys are TBranch names and values are TBranch objects. Since branches can be nested, both TTree and TBranch inherit from HasBranches.

To inspect the structure of a TTree without reading data:

• Use .keys() to see available branch names.
• Use .values() to see the TBranch objects.
• Use .typenames() to see the data types of each branch.
• Use .show() for a human-readable summary of names, types, and how the data is interpreted (e.g., how it maps to arrays).

>>> events = uproot.open("https://scikit-hep.org/uproot3/examples/Zmumu.root:events")
>>> events.keys()
['Type', 'Run', 'Event', 'E1', 'px1', 'py1', 'pz1', 'pt1', 'eta1', 'phi1', 'Q1', 'E2', 'px2', 'py2', 'pz2', 'pt2', 'eta2', 'phi2', 'Q2', 'M']
>>> events.typenames()
{'Type': 'char*', 'Run': 'int32_t', 'Event': 'int32_t', 'E1': 'double', ...}
>>> events.show()
name                 | typename                 | interpretation
---------------------+--------------------------+-------------------------------
Type                 | char*                    | AsStrings()
Run                  | int32_t                   | AsDtype('>i4')
...