mFSD Report¶

Interactive HTML report for per-variant Mutant Fragment Size Distribution analysis.

Overview¶

The --mfsd-report flag generates a self-contained HTML file alongside the MAF output (it requires --format maf). The report provides an interactive visual diagnostic for evaluating fragment size distributions at each variant position, grading how far each variant's ALT fragments are shorter than its REF fragments. The grade is evidence toward a tumor origin, never an origin call; it does not separate tumor from clonal hematopoiesis (CH), which matched-normal data decide.

gbcms dna --mfsd --mfsd-parquet --mfsd-report --format maf \
  -v variants.maf -b sample.bam -f ref.fa -o output/

CLI Options¶

Report Sections¶

1. Header & Sample Info¶

The report title displays the sample name (from --bam sample_id:path or derived from the BAM filename). A theme toggle (☀/🌙) switches between light and dark modes.

2. Summary Dashboard¶

Three metric cards give an at-a-glance overview of the fragment-size evidence:

Each card counts the variants in one class: LEANS-SOMATIC, NO-SIZE-EVIDENCE and INSUFFICIENT (defined in QC Flags, shown below).

3. Caveat Banner¶

A clinical disclaimer noting that the fragment-size evidence is graded, not diagnostic, and should not be used as the sole basis for clinical decisions; matched-normal (buffy coat) sequencing decides CH.

4. Per-Variant Analysis Cards¶

Each qualifying variant gets a dedicated card containing:

• Variant identity: Gene symbol, genomic coordinates, allele change
• Fragment-size evidence: Class badge (LEANS-SOMATIC / NO-SIZE-EVIDENCE / INSUFFICIENT) with its explanation, and a note when the gene is CH-associated
• Key statistics table: Subnucleosomal enrichment, KS p-value, mean fragment sizes (REF vs ALT), delta, log-likelihood ratio
• Dual-axis histogram: Interactive Plotly chart showing:
  • Bar chart (left y-axis): Fragment count per size bin (REF in blue, ALT in red)
  • KDE curve (right y-axis): Smoothed density estimate overlaid for both alleles

Fragment-size Evidence¶

The report grades each variant's fragment-size evidence from the ALT and REF fragments at the same locus: the KS test's FDR q-value across the sample's variants (mfsd_qval_alt_ref, not the raw p-value) and the sub-nucleosomal shares. It is graded evidence, never an origin call; a CH-associated gene is shown as a note:

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.

Sub-nucleosomal Enrichment¶

Defined as:

enrichment = fraction_subnucleosomal_ALT / fraction_subnucleosomal_REF

Where subnucleosomal fragments are those with insert size < 150 bp (below the ~167 bp nucleosome-protected length). Tumor-derived cfDNA tends to be shorter due to increased nuclease accessibility at mutation sites.

Interactive Features¶

Variant Navigator¶

For reports with ≥ 2 variants, a sticky navigation bar appears below the header:

Theme Toggle¶

Click the ☀/🌙 button in the toolbar to switch between dark mode (default) and light mode. The preference is not persisted across page loads.

Interactive Charts¶

Each Plotly chart supports:

• Hover: View exact count/density values at each fragment size
• Zoom: Click and drag to zoom into a region
• Pan: Hold shift and drag to pan
• Reset: Double-click to reset the view
• Download: Use the Plotly toolbar to save as PNG

Print & PDF Export¶

The report is designed for audit-compliant printing:

• All interactive controls (navigator, theme toggle, buttons) are hidden via @media print CSS
• All variant cards are shown at full opacity (Focus mode dimming is removed)
• Charts are rendered at full width
• The branded footer is included

To export: use your browser's Print → Save as PDF function.

mFSD Output Columns¶

For the complete reference of all 41 MAF columns and 13 VCF INFO fields added by --mfsd, see Counting & Metrics → mFSD.

Additional Columns (Physical Sizing)¶

These columns are added by the physical sizing engine (new in v4.1):

Related¶

• Counting & Metrics → mFSD — Complete column schema
• Output Formats — VCF and MAF output structure
• DNA Command — CLI flag reference