uproot.WritableDirectory

Defined in uproot.writing.writable on line 454.

Inheritance order:

  1. collections.abc.MutableMapping

  2. collections.abc.Mapping

  3. collections.abc.Collection

  4. collections.abc.Sized

  5. collections.abc.Iterable

  6. 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, branch_types, title='')
Parameters:
  • name (str) – Name of the new RNTuple.

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

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