ybkim95's picture
Create codas_engine/reporting.py
44de70a verified
Raw History Blame Contribute Delete
4.47 kB
"""Deterministic report assembly grounded in the CoDaS Fact Sheet."""
from __future__ import annotations
from collections import Counter
from .models import BiomarkerCandidate, DatasetProfile
def _status_label(verdict: str) -> str:
if verdict == "validated":
return "battery-passing"
if verdict == "conditional":
return "conditional"
if verdict == "rejected":
return "failed internal gate"
return verdict or "not tested"
def build_fact_sheet(
profile: DatasetProfile,
candidates: list[BiomarkerCandidate],
target_column: str,
ml_metrics: dict[str, float | int | str | None],
discovery_rounds: int,
feature_count: int,
battery_evaluated_count: int | None = None,
battery_passing_count: int | None = None,
) -> dict[str, object]:
verdicts = Counter(candidate.verdict for candidate in candidates)
reported_battery_passing = verdicts.get("validated", 0)
return {
"target_column": target_column,
"rows": profile.rows,
"columns": profile.columns,
"numeric_columns": len(profile.numeric_columns),
"candidate_features_screened": feature_count,
"reported_candidate_variants": len(candidates),
"candidate_features_reported": len(candidates),
"internal_battery_evaluated_variants": battery_evaluated_count or len(candidates),
"internal_battery_passing_variants_evaluated": battery_passing_count if battery_passing_count is not None else reported_battery_passing,
"reported_battery_passing_variants": reported_battery_passing,
"internal_battery_passing_variants": reported_battery_passing,
"conditional_candidates": verdicts.get("conditional", 0),
"rejected_candidates": verdicts.get("rejected", 0),
"discovery_rounds": discovery_rounds,
"ml_metric_name": ml_metrics.get("metric_name"),
"ml_metric_value": ml_metrics.get("metric_value"),
"ml_feature_count": ml_metrics.get("feature_count"),
"ml_cv_strategy": ml_metrics.get("cv_strategy"),
"ml_metric_null_mean": ml_metrics.get("null_metric_mean"),
"ml_metric_null_p95": ml_metrics.get("null_metric_p95"),
"ml_metric_vs_null_p": ml_metrics.get("metric_vs_null_p"),
"ml_above_chance": ml_metrics.get("above_chance"),
"ml_n_samples": ml_metrics.get("n_samples"),
"ml_low_confidence": ml_metrics.get("low_confidence"),
"ml_pr_auc": ml_metrics.get("pr_auc"),
"ml_positive_rate": ml_metrics.get("positive_rate"),
}
def candidate_table(candidates: list[BiomarkerCandidate], limit: int | None = None) -> str:
lines = [
"| Feature variant | Internal status | Spearman rho | q-value | Pass rate | Evidence |",
"| --- | --- | ---: | ---: | ---: | --- |",
]
for candidate in (candidates if limit is None else candidates[:limit]):
lines.append(
"| {feature} | {verdict} | {rho:.3f} | {q:.3g} | {rate:.0%} | {evidence} |".format(
feature=candidate.feature,
verdict=_status_label(candidate.verdict),
rho=candidate.rho,
q=candidate.q_value,
rate=candidate.pass_rate,
evidence=candidate.evidence.replace("validation checks", "audit checks"),
)
)
return "\n".join(lines)
def build_markdown_report(
fact_sheet: dict[str, object],
candidates: list[BiomarkerCandidate],
warnings: list[str],
) -> str:
lines = [
"# CoDaS Report",
"",
"## Fact Sheet",
"",
]
for key, value in fact_sheet.items():
# Round floats so the report doesn't show noise like 0.802005643204628 (a skeptical
# reviewer reads 15-decimal values as sloppy); 4 significant figures is plenty here.
if isinstance(value, float):
value = f"{value:.4g}"
lines.append(f"- `{key}`: {value}")
lines.extend([
"",
"## Biomarker Candidates",
"",
candidate_table(candidates),
"",
"## Interpretation Boundary",
"",
"These findings are internally audited, hypothesis-generating associations. They do not establish clinical validation, external replication, diagnostic utility, or causality.",
])
if warnings:
lines.extend(["", "## Warnings", ""])
lines.extend([f"- {warning}" for warning in warnings])
return "\n".join(lines)