Bio Clinical Databases Somatic Signatures

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::fit_to_signatures() (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.