uproot.WritableDirectory — Uproot documentation

# uproot.WritableDirectory

Defined in uproot.writing.writable on line 454.

Inheritance order:
`collections.abc.MutableMapping` `collections.abc.Mapping` `collections.abc.Collection` `collections.abc.Sized` `collections.abc.Iterable` `collections.abc.Container`

class uproot.writing.writable.WritableDirectory(path, file, cascading)
  Parameters:

    - path (tuple of str) – Path of directory names to this subdirectory; `()` for the root (first) directory.

    - file (uproot.WritableFile) – Handle to the file in which this directory can be found.

    - cascading (uproot.writing._cascade.CascadingDirectory) – The low-level directory object.

  Represents a writable `TDirectory` from a ROOT file.

  Be careful not to confuse uproot.WritableFile and uproot.WritableDirectory: files are for modifying global information such as the TStreamerInfo and FreeSegments, whereas directories are for data in local hierarchies.

  A uproot.WritableDirectory is a Python `MutableMapping`, which uses square bracket syntax to read, write, and delete objects:

      my_directory["histogram"]
      my_directory["histogram"] = np.histogram(...)
      del my_directory["histogram"]

  Objects in ROOT files also have “cycle numbers,” which allow multiple versions of an object to exist with the same name. A cycle number may be specified after a semicolon for reading and deleting only:

      my_directory["histogram;2"]
      del my_directory["histogram;2"]

  When writing, cycle numbers are generated to avoid overwriting previous objects:

      my_directory["histogram"] = np.histogram(...)   # creates a new histogram
      my_directory["histogram"] = np.histogram(...)   # creates another histogram

  Note that this is unlike a Python `MutableMapping`, which would overwrite the object in the second assignment. However, it is the way ROOT I/O works; use `del` to remove unwanted versions of objects.

  Any types of objects that can be read from a uproot.ReadOnlyDirectory can be read from a uproot.WritableDirectory except TTrees. A TTree can only be read from a uproot.ReadOnlyDirectory if it was created in this open file handle, and then it returns a uproot.WritableTree instead of the uproot.TTree that you would get from a uproot.ReadOnlyDirectory. Readable TTrees and writable TTrees are distinct, with separate sets of features.

  Note that subdirectories can be created by assigning to path names that include slashes:

      my_directory["subdir1/subdir2/new_object"] = new_object

  Subdirectories created this way will never be empty; to make an empty directory, use mkdir.

  Similarly, non-empty TTrees can be created by assignment (see uproot.WritableTree for recognized TTree-like data), but empty TTrees require the mktree method.

## path

WritableDirectory.path

  Path of directory names to this subdirectory as a tuple of strings; e.g. `()` for the root (first) directory.

## object_path

WritableDirectory.object_path

  Path of directory names to this subdirectory as a single string, delimited by slashes.

## file_path

WritableDirectory.file_path

  Filesystem path of the open file, or None if using a file-like object.

## file

WritableDirectory.file

  Handle to the uproot.WritableDirectory in which this directory can be found.

## close

WritableDirectory.close()

  Explicitly close the file.

  (Files can also be closed with the Python `with` statement, as context managers.)

  After closing, objects cannot be read from or written to the file.

## closed

WritableDirectory.closed

  True if the file has been closed; False otherwise.

  The file may have been closed explicitly with close or implicitly in the Python `with` statement, as a context manager.

  After closing, objects cannot be read from or written to the file.

## compression

WritableDirectory.compression

  Compression algorithm and level (uproot.compression.Compression or None) for new objects added to the file.

  This property can be changed, which allows you to write different objects with different compression settings.

## keys

WritableDirectory.keys(*, recursive=True, cycle=True, filter_name=<function no_filter>, filter_classname=<function no_filter>)
  Parameters:

    - recursive (bool) – If True, descend into any nested subdirectories. If False, only return the names of objects directly accessible in this `TDirectory`.

    - cycle (bool) – If True, include the cycle numbers in those names.

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

    - filter_classname (None, glob string, regex string in `"/pattern/i"` syntax, function of str → bool, or iterable of the above) – A filter to select keys by C++ (decoded) classname.

  Returns the names of the objects in this `TDirectory` as a list of strings.

  Note that this does not read any data from the file.

## values

WritableDirectory.values(*, recursive=True, filter_name=<function no_filter>, filter_classname=<function no_filter>)
  Parameters:

    - recursive (bool) – If True, descend into any nested subdirectories. If False, only return objects directly accessible in this `TDirectory`.

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

    - filter_classname (None, glob string, regex string in `"/pattern/i"` syntax, function of str → bool, or iterable of the above) – A filter to select keys by C++ (decoded) classname.

  Returns objects in this `TDirectory` as a list of uproot.Model.

  Note that this reads all objects that are selected by `filter_name` and `filter_classname`.

## items

WritableDirectory.items(*, recursive=True, cycle=True, filter_name=<function no_filter>, filter_classname=<function no_filter>)
  Parameters:

    - recursive (bool) – If True, descend into any nested subdirectories. If False, only return (name, object) pairs directly accessible in this `TDirectory`.

    - cycle (bool) – If True, include the cycle numbers in the names.

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

    - filter_classname (None, glob string, regex string in `"/pattern/i"` syntax, function of str → bool, or iterable of the above) – A filter to select keys by C++ (decoded) classname.

  Returns (name, object) pairs for objects in this `TDirectory` as a list of 2-tuples of (str, uproot.Model).

  Note that this reads all objects that are selected by `filter_name` and `filter_classname`.

## classnames

WritableDirectory.classnames(*, recursive=True, cycle=True, filter_name=<function no_filter>, filter_classname=<function no_filter>)
  Parameters:

    - recursive (bool) – If True, descend into any nested subdirectories. If False, only return the names and classnames of objects directly accessible in this `TDirectory`.

    - cycle (bool) – If True, include the cycle numbers in the names.

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

    - filter_classname (None, glob string, regex string in `"/pattern/i"` syntax, function of str → bool, or iterable of the above) – A filter to select keys by C++ (decoded) classname.

  Returns the names and C++ (decoded) classnames of the objects in this `TDirectory` as a dict of str → str.

  Note that this does not read any data from the file.

## iterkeys

WritableDirectory.iterkeys(*, recursive=True, cycle=True, filter_name=<function no_filter>, filter_classname=<function no_filter>)
  Parameters:

    - recursive (bool) – If True, descend into any nested subdirectories. If False, only return the names of objects directly accessible in this `TDirectory`.

    - cycle (bool) – If True, include the cycle numbers in those names.

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

    - filter_classname (None, glob string, regex string in `"/pattern/i"` syntax, function of str → bool, or iterable of the above) – A filter to select keys by C++ (decoded) classname.

  Returns the names of the objects in this `TDirectory` as an iterator over strings.

  Note that this does not read any data from the file.

## itervalues

WritableDirectory.itervalues(*, recursive=True, filter_name=<function no_filter>, filter_classname=<function no_filter>)
  Parameters:

    - recursive (bool) – If True, descend into any nested subdirectories. If False, only return objects directly accessible in this `TDirectory`.

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

    - filter_classname (None, glob string, regex string in `"/pattern/i"` syntax, function of str → bool, or iterable of the above) – A filter to select keys by C++ (decoded) classname.

  Returns objects in this `TDirectory` as an iterator over uproot.Model.

  Note that this reads all objects that are selected by `filter_name` and `filter_classname`.

## iteritems

WritableDirectory.iteritems(*, recursive=True, cycle=True, filter_name=<function no_filter>, filter_classname=<function no_filter>)
  Parameters:

    - recursive (bool) – If True, descend into any nested subdirectories. If False, only return (name, object) pairs directly accessible in this `TDirectory`.

    - cycle (bool) – If True, include the cycle numbers in the names.

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

    - filter_classname (None, glob string, regex string in `"/pattern/i"` syntax, function of str → bool, or iterable of the above) – A filter to select keys by C++ (decoded) classname.

  Returns (name, object) pairs for objects in this `TDirectory` as an iterator over 2-tuples of (str, uproot.Model).

  Note that this reads all objects that are selected by `filter_name` and `filter_classname`.

## iterclassnames

WritableDirectory.iterclassnames(*, recursive=True, cycle=True, filter_name=<function no_filter>, filter_classname=<function no_filter>)
  Parameters:

    - recursive (bool) – If True, descend into any nested subdirectories. If False, only return the names and classnames of objects directly accessible in this `TDirectory`.

    - cycle (bool) – If True, include the cycle numbers in the names.

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

    - filter_classname (None, glob string, regex string in `"/pattern/i"` syntax, function of str → bool, or iterable of the above) – A filter to select keys by C++ (decoded) classname.

  Returns the names and C++ (decoded) classnames of the objects in this `TDirectory` as an iterator of 2-tuples of (str, str).

  Note that this does not read any data from the file.

## mkdir

WritableDirectory.mkdir(name, *, initial_directory_bytes=None)
  Parameters:

    - name (str) – Name of the new subdirectory.

    - initial_directory_bytes (None or int) – Number of bytes to allocate for the new directory, so that TKeys can be added to it without immediately needing to rewrite the block. If None, the uproot.WritableFile’s value is used.

  Creates an empty subdirectory in this directory.

  Note that subdirectories can be created by assigning to path names that include slashes:

      my_directory["subdir1/subdir2/new_object"] = new_object

  but subdirectories created this way will never be empty. Use this method to make an empty directory or to control directory parameters.

## mktree

WritableDirectory.mktree(name, branch_types, title='', *, counter_name=<function WritableDirectory.<lambda>>, field_name=<function WritableDirectory.<lambda>>, initial_basket_capacity=10, resize_factor=10.0)
  Parameters:

    - name (str) – Name of the new TTree.

    - branch_types (dict or pairs of str → NumPy dtype/Awkward type) – Name and type specification for the TBranches.

    - title (str) – Title for the new TTree.

    - counter_name (callable of str → str) – Function to generate counter-TBranch names for Awkward Arrays of variable-length lists.

    - field_name (callable of str → str) – Function to generate TBranch names for columns of an Awkward record array or a Pandas DataFrame.

    - initial_basket_capacity (int) – Number of TBaskets that can be written to the TTree without rewriting the TTree metadata to make room.

    - resize_factor (float) – When the TTree metadata needs to be rewritten, this specifies how many more TBasket slots to allocate as a multiplicative factor.

  Creates an empty TTree in this directory.

  Note that TTrees can be created by assigning TTree-like data to a directory (see uproot.WritableTree for recognized TTree-like types):

      my_directory["tree"] = {"branch1": np.array(...), "branch2": ak.Array(...)}

  but TTrees created this way will never be empty. Use this method to make an empty TTree or to control its parameters.

## mkrntuple

WritableDirectory.mkrntuple(name, ak_form_or_data, title='')
  Parameters:

    - name (str) – Name of the new RNTuple.

    - ak_form_or_data (Awkward RecordForm or RecordArray) – Name and type specification for the fields. If a RecordForm is provided, the RNTuple will be empty. If a RecordArray is provided, the RNTuple will be initialized with the input data.

    - title (str) – Title for the new RNTuple.

  Creates an empty RNTuple in this directory.

## copy_from

WritableDirectory.copy_from(source, *, filter_name=<function no_filter>, filter_classname=<function no_filter>, rename=<function no_rename>, require_matches=True)
  Parameters:

    - source (uproot.WritableDirectory or uproot.ReadOnlyDirectory) – Directory from which to copy.

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

    - filter_classname (None, glob string, regex string in `"/pattern/i"` syntax, function of str → bool, or iterable of the above) – A filter to select keys by C++ (decoded) classname.

    - rename (None, regex string in `"/from/to/"` syntax, dict of str → str, function of str → str, or iterable of the above) – A function to convert old names into new names.

    - require_matches (bool) – If True and the filters do not match any data, raise a `ValueError`.

  Bulk-copy method to copy data from one ROOT file to another without interpretation or even decompression/recompression.

  This method will likely have performance advantages over copying objects one at a time, in part because it avoids interpretation and decompression/recompression, and also because it collects TStreamerInfo from all of the data types and rewrites the output file’s TStreamerInfo exactly once.

## update

WritableDirectory.update(pairs=None, **more_pairs)
  Parameters:

    - pairs (dict or pairs of str → writable data) – Names and data to write.

    - more_pairs (dict or pairs of str → writable data) – More names and data to write.

  Bulk-update function, like assignment, but it collects TStreamerInfo for a single update.