Reporting

reporting

Pure-Python report generation (matplotlib only, no R/Quarto).

MPL_DIR module-attribute

MPL_DIR = Path.cwd() / '.mplconfig'

write_graphs

write_graphs(results, df, assets_dir)

Write PNG graphs to assets_dir. Returns list of {title, image} dicts.

Source code in metrics_petri/pipeline/reporting.py

def write_graphs(
    results: list[dict],
    df: pd.DataFrame,
    assets_dir: Path,
) -> list[dict[str, str]]:
    """Write PNG graphs to assets_dir. Returns list of {title, image} dicts."""
    assets_dir.mkdir(parents=True, exist_ok=True)
    sections: list[dict[str, str]] = []

    graph_specs = [
        (
            "01_colony_expansion.png",
            "Colony expansion",
            lambda ax: _plot_lines(
                ax, df,
                [("area", "Area (mm²)", "#4f46e5"), ("diameter", "Diameter (mm)", "#059669")],
                "Colony expansion over time", "Time (days)", "Size (mm² / mm)",
            ),
        ),
        (
            "02_growth_roughness.png",
            "Relative growth and edge roughness",
            lambda ax: _plot_lines(
                ax, df,
                [
                    ("relative_growth_rate", "Relative growth rate (1/day)", "#ea580c"),
                    ("edge_roughness", "Edge roughness", "#b45309"),
                ],
                "Relative growth and edge roughness", "Time (days)", "Growth / roughness",
            ),
        ),
        (
            "03_crack_burden.png",
            "Crack burden",
            lambda ax: _plot_lines(
                ax, df,
                [
                    ("crack_coverage", "Crack coverage (%)", "#f59e0b"),
                    ("crack_count", "Crack count", "#7c2d12"),
                ],
                "Crack burden over time", "Time (days)", "Coverage / count",
            ),
        ),
        (
            "04_texture.png",
            "Texture organisation",
            lambda ax: _plot_lines(
                ax, df,
                [
                    ("entropy", "Texture entropy (bits)", "#0f766e"),
                    ("center_edge_delta", "Center-to-edge intensity", "#14b8a6"),
                ],
                "Texture organisation", "Time (days)", "Texture signal",
            ),
        ),
        ("05_area_circularity.png", "Area vs circularity", lambda ax: _plot_scatter(ax, df)),
        ("06_feature_correlation.png", "Feature correlation heatmap", lambda ax: _plot_heatmap(ax, df)),
    ]

    for filename, title, renderer in graph_specs:
        fig, ax = plt.subplots(figsize=(8.5, 4.5))
        renderer(ax)
        path = assets_dir / filename
        _save_figure(fig, path)
        sections.append({"title": title, "image": path.name})

    # Area distribution
    fig, ax = plt.subplots(figsize=(8.5, 4.5))
    if not df.empty:
        bins = min(8, max(3, len(df)))
        ax.hist(df["area"], bins=bins, color="#6366f1", alpha=0.85, edgecolor="white")
        ax.grid(alpha=0.2)
    else:
        ax.text(0.5, 0.5, "No data", ha="center", va="center")
    ax.set_title("Area distribution")
    ax.set_xlabel("Area (mm²)")
    ax.set_ylabel("Image count")
    path = assets_dir / "07_area_distribution.png"
    _save_figure(fig, path)
    sections.append({"title": "Area distribution", "image": path.name})

    # Summary tables
    _save_table_figure(
        assets_dir / "08_table_morphology.png",
        "Per-image morphology and QC",
        df,
        ["filename", "day", "area", "diameter", "perimeter", "eccentricity", "qc_status"],
    )
    _save_table_figure(
        assets_dir / "09_table_texture.png",
        "Per-image texture metrics",
        df,
        ["filename", "entropy", "center_edge_delta", "density_index"],
    )
    _save_table_figure(
        assets_dir / "10_table_growth.png",
        "Per-image crack and growth metrics",
        df,
        ["filename", "crack_coverage", "relative_growth_rate", "area_growth_rate"],
    )

    return sections

generate_report

generate_report(run_dir, experiment_override='')

Generate matplotlib report assets from a saved run directory.

The run_dir must contain analysis.json and manifest.json. Returns a dict with paths to generated assets.

Source code in metrics_petri/pipeline/reporting.py

def generate_report(
    run_dir: Path,
    experiment_override: str = "",
) -> dict[str, Any]:
    """Generate matplotlib report assets from a saved run directory.

    The run_dir must contain analysis.json and manifest.json.
    Returns a dict with paths to generated assets.
    """
    results = _read_json(run_dir / "analysis.json")
    if not isinstance(results, list):
        raise ValueError("analysis.json must contain a list of results")

    df = _build_dataframe(results)
    assets_dir = run_dir / "report_assets"
    sections = write_graphs(results, df, assets_dir)

    manifest_path = run_dir / "manifest.json"
    manifest = _read_json(manifest_path) if manifest_path.exists() else {}
    experiment_name = experiment_override.strip() or str(
        manifest.get("metadata", {}).get("experiment_name", "") or ""
    ).strip()

    record = {
        "runId": run_dir.name,
        "generatedAt": datetime.now(timezone.utc).isoformat(),
        "assetsDir": str(assets_dir),
        "graphCount": len(sections),
        "experimentName": experiment_name,
        "sections": sections,
    }
    (run_dir / "report_bundle.json").write_text(
        json.dumps(record, indent=2), encoding="utf-8"
    )
    return record