QC Flags¶

Every flag, reason and class gbcms writes is defined here, once. Other pages include these tables (snippet sections of this file) or link to them, so a definition is written in one place. Three tests keep it that way: one fails when a flag the code emits is missing from this page, one when a flag is defined anywhere else in the docs, and one when the end-of-run summary's table (below) and this page's definitions differ.

Where flags appear. MAF columns are listed first, then the VCF field. In VCF, ; inside a value is written |. The run log ends with a summary of the flags that fired and the rows that need a look: End-of-run summary.

Verdict and status reasons¶

gbcms_status is the verdict: PASS (counted) or FAIL (not counted; zero counts, the row kept). gbcms_status_reason lists |-separated reasons, empty for a clean PASS; reasons stack (WARN_REF_CORRECTED|MULTI_ALLELIC), and the same string is in the VCF GSR INFO. How each is decided: Variant Normalization.

Diagnostics¶

gbcms_diagnostic (VCF GD) says what the reads, or the reference, show about a row. Semicolon-separated in MAF, | in VCF; empty when none. Set after counting on a PASS row; on a FAIL row only REF_AT_OFFSET. Parametric flags count under their base name in the run log. Examples: ZERO_ALT, PARTIAL_DOMINANT;MNP_DISC_RATIO(2/5);MNP_RESCUE_ELIGIBLE.

OBSERVED_ALLELE and COEXISTING_ALLELE both need n ≥ 3, n > m, n ≥ 5% of the scanned reads, and an allele that is not already an input row. One exception: at a deletion of 50 bp or more beside a run of its unit, another unit count present at its breakpoint (listed in the input, always; or, unlisted, spelled in full on 3 or more fragments the aligner places here) holds the row's ALT calls (RJ-24, rule X); where it takes one, it is named in the same form at the deletion's anchor, listed or not, with n the fragments fitting the ALT's windows whose ALT call it takes and m those that tell the given count from it (OBSERVED_ALLELE where m is 0). n and m are taken over the reads the counts read (first-class reads the mapping rule admits: in RNA a unique mapper, NH:i:1, below --min-mapq; under strandedness enforcement, sense reads only), so they compare with alt_count and ref_count.

Before 6.6.0 the scan used its own filter (not secondary, not supplementary, mapq >= min_mapq): it had no strand filter, so antisense reads that enforcement keeps out of the counts still entered n and m, and it did not keep the loop's NH:i:1 rescue. A review measured COEXISTING_ALLELE(...:16/12) with antisense reads present against 8/6 without them, both enforced. The diagnostic now shares the counting loop's admission rule (O8 #186, built in #217). Measured on FORTE: counts unchanged everywhere; the diagnostic changes on 1 exon-edge probe row (100/0 → 98/0) and 5 of 7,224 splice-probe rows. Other tools tally other alleles over the same filtered reads as their primary counts (bam-readcount, ASEReadCounter otherBases, VarDict).

MNP rescue¶

gbcms_rescue (VCF GR), with --rescue-mnp only, is an audit trail: method=decomposed;outcome=<outcome>;original_ref=R;original_alt=A;original_partial=P;original_confirmed=C[;adopted=chr:pos(R>A)][;positions=…]. See Architecture → MNP Rescue Pass.

ASJD splice flags¶

RNA with --gtf. asjd_diagnostic lists QC flags, semicolon-separated; counts are per fragment (a molecule's R1 and R2 are one vote). Motifs (asjd_ref_motif, asjd_alt_motif) are GT-AG, GC-AG, AT-AC, OTHER or UNKNOWN. The ASJD columns: Output Formats.

The floors are ASJD's own junction-evidence minimums (LOW_REF_JUNC / LOW_ALT_JUNC). When RETENTION_DOMINANT is present, any junction flags alongside it (NOVEL_ALT_JUNC, MULTI_JUNCTION, …) describe the allele-classified reads — by the marker's own condition the junction-bearing minority of an intron-retaining population — not the spliced majority, which only the ASJD-2 markers report.

QC columns¶

Columns whose value is itself a flag. Each column's place in the output is in Output Formats; this is its definition.

Merged output¶

gbcms merge writes a combined simplex_duplex_* cell as NA where it cannot add the two inputs' counts. The flag below is not a column: the end-of-run summary derives it from a merged MAF.

mFSD report classes¶

The --mfsd-report HTML grades each variant's fragment-size evidence (see mFSD Report): the ALT fragments against the REF fragments at the same locus in the same plasma sample. It is graded evidence, never an origin call; the KS threshold is on the BH-FDR q-value across the sample's variants (mfsd_qval_alt_ref), not the raw p-value. Nothing leans toward CH: at the fragment counts a targeted cfDNA panel produces, a tumor variant usually looks like REF too (on labeled ACCESS plasma, about 30% of tumor variants below 50 ALT fragments did), so similar sizes are no evidence for clonal hematopoiesis. Matched-normal (buffy coat) data decide CH; a CH-associated gene is shown as a note and changes nothing.

flowchart TD
    Start(["Variant"]) --> AltCheck{"ALT fragments ≥
--mfsd-report-min-alt?"}
    AltCheck -->|"No"| Insufficient(["INSUFFICIENT"]):::grey
    AltCheck -->|"Yes"| KSValid{"KS test ran?
(mfsd_ks_valid)"}
    KSValid -->|"No"| Insufficient
    KSValid -->|"Yes"| Shorter{"KS q < 0.05, ALT shorter
where the size distributions
differ most?"}
    Shorter -->|"Yes"| Somatic(["LEANS-SOMATIC"]):::green
    Shorter -->|"No"| None(["NO-SIZE-EVIDENCE"]):::blue

    classDef green fill:#27ae60,color:#fff,stroke:#1e8449,stroke-width:2px;
    classDef blue fill:#7f8c8d,color:#fff,stroke:#616a6b,stroke-width:2px;
    classDef grey fill:#95a5a6,color:#fff,stroke:#7f8c8d,stroke-width:2px;

Variants with fewer ALT fragments than --mfsd-report-min-alt are left out of the report.

In VCF, the mFSD summary is in INFO: MFSD_REF_COUNT, MFSD_ALT_COUNT, MFSD_REF_LLR, MFSD_ALT_LLR, MFSD_DELTA_ALT_REF, MFSD_KS_ALT_REF, MFSD_PVAL_ALT_REF, MFSD_QVAL_ALT_REF, MFSD_SUB_NUC_REF_FRAC, MFSD_SUB_NUC_ALT_FRAC, MFSD_SUB_NUC_ENRICHMENT, MFSD_MONO_NUC_REF_FRAC and MFSD_MONO_NUC_ALT_FRAC (Output Formats → INFO).

Record shapes in VCF output¶

End-of-run summary¶

At the end of every gbcms dna and gbcms rna run the log carries a QC summary: which flags fired, on how many rows, which rows need a look, and what to do about each. Most users read the counts and the VAF and never open the flag columns; the summary points to the few rows where that is not enough.

It reads the output the run has written, MAF or VCF, after writing it. It changes no count, column or row, writes no file and does not change the exit code. If a sample's output cannot be read, the run logs a warning and carries on; the sample is named in the block under "Not checked", with a sample that failed to count, and the closing line is a WARNING that says "k of n samples not checked", so an incomplete check never reads as a clean one.

Each flag is in one of three tiers. The first two are the rows that need a look.

For each tier the block gives the number of rows (a row with flags in two tiers is in both) and each flag that fired, most rows first. The first two tiers show a zero as none, so a clean run reads as one. It then names the first rows that need a look (input problems first) and the output fields to filter on for the rest. With several samples in one run the block combines them: each flag with the number of samples it fired in, and the samples with the most rows to look at. A flag the reading build does not know, written by another build, is listed apart and is not counted as needing a look, except on a FAIL row.

The run's last line is a WARNING when any row needs a look and an INFO line when none does; the exit code is unchanged, so flagged rows never fail a pipeline.

gbcms summarize makes the same summary from outputs already written (older runs, many samples, a merged MAF), as text, JSON, a cohort table or MultiQC content.

The mFSD report classes are not in the output rows, so the summary leaves them out.

An example, from 2,000 synthetic rows:

QC summary for sample S: 40 of 2,000 rows need a look (2.0%)
  Rows with only informational flags: 107; with no flag: 1,853
  Fix the input: 2 rows
    REF_MISMATCH: 2 rows
      The REF does not match the reference: check the build and coordinates;
      REF_AT_OFFSET says where it does match
    REF_AT_OFFSET: 1 row
      The REF matches the reference a few bases away: correct the input's coordinates
      (the row is not moved or counted)
  Check the call: 38 rows
    PARTIAL_DOMINANT: 30 rows
      More reads partly match the ALT than carry it, often a coexisting allele the
      annotation misses: inspect the locus (--trace shows per-read lengths)
    OBSERVED_ALLELE: 7 rows
      No read carries the given allele but others carry another one: the input is likely
      mis-described; the counts stay the given allele's
    CLIP_CANDIDATES: 1 row
      An insertion with no ALT reads, but soft-clipped reads may hold its carriers:
      inspect in IGV
  Informational: 113 rows
    ZERO_ALT: 55 rows (no read carries the ALT)
    MULTI_ALLELIC: 40 rows (another row has a different ALT here)
    COEXISTING_ALLELE: 18 rows (another allele is more frequent: a VAF caveat)
  Rows to look at (first 5 of 40, input problems first):
    chr1:1000 A>T (GENE1): REF_MISMATCH, REF_AT_OFFSET(2)
    chr1:1001 A>T (GENE2): REF_MISMATCH
    chr1:1002 A>T (GENE3): PARTIAL_DOMINANT
    chr1:1003 A>T (GENE4): PARTIAL_DOMINANT
    chr1:1004 A>T (GENE5): PARTIAL_DOMINANT
  Find them in the output (MAF columns): gbcms_diagnostic, gbcms_status, gbcms_status_reason
  What each flag means and what to do: https://msk-access.github.io/gbcms/reference/qc-flags/

The tables list every flag by tier with the line the summary prints for it (a short gloss for an informational flag). The definitions are above; the tests keep the two in step.

Fix the input¶

Check the call¶

Informational¶