cosmotron_mcp.tools.bmode_diagnosis

diagnose_bmode_excess_from_session

diagnose_bmode_excess_from_session(session_dir: str, significance: float | None = None) -> dict

Classify a failing shear B-mode null as benign noise-model residual vs a real colored excess — deterministically (L1 discriminant).

A BB/EB null can fail either because the analytic shot-noise model is a few % off the true map noise (a benign estimator artefact the sub-percent covariance over-rejects) or because there is a genuine ℓ-dependent B-mode. This fits a single high-ℓ shot-noise amplitude α, re-runs the null with N→α·N, and inspects the residual's ℓ-shape to classify each bin/component: BENIGN_NOISE_MODEL / BENIGN_FLAG / COLORED_EXCESS.

ADVISORY ONLY — it never changes the systematics-gate PASS/FAIL and never touches the EE data covariance or SACC. Cheap (reads the per-bin auto Cℓ JSONs; no catalogue read). Writes results/systematics/bmode_diagnosis.json.

Parameters:

Name	Type	Description	Default
session_dir	str	Session directory.	required
significance	float | None	Null p-value threshold; defaults to the session's systematics.bmode_pvalue_min.	None

Returns:

Type	Description
dict	``{overall_verdict, per_bin: [{bin, component, alpha, p_orig,
dict	p_rescaled, chi2_lowell_frac, ee_bb_corr, verdict}], output_path}``.

Source code in cosmotron_mcp/server.py

@mcp.tool()
@sync_budget_guard
def diagnose_bmode_excess_from_session(
    session_dir: str, significance: float | None = None,
) -> dict:
    """Classify a failing shear B-mode null as benign noise-model residual vs a
    real colored excess — deterministically (L1 discriminant).

    A BB/EB null can fail either because the analytic shot-noise model is a few %
    off the true map noise (a benign estimator artefact the sub-percent covariance
    over-rejects) or because there is a genuine ℓ-dependent B-mode. This fits a
    single high-ℓ shot-noise amplitude ``α``, re-runs the null with ``N→α·N``, and
    inspects the residual's ℓ-shape to classify each bin/component:
    ``BENIGN_NOISE_MODEL`` / ``BENIGN_FLAG`` / ``COLORED_EXCESS``.

    ADVISORY ONLY — it never changes the systematics-gate PASS/FAIL and never
    touches the EE data covariance or SACC. Cheap (reads the per-bin auto Cℓ
    JSONs; no catalogue read). Writes ``results/systematics/bmode_diagnosis.json``.

    Args:
        session_dir: Session directory.
        significance: Null p-value threshold; defaults to the session's
            ``systematics.bmode_pvalue_min``.

    Returns:
        ``{overall_verdict, per_bin: [{bin, component, alpha, p_orig,
        p_rescaled, chi2_lowell_frac, ee_bb_corr, verdict}], output_path}``.
    """
    _require_human_gates(session_dir)
    result = _diagnose_bmode_excess_from_session(session_dir, significance)
    _log_tool_call(session_dir, "diagnose_bmode_excess_from_session",
                   {"significance": significance})
    return _compact_result(result)