cosmotron_mcp.plotting

plot_cls_comparison

plot_cls_comparison(session_dir: str, bin_index: int = 0, scaling: str = 'ell_cl', theory_file: str | None = None, theory_file_pattern: str | None = None, show_noise: bool = True, output_name: str | None = None, pair: list[int] | None = None, component: str = 'EE') -> dict

Plot measured Cℓ (with covariance error bars) vs theory for one bin or cross-pair.

AUTO-SPECTRUM (default): bin_index=N. Reads cls_bin_{N}.json + covariance_bin_{N}.json (or extracts from covariance_all_bins.json in tomo mode). Theory from theory_file_pattern → per-bin manifest → theory_file, drawn UNBINNED. Shot-noise overlay when show_noise=True.

CROSS-SPECTRUM: pair=[i, j] (i<j). Reads cls_bin_{i}x.json. Error bars from covariance_all_bins.json block. No shot noise. No theory unless theory_file given. Saves plots/cls_comparison_cross_{i}x.png.

scaling: "ell_cl" (ℓCℓ, default) | "ell2_cl" (ℓ(ℓ+1)Cℓ/2π) | "cl" (raw). output_name: override the output filename — satisfied BY THIS TOOL.

component: "EE" (default) | "BB" | "EB". Use component='BB' for B-mode null-test style plots ("plot the B modes the same way as the E modes"), 'EB' for the EB cross — do NOT hand-write matplotlib. No noise line for BB/EB. Error bars come from covariance_validation_{BB|EB}.json for auto bins (that file is auto-bin-only); cross pairs get an analytic Gaussian estimate from the measured spectra instead. NO theory curve is drawn — a zero reference line is drawn instead (theory_file/theory_file_pattern are ignored). Requires a spin-2 bin/pair (ValueError otherwise). Saves cls_comparison_bin_{N}BB.png / cls_comparison_crossx_BB.png (EE default filenames unchanged).

Parameters:

Name	Type	Description	Default
session_dir	str	Session directory.	required
bin_index	int	Auto-spectrum bin index (ignored when pair is given).	0
scaling	str	"ell_cl" (ℓCℓ, default), "ell2_cl" (ℓ(ℓ+1)Cℓ/2π), or "cl" (raw).	'ell_cl'
theory_file	str | None	Single theory Cℓ file for the auto-spectrum, used if theory_file_pattern and the per-bin manifest theory don't resolve one.	None
theory_file_pattern	str | None	Per-bin theory file pattern (e.g. "theory_cls/true_cls_bin{bin_index}.txt", relative to data_folder).	None
show_noise	bool	Overlay the shot-noise line (EE only).	True
output_name	str | None	Override the output filename.	None
pair	list[int] | None	[i, j] (i<j) to plot a cross-spectrum instead of an auto-spectrum.	None
component	str	"EE" (default), "BB", or "EB". BB/EB draw a zero reference line instead of theory and require a spin-2 bin/pair.	'EE'

Returns:

Type	Description
dict	The plot result dict, including the saved PNG path(s).

Source code in cosmotron_mcp/server.py

@mcp.tool()
@sync_budget_guard
def plot_cls_comparison(
    session_dir: str,
    bin_index: int = 0,
    scaling: str = "ell_cl",
    theory_file: str | None = None,
    theory_file_pattern: str | None = None,
    show_noise: bool = True,
    output_name: str | None = None,
    pair: list[int] | None = None,
    component: str = "EE",
) -> dict:
    """Plot measured Cℓ (with covariance error bars) vs theory for one bin or cross-pair.

    AUTO-SPECTRUM (default): bin_index=N. Reads cls_bin_{N}.json +
    covariance_bin_{N}.json (or extracts from covariance_all_bins.json in tomo mode).
    Theory from theory_file_pattern → per-bin manifest → theory_file, drawn UNBINNED.
    Shot-noise overlay when show_noise=True.

    CROSS-SPECTRUM: pair=[i, j] (i<j). Reads cls_bin_{i}_x_{j}.json. Error bars
    from covariance_all_bins.json block. No shot noise. No theory unless theory_file given.
    Saves plots/cls_comparison_cross_{i}_x_{j}.png.

    scaling: "ell_cl" (ℓCℓ, default) | "ell2_cl" (ℓ(ℓ+1)Cℓ/2π) | "cl" (raw).
    output_name: override the output filename — satisfied BY THIS TOOL.

    component: "EE" (default) | "BB" | "EB". Use component='BB' for B-mode
    null-test style plots ("plot the B modes the same way as the E modes"),
    'EB' for the EB cross — do NOT hand-write matplotlib. No noise line for
    BB/EB. Error bars come from covariance_validation_{BB|EB}.json for auto
    bins (that file is auto-bin-only); cross pairs get an analytic Gaussian
    estimate from the measured spectra instead. NO theory curve is drawn — a
    zero reference line is drawn instead (theory_file/theory_file_pattern are
    ignored). Requires a spin-2 bin/pair (ValueError otherwise). Saves
    cls_comparison_bin_{N}_BB.png / cls_comparison_cross_{i}_x_{j}_BB.png
    (EE default filenames unchanged).

    Args:
        session_dir: Session directory.
        bin_index: Auto-spectrum bin index (ignored when `pair` is given).
        scaling: ``"ell_cl"`` (ℓCℓ, default), ``"ell2_cl"``
            (ℓ(ℓ+1)Cℓ/2π), or ``"cl"`` (raw).
        theory_file: Single theory Cℓ file for the auto-spectrum, used if
            `theory_file_pattern` and the per-bin manifest theory don't
            resolve one.
        theory_file_pattern: Per-bin theory file pattern (e.g.
            ``"theory_cls/true_cls_bin{bin_index}.txt"``, relative to
            `data_folder`).
        show_noise: Overlay the shot-noise line (EE only).
        output_name: Override the output filename.
        pair: ``[i, j]`` (i<j) to plot a cross-spectrum instead of an
            auto-spectrum.
        component: ``"EE"`` (default), ``"BB"``, or ``"EB"``. BB/EB draw a
            zero reference line instead of theory and require a spin-2
            bin/pair.

    Returns:
        The plot result dict, including the saved PNG path(s).
    """
    _require_human_gates(session_dir)
    pair_t = tuple(pair) if pair is not None else None
    result = _plot_cls_comparison(
        session_dir, bin_index=bin_index, scaling=scaling,
        theory_file=theory_file, theory_file_pattern=theory_file_pattern,
        show_noise=show_noise, output_name=output_name, pair=pair_t,
        component=component,
    )
    _log_tool_call(session_dir, "plot_cls_comparison", {
        "bin_index": bin_index, "scaling": scaling,
        "theory_file": theory_file, "theory_file_pattern": theory_file_pattern,
        "show_noise": show_noise, "output_name": output_name, "pair": pair,
        "component": component,
    })
    return result

plot_cls_grid

plot_cls_grid(session_dir: str, scaling: str = 'ell_cl', theory_file: str | None = None, theory_file_pattern: str | None = None, theory_file_pattern_cross: str | None = None, show_noise: bool = True, output_name: str | None = None, component: str = 'EE') -> dict

Plot all available Cℓ spectra in a single collated publication figure.

Auto-spectra only → vertical strip (N rows). Cross-correlations present → NxN upper-triangle grid (diagonal=auto, upper=cross, lower=blank).

Theory per auto-bin: resolved via theory_file_pattern (e.g. "theory_cls/true_cls_bin{bin_index}.txt", relative to data_folder) → per-bin manifest theory_path → theory_file (single file), drawn UNBINNED.

Theory for cross-panels: resolved via theory_file_pattern_cross (e.g. "glass_true_cls_bin{i}x{j}.txt") with {i} and {j} placeholders substituted per-panel. No fallback to theory_file_pattern — bin i's auto theory is not the (i, j) cross theory; without a matching cross file the panel is plotted measured-only.

The CCL cls_theory from covariance JSONs is NOT used — it is approximate and can be 2–4× off the simulation ground truth. Saves plots/cls_grid.png.

scaling: "ell_cl" (ℓCℓ, default) | "ell2_cl" (ℓ(ℓ+1)Cℓ/2π) | "cl" (raw). show_noise: overlay the noise line on EE auto panels (default True; labelled shear vs shot noise by spin). No-op for BB/EB (no noise line drawn there). output_name: override the output filename (satisfied by this tool — no matplotlib).

component: "EE" (default) | "BB" | "EB". Use component='BB' for B-mode null-test style plots ("plot the B modes the same way as the E modes"), 'EB' for the EB cross — do NOT hand-write matplotlib. theory_file/ theory_file_pattern* are ignored (a zero reference line is drawn instead); error bars come from covariance_validation_{BB|EB}.json for auto panels (cross panels get an analytic Gaussian estimate instead). A panel whose bin/pair is spin-0 shows a grey placeholder instead of failing; ValueError only if NO panel has the component. Saves cls_grid_BB.png (EE default cls_grid.png unchanged).

Parameters:

Name	Type	Description	Default
session_dir	str	Session directory.	required
scaling	str	"ell_cl" (ℓCℓ, default), "ell2_cl" (ℓ(ℓ+1)Cℓ/2π), or "cl" (raw).	'ell_cl'
theory_file	str | None	Single theory Cℓ file fallback for auto-panels.	None
theory_file_pattern	str | None	Per-bin theory file pattern for auto-panels.	None
theory_file_pattern_cross	str | None	Per-pair theory file pattern for cross-panels, with {i}/{j} placeholders.	None
show_noise	bool	Overlay the shot-noise line on EE auto panels.	True
output_name	str | None	Override the output filename.	None
component	str	"EE" (default), "BB", or "EB".	'EE'

Returns:

Type	Description
dict	The plot result dict, including the saved PNG path.

Source code in cosmotron_mcp/server.py

@mcp.tool()
@sync_budget_guard
def plot_cls_grid(
    session_dir: str,
    scaling: str = "ell_cl",
    theory_file: str | None = None,
    theory_file_pattern: str | None = None,
    theory_file_pattern_cross: str | None = None,
    show_noise: bool = True,
    output_name: str | None = None,
    component: str = "EE",
) -> dict:
    """Plot all available Cℓ spectra in a single collated publication figure.

    Auto-spectra only → vertical strip (N rows). Cross-correlations present →
    NxN upper-triangle grid (diagonal=auto, upper=cross, lower=blank).

    Theory per auto-bin: resolved via ``theory_file_pattern`` (e.g.
    "theory_cls/true_cls_bin{bin_index}.txt", relative to data_folder) →
    per-bin manifest theory_path → theory_file (single file), drawn UNBINNED.

    Theory for cross-panels: resolved via ``theory_file_pattern_cross`` (e.g.
    "glass_true_cls_bin{i}x{j}.txt") with ``{i}`` and ``{j}`` placeholders
    substituted per-panel. No fallback to ``theory_file_pattern`` — bin i's
    auto theory is not the (i, j) cross theory; without a matching cross file
    the panel is plotted measured-only.

    The CCL cls_theory from covariance JSONs is NOT used — it is approximate and
    can be 2–4× off the simulation ground truth. Saves plots/cls_grid.png.

    scaling: "ell_cl" (ℓCℓ, default) | "ell2_cl" (ℓ(ℓ+1)Cℓ/2π) | "cl" (raw).
    show_noise: overlay the noise line on EE auto panels (default True; labelled
    shear vs shot noise by spin). No-op for BB/EB (no noise line drawn there).
    output_name: override the output filename (satisfied by this tool — no matplotlib).

    component: "EE" (default) | "BB" | "EB". Use component='BB' for B-mode
    null-test style plots ("plot the B modes the same way as the E modes"),
    'EB' for the EB cross — do NOT hand-write matplotlib. theory_file/
    theory_file_pattern* are ignored (a zero reference line is drawn instead);
    error bars come from covariance_validation_{BB|EB}.json for auto panels
    (cross panels get an analytic Gaussian estimate instead). A panel whose
    bin/pair is spin-0 shows a grey placeholder instead
    of failing; ValueError only if NO panel has the component. Saves
    cls_grid_BB.png (EE default cls_grid.png unchanged).

    Args:
        session_dir: Session directory.
        scaling: ``"ell_cl"`` (ℓCℓ, default), ``"ell2_cl"``
            (ℓ(ℓ+1)Cℓ/2π), or ``"cl"`` (raw).
        theory_file: Single theory Cℓ file fallback for auto-panels.
        theory_file_pattern: Per-bin theory file pattern for auto-panels.
        theory_file_pattern_cross: Per-pair theory file pattern for
            cross-panels, with ``{i}``/``{j}`` placeholders.
        show_noise: Overlay the shot-noise line on EE auto panels.
        output_name: Override the output filename.
        component: ``"EE"`` (default), ``"BB"``, or ``"EB"``.

    Returns:
        The plot result dict, including the saved PNG path.
    """
    _require_human_gates(session_dir)
    result = _plot_cls_grid(
        session_dir, scaling=scaling,
        theory_file=theory_file, theory_file_pattern=theory_file_pattern,
        theory_file_pattern_cross=theory_file_pattern_cross,
        show_noise=show_noise, output_name=output_name,
        component=component,
    )
    _log_tool_call(session_dir, "plot_cls_grid", {
        "scaling": scaling, "theory_file": theory_file,
        "theory_file_pattern": theory_file_pattern,
        "theory_file_pattern_cross": theory_file_pattern_cross,
        "show_noise": show_noise, "output_name": output_name,
        "component": component,
    })
    return result

plot_covariance

plot_covariance(session_dir: str, bin_index: int | None = None, output_name: str | None = None) -> dict

Plot the normalised covariance (correlation) matrix.

bin_index=None (default): assembles ALL covariance_bin_*.json into one block-diagonal matrix with white dividing lines between tomographic bins — matches publication-style combined-covariance figures. Saves to plots/covariance_combined.png. bin_index=N: single-bin plot → plots/covariance_bin_{N:02d}.png. output_name overrides the filename.

Parameters:

Name	Type	Description	Default
session_dir	str	Session directory.	required
bin_index	int | None	Single bin to plot; None assembles the combined block-diagonal matrix across all bins.	None
output_name	str | None	Override the output filename.	None

Returns:

Type	Description
dict	The plot result dict, including the saved PNG path.

Source code in cosmotron_mcp/server.py

@mcp.tool()
@sync_budget_guard
def plot_covariance(session_dir: str, bin_index: int | None = None,
                    output_name: str | None = None) -> dict:
    """Plot the normalised covariance (correlation) matrix.

    bin_index=None (default): assembles ALL covariance_bin_*.json into one
    block-diagonal matrix with white dividing lines between tomographic bins —
    matches publication-style combined-covariance figures. Saves to
    plots/covariance_combined.png.
    bin_index=N: single-bin plot → plots/covariance_bin_{N:02d}.png.
    output_name overrides the filename.

    Args:
        session_dir: Session directory.
        bin_index: Single bin to plot; `None` assembles the combined
            block-diagonal matrix across all bins.
        output_name: Override the output filename.

    Returns:
        The plot result dict, including the saved PNG path.
    """
    _require_human_gates(session_dir)
    result = _plot_covariance(session_dir, bin_index=bin_index, output_name=output_name)
    _log_tool_call(session_dir, "plot_covariance", {"bin_index": bin_index, "output_name": output_name})
    return result

plot_catalogue_diagnostics

plot_catalogue_diagnostics(session_dir: str, output_name: str | None = None) -> dict

Plot catalogue diagnostics (n(z) from the survey file, sky footprint).

Reads manifest.json. Plots whatever inputs are present and skips-with-note the rest; never fabricates data, never blocks.

Parameters:

Name	Type	Description	Default
session_dir	str	Session directory.	required
output_name	str | None	Override the default filenames (still two files: a {output_name}_n_of_z.png + {output_name}_sky_footprint.png pair).	None

Returns:

Type	Description
dict	{paths, skipped}.

Source code in cosmotron_mcp/server.py

@mcp.tool()
@sync_budget_guard
def plot_catalogue_diagnostics(session_dir: str, output_name: str | None = None) -> dict:
    """Plot catalogue diagnostics (n(z) from the survey file, sky footprint).

    Reads manifest.json. Plots whatever inputs are present and skips-with-note
    the rest; never fabricates data, never blocks.

    Args:
        session_dir: Session directory.
        output_name: Override the default filenames (still two files: a
            ``{output_name}_n_of_z.png`` + ``{output_name}_sky_footprint.png``
            pair).

    Returns:
        ``{paths, skipped}``.
    """
    _require_human_gates(session_dir)
    result = _plot_catalogue_diagnostics(session_dir, output_name=output_name)
    _log_tool_call(session_dir, "plot_catalogue_diagnostics", {"output_name": output_name})
    return result

plot_covariance_validation

plot_covariance_validation(session_dir: str, bin_index: int = 0, output_name: str | None = None, pair: list[int] | None = None, component: str = 'EE') -> dict

Two-panel Knox covariance validation plot for one auto-bin or cross-pair.

AUTO-BIN (default): bin_index=N. Reads covariance_bin_{N}.json (with cls_theory, from compute_covariance). Falls back to the matching block in covariance_all_bins.json in tomographic mode where per-bin files are absent.

CROSS-PAIR: pair=[i, j] (i<j). Extracts the (i,j) diagonal block from covariance_all_bins.json and overlays the analytic Knox cross-pair estimate Var[C^ij] ≈ (C^ii·C^jj + (C^ij)²) / modes. Saves plots/covariance_validation_cross_{i}x.png.

Upper panel: σ_NaMaster(ℓ) vs σ_Knox(ℓ). Lower panel: ratio cov / Knox vs ℓ with tolerance band.

component: "EE" (default, unchanged) | "BB" | "EB". Reads covariance_validation_{BB|EB}.json instead (written by compute_validation_covariance_from_session) and checks it against the same analytic Knox formula used to build it. Auto-bin only — pair= with a non-EE component raises ValueError (no BB/EB cross covariance exists). Saves covariance_validation_bin_{N}_BB.png.

Parameters:

Name	Type	Description	Default
session_dir	str	Session directory.	required
bin_index	int	Auto-bin index (ignored when pair is given).	0
output_name	str | None	Override the output filename.	None
pair	list[int] | None	[i, j] (i<j) to validate a cross-pair block instead of an auto-bin (EE component only).	None
component	str	"EE" (default), "BB", or "EB" — auto-bin only for BB/EB.	'EE'

Returns:

Type	Description
dict	{path, median_ratio, verdict}.

Source code in cosmotron_mcp/server.py

@mcp.tool()
@sync_budget_guard
def plot_covariance_validation(
    session_dir: str,
    bin_index: int = 0,
    output_name: str | None = None,
    pair: list[int] | None = None,
    component: str = "EE",
) -> dict:
    """Two-panel Knox covariance validation plot for one auto-bin or cross-pair.

    AUTO-BIN (default): bin_index=N. Reads covariance_bin_{N}.json (with cls_theory,
    from compute_covariance). Falls back to the matching block in covariance_all_bins.json
    in tomographic mode where per-bin files are absent.

    CROSS-PAIR: pair=[i, j] (i<j). Extracts the (i,j) diagonal block from
    covariance_all_bins.json and overlays the analytic Knox cross-pair estimate
    Var[C^ij] ≈ (C^ii·C^jj + (C^ij)²) / modes.
    Saves plots/covariance_validation_cross_{i}_x_{j}.png.

    Upper panel: σ_NaMaster(ℓ) vs σ_Knox(ℓ).
    Lower panel: ratio cov / Knox vs ℓ with tolerance band.

    component: "EE" (default, unchanged) | "BB" | "EB". Reads
    covariance_validation_{BB|EB}.json instead (written by
    compute_validation_covariance_from_session) and checks it against the same
    analytic Knox formula used to build it. Auto-bin only — pair= with a
    non-EE component raises ValueError (no BB/EB cross covariance exists).
    Saves covariance_validation_bin_{N}_BB.png.

    Args:
        session_dir: Session directory.
        bin_index: Auto-bin index (ignored when `pair` is given).
        output_name: Override the output filename.
        pair: ``[i, j]`` (i<j) to validate a cross-pair block instead of an
            auto-bin (EE component only).
        component: ``"EE"`` (default), ``"BB"``, or ``"EB"`` — auto-bin only
            for BB/EB.

    Returns:
        ``{path, median_ratio, verdict}``.
    """
    _require_human_gates(session_dir)
    pair_t = tuple(pair) if pair is not None else None
    result = _plot_covariance_validation(
        session_dir, bin_index=bin_index, output_name=output_name, pair=pair_t,
        component=component,
    )
    _log_tool_call(session_dir, "plot_covariance_validation",
                   {"bin_index": bin_index, "output_name": output_name, "pair": pair,
                    "component": component})
    return result

plot_bmode_diagnosis

plot_bmode_diagnosis(session_dir: str, bin_index: int = 0, component: str = 'BB', output_name: str | None = None) -> dict

Plot the L1 B-mode excess diagnosis for one spin-2 auto-bin.

Shows the measured B-mode bandpowers against BOTH the analytic shot-noise error (what the null test used) and the high-ℓ α-rescaled error, annotated with the deterministic verdict / α / p_orig / p_rescaled from diagnose_bmode_excess_from_session. A benign noise-model residual is swallowed by the rescaled band; a colored excess sticks out of both. Run diagnose_bmode_excess_from_session first.

Parameters:

Name	Type	Description	Default
session_dir	str	Session directory.	required
bin_index	int	Spin-2 auto-bin id.	0
component	str	"BB" or "EB".	'BB'
output_name	str | None	Override the output filename (saved under plots/).	None

Returns:

Type	Description
dict	{path, verdict, alpha, p_orig, p_rescaled}.

Source code in cosmotron_mcp/server.py

@mcp.tool()
@sync_budget_guard
def plot_bmode_diagnosis(
    session_dir: str,
    bin_index: int = 0,
    component: str = "BB",
    output_name: str | None = None,
) -> dict:
    """Plot the L1 B-mode excess diagnosis for one spin-2 auto-bin.

    Shows the measured B-mode bandpowers against BOTH the analytic shot-noise
    error (what the null test used) and the high-ℓ α-rescaled error, annotated
    with the deterministic verdict / α / p_orig / p_rescaled from
    diagnose_bmode_excess_from_session. A benign noise-model residual is swallowed
    by the rescaled band; a colored excess sticks out of both. Run
    diagnose_bmode_excess_from_session first.

    Args:
        session_dir: Session directory.
        bin_index: Spin-2 auto-bin id.
        component: ``"BB"`` or ``"EB"``.
        output_name: Override the output filename (saved under plots/).

    Returns:
        ``{path, verdict, alpha, p_orig, p_rescaled}``.
    """
    _require_human_gates(session_dir)
    result = _plot_bmode_diagnosis(
        session_dir, bin_index=bin_index, component=component,
        output_name=output_name,
    )
    _log_tool_call(session_dir, "plot_bmode_diagnosis",
                   {"bin_index": bin_index, "component": component,
                    "output_name": output_name})
    return result

plot_covariance_validation_grid

plot_covariance_validation_grid(session_dir: str, component: str = 'EE') -> dict

Covariance-validation (Knox) plots for EVERY auto-bin and cross-pair, one call.

Mirrors plot_cls_grid's "auto-detects autos vs cross-correlations" guarantee for plot_covariance_validation, which otherwise takes one bin_index/pair at a time — a multi-bin session silently got only its bin_index=0 plot unless every pair was named explicitly. Detects every auto-bin and cross-pair present under results/spectra/ and calls plot_covariance_validation once per pair, saving each under its normal default filename (covariance_validation_bin_{i}.png / ...crossx.png / ...bin.png) — no single combined figure (a Knox panel is already a 2-row figure; an NxN grid of those would be unreadable).}_{BB|EB

component: "EE" (default) — auto-bin plots for every bin AND cross-pair plots for every detected (i, j). "BB"/"EB" — auto-bin only (no cross covariance exists for either), restricted to the spin-2 bins actually recorded in covariance_validation_{BB|EB}.json; a spin-0 session or one where compute_validation_covariance_from_session was never run returns {"skipped": ..., "paths": []} rather than raising. A per-pair failure is recorded in results with a "skipped" key and does not abort the rest.

Parameters:

Name	Type	Description	Default
session_dir	str	Session directory.	required
component	str	"EE" (default), "BB", or "EB".	'EE'

Returns:

Type	Description
dict	{"paths": [...], "results": [...], "n_bins", "n_pairs"}.

Source code in cosmotron_mcp/server.py

@mcp.tool()
@sync_budget_guard
def plot_covariance_validation_grid(
    session_dir: str,
    component: str = "EE",
) -> dict:
    """Covariance-validation (Knox) plots for EVERY auto-bin and cross-pair, one call.

    Mirrors plot_cls_grid's "auto-detects autos vs cross-correlations" guarantee
    for plot_covariance_validation, which otherwise takes one bin_index/pair at a
    time — a multi-bin session silently got only its bin_index=0 plot unless
    every pair was named explicitly. Detects every auto-bin and cross-pair
    present under results/spectra/ and calls plot_covariance_validation once per
    pair, saving each under its normal default filename
    (covariance_validation_bin_{i}.png / ..._cross_{i}_x_{j}.png /
    ..._bin_{i}_{BB|EB}.png) — no single combined figure (a Knox panel is
    already a 2-row figure; an NxN grid of those would be unreadable).

    component: "EE" (default) — auto-bin plots for every bin AND cross-pair
    plots for every detected (i, j). "BB"/"EB" — auto-bin only (no cross
    covariance exists for either), restricted to the spin-2 bins actually
    recorded in covariance_validation_{BB|EB}.json; a spin-0 session or one
    where compute_validation_covariance_from_session was never run returns
    {"skipped": ..., "paths": []} rather than raising. A per-pair failure is
    recorded in `results` with a "skipped" key and does not abort the rest.

    Args:
        session_dir: Session directory.
        component: "EE" (default), "BB", or "EB".

    Returns:
        {"paths": [...], "results": [...], "n_bins", "n_pairs"}.
    """
    _require_human_gates(session_dir)
    result = _plot_covariance_validation_grid(session_dir, component=component)
    _log_tool_call(session_dir, "plot_covariance_validation_grid",
                   {"component": component})
    return result

plot_healpix_maps

plot_healpix_maps(session_dir: str, map_paths: list[str] | None = None, output_name: str | None = None) -> dict

Mollweide projection plots of HEALPix maps from the session.

When map_paths is None, auto-detects delta_map/mask AND shear maps (roles shear_q/shear_u, from compute_cls_from_session(..., save_maps=True) on spin-2 bins) from artefact_registry.json: rows=bins, cols=(γ₁/Q, γ₂/U, mask) for shear, (δ_g, mask) for density, or all four for a mixed 3×2pt session (blank cell where a bin has no map for that column). Diverging RdBu_r colormap for the shear columns. Use for any "plot the shear / Q/U maps" request — never healpy scripting. For tomographic sessions each subplot title contains the bin index and redshift range (z_min–z_max from manifest).

Requires healpy.

Parameters:

Name	Type	Description	Default
session_dir	str	Session directory.	required
map_paths	list[str] | None	Explicit map paths to plot; None auto-detects from artefact_registry.json.	None
output_name	str | None	Override the output filename.	None

Returns:

Type	Description
dict	{path, n_maps, layout, roles}.

Source code in cosmotron_mcp/server.py

@mcp.tool()
@sync_budget_guard
def plot_healpix_maps(
    session_dir: str,
    map_paths: list[str] | None = None,
    output_name: str | None = None,
) -> dict:
    """Mollweide projection plots of HEALPix maps from the session.

    When map_paths is None, auto-detects delta_map/mask AND shear maps (roles
    shear_q/shear_u, from compute_cls_from_session(..., save_maps=True) on
    spin-2 bins) from artefact_registry.json: rows=bins, cols=(γ₁/Q, γ₂/U, mask)
    for shear, (δ_g, mask) for density, or all four for a mixed 3×2pt session
    (blank cell where a bin has no map for that column). Diverging RdBu_r
    colormap for the shear columns. Use for any "plot the shear / Q/U maps"
    request — never healpy scripting. For tomographic sessions each subplot
    title contains the bin index and redshift range (z_min–z_max from manifest).

    Requires healpy.

    Args:
        session_dir: Session directory.
        map_paths: Explicit map paths to plot; `None` auto-detects from
            `artefact_registry.json`.
        output_name: Override the output filename.

    Returns:
        ``{path, n_maps, layout, roles}``.
    """
    _require_human_gates(session_dir)
    result = _plot_healpix_maps(
        session_dir, map_paths=map_paths, output_name=output_name
    )
    _log_tool_call(session_dir, "plot_healpix_maps",
                   {"map_paths": map_paths, "output_name": output_name})
    return result