uproot-custom 2.2.0

uproot extension for reading custom classes

Introduction

Uproot-custom is an extension of Uproot that provides an enhanced way to read custom classes stored in TTree.

What uproot-custom can do

Uproot-custom can natively read complicated combinations of nested classes and c-style arrays (e.g. map<int, map<int, map<int, string>>>, vector<TString>[3], etc), and memberwisely stored classes. It also exposes a way for users to implement their own readers for custom classes that are not supported by Uproot or uproot-custom built-in readers, so that users can read their custom classes seamlessly.

When to use uproot-custom

Uproot-custom aims to handle cases that classes are too complex for Uproot to read, such as when their Streamer methods are overridden or some specific data members are not supported by Uproot.

How uproot-custom works

Uproot-custom uses a reader/factory mechanism to read classes:

flowchart TD
    subgraph py["Python field"]
        direction TB
        AsCustom --> fac["Factory (Primitive, STLVector, TString, ...)"]
        fac["Factory (Primitive, STLVector, TString, ...)"] -- Optional --> form(["construct awkward forms"])
        fac --> build_reader(["build corresponding C++ reader"])
        fac --> build_ak(["construct awkward arrays"])
    end

    user_fac["User's Factory"] -. Register .-> fac

    subgraph cpp["C++ field"]
        direction TB
        build_reader --> reader["C++ Reader"]
        reader --> read_bin(["read binary data"])
        read_bin --> ret_data(["return data"])
    end

    ret_data --> raw_data[("tuple, list, numpy arrays, ...")]
    raw_data --> build_ak

• reader is a C++ class that implements the logic to read data from binary buffers.
• factory is a Python class that creates, combines readers, and post-processes the data read by readers.

This machanism is implemented basing on uproot_custom.AsCustom interpretation. This makes uproot-custom well compatible with Uproot.

[!TIP] Users can implement their own factory and reader, register them to uproot-custom. An example of implementing a custom factory/reader can be found in the example repository.

[!NOTE] Uproot-custom does not provide a full reimplementation of ROOT's I/O system. Users are expected to implement their own factory/reader for their custom classes that built-in factories cannot handle.

Documentation

View the documentation for more details about customizing your own reader/factory, the architecture of uproot-custom, and build-only dependencies (e.g., pybind11 is needed only at build time and should not be present in the runtime environment).