Opening files

Unlike ROOT, uproot strongly assumes that the input file does not change while you read it. File Sources do not lock the file, and they may open, close, and reopen it as needed to read the file in parallel. Therefore, if another process is changing the contents of a file while uproot reads it, the behavior is undefined (but likely bad!).

uproot.open

All ROOT objects come from ROOT files, so open is probably the first function you’ll call. The ROOTDirectory object it returns is a handle for accessing contents deeper within the file.

uproot.rootio.open(path, localsource=<function defaults>, xrootdsource=<function defaults>, httpsource=<function defaults>, **options)

Opens a ROOT file (local or remote), specified by file path.

Parameters:
  • path (str) – local file path or URL specifying the location of a file (note: not a Python file object!). If the URL schema is “root://”, xrootd will be called.
  • localsource (function: path ⇒ Source <uproot.source.source.Source> or ``dict` of keyword arguments`) – function that will be applied to the path to produce an uproot Source object if the path is a local file. Default is MemmapSource.defaults for memory-mapped files. If a dict, the dict is passed as keyword arguments to MemmapSource constructor.
  • xrootdsource (function: path ⇒ Source <uproot.source.source.Source> or ``dict` of keyword arguments`) – function that will be applied to the path to produce an uproot Source object if the path is an XRootD URL. Default is XRootDSource.defaults for XRootD with default chunk size/caching. (See XRootDSource constructor for details.) If a dict, the dict is passed as keyword arguments to XRootDSource constructor.
  • **options – passed to ROOTDirectory constructor.
Returns:

top-level directory of the ROOT file.

Return type:

ROOTDirectory

Notes

The ROOTDirectory returned by this function is not necessarily an open file. File handles are managed internally by Source objects to permit parallel reading. Although this function can be used in a with construct (which protects against unclosed files), the with construct has no meaning when applied to this function. Files will be opened or closed as needed to read data on demand.

uproot.xrootd

Although open opens files regardless of whether they’re local or remote, you can explicitly invoke XRootD with xrootd. You get the same kind of ROOTDirectory as from open.

uproot.rootio.xrootd(path, xrootdsource=<function defaults>, **options)

Opens a remote ROOT file with XRootD (if installed).

Parameters:
  • path (str) – URL specifying the location of a file.
  • xrootdsource (function: path ⇒ Source <uproot.source.source.Source> or ``dict` of keyword arguments`) – function that will be applied to the path to produce an uproot Source object if the path is an XRootD URL. Default is XRootDSource.defaults for XRootD with default chunk size/caching. (See XRootDSource constructor for details.) If a dict, the dict is passed as keyword arguments to XRootDSource constructor.
  • **options – passed to ROOTDirectory constructor.
Returns:

top-level directory of the ROOT file.

Return type:

ROOTDirectory

uproot.iterate

With a ROOTDirectory, you can dig into a file and extract objects, subdirectories, or TTree data, but sometimes you know exactly where to find a TTree and have a collection of identically-typed files to iterate through.

The iterate function gives you an iterator over groups of arrays just like TreeMethods.iterate, except that it iterates over a large set of files (and verifies that the selected TTree branches are compatible). This serves essentially the same function as ROOT’s TChain, allowing you to use TTrees in a set of files the same way you would use a single TTree.

uproot.tree.iterate(path, treepath, branches=None, entrysteps=None, outputtype=<type 'dict'>, namedecode=None, reportentries=False, flatten=False, cache=None, basketcache=None, keycache=None, executor=None, blocking=True, localsource=<function defaults>, xrootdsource=<function defaults>, httpsource=<function defaults>, **options)

Opens a series of ROOT files (local or remote), yielding the same number of entries from all selected branches in each step.

Depending on the “entrysteps” parameter, the number of entries in one step may differ from the number of entries in the next step, but in every step, the same number of entries is retrieved from all baskets.

All but the first two parameters are identical to uproot.tree.TreeMethods.iterate.

Parameters:
  • path (str or list of str) – glob pattern(s) for local file paths (POSIX wildcards like “*”) or URLs specifying the locations of the files. A list of filenames are processed in the given order, but glob patterns get pre-sorted to ensure a predictable order.
  • treepath (str) – path within each ROOT file to find the TTree (may include “/” for subdirectories or “;” for cycle numbers).
  • branches
    • if None (default), select all interpretable branches;
    • if a function TBranchMethodsNone or Interpretation, select branches for which the function does not return None and use the interpretation it returns otherwise;
    • if a dict of str → Interpretation, select branches named by keys and use interpretations from the associated values;
    • if a list of str, select branches by name;
    • if a single str, select a single branch. The selection by string can include filename-like glob characters (*, ?, [...]) or it can be a full regular expression (Python flavored) if surrounded by slashes, like /pattern/i (where i is an optional Python re flag).
  • entrysteps (None, positive int, or iterable of (int, int) pairs) – if None (default), iterate in steps of TTree clusters (number of entries for which all branches’ baskets align); if an integer, iterate in steps of equal numbers of entries (except at the end of a file); otherwise, iterate in explicit, user-specified (start, stop) intervals (“start” is inclusive and “stop” is exclusive).
  • outputtype (type) – constructor for the desired yield type, such as dict (default), OrderedDict, tuple, namedtuple, custom user class, etc.
  • namedecode (None or str) – if None (default) return names as uninterpreted byte strings (type bytes in Python 3); if a string like "ascii" or "utf-8", decode bytes to a string using the specified encoding.
  • reportentries (bool) – if False (default), yield only arrays (as outputtype); otherwise, yield 3-tuple: (entry start, entry stop, arrays), where entry start is inclusive and entry stop is exclusive.
  • flatten (bool) – if True (not default), convert JaggedArrays into flat Numpy arrays.
  • cache (None or dict-like object) – if not None (default), fully interpreted arrays will be saved in the dict-like object for later use. Accessing the same arrays with a different interpretation or a different entry range results in a cache miss.
  • basketcache (None or dict-like object) – if not None (default), raw basket data will be saved in the dict-like object for later use. Accessing the same arrays with a different interpretation or a different entry range fully utilizes this cache, since the interpretation/construction from baskets is performed after retrieving data from this cache.
  • keycache (None or dict-like object) – if not None (default), basket TKeys will be saved in the dict-like object for later use. TKeys are small, but require file access, so caching them can speed up repeated access.
  • executor (concurrent.futures.Executor) – if not None (default), parallelize basket-reading and decompression by scheduling tasks on the executor. Assumes caches are thread-safe.
  • blocking (bool) – if True (default), do not exit this function until the arrays are read, and return those arrays. If False, exit immediately and return a zero-argument function. That zero-argument function returns the desired array, and it blocks until the array is available. This option is only useful with a non-None executor.
  • localsource (function: path ⇒ Source <uproot.source.source.Source> or ``dict` of keyword arguments`) – function that will be applied to the path to produce an uproot Source object if the path is a local file. Default is MemmapSource.defaults for memory-mapped files. If a dict, the dict is passed as keyword arguments to MemmapSource constructor.
  • xrootdsource (function: path ⇒ Source <uproot.source.source.Source> or ``dict` of keyword arguments`) – function that will be applied to the path to produce an uproot Source object if the path is an XRootD URL. Default is XRootDSource.defaults for XRootD with default chunk size/caching. (See XRootDSource constructor for details.) If a dict, the dict is passed as keyword arguments to XRootDSource constructor.
  • **options – passed to ROOTDirectory constructor.
Returns:

aligned array segments from the files.

Return type:

iterator over (int, int, outputtype) (if reportentries) or just outputtype (otherwise)