uproot.concatenate

Defined in uproot.behaviors.TBranch on line 268.

uproot.behaviors.TBranch.concatenate(files, expressions=None, cut=None, *, filter_name=<function no_filter>, filter_typename=<function no_filter>, filter_branch=<function no_filter>, filter_field=<function no_filter>, aliases=None, language=uproot.language.python.PythonLanguage(), entry_start=None, entry_stop=None, decompression_executor=None, interpretation_executor=None, library='ak', ak_add_doc=False, how=None, custom_classes=None, allow_missing=False, **options)
Parameters:

  • files – See below.

  • expressions (None, str, or list of str) – Names of TBranches or aliases to convert to arrays or mathematical expressions of them. Uses the language to evaluate. If None, all TBranches selected by the filters are included.

  • cut (None or str) – If not None, this expression filters all of the expressions.

  • filter_name (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select TBranches by name.

  • filter_typename (None, glob string, regex string in "/pattern/i" syntax, function of str → bool, or iterable of the above) – A filter to select TBranches by type.

  • filter_branch (None or function of uproot.TBranch → bool, uproot.interpretation.Interpretation, or None) – A filter to select TBranches using the full uproot.TBranch object. If the function returns False or None, the TBranch is excluded; if the function returns True, it is included with its standard interpretation; if an uproot.interpretation.Interpretation, this interpretation overrules the standard one. Only used for TTrees.

  • filter_field (None or function of uproot.models.RNTuple.RField → bool, or None) – A filter to select RFields using the full uproot.models.RNTuple.RField object. If the function returns False or None, the RField is excluded; if the function returns True, it is included. Only used for RNTuples.

  • aliases (None or dict of str → str) – Mathematical expressions that can be used in expressions or other aliases (without cycles). Uses the language engine to evaluate. If None, only the aliases are available.

  • language (uproot.language.Language) – Language used to interpret the expressions and aliases.

  • entry_start (None or int) – The first entry to include. If None, start at zero. If negative, count from the end, like a Python slice.

  • entry_stop (None or int) – The first entry to exclude (i.e. one greater than the last entry to include). If None, stop at num_entries. If negative, count from the end, like a Python slice.

  • decompression_executor (None or Executor with a submit method) – The executor that is used to decompress TBaskets; if None, a uproot.TrivialExecutor is created.

  • interpretation_executor (None or Executor with a submit method) – The executor that is used to interpret uncompressed TBasket data as arrays; if None, a uproot.TrivialExecutor is created.

  • library (str or uproot.interpretation.library.Library) – The library that is used to represent arrays. Options are "np" for NumPy, "ak" for Awkward Array, and "pd" for Pandas.

  • ak_add_doc (bool | dict) – If True and library="ak", add the TBranch title to the Awkward __doc__ parameter of the array. if dict = {key:value} and library="ak", add the TBranch value to the Awkward key parameter of the array.

  • how (None, str, or container type) – Library-dependent instructions for grouping. The only recognized container types are tuple, list, and dict. Note that the container type itself must be passed as how, not an instance of that type (i.e. how=tuple, not how=()). For library="ak", passing how="zip" applies ak.zip to interleave data from compatible branches.

  • custom_classes (None or dict) – If a dict, override the classes from the uproot.ReadOnlyFile or uproot.classes.

  • allow_missing (bool) – If True, skip over any files that do not contain the specified TTree.

  • options – See below.

Returns an array with data from a set of files concatenated into one.

For example:

>>> array = uproot.concatenate("files*.root:tree", ["x", "y"])

Depending on the number of files, the number of selected TBranches, and the size of your computer’s memory, this function might not have enough memory to run.

Allowed types for the files parameter:

  • str/bytes: relative or absolute filesystem path or URL, without any colons other than Windows drive letter or URL schema. Examples: "rel/file.root", "C:\abs\file.root", "http://where/what.root"

  • str/bytes: same with an object-within-ROOT path, separated by a colon. Example: "rel/file.root:tdirectory/ttree"

  • pathlib.Path: always interpreted as a filesystem path or URL only (no object-within-ROOT path), regardless of whether there are any colons. Examples: Path("rel:/file.root"), Path("/abs/path:stuff.root")

  • glob syntax in str/bytes and pathlib.Path. Examples: Path("rel/*.root"), "/abs/*.root:tdirectory/ttree"

  • dict: keys are filesystem paths, values are objects-within-ROOT paths. Example: {{"/data_v1/*.root": "ttree_v1", "/data_v2/*.root": "ttree_v2"}}

  • already-open TTree objects.

  • iterables of the above.

Options (type; default):

  • handler (uproot.source.chunk.Source class; None): Class implementing reading from the data source. If None, deduced from input file type.

  • timeout (float for HTTP, int for XRootD; default defined by source implementation): The time in seconds to wait before giving up on the connection. Ignored for non-internet sources like local file paths.

  • max_num_elements (None or int; None): The maximum number of byte ranges requested in a single XRootD vector read. This does not limit the number of TTree or RNTuple entries read; pass entry_stop to arrays, uproot.iterate, or uproot.concatenate instead.

  • num_workers (int; 1): Number of tasks to spawn for reading, only used by some source types

  • use_threads (bool; False on the emscripten platform (i.e. in a web browser), else True): Use multi-threading when spawning workers.

  • num_fallback_workers (int; 10): Number of tasks to spawn for reading in fallback mode (for example, multi-threading requests instead of a multipart GET for an http source)

  • begin_chunk_size (memory_size; 403, the smallest a ROOT file can be): Size of first chunk that we attempt to read in bytes.

  • minimal_ttree_metadata (bool; True): Skip rarely used metadata and defer reading of embedded TBaskets

  • http_max_header_bytes (int; 21784): Maximum size of HTTP packet in bytes when the source is http

Other file entry points:

  • uproot.open: opens one file to read any of its objects.

  • uproot.iterate: iterates through chunks of contiguous entries in TTrees.

  • uproot.concatenate (this function): returns a single concatenated array from TTrees.

  • uproot.dask: returns an unevaluated Dask array from TTrees.