v1.6.1: zygosity column, CADD fixes, methylation panel, config UX (#44)

Closes #31, #41, #42, #43, #45.

Author: dial481

CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.6.1]
+
+### Added
+- **Zygosity column in all report outputs (#41).** Every annotation row
+  now shows `Heterozygous`, `Homozygous`, or `No Call` — derived from
+  the genotype call. Appears in HTML, terminal, and JSON reports.
+  Functional-medicine `+/−` notation deferred until the risk allele
+  field lands (v2.1+).
+- **CADD PHRED styling in HTML reports (#42).** CADD scores are now
+  color-coded by deleteriousness tier: red (≥30, top 0.1%), orange
+  (≥20, top 1%), gray (10–20, top 10%), gray (<10, no tooltip).
+  Tooltip shows the percentile tier on hover for scores ≥10.
+- **Config file path in `config get` / `config set` output (#43).**
+  Both commands now print the resolved config file path, so users know
+  which file is being read or written.
+
+### Changed
+- **JSON schema version bumped to 4.** New `zygosity` field on every
+  annotation. Diff between v1–v4 reports still works.
+- **Methylation panel expanded to 34 genes (#31).** Added ACAT1, DHFR,
+  GNMT, MAOA, NOS3, SUOX, VDR. Sorted alphabetically.
+
+### Fixed
+- **CADD multi-allelic scoring bug (#45).** At multi-allelic positions,
+  `_enrich_cadd` max-reduced CADD PHRED across all alts, stamping the
+  highest score regardless of which allele the user carries. Now looks
+  up the score for the user's specific allele (direct match preferred
+  over complement). Biallelic sites were unaffected.
+- **Test protocol AM column name.** `FULL_TEST_PROTOCOL.md` referenced
+  "AM Score" but the actual HTML header is "AM".
+
 ## [1.6.0]
 
 ### Added
@@ -1529,6 +1560,7 @@ All notable changes are documented here. Format follows [Keep a Changelog](https
 - GitHub Actions CI matrix on Python 3.11 and 3.12.
 
 
+[1.6.1]: https://github.com/dial481/allelix/compare/v1.6.0...v1.6.1
 [1.6.0]: https://github.com/dial481/allelix/compare/v1.5.3...v1.6.0
 [1.5.3]: https://github.com/dial481/allelix/compare/v1.5.2...v1.5.3
 [1.5.2]: https://github.com/dial481/allelix/compare/v1.5.1...v1.5.2

allelix/cli.py

@@ -1306,6 +1306,7 @@ def config_get(data_dir: Path | None, key: str | None) -> None:
     cfg = load_config(resolved)
 
     if key is None:
+        console.print(f"[dim]Config: {resolved / 'config.toml'}[/dim]")
         click.echo(_serialize(cfg))
         return
 
@@ -1397,6 +1398,7 @@ def config_set(data_dir: Path | None, key: str, value: str) -> None:
         )
 
     save_config(resolved, cfg)
+    console.print(f"[dim]Config: {resolved / 'config.toml'}[/dim]")
     console.print(f"[green]Set {key} = {val_lower}[/green]")
 
 

allelix/models.py

@@ -105,3 +105,13 @@ class Annotation:
     am_pathogenicity: float | None = None
     am_class: str = ""
     cadd_phred: float | None = None
+
+    @property
+    def zygosity(self) -> str:
+        """Classify the genotype call as Heterozygous, Homozygous, or No Call."""
+        if NO_CALL_MARKER in self.genotype_match:
+            return "No Call"
+        parts = self.genotype_match.split("/")
+        if len(parts) != 2:
+            return "Homozygous" if len(set(self.genotype_match)) == 1 else "Heterozygous"
+        return "Heterozygous" if parts[0] != parts[1] else "Homozygous"

allelix/reports/_pipeline.py

@@ -231,6 +231,28 @@ def rollup_gwas_duplicates(annotations: list[Annotation]) -> list[Annotation]:
     return survivors
 
 
+def _lookup_user_allele(
+    user_alt: str,
+    coords: list[tuple[str, int, str, str]],
+    scores: dict[tuple[str, int, str, str], float],
+    resolve_strand: Callable[[str, str, str], str | None],
+) -> float | None:
+    """Find the CADD score for a specific user allele at a multi-allelic site.
+
+    Prefers a direct allele match over a complement (minus-strand) match
+    to avoid false positives where the complement of the user's allele
+    coincidentally equals a different alt at the same position.
+    """
+    for chrom, pos, ref, alt in coords:
+        if user_alt == alt:
+            return scores.get((chrom, pos, ref, alt))
+    for chrom, pos, ref, alt in coords:
+        resolved = resolve_strand(user_alt, ref, alt)
+        if resolved is not None and resolved == alt:
+            return scores.get((chrom, pos, ref, alt))
+    return None
+
+
 def _enrich_cadd(
     annotations: list[Annotation],
     gnomad: GnomadAnnotator,
@@ -260,18 +282,16 @@ def _enrich_cadd(
         coords = coord_map.get(a.rsid)
         if not coords:
             continue
-        best: float | None = None
-        for chrom, pos, ref, alt in coords:
-            if a.alt:
-                resolved = resolve_strand(a.alt, ref, alt)
-                if resolved is None:
-                    continue
-                score = scores.get((chrom, pos, ref, resolved))
-            else:
+        if a.alt:
+            score = _lookup_user_allele(a.alt, coords, scores, resolve_strand)
+            a.cadd_phred = score
+        else:
+            best: float | None = None
+            for chrom, pos, ref, alt in coords:
                 score = scores.get((chrom, pos, ref, alt))
-            if score is not None and (best is None or score > best):
-                best = score
-        a.cadd_phred = best
+                if score is not None and (best is None or score > best):
+                    best = score
+            a.cadd_phred = best
 
 
 def run_analysis(

allelix/reports/diff.py

@@ -25,7 +25,7 @@
 
     from allelix.models import Annotation
 
-_SUPPORTED_SCHEMA_VERSIONS = {"1", "2", "3"}
+_SUPPORTED_SCHEMA_VERSIONS = {"1", "2", "3", "4"}
 
 
 @dataclass

allelix/reports/html.py

@@ -108,6 +108,9 @@
 .am-benign { color: #2e7d32; font-weight: 600; }
 .am-ambiguous { color: #f9a825; font-weight: 600; }
 .am-score { color: #999; }
+.cadd-high { color: #c62828; font-weight: 600; }
+.cadd-med { color: #e65100; font-weight: 600; }
+.cadd-low { color: #999; }
 tr.diff-new { background: #e8f5e9; }
 tr.diff-changed { background: #fff3e0; }
 tr.diff-removed { background: #fafafa; text-decoration: line-through; color: #999; }
@@ -306,7 +309,15 @@ def _format_cadd(score: float | None) -> str:
     """Format a CADD PHRED score for display."""
     if score is None:
         return "—"
-    return f"{score:.1f}"
+    if score >= 30:
+        css, tip = "cadd-high", "top 0.1% most deleterious"
+    elif score >= 20:
+        css, tip = "cadd-med", "top 1% most deleterious"
+    else:
+        css, tip = "cadd-low", "top 10% most deleterious" if score >= 10 else ""
+    if tip:
+        return f'<span class="{css}" title="{tip}">{score:.1f}</span>'
+    return f'<span class="{css}">{score:.1f}</span>'
 
 
 def _row_html(
@@ -346,6 +357,7 @@ def _row_html(
         f'<span class="bar" style="width: {bar_width}px;"></span>'
         f"{a.magnitude:.1f}</td>"
         f"<td>{_escape(a.genotype_match)}</td>"
+        f"<td>{_escape(a.zygosity)}</td>"
         f"{freq_td}"
         f"{am_td}"
         f"{cadd_td}"
@@ -510,7 +522,7 @@ def _th(label: str) -> str:
             "<table>"
             "<thead><tr>"
             f"{_th('rsID')}{_th('Gene')}{_th('Source')}{_th('Significance')}"
-            f"{review_th}{_th('Magnitude')}{_th('Genotype')}"
+            f"{review_th}{_th('Magnitude')}{_th('Genotype')}{_th('Zygosity')}"
             f"{freq_th}"
             f"{am_th}"
             f"{cadd_th}"

allelix/reports/json_report.py

@@ -5,7 +5,7 @@
 Output schema (versioned via `schema_version`):
 
     {
-      "schema_version": "3",
+      "schema_version": "4",
       "allelix_version": "1.1.0",
       "generated_at": "2026-05-11T12:34:56+00:00",
       "regulatory_notice": "...",
@@ -52,12 +52,13 @@
     from allelix.reports.diff import DiffResult
 
 
-SCHEMA_VERSION = "3"
+SCHEMA_VERSION = "4"
 
 
 def _annotation_dict(a: Annotation) -> dict:
     """Serialize an annotation, adding AM caveat for non-protein sources."""
     d = {k: v for k, v in asdict(a).items() if k != "is_must_include"}
+    d["zygosity"] = a.zygosity
     if a.am_pathogenicity is not None and a.source == "pharmgkb":
         d["am_caveat"] = "protein structure impact only"
     return d

allelix/reports/methylation.py

@@ -12,32 +12,39 @@
 # Folate / one-carbon / methylation cycle genes. Add via PR + ADR if expanding.
 METHYLATION_PANEL_GENES: frozenset[str] = frozenset(
     {
-        "MTHFR",
-        "MTR",
-        "MTRR",
-        "COMT",
-        "CBS",
+        "ACAT1",
+        "AHCY",
         "BHMT",
         "BHMT2",
-        "MTHFD1",
-        "MTHFD1L",
-        "AHCY",
-        "MAT1A",
-        "MAT2A",
-        "MAT2B",
-        "TCN1",
-        "TCN2",
-        "FUT2",
-        "GSTM1",
-        "GSTP1",
+        "CBS",
+        "COMT",
+        "DHFR",
         "DNMT1",
         "DNMT3A",
         "DNMT3B",
-        "PEMT",
         "FOLR1",
         "FOLR2",
-        "SLC19A1",
+        "FUT2",
+        "GNMT",
+        "GSTM1",
+        "GSTP1",
+        "MAOA",
+        "MAT1A",
+        "MAT2A",
+        "MAT2B",
+        "MTHFD1",
+        "MTHFD1L",
+        "MTHFR",
+        "MTR",
+        "MTRR",
+        "NOS3",
+        "PEMT",
         "SHMT1",
         "SHMT2",
+        "SLC19A1",
+        "SUOX",
+        "TCN1",
+        "TCN2",
+        "VDR",
     }
 )

allelix/reports/terminal.py

@@ -164,6 +164,7 @@ def _print_table(filtered: list[Annotation], console: Console) -> None:
     table.add_column("Review Status", style="dim")
     table.add_column("Magnitude", justify="right")
     table.add_column("Genotype", no_wrap=True)
+    table.add_column("Zygosity", no_wrap=True)
     if has_freq:
         table.add_column("Freq", justify="right", no_wrap=True)
     if has_am:
@@ -181,6 +182,7 @@ def _print_table(filtered: list[Annotation], console: Console) -> None:
             a.review_status or "—",
             f"{a.magnitude:.1f}",
             a.genotype_match,
+            a.zygosity,
         ]
         if has_freq:
             row.append(_format_freq(a.allele_frequency))

docs/adr/0033-schema-version-bump-policy.md

@@ -0,0 +1,34 @@
+# ADR-0033: Schema Version Bump Policy
+
+**Status:** Accepted
+**Date:** 2026-06-11
+**Supersedes:** The schema-version carve-out in ADR-0032 (Context section,
+"JSON schema version stays at 3").
+
+## Context
+
+ADR-0032 stated that additive optional fields (specifically `cadd_phred`)
+do not require a schema version bump. v1.6.1 adds `zygosity`, also an
+additive optional field, and bumps the schema to version 4. The two
+decisions are inconsistent.
+
+## Decision
+
+Every new field emitted in JSON report output bumps the schema version,
+even if the field is optional and additive. This gives consumers a
+reliable signal that the output shape changed.
+
+The `cadd_phred` addition in v1.6.0 should have bumped the schema from
+2 to 3 under this policy. It did not (ADR-0032 carved it out). That
+ship has sailed — v1.6.0 emits schema version 3 with `cadd_phred`
+present, and changing it retroactively would break existing consumers.
+Going forward, all new fields bump.
+
+## Consequences
+
+- Any commit that adds, removes, or renames a field in the JSON report
+  output must increment `_SCHEMA_VERSION` and update
+  `_SUPPORTED_SCHEMA_VERSIONS` in the diff loader.
+- The diff loader's supported-versions set grows monotonically.
+- ADR-0032's body is not edited (ADR immutability). This ADR supersedes
+  its schema-version stance.