gbcms merge¶

Merge per-BAM-type genotyped MAFs (e.g., duplex, simplex) into a single output MAF with type-prefixed count columns.

Quick Start¶

# Merge duplex + simplex MAFs with combined columns
gbcms merge \
    --input duplex:sample1-duplex.maf \
    --input simplex:sample1-simplex.maf \
    --output sample1.merged.maf

# Merge 3 BAM types, no combined columns
gbcms merge \
    --input duplex:sample1-duplex.maf \
    --input simplex:sample1-simplex.maf \
    --input standard:sample1-unfiltered.maf \
    --output sample1.merged.maf \
    --no-combined

Arguments¶

Required¶

Optional¶

How It Works¶

flowchart LR
    subgraph Inputs
        D["duplex.maf"]
        S["simplex.maf"]
    end

    subgraph Engine ["Merge Engine (Polars)"]
        Scan["Lazy Scan"] --> Prefix["Auto-prefix\ncount columns"]
        Prefix --> Join["Outer Join\non variant key"]
        Join --> Fill["Null → 0\n(missing counts)"]
        Fill --> Combine["Additive\ncombined columns"]
        Combine --> SB["Fisher Strand Bias\n(Rust)"]
    end

    subgraph Output
        M["merged.maf"]
    end

    D --> Scan
    S --> Scan
    SB --> M

Step-by-Step¶

1. Scan — Each input MAF is lazily scanned with all columns as strings
2. Per-input names — Every gbcms column (counts, status, diagnostics, strand bias, mFSD, RNA; the set is the writer's) is renamed to {type}_{name} (e.g., ref_count → duplex_ref_count). Counts written with --column-prefix (duplex_ as the pipeline runs it, t_) are found under that prefix; the other columns are written unprefixed and found as they are.
3. Outer Join — Progressive full outer join on the variant: Chromosome, Start_Position, Reference_Allele, Tumor_Seq_Allele2. End_Position follows from Start and REF and is not joined on, so inputs that write it differently for one variant still join (the output keeps the first input's, and the log names each input that differs); a variant only a later input has takes its End_Position from that input. When an input lists one variant twice with different End_Position, it joins on End_Position too, so each row pairs with its own counterpart. The output's columns are the first input's: without End_Position there, the output has none. When every input is VCF-derived (carries vcf_pos / vcf_ref / vcf_alt), the VCF record is added to the key: two VCF records can describe one MAF record (TCT>TCG and T>G at the changed base), and each should stay its own row. The MAF columns stay in the key, so a variant only a later input has keeps its coordinates and alleles. An input that lists one join key more than once gets a WARN, since each such row pairs with every matching row of the other inputs. Merge MAFs genotyped by the same gbcms version: merge warns when the inputs' version lines differ, and stops when one input is a VCF-input MAF from before 6.5.0 (vcf_pos without vcf_ref/vcf_alt) and another is not, since 6.5.0 changed VCF-input coordinates and their rows would not join. A row only a later input has takes the first input's annotation columns from the earliest later input that has it. Chromosome is compared by the same rule counting uses to reconcile contigs (chr1 ~ 1, chrM ~ MT), so inputs counted from differently named variant files still join. Each contig is written one way. That is the first input's name for it, or, for a contig the first input lacks, the name used by the earliest input that has it. When a later input names contigs differently, the log says so (one INFO line per input). An input column named _contig_key, or starting with _row_, _chrom_, _end_ or _ann_, is rejected: those names are reserved for the join. If one input names a contig two ways (e.g. chrM and MT), a variant listed under both joins once per name, and merge logs a WARN.
4. Absent rows — A row an input lacks gets "0" for that input's read and fragment counts, "" for its status columns, and empty mFSD/RNA columns; the log counts the rows each input lacks. A row an input has keeps its cells as written: a missing count stays missing.
5. Combined Columns — If both simplex and duplex are present and --no-combined is not set:
   • Phase 1: Additive sums (12 columns: read + fragment + strand counts); NA where either flavor's cell is missing or non-numeric, warned once per column
   • Phase 2a: Derived totals (total_count, total_count_fragment)
   • Phase 2b: Derived VAFs (vaf, vaf_fragment)
   • Phase 3: Fisher's exact test for strand bias (read + fragment level, via Rust)
6. Write — Materialized DataFrame written as tab-separated MAF, after provenance lines (its own #gbcms/#command, and one #input line per input with that input's version line), atomically (a temp file renamed into place). Rows follow the inputs: the first input's rows in its order, then rows only a later input has, in that input's order. The output is identical on every run.

Combined Columns¶

When both simplex and duplex inputs are present, 20 combined simplex_duplex_* columns are computed (assuming all strand-level counts are present in the input):

Nextflow Integration¶

When running via the Nextflow pipeline, enable merge with:

nextflow run main.nf \
    --input samplesheet.csv \
    --variants mutations.maf \
    --fasta reference.fa \
    --format maf \
    --merge_counts \
    -profile slurm

The samplesheet should include a bam_type column:

sample,bam,bai,suffix,bam_type
sample1,sample1.duplex.bam,,-duplex,duplex
sample1,sample1.simplex.bam,,-simplex,simplex

When bam_type is set, the DNA module automatically derives --column-prefix from the type label, so counts are pre-prefixed in the per-BAM MAF output.

Related¶

• Output Formats — Column schema reference
• Architecture — System design
• gbcms dna — Per-BAM DNA counting
• gbcms summarize — QC summary of a merged MAF, with a flag for rows whose combined cells are NA