colstore.from_root

colstore.from_root(source, path, *, backend='auto', treename=None, columns=None, keep_valid_only=True, batch_size='512 MiB', compact=True, mode='create', show_progress=True)[source]

Convert a ROOT source into a .cstore file and open it for reading.

Parameters:

  • source (ROOT.RDataFrame, str, os.PathLike, list, or dict) – An existing RDataFrame (read only by the "ROOT" backend); a path to a .root file (its single tree is used, or treename selects one); a list of paths read as one combined dataset over a shared tree (from treename, an embedded "file.root:treename", or the first file’s sole tree); or a {treename: files} mapping with exactly one entry (files may be a path or a list). A str path may embed the tree as "file.root:treename" (the uproot convention; URL-scheme and Windows-drive colons are not separators). To read a file whose name contains a colon, pass it as a pathlib.Path (never split) or use the mapping form.

  • path (str or os.PathLike) – Destination .cstore file.

  • backend (str, optional) – Backend to read with: "auto" (default) uses PyROOT if importable, else uproot; "ROOT" forces PyROOT/RDataFrame; "uproot" forces uproot. Raises if the requested backend is missing.

  • treename (str or None, optional) – Tree to read when source is a bare .root path. None auto-detects the file’s sole tree and errors if there are several. It is an error to pass a treename that disagrees with an embedded "file.root:treename".

  • columns (list[str] or None, optional) – Columns to store, in this order. None (default) considers every column in the tree.

  • keep_valid_only (bool, optional) – True (default) keeps the fixed-size scalar columns and skips any non-storable (jagged / array / pointer) column with a warning, whether it was auto-discovered or named in columns. False raises if any column in scope is not storable.

  • batch_size (int, str, or None, optional) – Memory budget per batch. None reads everything in one pass; an int is rows per batch; a str (default "512 MiB") is a byte budget converted to rows. Each batch becomes one record.

  • compact (bool, optional) – Collapse the records into one afterward for the single-record fast read path. Defaults to True.

  • mode (str, optional) – "create" (default), "recreate", or "update".

  • show_progress (bool, optional) – Whether to display a progress bar. Defaults to True.

Returns:

colstore.ColStoreReader – An opened reader over the written file.

Return type:

ColStoreReader