File size: 4,467 Bytes
44de70a
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
"""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)