uproot.concatenate — Uproot documentation

# uproot.concatenate

Defined in uproot.behaviors.TBranch on line 234.

uproot.behaviors.TBranch.concatenate(files, expressions=None, cut=None, *, filter_name=<function no_filter>, filter_typename=<function no_filter>, filter_branch=<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.

    - 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=()`).

    - 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)

  - timeout (float for HTTP, int for XRootD; 30)

  - max_num_elements (None or int; None)

  - num_workers (int; 1)

  - use_threads (bool; False on the emscripten platform (i.e. in a web browser), else True)

  - num_fallback_workers (int; 10)

  - begin_chunk_size (memory_size; 403, the smallest a ROOT file can be)

  - minimal_ttree_metadata (bool; True)

  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`.