Skip to content
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ Each release's notes. From 1.0.0 on, a major or minor release has hand-written n

## Unreleased

- The CPIC report no longer calls a gene normal when PharmCAT never read a position that defines one of its alleles. PharmCAT calls a gene from the positions it read, so an exome that misses CYP2C19 \*2's site got `*1/*1`, Normal Metabolizer, and step 27 (`og pgx cpic-report`) gave the normal-function answer. Step 27 now reads the positions PharmCAT's `report.json` lists with no call. Such a gene gets the status `incomplete` in step 27's phenotypes table, with the mark `[incomplete: positions not read: ...]` on its phenotype. It is listed in a new section, "Genes Called With Positions Not Read", with every unread position, and it gets no drug guidance. A non-normal call with an unread position keeps its drug list and gets the same mark. `summary.json` counts these genes under `sections.cpic.data.incomplete`, a key written only when there is one. A whole genome where PharmCAT read every position gets the same report as before.
- The E2E run dispatched on a batch of pull requests finishes sooner, with every case and check it ran before. The shard split now weighs `prs-3-panel-measure` at its measured 2900 seconds on a run dispatched on a branch (`E2E_SECONDS`), where it measures the 1000 Genomes panel, so its shard no longer gets a full share of other cases on top. The base leg sets up while `og` builds, and the job `og` builds only the Linux x86_64 binary the legs run (`OG_ARCHES`, `OG_DARWIN_ARCHES` in `rust/og.sh`); Guard's `rust` job still builds all four on every pull request, as does the Rust `images` job when it runs. The nightly Rust run, which is the `streams` job only, now builds only `og-linux-x86_64`, the binary it runs. Container Test runs at most 8 smoke rows at once, so a change to every image no longer takes the runners the E2E legs wait for. The jobs that only build `og --release` lose their Rust cache, which did not speed them up, and Guard's `rust` job saves its cache on main only, so the E2E image and data caches fit the 10 GB budget.
- The carrier list in `summary.json` keeps each hit's call quality and zygosity. It judged every hit at GQ 30 and DP 10, whatever floor the hits file states (`##PGP_CALL_FLOOR`), and it dropped the low-confidence mark the ClinVar section shows for the same hit. Each row of `sections.carrier.data` now has `zygosity` (`het`, `hom`, `hemizygous` or `unknown`), `gq`, `dp` and `low_confidence`, judged against the file's own floor. A homozygous or hemizygous P/LP row has no unchanged copy, so it is no carrier finding: it moves from `carriers` to a new list, `hom_or_hemizygous`. Both reports still print it in the carrier list, on a line of its own that says it is not the pattern of a carrier, and the list's first line counts it apart (`2 with no unchanged copy`); the live page keeps its finding for it, and its carrier headline (the Python server's and `og live serve`'s) asks for attention. Two different heterozygous hits in one recessive gene are now counted as copies, with the phase rule of the secondary-findings card: each row gets `pair` (`two hits` when read-backed phase puts them on different copies, `possible two hits` when the phase is unknown; none when they sit on one copy) and `phase`, which says why. The carrier list and the secondary-findings card now count a gene's hits the same way, twice: with every call, and with the confident calls alone. A pair that the confident calls prove stays `two hits` on the list and `biallelic` on the card, even when another hit of the gene is a low-confidence call; so does a confident homozygous call or a confident deletion pair. When the confident hits count two copies of unknown phase, the pair is `possible two hits` on the list and `possibly biallelic` on the card, even when a low-confidence call would prove it. Any other pair that needs a low-confidence call is `possible two hits (low-confidence call)` on the list and `possibly biallelic (low-confidence call)` on the card. On the card a low-confidence call is one below step 06's call floor or a weak HIGH-impact call (`weak_call`). A deletion plus a low-confidence call reads `possibly biallelic (low-confidence call)` under `two_hits` and on the card's two-hit line. A combined allele counts as confident when any call of it is, and it then counts with the copies, GT and phase set of that confident call, beside a deletion too. The list's `pair` counts heterozygous hits only. For a recessive gene that the card counts by two copies (MUTYH, ATP7B, CYP27A1, GAA, RPE65, CASQ2, TRDN, and BTD apart from its hypomorph), the two give the gene the same answer, apart from rare deletion shapes where the card is more cautious (a combined allele across a deletion's end) and from a call the card judges by its HIGH-impact record (a lower call floor in the clinical VCF, or a HIGH-impact call of a part of a combined allele): on the list, that answer is the best of `pair`, the gene's `two_hits` verdict and its `hom_or_hemizygous` rows. Output change: rows move from `carriers` to `hom_or_hemizygous`, and fields are added; no field is renamed or removed. `tests/schema/summary.schema.json` now describes the carrier section. Part of #411 (clin-15, clin-19).
- A step you selected that produced nothing now says so. A report-only Nextflow step (TelomereHunter, VNtyper, the CHIP genes and the others in `nextflow.config`) is dropped when it fails, after one retry when the exit was a memory kill. Its section had no file, so the report listed it as not run, the same as a step nobody asked for. `HTML_REPORT` now records the run's `--tools` list, and `og summary collect` lists selected sections with no file under Steps Not Run as "(selected, no result)", with a note naming the tool and the step. Y haplogroup, Y tree placement, and Y-STR markers get this label only for samples declared male. `summary.json` gets a new top-level list, `selected_no_result`, with those section keys. It is present only when the run recorded its tool list, so a bash run's summary is unchanged. The section's state stays `missing`.
Expand Down
2 changes: 1 addition & 1 deletion docs/07-pharmacogenomics.md
Original file line number Diff line number Diff line change
Expand Up @@ -124,7 +124,7 @@ docker run --rm \
- **HLA-A, HLA-B and CYP2D6** are not called from a VCF: PharmCAT 3.4.0 reports them with no result (`callSource` `NONE`). [Step 36](36-pgx-consensus.md) gives PharmCAT T1K's HLA types (step 8) and a CYP2D6 call only when pypgx (step 32) and Cyrius (step 21, opt-in) agree on depth that passed its check; PharmCAT reads them with `-po` (`callSource` `OUTSIDE`). Run step 36 before this step, or run this step again after it. A disagreement, or one caller alone, leaves CYP2D6 without a result, on purpose.
- **MT-RNR1** is an outside call from step 20's chrM calls (see above): PharmCAT 3.4.0 does not call it from a VCF. A heteroplasmic named allele, such as m.1555A>G at AF 0.4, is passed and gets the aminoglycoside recommendation; the PharmCAT report does not show its AF, the step log does. A named allele below AF 0.05 is not passed. With no other named allele called, the gene stays No Result and the step log names the allele and its AF as below the detection floor. At that level the call cannot be told from noise or NuMT reads, so it is not called absent either.
- **CYP4F2 can come out No Result** when unphased heterozygous calls elsewhere in the gene, a weak one among them, leave no diplotype that matches. CPIC's warfarin guidance needs only the \*3 position (rs2108622). Step 27 then reads the genotype PharmCAT itself lists at that position in `report.json` (the gene's `variants`) and prints it in a section headed "Single-Position Fallback (not a PharmCAT call)", with the CPIC warfarin rule when you carry the variant. It does the same for VKORC1 at rs9923231 (-1639G>A). PharmCAT's own result for the gene stays No Result in the phenotypes table. A position with no genotype is reported as not callable. The report carries no GQ or read depth for the position: check it in your VCF before acting on it.
- **Exome input.** An exome reads the coding exons and little else, and some defining variants sit outside them: CYP2C19 \*17 in the promoter, CYP3A5 \*3 and CYP3A4 \*22 in introns, UGT1A1 \*80 and \*28 in the promoter, and others. PharmCAT drops a position it has no call for, so it cannot call an allele defined there. When the positions it did read match the reference, the gene can come out as a normal-function call such as \*1/\*1, and step 27 gives the normal-function recommendation. Step 27's CPIC report does not mark such a gene as incomplete. The positions PharmCAT had no call for are in `${SAMPLE}.missing_pgx_var.vcf`: check it before you act on a call from an exome. The [WES guide](wes-guide.md#drug-gene-answers-on-an-exome) lists the positions a typical capture misses, gene by gene.
- **Exome input.** An exome reads the coding exons and little else, and some defining variants sit outside them: CYP2C19 \*17 in the promoter, CYP3A5 \*3 and CYP3A4 \*22 in introns, UGT1A1 \*80 and \*28 in the promoter, and others. PharmCAT drops a position it has no call for, so it cannot call an allele defined there. When the positions it did read match the reference, the gene can come out as a normal-function call such as \*1/\*1. Step 27 reads the positions PharmCAT lists with no call and marks such a gene `incomplete`, not `normal`: it names the unread positions and gives no drug guidance for it ([step 27](27-cpic-lookup.md#what-the-script-does-internally), point 4). A non-normal call with an unread position keeps its drug list and gets the same mark. The positions PharmCAT had no call for are also in `${SAMPLE}.missing_pgx_var.vcf`: check it before you act on a call from an exome. The [WES guide](wes-guide.md#drug-gene-answers-on-an-exome) lists the positions a typical capture misses, gene by gene.
- PharmCAT may disagree with lab reports on complex haplotypes (e.g., NAT2). Discrepancies can arise from different genome builds (hg19 vs hg38), different star allele definitions, or different variant calling pipelines. When a discrepancy matters clinically, compare both sets of raw variant calls and consult the PharmVar database for the current allele definitions — do not blindly trust either source.
- PharmCAT output structure changes across releases. If you upgrade PharmCAT, re-test step 27 (`27-cpic-lookup.sh`) because it parses the JSON output directly.

Expand Down
Loading
Loading