root_mcp.core.io.readers module

Readers for TTree and histogram data.

class root_mcp.core.io.readers.HistogramReader(config, file_manager)[source]

Bases: object

High-level interface for reading histograms.

Provides access to TH1, TH2, TH3, and TProfile objects.

Parameters:
__init__(config, file_manager)[source]

Initialize HistogramReader.

Parameters:

  • config (Config) – Server configuration

  • file_manager (FileManager) – File manager instance

read_histogram(path, hist_name)[source]

Read a histogram from a ROOT file.

Parameters:

  • path (str) – File path

  • hist_name (str) – Histogram name or path

Returns:

Histogram data and metadata

Return type:

dict[str, Any]

class root_mcp.core.io.readers.TreeReader(config, file_manager)[source]

Bases: object

High-level interface for reading TTree data.

Provides safe, efficient access to TTree branches with chunking, filtering, and pagination.

Parameters:
__init__(config, file_manager)[source]

Initialize TreeReader.

Parameters:

  • config (Config) – Server configuration

  • file_manager (FileManager) – File manager instance

compute_branch_stats(path, tree_name, branches, selection=None)[source]

Compute statistics for branches.

Parameters:

  • path (str) – File path

  • tree_name (str) – Tree name

  • branches (list[str]) – Branches to analyze

  • selection (str | None) – Optional cut expression

Returns:

Dictionary mapping branch names to statistics

Return type:

dict[str, dict[str, float]]

get_branch_info(path, tree_name, pattern=None)[source]

Get information about branches in a tree.

Parameters:

  • path (str) – File path

  • tree_name (str) – Tree name

  • pattern (str | None) – Optional glob pattern to filter branches

Returns:

List of branch info dictionaries

Return type:

list[dict[str, Any]]

read_branches(path, tree_name, branches, selection=None, limit=None, offset=0, flatten=False, defines=None)[source]

Read branch data from a TTree.

Parameters:

  • path (str) – File path

  • tree_name (str) – Tree name

  • branches (list[str]) – List of branch names to read (can include derived branches from defines)

  • selection (str | None) – Optional ROOT-style cut expression

  • limit (int | None) – Maximum number of entries to return

  • offset (int) – Number of entries to skip

  • flatten (bool) – Flatten jagged arrays

  • defines (dict[str, str] | None) – Optional derived variable definitions {name: expression}

Returns:

Dictionary with data and metadata

Return type:

dict[str, Any]

sample_tree(path, tree_name, size=100, method='first', branches=None, seed=None)[source]

Get a sample from a tree.

Parameters:

  • path (str) – File path

  • tree_name (str) – Tree name

  • size (int) – Sample size

  • method (str) – “first” or “random”

  • branches (list[str] | None) – Branches to include (None = all)

  • seed (int | None) – Random seed for reproducibility

Returns:

Sample data and metadata

Return type:

dict[str, Any]

stream_branches(path, tree_name, branches, chunk_size=10000, selection=None)[source]

Stream branch data in chunks for large files.

Parameters:

  • path (str) – File path

  • tree_name (str) – Tree name

  • branches (list[str]) – Branches to read

  • chunk_size (int) – Number of entries per chunk

  • selection (str | None) – Optional cut expression

Yields:

Chunks of data as awkward arrays