Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,8 @@ Each release's notes. From 1.0.0 on, a major or minor release has hand-written n
- `og y private-snps` drops a call as public only when a table names the same change at that position (the same two bases, either order). Another base at a known position is a new mutation and stays in the list. A VCF with more than one sample is read only when `--sample` names one of its columns, and refused otherwise; before, the scan read the first column, which could be another man's. The file's columns do not change.
- HLA-B drug answers no longer depend on the order T1K prints tied alleles. T1K writes equally likely candidates of one allele comma-separated, with one quality. Step 36 (`og pgx outside-calls`) cut the whole field to two fields, so PharmCAT got whichever candidate T1K printed first: a B\*57:01/B\*58:01 tie passed as B\*57:01 in one order and B\*58:01 in the other, which flips abacavir and allopurinol guidance. Now each candidate is read. When the tie, or an allele with an expression suffix (`N` null, `Q` questionable), leaves open whether HLA-A\*31:01, HLA-B\*15:02, \*57:01 or \*58:01 is there, the gene is `indeterminate`, is not passed, and its reason reads `ambiguous: B*57:01 possible, B*58:01 possible (T1K ties *57:01 and *58:01 on one allele)`. An OptiType call that matches one candidate does not decide it. A tie or a null that names none of those alleles still passes the gene, so a sure B\*57:01 on the other copy is not lost; the reason names the stand-in. Two-field names keep their expression suffix (`*02:53N`), so a T1K null no longer agrees with OptiType's expressed `*02:53` in step 08's concordance table, which also lists tied candidates comma-separated. OptiType never calls a null, so step 36 still compares it with the names PharmCAT reads and passes such a pair; the table's note says so. `summary.json`'s `withheld_from_pharmcat` follows the same rule, and the HLA allele table reads a null form of an allele (`B*57:01:01N`) as uncertain, not present. `og summary collect` also finds `bin/hla_alleles.tsv` beside its `--assets` folder, so a binary outside the checkout run from another folder no longer reads the HLA section as unreadable. No option, file or column changes; only these values do, and every input without a tie or a suffix gives the same bytes as before. When pypgx and Cyrius agree on CYP2D6 with a passed depth check, the call is still passed whatever pypgx's `Defining_filter` and `Quality` say; a cargo test now pins that rule. The docs no longer call OptiType independent: both callers read the same alignment, so their agreement is extra evidence, not validation.
- Step 20's section of `summary.json` flags the heteroplasmic calls that PASS alone does not make reliable, and keeps them counted. A call whose bases touch either end of the control region (m.1-500 or m.16000-16569, where reads that span the origin of the circular reference align poorly) gets `origin_edge`. A call under 0.10 AF, the low-level range where missed NuMT reads look like calls, gets `low_af`. Before, both read like every other PASS call, ClinVar class included. Each entry of `heteroplasmic_sites` and each row of `annotation.variants` now carries both flags, and `heteroplasmic_origin_edge` and `heteroplasmic_low_af` count the flagged calls beside the `heteroplasmic` total, with `origin_edge_regions` and `low_af_ceiling` naming the limits. No call leaves a count or a list: a PASS m.3243A>G at AF 0.07 carries `low_af` and is still in the ClinVar pathogenic count and the confirmed variants. Fields are only added; none is renamed or removed. The reports do not show the flags yet.
- Step 20 now finds the ClinVar and gnomAD record of a mitochondrial indel wherever in its repeat each side writes it. `og mito annotate` matched an indel only on the exact spelling, and looked for ClinVar's record at most one base away. An indel in a homopolymer can be written at any place in it, so one C more in the m.311-315 tract, written m.315C>CC by one side and m.310T>TC by the other, got no ClinVar class and no gnomAD frequency. When the exact spelling finds nothing, the allele is now moved to the left end of its repeat on the rCRS (GRCh38's chrM) and matched there, on both sides; an exact match still wins, and an allele whose REF, as written, is not the rCRS is not moved. `<id>_chrM_annotated.tsv` keeps its columns, and each row keeps the call's trimmed position, REF and ALT as before, never the moved spelling; only `.` cells can now hold a value. Part of #411 (lin-35).
- Step 20 and the Nextflow run (on the console, when it starts) warn when the NuMT filter had no autosomal depth (no mosdepth output, and no `AUTOSOMAL_COVERAGE` in step 20), so it ran at depth 0 and marked nothing, and the annotation table says so. `og mito annotate` has a new switch, `--numt-default`, which adds a `# numt` header line that reads `NuMT filter used a default depth` to `<id>_chrM_annotated.tsv`; step 20 and `MITO_VARIANTS_ANNOTATE` pass it in that case. A run with a depth writes the table as before. The reports do not show the line yet. Part of #411 (lin-32).
- The run manifest stays whole when two scripts write it at once. `bin/write_manifest.sh` built every manifest in one shared file, `run_manifest.tsv.tmp`. When a run and a report script wrote one sample's manifest at the same time, each emptied and appended to the other's file, and the manifest that landed had rows missing or repeated. Each writer now builds its manifest in a temporary file of its own beside `run_manifest.tsv` and renames it into place, so the manifest is always one writer's whole manifest. A writer that stops early removes its temporary file. `tests/test_write_manifest.sh` runs three writers at once; its control copy with the shared name breaks the manifest. The manifest's rows and format do not change.
- The delta report words each reason it gives for a changed result as a guess. The "why" of a change read `changed inputs: VEP_CACHE_RELEASE 115 -> 116`, which reads as the cause. The delta only knows which inputs changed and which inputs feed the section, so it now reads `likely from changed inputs: VEP_CACHE_RELEASE 115 -> 116`, in `<sample>_delta.json`, `.txt` and `.html`. The line for a result whose tracked inputs did not change names no cause and stays as it was. No file, field or column changes; only the text of `why`.
- Step 46's LPA KIV-2 message now says what its interval covers and what the count adds up. It read `about N KIV-2 repeats in total (95% interval LOW to HIGH)`, which looked like a calibrated range for one chromosome. The interval comes only from how the depth varies between exons, read as independent, so it covers read sampling and leaves out any aligner or library bias; the count is the total over both copies of chromosome 6. The message is now `about N KIV-2 repeats in total over both copies (95% interval for read sampling, LOW to HIGH; aligner or library bias not included)`, then the class reading as before. Only the `message` value of `lpa/<sample>_lpa_kiv2.tsv` and the step's stdout line change; the columns `kiv2_copies`, `ci95_low` and `ci95_high` keep their names and values.
Expand Down
4 changes: 2 additions & 2 deletions docs/20-mtoolbox.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ The last stage (`og mito annotate`, in `PYTHON_IMAGE`) writes `${SAMPLE}_chrM_an
- ClinVar's record of the same allele from `clinvar/clinvar_chr.vcf.gz`, the ClinVar file `setup.sh` installs: `clinvar_id`, `clinvar_significance` (CLNSIG), `clinvar_review` (CLNREVSTAT) and `clinvar_condition` (CLNDN);
- gnomAD v3.1's chrM sites of the same allele (`gnomad_mito/`, pinned in `versions.env`): `gnomad_af_hom` (the share of gnomAD's samples with the allele at 95% or more), `gnomad_af_het` (at 10% to 95%) and `gnomad_max_hl` (the highest level gnomAD saw).

Alleles are matched by position, REF and ALT after the bases they share are trimmed, so Mutect2's multi-allelic indels meet ClinVar's and gnomAD's single-allele records. A file that is not installed leaves its columns `.`, and the table's first lines say which. The reports list each PASS call that is heteroplasmic, or that ClinVar classes as anything but benign (a record with no classification, `not_provided`, does not count), with these columns, and count the ClinVar pathogenic or likely pathogenic ones.
Alleles are matched by position, REF and ALT after the bases they share are trimmed, so Mutect2's multi-allelic indels meet ClinVar's and gnomAD's single-allele records. An indel in a repeat can be written at any place in it, so an indel that finds no record that way is moved to the left end of its repeat on the rCRS (GRCh38's chrM) and matched there, on both sides. One C more in the m.311-315 tract then meets its record whether either side writes it m.310T>TC or m.315C>CC. An exact spelling wins over a moved one, and an allele whose REF, as written, is not the rCRS at its position is not moved. The table writes each call's position, REF and ALT trimmed as above (Mutect2's m.302 AC>ACC reads m.302 A>AC), never the moved spelling. A file that is not installed leaves its columns `.`, and the table's first lines say which. The reports list each PASS call that is heteroplasmic, or that ClinVar classes as anything but benign (a record with no classification, `not_provided`, does not count), with these columns, and count the ClinVar pathogenic or likely pathogenic ones.

Step 13's VEP annotates the main VCF, whose chrM records come from the nuclear caller: a heteroplasmic call only Mutect2 makes has no VEP record, so this step annotates its own calls. In the Nextflow pipeline `MITO_VARIANTS_ANNOTATE` does the same after `MITO_VARIANTS`, with the files of `--mito_clinvar` and `--gnomad_mito`; without them its table names each file as not given and leaves its columns `.`.

Expand Down Expand Up @@ -100,7 +100,7 @@ The copy-number catalog (`bin/cn_loci.tsv`, [docs/cn-loci.md](cn-loci.md)) has n

### NuMTs

NuMTs are copies of mitochondrial DNA in the nuclear genome. Their reads can map to chrM and look like low-level heteroplasmy. GATK's NuMTFilterTool marks an allele `possible_numt` when its depth is no more than such copies could give at the sample's autosomal depth. The script reads the median autosomal depth from step 16b's mosdepth output (`mosdepth/<sample>.mosdepth.summary.txt` and `.global.dist.txt`), so run step 16b first; `AUTOSOMAL_COVERAGE=30` sets it by hand. Without either, the filter runs at depth 0 and marks nothing, and the step says so. The Nextflow `MITO_VARIANTS` runs the same filter with the same depth, read from `MOSDEPTH`'s output when `mosdepth` is in `--tools` (a default tool); without it, at depth 0.
NuMTs are copies of mitochondrial DNA in the nuclear genome. Their reads can map to chrM and look like low-level heteroplasmy. GATK's NuMTFilterTool marks an allele `possible_numt` when its depth is no more than such copies could give at the sample's autosomal depth. The script reads the median autosomal depth from step 16b's mosdepth output (`mosdepth/<sample>.mosdepth.summary.txt` and `.global.dist.txt`), so run step 16b first; `AUTOSOMAL_COVERAGE=30` sets it by hand. Without either, the filter runs at depth 0 and marks nothing. The step then prints a `WARNING`, and the annotation table gets a `# numt` header line that reads `NuMT filter used a default depth` (`og mito annotate --numt-default`). The Nextflow `MITO_VARIANTS` runs the same filter with the same depth, read from `MOSDEPTH`'s output when `mosdepth` is in `--tools` (a default tool). Without it the depth is 0: the run prints a warning on the console when it starts, and `MITO_VARIANTS_ANNOTATE` writes the same `# numt` line. The reports do not show that line yet.

## Output
- `${SAMPLE}_chrM_mutect2.vcf.gz` — Raw mitochondrial variant calls
Expand Down
13 changes: 9 additions & 4 deletions modules/local/mito_variants/main.nf
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,8 @@
the median autosomal depth, read from MOSDEPTH's summary and
global distribution with the awk of scripts/20-mtoolbox.sh. Without
mosdepth in --tools the depth is 0 and the filter marks nothing, as
step 20 does without step 16b's output.
step 20 does without step 16b's output: the task warns, and
MITO_VARIANTS_ANNOTATE writes the '# numt' line that says so.

MITO_VARIANTS_ANNOTATE, after it, annotates each call with its ClinVar
record and gnomAD v3.1's chrM sites (og mito annotate), as step 20's
Expand Down Expand Up @@ -93,7 +94,7 @@ process MITO_VARIANTS {
echo "Median autosomal coverage: \${AUTOSOMAL_COVERAGE} (from \${DEPTH_FILES})"
else
AUTOSOMAL_COVERAGE=0
echo "mosdepth is not in --tools: NuMTFilterTool runs at depth 0 and marks nothing"
echo "WARNING: mosdepth is not in --tools: NuMTFilterTool runs at the default depth 0 and marks nothing" >&2
fi
gatk NuMTFilterTool \\
-R ${reference} \\
Expand Down Expand Up @@ -133,7 +134,9 @@ process MITO_VARIANTS {
it) and gnomAD v3.1's chrM sites (AF_hom, AF_het, max_hl, from
--gnomad_mito, the file GNOMAD_MITO_URL in versions.env names), into
<id>_chrM_annotated.tsv. A file not given is named in the table's header
and its columns are '.', as step 20 does without it.
and its columns are '.', as step 20 does without it. Without mosdepth in
--tools MITO_VARIANTS had no autosomal depth for the NuMT filter, so the
table gets the '# numt' line (--numt-default), as step 20 writes it.

Equivalent to: stage 6 of scripts/20-mtoolbox.sh
*/
Expand All @@ -159,8 +162,10 @@ process MITO_VARIANTS_ANNOTATE {
script:
def cv = clinvar ? "--clinvar ${clinvar}" : ''
def gn = gnomad ? "--gnomad ${gnomad}" : ''
// MITO_VARIANTS gets mosdepth's output exactly when mosdepth is in --tools.
def numt = (params.tools ?: '').toString().split(',').collect { it.trim() }.contains('mosdepth') ? '' : '--numt-default'
"""
og mito annotate --vcf ${vcf} ${cv} ${gn} --out ${meta.id}_chrM_annotated.tsv
og mito annotate --vcf ${vcf} ${cv} ${gn} ${numt} --out ${meta.id}_chrM_annotated.tsv

printf '"%s":\\n python: %s\\n' "${task.process}" "${task.container.replaceFirst(/^[^:@]+[:@]/, '')}" > versions.yml
"""
Expand Down
Loading
Loading