root_mcp.extended.analysis package

Extended analysis operations.

class root_mcp.extended.analysis.AnalysisOperations(config, file_manager)

Bases: object

High-level physics analysis operations.

Provides histogramming, selection, projections, and derived quantities.

Parameters:

• config (Config)

• file_manager (FileManager)

__init__(config, file_manager)

Initialize analysis operations.

Parameters:

• config (Config) – Server configuration

• file_manager (FileManager) – File manager instance

apply_selection(path, tree_name, selection, defines=None)

Count entries passing a selection.

Parameters:

• path (str) – File path

• tree_name (str) – Tree name

• selection (str) – Cut expression

• defines (dict[str, str] | None) – Optional variable definitions

Returns:

Selection statistics

Return type:

dict[str, Any]

compute_histogram(path, tree_name, branch, bins, range=None, selection=None, weights=None, defines=None, flatten=True)

Compute a 1D histogram.

Parameters:

• path (str | list[str]) – File path or list of file paths

• tree_name (str) – Tree name

• branch (str) – Branch to histogram

• bins (int) – Number of bins

• range (tuple[float, float] | None) – (min, max) for histogram range (auto if None, based on first file)

• selection (str | None) – Optional cut expression

• weights (str | None) – Optional branch for weights

• defines (dict[str, str] | None) – Optional derived variable definitions

• flatten (bool) – Flatten jagged arrays before histogramming

Returns:

Histogram data and metadata

Return type:

dict[str, Any]

compute_histogram_2d(path, tree_name, x_branch, y_branch, x_bins, y_bins, x_range=None, y_range=None, selection=None, defines=None, flatten=True)

Compute a 2D histogram.

Parameters:

• path (str | list[str]) – File path or list of paths

• tree_name (str) – Tree name

• x_branch (str) – Branch for x-axis

• y_branch (str) – Branch for y-axis

• x_bins (int) – Number of bins in x

• y_bins (int) – Number of bins in y

• x_range (tuple[float, float] | None) – (min, max) for x-axis

• y_range (tuple[float, float] | None) – (min, max) for y-axis

• selection (str | None) – Optional cut expression

• defines (dict[str, str] | None) – Optional derived variable definitions

• flatten (bool) – Flatten jagged arrays

Returns:

2D histogram data and metadata

Return type:

dict[str, Any]

compute_histogram_arithmetic(operation, data1, data2)

Perform arithmetic on two histograms.

Parameters:

• operation (str) – One of “add”, “subtract”, “multiply”, “divide”, “asymmetry”

• data1 (dict[str, Any]) – First histogram object

• data2 (dict[str, Any]) – Second histogram object

Returns:

New histogram object with computed values.

Return type:

dict[str, Any]

compute_kinematics(path, tree_name, computations, selection=None, limit=None)

Compute kinematic quantities from four-momenta.

Parameters:

• path (str) – File path

• tree_name (str) – Tree name

• computations (list[dict[str, Any]]) – List of kinematic calculations. Each entry is a dict with keys name (output variable name), type (one of invariant_mass, invariant_mass_squared, transverse_mass, delta_r, delta_phi), particles (list of branch prefixes), and optionally components (component suffixes; defaults vary by type).

• selection (str | None) – Optional cut expression

• limit (int | None) – Maximum entries to process

Returns:

Dictionary with computed kinematic quantities

Return type:

dict[str, Any]

compute_profile(path, tree_name, x_branch, y_branch, x_bins, x_range=None, selection=None)

Compute a profile histogram (mean of y vs binned x).

Parameters:

• path (str) – File path

• tree_name (str) – Tree name

• x_branch (str) – Branch to bin

• y_branch (str) – Branch to average

• x_bins (int) – Number of bins in x

• x_range (tuple[float, float] | None) – (min, max) for x-axis

• selection (str | None) – Optional cut

Returns:

Profile data and metadata

Return type:

dict[str, Any]

export_to_formats(data, output_path, format)

Export data to various formats.

Parameters:

• data (awkward.Array) – Awkward array to export

• output_path (str) – Destination path

• format (str) – Output format (json, csv, parquet)

Returns:

Export metadata

Return type:

dict[str, Any]

class root_mcp.extended.analysis.CorrelationAnalysis(config, file_manager)

Bases: object

Statistical correlation and covariance analysis.

Provides: - Pearson correlation coefficients - Spearman rank correlation - Covariance matrices - Correlation matrices - Significance testing

Parameters:

• config (Config)

• file_manager (FileManager)

__init__(config, file_manager)

Initialize correlation analysis.

Parameters:

• config (Config) – Server configuration

• file_manager (FileManager) – File manager instance

compute_correlation(path, tree_name, branch_x, branch_y, selection=None, method='pearson')

Compute correlation coefficient between two branches.

Parameters:

• path (str) – File path

• tree_name (str) – Tree name

• branch_x (str) – First branch

• branch_y (str) – Second branch

• selection (str | None) – Optional cut expression

• method (str) – Correlation method (‘pearson’ or ‘spearman’)

Returns:

Correlation coefficient, p-value, and metadata

Return type:

dict[str, Any]

compute_correlation_matrix(path, tree_name, branches, selection=None, method='pearson')

Compute correlation matrix for multiple branches.

Parameters:

• path (str) – File path

• tree_name (str) – Tree name

• branches (list[str]) – List of branches to correlate

• selection (str | None) – Optional cut expression

• method (str) – Correlation method (‘pearson’ or ‘spearman’)

Returns:

Correlation matrix and metadata

Return type:

dict[str, Any]

compute_covariance_matrix(path, tree_name, branches, selection=None)

Compute covariance matrix for multiple branches.

Parameters:

• path (str) – File path

• tree_name (str) – Tree name

• branches (list[str]) – List of branches

• selection (str | None) – Optional cut expression

Returns:

Covariance matrix and metadata

Return type:

dict[str, Any]

compute_mutual_information(path, tree_name, branch_x, branch_y, bins=50, selection=None)

Compute mutual information between two branches.

Parameters:

• path (str) – File path

• tree_name (str) – Tree name

• branch_x (str) – First branch

• branch_y (str) – Second branch

• bins (int) – Number of bins for discretization

• selection (str | None) – Optional cut expression

Returns:

Mutual information and metadata

Return type:

dict[str, Any]

class root_mcp.extended.analysis.HistogramOperations(config, file_manager)

Bases: object

Advanced histogram operations with scipy-based fitting.

Extends core histogram capabilities with: - 2D and 3D histograms - Profile histograms - Weighted histograms with proper error propagation - Histogram arithmetic

Parameters:

• config (Config)

• file_manager (FileManager)

__init__(config, file_manager)

Initialize histogram operations.

Parameters:

• config (Config) – Server configuration

• file_manager (FileManager) – File manager instance

compute_histogram_1d(path, tree_name, branch, bins, range=None, selection=None, weights=None)

Compute a 1D histogram with advanced features.

Parameters:

• path (str) – File path

• tree_name (str) – Tree name

• branch (str) – Branch to histogram

• bins (int) – Number of bins

• range (tuple[float, float] | None) – (min, max) for histogram

• selection (str | None) – Optional cut expression

• weights (str | None) – Optional weight branch

Returns:

Histogram data with metadata

Return type:

dict[str, Any]

compute_histogram_2d(path, tree_name, branch_x, branch_y, bins_x, bins_y, range_x=None, range_y=None, selection=None, weights=None)

Compute a 2D histogram.

Parameters:

• path (str) – File path

• tree_name (str) – Tree name

• branch_x (str) – X-axis branch

• branch_y (str) – Y-axis branch

• bins_x (int) – Number of bins in X

• bins_y (int) – Number of bins in Y

• range_x (tuple[float, float] | None) – (min, max) for X axis

• range_y (tuple[float, float] | None) – (min, max) for Y axis

• selection (str | None) – Optional cut expression

• weights (str | None) – Optional weight branch

Returns:

2D histogram data

Return type:

dict[str, Any]

compute_profile(path, tree_name, branch_x, branch_y, bins, range_x=None, selection=None)

Compute a profile histogram (mean of Y vs X).

Parameters:

• path (str) – File path

• tree_name (str) – Tree name

• branch_x (str) – X-axis branch

• branch_y (str) – Y-axis branch (to be averaged)

• bins (int) – Number of bins in X

• range_x (tuple[float, float] | None) – (min, max) for X axis

• selection (str | None) – Optional cut expression

Returns:

Profile histogram data

Return type:

dict[str, Any]

class root_mcp.extended.analysis.KinematicsOperations(config, file_manager)

Bases: object

Particle physics kinematics calculations.

Provides: - Invariant mass calculations - Transverse momentum (pT) - Pseudorapidity (eta) - Azimuthal angle (phi) - Delta R separation - Lorentz transformations - Dalitz variables

Parameters:

• config (Config)

• file_manager (FileManager)

__init__(config, file_manager)

Initialize kinematics operations.

Parameters:

• config (Config) – Server configuration

• file_manager (FileManager) – File manager instance

compute_boost_to_cm(path, tree_name, pt_branches, eta_branches, phi_branches, mass_branches, selection=None)

Boost particles to center-of-mass frame.

Parameters:

• path (str) – File path

• tree_name (str) – Tree name

• pt_branches (list[str]) – List of pT branches

• eta_branches (list[str]) – List of eta branches

• phi_branches (list[str]) – List of phi branches

• mass_branches (list[str]) – List of mass branches

• selection (str | None) – Optional cut expression

Returns:

Dictionary with boosted 4-vectors

Return type:

dict[str, Any]

compute_dalitz_variables(path, tree_name, pt_branches, eta_branches, phi_branches, mass_branches, selection=None)

Compute Dalitz plot variables for 3-body decay.

Parameters:

• path (str) – File path

• tree_name (str) – Tree name

• pt_branches (list[str]) – List of 3 pT branches

• eta_branches (list[str]) – List of 3 eta branches

• phi_branches (list[str]) – List of 3 phi branches

• mass_branches (list[str]) – List of 3 mass branches

• selection (str | None) – Optional cut expression

Returns:

Dictionary with m12_squared and m23_squared arrays

Return type:

dict[str, Any]

compute_delta_r(path, tree_name, eta1, phi1, eta2, phi2, selection=None)

Compute Delta R separation between two objects.

Parameters:

• path (str) – File path

• tree_name (str) – Tree name

• eta1 (str) – First object eta branch

• phi1 (str) – First object phi branch

• eta2 (str) – Second object eta branch

• phi2 (str) – Second object phi branch

• selection (str | None) – Optional cut expression

Returns:

Dictionary with Delta R array

Return type:

dict[str, Any]

compute_invariant_mass(path, tree_name, pt_branches, eta_branches, phi_branches, mass_branches=None, selection=None)

Compute invariant mass from 4-vectors.

Parameters:

• path (str) – File path

• tree_name (str) – Tree name

• pt_branches (list[str]) – List of pT branches

• eta_branches (list[str]) – List of eta branches

• phi_branches (list[str]) – List of phi branches

• mass_branches (list[str] | None) – List of mass branches (optional, assumes massless if None)

• selection (str | None) – Optional cut expression

Returns:

Dictionary with invariant mass array

Return type:

dict[str, Any]

compute_transverse_mass(path, tree_name, pt1, phi1, pt2, phi2, selection=None)

Compute transverse mass (useful for W->lν analyses).

Parameters:

• path (str) – File path

• tree_name (str) – Tree name

• pt1 (str) – First particle pT branch

• phi1 (str) – First particle phi branch

• pt2 (str) – Second particle pT branch (e.g., MET)

• phi2 (str) – Second particle phi branch

• selection (str | None) – Optional cut expression

Returns:

Dictionary with transverse mass array

Return type:

dict[str, Any]

class root_mcp.extended.analysis.SafeExprEvaluator(names)

Bases: NodeVisitor

Safe expression evaluator for limited math subset. Uses abstract syntax tree to evaluate expressions without eval().

Parameters:

names (dict[str, Any])

__init__(names)

Initialize evaluator.

Parameters:

names (dict[str, Any]) – Dictionary of allowed variable names and their values

generic_visit(node)

Called if no explicit visitor function exists for a node.

Parameters:

node (AST)

Return type:

Any

visit_BinOp(node)

Parameters:

node (BinOp)

Return type:

Any

visit_Call(node)

Parameters:

node (Call)

Return type:

Any

visit_Compare(node)

Parameters:

node (Compare)

Return type:

Any

visit_Constant(node)

Parameters:

node (Constant)

Return type:

Any

visit_Expression(node)

Parameters:

node (Expression)

Return type:

Any

visit_Name(node)

Parameters:

node (Name)

Return type:

Any

visit_UnaryOp(node)

Parameters:

node (UnaryOp)

Return type:

Any

root_mcp.extended.analysis.fit_histogram(data, model, initial_guess=None, bounds=None, fixed_parameters=None)

Fit a model to histogram data.

Parameters:

• data (dict[str, Any]) – Histogram data dictionary

• model (str | list[str | dict[str, Any]] | dict[str, Any]) – Model definition. Can be: - str: Name of built-in model (e.g., “gaussian”) - list[str]: List of built-in models (e.g., [“gaussian”, “exponential”]) - list[dict]: List of models with config (e.g., [{"name": "gaussian", "prefix": "s_"}]) - dict: Custom model definition (e.g. {“expr”: “A*x + B”, “params”: [“A”, “B”]})

• initial_guess (list[float] | None) – Initial parameter values

• bounds (list[list[float]] | None) – List of [min, max] pairs for each parameter. Use [-np.inf, np.inf] for no bound.

• fixed_parameters (dict[str | int, float] | None) – Dictionary of parameters to fix. Keys can be index (int) or name (str).

Returns:

Dictionary with fitted parameters, errors, and stats

Return type:

dict[str, Any]

root_mcp.extended.analysis.fit_histogram_2d(x, y, z, z_errors=None, model='gaussian_2d', initial_params=None, fixed_params=None, bounds=None)

Fit a 2D histogram with a model function.

Parameters:

• x (ndarray) – X-coordinate array (flattened)

• y (ndarray) – Y-coordinate array (flattened)

• z (ndarray) – Z-values (bin contents, flattened)

• z_errors (ndarray | None) – Errors on z-values

• model (str) – Model name from MODEL_REGISTRY_2D

• initial_params (list[float] | None) – Initial parameter guesses

• fixed_params (dict[str, float] | None) – Dictionary of {param_name: value} for fixed parameters

• bounds (tuple[list[float], list[float]] | None) – Tuple of (lower_bounds, upper_bounds)

Returns:

Dictionary with fit results

Return type:

dict[str, Any]

root_mcp.extended.analysis.generate_plot(data, plot_type='histogram', fit_data=None, options=None, config=None)

Generate a plot from analysis data.

Parameters:

• data (dict[str, Any]) – Analysis result (histogram data)

• plot_type (str) – Type of plot (histogram, etc.)

• fit_data (dict[str, Any] | None) – Optional fit results to overlay

• options (dict[str, Any] | None) – Plotting options (title, labels, etc.)

• config (Any | None) – Configuration object with plotting settings

Returns:

Dictionary with base64 encoded image

Return type:

dict[str, str]

root_mcp.extended.analysis.strip_outer_parens(expr)

Strip outer parentheses from expression.

Parameters:

expr (str)

Return type:

str

root_mcp.extended.analysis.translate_leaf_expr(expr)

Translate C++ style expression to Python.

Parameters:

expr (str)

Return type:

str

Submodules

• root_mcp.extended.analysis.correlations module
  • CorrelationAnalysis
    • CorrelationAnalysis.__init__()
    • CorrelationAnalysis.compute_correlation()
    • CorrelationAnalysis.compute_correlation_matrix()
    • CorrelationAnalysis.compute_covariance_matrix()
    • CorrelationAnalysis.compute_mutual_information()
• root_mcp.extended.analysis.expression module
  • SafeExprEvaluator
    • SafeExprEvaluator.__init__()
    • SafeExprEvaluator.generic_visit()
    • SafeExprEvaluator.visit_BinOp()
    • SafeExprEvaluator.visit_Call()
    • SafeExprEvaluator.visit_Compare()
    • SafeExprEvaluator.visit_Constant()
    • SafeExprEvaluator.visit_Expression()
    • SafeExprEvaluator.visit_Name()
    • SafeExprEvaluator.visit_UnaryOp()
  • strip_outer_parens()
  • translate_leaf_expr()
• root_mcp.extended.analysis.fitting module
  • CompositeModel
    • CompositeModel.__init__()
  • CustomModel
    • CustomModel.__init__()
  • ModelInfo
    • ModelInfo.func
    • ModelInfo.n_params
    • ModelInfo.param_names
  • crystal_ball()
  • exponential()
  • fit_histogram()
  • fit_histogram_2d()
  • gaussian()
  • gaussian_2d()
  • polynomial()
  • polynomial_2d()
• root_mcp.extended.analysis.histograms module
  • HistogramOperations
    • HistogramOperations.__init__()
    • HistogramOperations.compute_histogram_1d()
    • HistogramOperations.compute_histogram_2d()
    • HistogramOperations.compute_profile()
• root_mcp.extended.analysis.kinematics module
  • KinematicsOperations
    • KinematicsOperations.__init__()
    • KinematicsOperations.compute_boost_to_cm()
    • KinematicsOperations.compute_dalitz_variables()
    • KinematicsOperations.compute_delta_r()
    • KinematicsOperations.compute_invariant_mass()
    • KinematicsOperations.compute_transverse_mass()
• root_mcp.extended.analysis.operations module
  • AnalysisOperations
    • AnalysisOperations.__init__()
    • AnalysisOperations.apply_selection()
    • AnalysisOperations.compute_histogram()
    • AnalysisOperations.compute_histogram_2d()
    • AnalysisOperations.compute_histogram_arithmetic()
    • AnalysisOperations.compute_kinematics()
    • AnalysisOperations.compute_profile()
    • AnalysisOperations.export_to_formats()
• root_mcp.extended.analysis.plotting module
  • generate_plot()