Skip to content

fix(pgx): require real depth before two CYP2D6 callers count as agreeing - #535

Open
geiresx wants to merge 3 commits into
GeiserX:mainfrom
geiresx:pgp/i411-cyp2d6-gate
Open

geiresx wants to merge 3 commits into
GeiserX:mainfrom
geiresx:pgp/i411-cyp2d6-gate

Conversation

@geiresx

@geiresx geiresx commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator

Problem

Step 36 passes a CYP2D6 call to PharmCAT when pypgx and Cyrius agree and the CYP2D6 depth check passed. That check looked only at the share of reads with MAPQ 0. Flanks at 6x, with every read mapped well, passed as "fit for a copy-number call". Two callers could then agree on too few reads, and their shared diplotype steered drug guidance.

The consensus table also hid weak pypgx evidence. When the variants that define pypgx's star alleles were not all PASS, or had a low GQ, an agreed call read the same as a well-supported one.

Fix

  • og pgx cyp2d6-check (rust/crates/og-bam/src/cyp2d6.rs) now also needs 10x or more in the flanks at MAPQ >= 1, the reads the callers use. 10x is the approved threshold (D10). Under it the status is unreliable and the message reads CYP2D6 copy number unreliable, agreement not counted (depth): .... Multi-mapped reads keep their own message and are named first, because realigning fixes that cause.
  • Every consumer already treats a non-ok status as a failed check. So pypgx's CYP2D6 row reads Indeterminate, Cyrius's call gets Filter CYP2D6_depth_unreliable, and step 36 withholds CYP2D6 with the message as its reason. No script or module changes.
  • og pgx outside-calls (rust/crates/og-steps/src/pgx_rules.rs) reads step 32's Defining_filter and Quality columns. When either is weak, the Evidence column reads pypgx: *1/*4, weak evidence (<the weak columns>). A call Cyrius agrees with is still passed: the flag shows the weakness, it does not withhold the call. A summary from before those columns gets no flag.
  • docs/32-pypgx.md, docs/21-cyrius.md, docs/36-pgx-consensus.md and the changelog say the same.

Output changes: no file name or column changes. The depth check's verdict on flanks under 10x is new (unreliable instead of ok), and the Evidence text of pgx_consensus.tsv gains the weak-evidence note.

Decisions:

  • The floor reads the MAPQ >= 1 flank depth, not the depth of all reads, because the callers ignore MAPQ 0 reads.
  • The gate lives in the depth check, not only in step 36. A check that says "fit for a copy-number call" at 6x would be false for pypgx alone too. So a shallow sample also loses pypgx's lone CYP2D6 call and its "probable" label in the reports.
  • No parity golden changes. Every committed depth table has flanks near 30x, and the multi-mapped case is named first, so og and the Python oracle still write the same bytes on every case. The e2e fixture has 29.6x flanks, so the pgx-cyp2d6-check shadow still agrees there. The shadow rule says a tool leaves OG_SHADOW once og differs from its oracle on purpose. .github/workflows/e2e.yml is not in this package's files, so the orchestrator should decide whether to drop it.

Left for a follow-up

These need files outside this package, so this PR does not touch them:

  • og pgx cyp2d6-check now differs from its Python oracle on purpose when the flanks are under 10x at MAPQ >= 1. It should leave OG_SHADOW in .github/workflows/e2e.yml, docs/testing.md should stop listing it as shadowed, and a shallow-flank parity case (q0/q1 tables with 6x flanks, inputs under tests/parity/inputs/pgx-cyp2d6-check/, a row in tests/parity/cases.tsv) with its golden under tests/parity/golden/pgx-cyp2d6-check/ should pin the difference. Nothing breaks today: every depth table and both fixture BAMs have flanks near 30x.
  • Some lines name multi-mapped reads as the only cause of an unreliable CYP2D6 depth check. They should add "or flanks under 10x at MAPQ >= 1": docs/lessons-learned.md, docs/releases/v1.0.0.md (which also says the og cyp2d6 ports write what the Python writes), and the comments in scripts/32-pypgx.sh, scripts/21-cyrius.sh, modules/local/pypgx/main.nf and modules/local/cyrius/main.nf.

How it was checked

e2e cases the batch tip must run: tests/e2e/pgx-1-depth-check.sh, tests/e2e/pgx-2-outside-calls.sh, tests/e2e/pypgx-cyp2d6-section-1-summary.sh, tests/e2e/hla-second-caller-1-bash.sh, tests/e2e/hla-second-caller-2-nextflow.sh, plus the e2e base (the shadow of pgx-cyp2d6-check).

Beads: pgx-09, pgx-01, D10 (the CYP2D6 flank threshold).

Summary by CodeRabbit

  • Behavior Updates
    • CYP2D6 calls are marked unreliable when flank coverage is below 10x at MAPQ ≥1, and are withheld from consensus. When both low coverage and multi-mapped reads are present, the multi-mapped-read status takes precedence.
    • Weak pypgx filter or quality evidence is flagged in reports. Calls are still passed when pypgx and Cyrius agree and the depth check passes.
  • Documentation
    • Updated guidance to describe CYP2D6 depth requirements, status handling, and weak-evidence reporting.

The CYP2D6 depth check read only the share of MAPQ 0 reads, so flanks
at 6x with every read mapped well passed as fit for a copy-number call,
and two callers could agree on too few reads. Flanks under 10x at
MAPQ >= 1 now make the verdict unreliable, with the message "agreement
not counted (depth)". Multi-mapped reads are still named first.

Bead: pgx-09
Bead: D10
A pypgx CYP2D6 call whose defining variants are not all PASS, or not of
good quality, now reads "weak evidence (...)" in the Evidence column of
pgx_consensus.tsv. A call Cyrius agrees with is still passed: the flag
shows the weakness, it does not withhold the call.

Bead: pgx-01
…ypgx evidence shows

Bead: pgx-09
Bead: pgx-01
@coderabbitai

coderabbitai Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The CYP2D6 depth check now requires at least 10x flank coverage at MAPQ ≥ 1 and preserves multi-mapping precedence. The consensus code records weak pypgx filter or quality evidence while retaining its existing caller-agreement and depth-check gates.

Changes: CYP2D6 depth and consensus

Layer / File(s) Summary
Flank-depth verdict and gate
rust/crates/og-bam/src/cyp2d6.rs, rust/crates/og-bam/tests/i411_cyp2d6_gate.rs, docs/21-cyrius.md, docs/32-pypgx.md
The depth check marks MAPQ ≥ 1 flank coverage below 10x as unreliable. It checks for multi-mapped reads first. Unit and integration tests cover the 10x boundary and precedence.
Consensus evidence and depth handling
rust/crates/og-steps/src/pgx_rules.rs, docs/36-pgx-consensus.md, CHANGELOG.md
The consensus code includes nonaccepted pypgx filter or quality values in evidence without disqualifying an otherwise agreeing call. Tests cover weak evidence and withholding a call when the depth check fails.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Bug fix

Merge Risk: Minimal · up to 7e665

The CYP2D6 depth check now requires 10x flank depth at MAPQ ≥ 1, and weak pypgx evidence is flagged in the consensus table. No actionable merge-blocking risk was found.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title names the main change: the CYP2D6 depth gate now requires real flank depth before two callers count as agreeing. The raw summary confirms a 10x flank-depth requirement at MAPQ >= 1 that make…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Full details: Title check

Explanation

The title names the main change: the CYP2D6 depth gate now requires real flank depth before two callers count as agreeing. The raw summary confirms a 10x flank-depth requirement at MAPQ >= 1 that makes the agreement check return unreliable when depth is insufficient. The title's fix(pgx) prefix is a conventional commit type and does not hurt clarity. The title is 72 characters, within normal limits.

Finishing Touches

Generate unit tests (beta)

  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between fd81a5c and 7e6654e.

Files selected for processing: 7

  • CHANGELOG.md
  • docs/21-cyrius.md
  • docs/32-pypgx.md
  • docs/36-pgx-consensus.md
  • rust/crates/og-bam/src/cyp2d6.rs
  • rust/crates/og-bam/tests/i411_cyp2d6_gate.rs
  • rust/crates/og-steps/src/pgx_rules.rs

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

geiresx pushed a commit to geiresx/OwnGenome that referenced this pull request Nov 20, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants