Version Compatibility

Reference examples tested with: SigProfilerMatrixGenerator 1.2+ (Bergstrom 2019), SigProfilerExtractor 1.1.24+ (Islam 2022), SigProfilerAssignment 0.1+ (Diaz-Gay 2023), MutationalPatterns 3.12+ (Manders 2022), MuSiCal 0.7+ (Jin 2024), SigNet (Serrano 2023, bioRxiv), HRDetect (Davies 2017 / Degasperi 2022 implementations), pandas 2.2+, R 4.3+. COSMIC v3.4 (2023, COSMIC v98): 86 SBS, 11 DBS, 18 ID, 21 CN, 16 SV signatures (v3.6 is the current catalog as of 2026).

Before using code patterns, verify installed versions match. If versions differ:

• Python: pip show <package> then help(module.function) to check signatures
• R: packageVersion('<pkg>') then ?function_name

If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying. COSMIC signature naming evolves: SBS40 was split to SBS40a/b/c in v3.4 (Senkin 2024); SBS17 split to SBS17a/b (5-FU); SBS10 split to SBS10a-d (POLE/POLD1).

Somatic Mutational Signatures; Etiology, Extraction, Clinical Use

'Extract mutational signatures from this tumor cohort and identify HRD/MMR/APOBEC processes' -> Generate 96-context (or DBS/ID/CN/SV) matrix from VCF; choose de novo extraction (NMF) vs refit-to-COSMIC by cohort size; map dominant signatures to etiology; flag clinical actionability.

• Python (recommended): SigProfilerMatrixGenerator -> SigProfilerExtractor (de novo) or SigProfilerAssignment (refit)
• R alternative: MutationalPatterns::fittosignatures() (strict refit) or extract_signatures() (NMF de novo)
• Python (mvNMF for non-uniqueness): MuSiCal (Jin 2024 Nat Genet)
• Python (deep learning low-mutation count): SigNet (Serrano 2023)
• R (HRD-specific): HRDetect (Davies 2017 Nat Med); the 6-feature BRCA-deficiency classifier

COSMIC v3.4 Catalog: Evolution and Composition

Recent splits to know:

• SBS40 -> SBS40a / SBS40b / SBS40c (Senkin 2024 Nature): pan-cancer active (40a); RCC-specific (40b/c).
• SBS17 -> SBS17a (T>C uncertain) / SBS17b (T>G in CTT, 5-FU) (Christensen 2019 Nat Commun; Pich 2019 Nat Genet).
• SBS7 -> SBS7a / 7b / 7c / 7d (UV photoproduct chemistry; Alexandrov 2020).
• SBS10 -> SBS10a (POLE P286R) / 10b (POLE V411L) / 10c / 10d (POLD1) (Hodel 2020 Mol Cell).

Etiology Table (Postdoc-grade)

CRITICAL CORRECTION: The widely-cited "SBS33 = FFPE artifact" is wrong. Modern literature attributes FFPE artifact to a signature resembling SBS30 (NTHL1-BER-deficiency profile); after enzymatic uracil repair the artifact instead resembles SBS1.

Tool Taxonomy

The deprecation: deconstructSigs is the most-cited signature tool in publications but is operationally deprecated. NNLS without regularization overfits onto the ~70-signature reference; reviewers flag manuscripts using it without SigProfilerAssignment sensitivity. Replace with SigProfilerAssignment or MutationalPatterns strict refit.

De Novo vs Refit: The Field's Most-Contested Choice

Degasperi 2022 Science (12,222 WGS, UK 100k Genomes) argued refitting underestimates novel signatures because variance is forced onto existing references. They identified 40 additional SBS and 18 DBS signatures by full de novo extraction.

Operational rule:

SigProfilerExtractor stability gates:

• nmf_replicates = 100 (default 100, do not reduce)
• minimum stability >= 0.2 per signature
• minimum average stability >= 0.8 across signatures
• combined stability == 1.0 for selected rank

Manuscripts reporting extraction without these stability values are unreviewable.

Decision Tree by Scenario

Standard Workflow: SigProfilerSuite

Goal: Generate 96-context mutation matrix, extract de novo signatures with stability validation, and decompose to COSMIC v3.4 reference.

Approach: Three-step pipeline with explicit version pinning and stability gates.

# Step 1: Install reference genome (one-time)
from SigProfilerMatrixGenerator import install as genInstall
genInstall.install('GRCh38')

# Step 2: Generate matrix
from SigProfilerMatrixGenerator.scripts import SigProfilerMatrixGeneratorFunc as matGen
matrices = matGen.SigProfilerMatrixGeneratorFunc(
    project='cohort_2026',
    genome='GRCh38',
    vcfFiles='/path/to/vcf_directory',
    plot=True,
    exome=False,  # True if WES; corrects trinucleotide capture bias
    bed_file=None,  # Restrict to BED region if panel
    chrom_based=False,
    tsb_stat=True  # Transcribed-strand statistics
)

# Step 3a (cohort >= 50): de novo extraction with stability gates
from SigProfilerExtractor import sigpro as sig
sig.sigProfilerExtractor(
    input_type='matrix',
    input_data='cohort_2026/output/SBS/cohort_2026.SBS96.all',
    output='extraction_output',
    reference_genome='GRCh38',
    opportunity_genome='GRCh38',
    minimum_signatures=1,
    maximum_signatures=12,
    nmf_replicates=100,            # Required for stability
    cpu=-1,
    seeds='random',
    matrix_normalization='gmm',
    resample=True,
    batch_size=1,
    refit_denovo_signatures=True,
    cosmic_version=3.4              # Match to current COSMIC release
)

# Step 3b (single sample or cohort < 50): refit to COSMIC
from SigProfilerAssignment import Analyzer as Analyze
Analyze.cosmic_fit(
    samples='cohort_2026/output/SBS/cohort_2026.SBS96.all',
    output='assignment_output',
    input_type='matrix',
    genome_build='GRCh38',
    cosmic_version=3.4,
    signature_database='SBS_GRCh38_GRCh38',  # Verify against the SigProfilerAssignment release; the bundled
                                              # COSMIC signature-database identifiers change between versions.
    nnls_add_penalty=0.05,         # Forward-add gate
    nnls_remove_penalty=0.01,      # Backward-remove gate
    initial_remove_penalty=0.05,
    refit_denovo_signatures=False,
    make_plots=True,
    sample_reconstruction_plots=True
)

MutationalPatterns Strict Refit (R Alternative)

Goal: Same as SigProfilerAssignment but in R; suited for Bioconductor pipelines.

Approach: Cosine-based stopping reduces overfitting vs deconstructSigs.

library(MutationalPatterns)
library(BSgenome.Hsapiens.UCSC.hg38)

# Load VCFs as GRanges
vcf_files <- list.files('vcf_dir', pattern = '\\.vcf$', full.names = TRUE)
sample_names <- gsub('\\.vcf$', '', basename(vcf_files))
vcfs <- read_vcfs_as_granges(vcf_files, sample_names,
                              ref_genome = 'BSgenome.Hsapiens.UCSC.hg38')

# Generate 96-context matrix
mut_mat <- mut_matrix(vcf_list = vcfs, ref_genome = 'BSgenome.Hsapiens.UCSC.hg38')

# Fit to COSMIC v3.4 with strict refit (cosine-stopping; avoids deconstructSigs overfit)
signatures <- get_known_signatures(muttype = 'snv', source = 'COSMIC_v3.4',
                                    sig_type = 'reference', genome = 'GRCh38')
strict_refit <- fit_to_signatures_strict(mut_mat, signatures, max_delta = 0.004)

# Plot relative + absolute contributions
plot_contribution(strict_refit$fit_res$contribution, signatures, mode = 'relative')

HRDetect for BRCA1/2 Deficiency

Goal: Classify tumors as HRD vs HR-proficient using the 6-feature Davies 2017 lasso.

Approach: Compute SBS3, SBS8, RS3 (rearrangement signature 3), RS5, HRD-LOH score, and the proportion of deletions with microhomology; apply lasso classifier.

# Davies 2017 HRDetect framework
# Features: SBS3, SBS8, RS3, RS5, HRD-LOH, proportion of deletions with microhomology
# Output: probability of HRD; threshold 0.7 = HRD-positive
library(signature.tools.lib)

hrdetect <- HRDetect_pipeline(
    SNV_vcf_files = snv_vcfs,
    Indels_vcf_files = indel_vcfs,
    SV_bedpe_files = sv_bedpes,
    CNV_tab_files = cnv_tables,
    genome.v = 'hg38',
    nparallel = 8
)

# hrdetect$hrdetect_output has BRCA_prob per sample
# >= 0.7 = HRD-positive; consider PARP inhibitor

Per-Operation Failure Modes

1. Single-sample de novo extraction

• Trigger: Run SigProfilerExtractor on a cohort of 1.
• Mechanism: NMF requires multiple samples to find stable rank; single-sample 96-context spectrum has unstable signature decomposition.
• Symptom: Tool runs but signatures are noisy and inconsistent across replicates.
• Fix: Use refit (SigProfilerAssignment) for cohorts < 50; never de novo on single samples.

2. Sub-100-mutation sample analyzed individually

• Trigger: Calculate signatures for a tumor with <100 mutations.
• Mechanism: 96-context SBS spectrum needs 200-500 mutations for stable estimation; sub-100 produces signal-to-noise dominated by stochastic context distribution.
• Symptom: Random or implausible signature contributions.
• Fix: Aggregate samples in a meta-tumor for cohort analysis; for single-sample at low count consider SigNet which is optimized for low counts.

3. FFPE artifact misclassified as SBS30 / SBS33

• Trigger: Pipeline reports SBS33 (or SBS30) as biologically meaningful.
• Mechanism: FFPE-induced C>T deamination produces a profile resembling SBS30 (~0.90 cosine); after enzymatic uracil repair resembles SBS1. Pre-2022 literature incorrectly cited SBS33.
• Symptom: False NTHL1-BER-deficiency or "unknown SBS33" reports in cohorts using FFPE samples without matched controls.
• Fix: Run matched fresh-frozen controls in cohort; flag FFPE samples for separate analysis; use enzymatic-uracil pretreatment; expect SBS30-like artifact, not SBS33.

4. WES + signature analysis without trinucleotide correction

• Trigger: Run SigProfilerExtractor on WES VCFs with exome=False.
• Mechanism: WES capture has biased trinucleotide composition vs whole genome.
• Symptom: Apparent signature differences from WGS-derived signatures are artifactual.
• Fix: Set exome=True; this triggers trinucleotide-context correction.

5. Refit chosen for cohort with novel etiology

• Trigger: Tropical-region cohort with putative novel mutagen exposure; refit to COSMIC.
• Mechanism: Refit constrains variance onto existing catalog; novel signatures appear as residual or are decomposed onto closest-cosine known signatures.
• Symptom: Apparent absence of novel etiology despite biological hypothesis.
• Fix: For cohorts >= 50 run de novo extraction with cross-validation; Senkin 2024 kidney cancer cohort exemplifies the gain.

6. APOBEC SBS2 vs SBS13 conflation; A3A vs A3B

• Trigger: Report "APOBEC activity" without subtype.
• Mechanism: Petljak 2022 Nature established APOBEC3A as dominant active deaminase; the SBS2/SBS13 ratio reflects REV1-dependent translesion synthesis.
• Symptom: Lose mechanistic insight; potential mis-attribution.
• Fix: Distinguish A3A (YTCA 5' tetranucleotide preference) vs A3B (RTCA); cite Petljak 2022.

7. SBS5 attributed to "polymerase fidelity errors"

• Trigger: Manuscript claims SBS5 = replication errors.
• Mechanism: SBS5 etiology is contested; clock-like, age-correlated, modulated by ERCC2/TC-NER but not established as polymerase errors.
• Symptom: Reviewers reject.
• Fix: Report as "unknown, clock-like" until field consensus.

8. Cross-version comparison without re-extraction

• Trigger: Compare SBS40 contributions from v3.2 (single signature) vs v3.4 (split into 40a/b/c).
• Mechanism: Signature splits/merges occur between versions; cross-version exposures are not directly comparable.
• Symptom: Apparent "loss" or "gain" of activity due to renaming.
• Fix: Re-run with current COSMIC version; document version in methods.

9. Strand bias ignored

• Trigger: SBS22 (aristolochic acid) reported without transcribed-strand bias.
• Mechanism: Aristolochic-acid mutagenesis strongly biased toward transcribed strand; SigProfiler handles via tsb_stat=True, MutationalPatterns supports, deconstructSigs ignores.
• Symptom: Mis-attribution; loss of mechanistic evidence.
• Fix: Use SigProfiler or MutationalPatterns; enable strand-bias output.

Reconciliation: When Methods Disagree

Quantitative Thresholds and Conventions

Common Errors

Anticipated Reviewer Pushback

References

• Alexandrov LB et al. 2020. The repertoire of mutational signatures in human cancer. Nature 578:94. (PCAWG)
• Tate JG et al. 2019. COSMIC: the Catalogue Of Somatic Mutations In Cancer. Nucleic Acids Res 47:D941. (COSMIC v86)
• Senkin S et al. 2024. Geographic variation of mutagenic exposures in kidney cancer genomes. Nature 629:910. (SBS40a/b/c split)
• Steele CD et al. 2022. Signatures of copy number alterations in human cancer. Nature 606:984. (COSMIC CN signatures)
• Petljak M et al. 2022. Mechanisms of APOBEC3 mutagenesis in human cancer cells. Nature 607:799. (A3A dominance)
• Bergstrom EN et al. 2019. SigProfilerMatrixGenerator: a tool for visualizing and exploring patterns of small mutational events. BMC Genomics 20:685.
• Islam SMA et al. 2022. Uncovering novel mutational signatures by de novo extraction with SigProfilerExtractor. Cell Genomics 2:100179.
• Diaz-Gay M et al. 2023. Assigning mutational signatures to individual samples and individual somatic mutations with SigProfilerAssignment. Bioinformatics 39:btad756.
• Manders F et al. 2022. MutationalPatterns: the one-stop shop for the analysis of mutational processes. BMC Genomics 23:134.
• Jin H et al. 2024. Accurate and sensitive mutational signature analysis with MuSiCal. Nat Genet 56:541.
• Davies H et al. 2017. HRDetect is a predictor of BRCA1 and BRCA2 deficiency based on mutational signatures. Nat Med 23:517.
• Degasperi A et al. 2022. Substitution mutational signatures in whole-genome-sequenced cancers in the UK population. Science 376:abl9283.
• Christensen S et al. 2019. 5-Fluorouracil treatment induces characteristic T>G mutations in human cancer. Nat Commun 10:4571. (SBS17b)
• Pich O et al. 2019. The mutational footprints of cancer therapies. Nat Genet 51:1732.
• Hayward NK et al. 2017. Whole-genome landscapes of major melanoma subtypes. Nature 545:175. (UV signatures)
• Schulze K et al. 2015. Exome sequencing of hepatocellular carcinomas. Nat Genet 47:505. (Aflatoxin SBS24)
• Hoang ML et al. 2013. Mutational signature of aristolochic acid exposure as revealed by whole-exome sequencing. Sci Transl Med 5:197ra102.
• Pleguezuelos-Manzano C et al. 2020. Mutational signature in colorectal cancer caused by genotoxic pks+ E. coli. Nature 580:269. (Colibactin SBS88)
• Gerstung M et al. 2020. The evolutionary history of 2,658 cancers. Nature 578:122. (MutationTimer)
• Hodel KP et al. 2020. POLE mutation spectra are shaped by the mutant allele identity, its abundance, and mismatch repair status. Mol Cell 78:1166.
• (FFPE-induced C>T mutational artifact: the earlier "Guyard 2022 Nat Commun" attribution could not be verified -- consult current FFPE-artifact literature for a confirmed primary citation.)
• COSMIC Signatures: https://cancer.sanger.ac.uk/signatures/

Related Skills

• clinical-databases/tumor-mutational-burden - TMB and ICI biomarker
• clinical-databases/msi-detection - MSI as MMR-D biomarker (paired with SBS6/15/26/44)
• variant-calling/variant-calling - Somatic VCF input
• variant-calling/variant-calling - Mutect2 / Strelka2 somatic upstream
• data-visualization/heatmaps-clustering - Signature contribution visualization