uproot.graphed

Defined in uproot._graphed on line 306.

uproot._graphed.graphed(files, *, filter_name=<function no_filter>, filter_typename=<function no_filter>, filter_branch=<function no_filter>, recursive=True, full_paths=False, library='ak', ak_add_doc=False, custom_classes=None, allow_missing=False, behavior=None, form_mapping=None, known_base_form=None, backend=None, decompression_executor=None, interpretation_executor=None, align_baskets=False, **options)
Parameters:
  • files – The TTree``(s) to read, in any form accepted by :doc:`uproot._dask.dask` (a path with ``"file.root:tree", a list, a dict, an open TTree, a dict entry with explicit "steps"; a single-TTree file needs no object path).

  • filter_name – TBranch selection, as in uproot.dask.

  • filter_typename – TBranch selection, as in uproot.dask.

  • filter_branch – TBranch selection, as in uproot.dask.

  • recursive – TBranch selection, as in uproot.dask.

  • full_paths – TBranch selection, as in uproot.dask.

  • library (str) – Only "ak" is supported (a single deferred graphed array). "np" and "pd" raise NotImplementedError.

  • ak_add_doc – As in uproot.dask.

  • custom_classes – As in uproot.dask.

  • allow_missing – As in uproot.dask.

  • behavior (dict or None) – An awkward behavior dict (e.g. vector’s) registered on the recording backend, for the default backend and the unmapped form: with gak.with_name, behavior PROPERTIES (.pt, .mass) work through plain attribute access — typetracer forms at record time, projectable down to exactly the branches a property reads.

  • form_mapping (ImplementsFormMapping or None) – The mapping uproot.dask takes — it restructures the flat TTree form into the one the user sees (coffea’s NanoEventsFactory is the archetype) and fills that form’s buffers from the file. The recorded array then has the MAPPED form and the mapping info’s behavior is registered on the backend. Without one, TrivialFormMapping reads the file’s form.

  • known_base_form (awkward.forms.Form | None) – If not none use this form instead of opening one file to determine the dataset’s form, as in uproot.dask. No file is opened at all; the TTree’s name then comes from the object path in files.

  • backend (graphed Backend or None) – The graphed backend instance the session records on, in place of the default graphed.awkward.AwkwardBackend — the route for a caller’s own Array subclass. Its behavior (and, with form_mapping, the mapping info’s) is then the caller’s business, so behavior= is refused beside it.

  • decompression_executor – As in uproot.dask; every partition read uses them.

  • interpretation_executor – As in uproot.dask; every partition read uses them.

  • align_baskets (bool) – If True, each blind partition’s entry range moves, when it is read, to the nearest TBasket boundaries shared by the TBranches it reads, so no TBasket is decompressed by two partitions. The partition count is unchanged; a partition can come out empty. Incompatible with explicit "steps"; TTrees only.

  • options – Passed through to file opening.

Returns a deferred graphed Array for the selected TTree``(s). Construction reads only metadata; running the recorded analysis (``graphed.aggregate_plan, graphed.awkward.to_parquet, uproot.graphed_write) triggers the read, partition by partition, fetching only the TBranches the recorded graph touches.

Partitioning is decided where a plan is built (steps_per_file= there), not here, so step_size, steps_per_file and open_files are refused by name; align_baskets= decides that the boundaries follow TBaskets. For one task per TBasket-sparse file, pass partitions=uproot._graphed.graphed_partitions(..., align_baskets=True) where the plan is built.

Experimental: tracks a pre-1.0 graphed; the API may change without a deprecation cycle.

This is the graphed analogue of uproot.dask.