Uproot Raw¶

Uproot-Raw queries call TTree.arrays() with configurable arguments and return the result. Multiple subqueries can be bundled into one request; ROOT objects can also be copied from the input file.

A query is a list of dictionaries. Each dictionary is either a query dictionary (contains treename) or a copy dictionary (contains copy_histograms).

query = [
         {
          'treename': 'reco',
          'filter_name': ['/mu.*/', 'runNumber', 'lbn', 'jet_pt_*'],
          'cut':'(count_nonzero(jet_pt_NOSYS>40e3)>=4)'
         },
         {
          'copy_histograms': ['CutBookkeeper*', '/cflow.*/', 'metadata', 'listOfSystematics']
         }
        ]

Query Dictionaries¶

treename : A string, list of strings, or dictionary. Selects the tree(s) to query. When a dictionary is provided, keys select input trees and values set the output tree name — allowing multiple queries on the same tree with distinct outputs.

expressions, cut, filter_name, aliases : Same meaning as in TTree.arrays(), except functions are not permitted (globs and regular expressions are allowed). Uproot-Raw extends the expression language with many Awkward Array functions. See the axis warning below.

fail_on_missing_trees : If True, the transformation fails when a requested tree is absent from any input file. By default, missing trees are silently ignored.

use_standard_awkward_axis : If True, disables the axis overrides described below, making expressions fully compatible with Awkward Array at the cost of potentially counterintuitive behavior in particle physics expressions.

Other keys are ignored. Most queries use filter_name to select branches and cut to filter rows. expressions computes new values from branches; aliases provides shorthand for complex expressions.

Warning

By default, Uproot-Raw redefines the axis argument of several Awkward Array functions from axis=0 to axis=1. This is because axis=0 evaluates across all events (rows) at once, whereas axis=1 evaluates within each event — which is almost always the intended behavior in particle physics cuts.

For example, any(jet_pt>50) in Uproot-Raw selects events where at least one jet exceeds 50. With the standard awkward definition (axis=0), it returns a scalar and causes an array shape mismatch error.

Explicit axis arguments in expressions override this default. Setting use_standard_awkward_axis to True restores the original awkward behavior.

Modified functions: concatenate, count, count_nonzero, sum, nansum, prod, nanprod, any, all, min, nanmin, max, nanmax, argmin, nanargmin, argmax, nanargmax, moment, mean, nanmedian, var, nanvar, std, nanstd, softmax. flatten defaults to axis=2.

Copy Dictionaries¶

copy_histograms : A string or list of strings passed to uproot.ReadOnlyDirectory.items() as filter_name. Accepts exact names (e.g. metadata), globs (e.g. CutBookkeeper*), or regular expressions (e.g. /cflow.*/). Objects other than histograms — such as TGraphs — can also be copied. At most one copy dictionary is typically needed per request.

Warning

Uproot-Raw supports parquet output, but with limitations: ROOT objects cannot be copied to parquet, and multiple output trees are supported only by concatenating them with an added treename column indicating the original tree name. All concatenated trees must have exactly the same structure.

API Reference¶

UprootRawQuery¶

class servicex.uproot_raw.uproot_raw.UprootRawQuery(query: List[TreeSubQuery | CopyHistogramSubQuery] | TreeSubQuery | CopyHistogramSubQuery, default_codegen: str = 'uproot-raw')[source]

generate_selection_string()[source]: override with the selection string to send to ServiceX

TreeSubQuery¶

Express an uproot-raw query on an ntuple. Arguments have the same meaning as the ones of the same name for uproot.arrays(): https://uproot.readthedocs.io/en/stable/uproot.behaviors.TBranch.HasBranches.html#uproot-behaviors-tbranch-hasbranches-arrays

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

field aliases: Mapping[str, str] | None = None: Define aliases to use in computation and expressions

field cut: str | None = None: Awkward Array expressions to select passing rows

field expressions: str | List[str] | None = None: Awkward Array expressions to evaluate for output

field fail_on_missing_trees: bool | None = None: Make queries fail if input trees are missing (default False)

field filter_name: str | List[str] | None = None: Expression to filter the list of considered input variables by name

field filter_typename: str | List[str] | None = None: Expression to filter the list of considered input variables by type name

model_config: ClassVar[ConfigDict] = {'use_attribute_docstrings': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

field treename: Mapping[str, str] | List[str] | str [Required]: Name of input ntuple in file

field use_standard_awkward_axis: bool | None = None: Do not override standard axis default arguments in awkward expressions (default False)

CopyHistogramSubQuery¶

class servicex.uproot_raw.uproot_raw.CopyHistogramSubQuery(*, copy_histograms: List[str] | str)[source]

Request the copying of a ROOT object from the input file to the output.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

field copy_histograms: List[str] | str [Required]: Objects to copy

model_config: ClassVar[ConfigDict] = {'use_attribute_docstrings': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].