Add mutational signature analysis (SigProfilerMatrixGenerator + SigProfilerAssignment, CHM13-aware)

CHANGELOG.md

@@ -5,6 +5,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## v1.2.0dev
 
+### `Added`
+
+- [#190](https://github.com/IntGenomicsLab/lrsomatic/pull/190) - Added mutational signature analysis: SigProfilerMatrixGenerator matrices (SBS/DBS/ID) and per-sample COSMIC signature fitting with SigProfilerAssignment on the phased somatic VCF, with CHM13-T2T support via a purpose-built image (`ghcr.io/ljwharbers/sigprofiler`) and CHM13-renormalised COSMIC signatures; new `--sigprofiler_*` / `--download_sigprofiler_genome` / `--skip_signatures` parameters (@ljwharbers).
+
 ### `Changed`
 
 - [#184](https://github.com/IntGenomicsLab/lrsomatic/pull/184) - Replaced the CHM13 Severus panel of normals with the merged 1000 Genomes + ASAP panel (@AmberVerhasselt).

CITATIONS.md

@@ -74,6 +74,14 @@
 
   > Keskus, A.G., Bryant, A., Ahmad, T. et al. Severus detects somatic structural variation and complex rearrangements in cancer genomes using long-read sequencing. Nat Biotechnol (2025). https://doi.org/10.1038/s41587-025-02618-8
 
+- [SigProfilerAssignment](https://pubmed.ncbi.nlm.nih.gov/38096571/)
+
+  > Díaz-Gay M, Vangara R, Barnes M, Wang X, Islam SMA, Vermes I, Duke S, Narasimman NB, Yang T, Jiang Z, Moody S, Senkin S, Brennan P, Stratton MR, Alexandrov LB. Assigning mutational signatures to individual samples and individual somatic mutations with SigProfilerAssignment. Bioinformatics. 2023 Dec 1;39(12):btad756. doi: 10.1093/bioinformatics/btad756. PubMed PMID: 38096571; PubMed Central PMCID: PMC10733897.
+
+- [SigProfilerMatrixGenerator](https://pubmed.ncbi.nlm.nih.gov/31470794/)
+
+  > Bergstrom EN, Huang MN, Mahto U, Barnes M, Stratton MR, Rozen SG, Alexandrov LB. SigProfilerMatrixGenerator: a tool for visualizing and exploring patterns of small mutational events. BMC Genomics. 2019 Aug 30;20(1):685. doi: 10.1186/s12864-019-6041-2. PubMed PMID: 31470794; PubMed Central PMCID: PMC6717374.
+
 - [Wakhan](https://github.com/KolmogorovLab/Wakhan)
 
   > A tool to analyze haplotype-specific chromosome-scale somatic copy number aberrations and aneuploidy using long reads (Oxford Nanopore, PacBio). https://github.com/KolmogorovLab/Wakhan

conf/igenomes.config

@@ -23,6 +23,7 @@ params {
             bed_file        = "https://raw.githubusercontent.com/KolmogorovLab/Severus/refs/heads/main/vntrs/human_GRCh38_no_alt_analysis_set.trf.bed"
             vep_genome      = "GRCh38"
             vep_species     = "homo_sapiens"
+            sigprofiler_genome = "GRCh38"
             gnomad          = "${params.igenomes_base}/Homo_sapiens/ClairSTO/GRCh38/Annotation/gnomad.r2.1.af-ge-0.001.sites.vcf.gz"
             dbsnp           = "${params.igenomes_base}/Homo_sapiens/ClairSTO/GRCh38/Annotation/dbsnp.b138.non-somatic.sites.vcf.gz"
             onekgenomes     = "${params.igenomes_base}/Homo_sapiens/ClairSTO/GRCh38/Annotation/1000g-pon.sites.vcf.gz"
@@ -39,6 +40,10 @@ params {
             bed_file        = "https://raw.githubusercontent.com/KolmogorovLab/Severus/refs/heads/main/vntrs/chm13.bed"
             vep_genome      = "T2T-CHM13v2.0"
             vep_species     = "homo_sapiens_gca009914755v4"
+            // SigProfilerMatrixGenerator CHM13-T2T payload (SigProfilerSuite/SigProfilerMatrixGenerator#250);
+            // not yet hosted on the AlexandrovLab FTP, so it is fetched from the IntGenomicsLab Globus collection
+            sigprofiler_genome     = "CHM13-T2T"
+            sigprofiler_genome_url = "https://g-608c0c.273595.03c0.data.globus.org/chm13_release_2026-08/CHM13-T2T.tar.gz"
             gnomad          = "${params.igenomes_base}/Homo_sapiens/ClairSTO/CHM13/Annotation/ClairSTO-pon/final_gnomad.vcf.gz"
             dbsnp           = "${params.igenomes_base}/Homo_sapiens/ClairSTO/CHM13/Annotation/ClairSTO-pon/final_dbsnp.vcf.gz"
             onekgenomes     = "${params.igenomes_base}/Homo_sapiens/ClairSTO/CHM13/Annotation/ClairSTO-pon/final_1kgenomes.vcf.gz"

conf/modules.config

@@ -575,6 +575,50 @@ process {
         ]
     }
 
+    ///////////////////////////
+    // Mutational signatures //
+    ///////////////////////////
+    withName: 'SIGPROFILER_INSTALL' {
+        // ~3 GB genome payload; published so later runs can reuse it via --sigprofiler_genome_dir
+        publishDir = [
+            mode: params.publish_dir_mode,
+            path: { params.outdir_cache ? "${params.outdir_cache}/sigprofiler" : "${params.outdir}/cache/sigprofiler" }
+        ]
+    }
+
+    withName : '.*:SIGNATURES_BCFTOOLS_VIEW' {
+        // SigProfilerMatrixGenerator ignores FILTER and reads plain-text VCF only
+        ext.args   = { "--apply-filters PASS --types snps,mnps,indels --exclude 'ALT=\"*\"' --output-type v" }
+        ext.prefix = { "${meta.id}_somatic_pass" }
+        publishDir = [
+            enabled: false
+        ]
+    }
+
+    withName : '.*:SIGPROFILER_MATRIXGENERATOR' {
+        ext.args   = { params.sigprofiler_matrix_args ?: '' }
+        publishDir = [
+            path: { "${params.outdir}/${meta.id}/signatures/matrices" },
+            mode: params.publish_dir_mode,
+            saveAs: { filename -> filename.equals('versions.yml') ? null : filename }
+        ]
+    }
+
+    withName : '.*:SIGPROFILER_ASSIGNMENT' {
+        ext.args   = {
+            [
+                params.sigprofiler_assignment_args ?: '',
+                params.sigprofiler_exclude_signature_subgroups ? "--exclude_signature_subgroups ${params.sigprofiler_exclude_signature_subgroups}" : ''
+            ].join(' ').trim()
+        }
+        ext.prefix = { "COSMIC_v${params.sigprofiler_cosmic_version}" }
+        publishDir = [
+            path: { "${params.outdir}/${meta.id}/signatures/assignment" },
+            mode: params.publish_dir_mode,
+            saveAs: { filename -> filename.equals('versions.yml') ? null : filename }
+        ]
+    }
+
     /////////
     // VEP //
     /////////

conf/test.config

@@ -58,5 +58,7 @@ params {
     skip_wakhan        = true
     skip_ascat         = true
     skip_modkit        = true
+    // needs a ~3 GB SigProfilerMatrixGenerator genome payload; validated manually, not in CI
+    skip_signatures    = true
 
 }

docs/output.md

@@ -29,6 +29,9 @@ The pipeline produces per-sample output directories. Two modes exist depending o
 │    │    │   ├── nanoplot_ubam_rep1
 │    │    │   └── samtools
 │    │    └── whatshap_stats
+│    ├── signatures
+│    │   ├── assignment
+│    │   └── matrices
 │    ├── variants
 │    │   ├── clairsto
 │    │   ├── deepsomatic
@@ -70,6 +73,9 @@ The pipeline produces per-sample output directories. Two modes exist depending o
 │    │    │   ├── nanoplot_ubam_rep1
 │    │    │   └── samtools
 │    │    └── whatshap_stats
+│    ├── signatures
+│    │   ├── assignment
+│    │   └── matrices
 │    ├── variants
 │    │   ├── clair3
 │    │   ├── clairs
@@ -433,6 +439,72 @@ Phased variant calls produced by Longphase. Present in all samples.
 
 </details>
 
+### `signatures`
+
+Mutational signature analysis of the PASS SNVs and indels in the phased somatic VCF: [SigProfilerMatrixGenerator](https://github.com/SigProfilerSuite/SigProfilerMatrixGenerator) builds the mutational matrices and [SigProfilerAssignment](https://github.com/SigProfilerSuite/SigProfilerAssignment) fits COSMIC reference signatures to them. For `--genome CHM13` the matrices use the `CHM13-T2T` genome and the SBS/DBS fits use COSMIC signatures renormalised to CHM13; ID83 signatures are not genome-normalised by COSMIC and always use the GRCh37 set. The `DBS78` and `ID83` directories are absent when a sample has no doublet substitutions or indels.
+
+<details markdown="1">
+<summary>Output files</summary>
+
+```
+├── signatures
+│   ├── matrices
+│   │   ├── output
+│   │   │   ├── SBS
+│   │   │   │   ├── sample.SBS96.all
+│   │   │   │   ├── sample.SBS288.all
+│   │   │   │   ├── sample.SBS1536.all
+│   │   │   │   └── ...
+│   │   │   ├── DBS
+│   │   │   │   ├── sample.DBS78.all
+│   │   │   │   └── ...
+│   │   │   ├── ID
+│   │   │   │   ├── sample.ID83.all
+│   │   │   │   └── ...
+│   │   │   ├── plots
+│   │   │   │   └── *.pdf
+│   │   │   ├── vcf_files
+│   │   │   └── logs
+│   │   │       ├── SigProfilerMatrixGenerator_sample_<genome>.out
+│   │   │       └── SigProfilerMatrixGenerator_sample_<genome>.err
+│   └── assignment
+│       └── COSMIC_v3.6
+│           ├── SBS96
+│           │   ├── Assignment_Solution
+│           │   │   ├── Activities
+│           │   │   │   ├── Assignment_Solution_Activities.txt
+│           │   │   │   ├── Assignment_Solution_Activity_Plots.pdf
+│           │   │   │   ├── Assignment_Solution_TMB_plot.pdf
+│           │   │   │   └── Decomposed_MutationType_Probabilities.txt
+│           │   │   ├── Signatures
+│           │   │   │   ├── Assignment_Solution_Signatures.txt
+│           │   │   │   └── SBS_96_plots_Assignment_Solution.pdf
+│           │   │   └── Solution_Stats
+│           │   │       ├── Assignment_Solution_Samples_Stats.txt
+│           │   │       └── Assignment_Solution_Signature_Assignment_log.txt
+│           │   └── JOB_METADATA_SPA.txt
+│           ├── DBS78
+│           │   └── ...
+│           └── ID83
+│               └── ...
+```
+
+| File                                                                                     | Description                                                                                                                                        |
+| ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `matrices/output/SBS/sample.SBS96.all`                                                   | SBS96 mutational matrix (mutation counts per trinucleotide class); further context sizes (SBS6, SBS24, SBS288, SBS384, SBS1536, SBS6144) alongside |
+| `matrices/output/DBS/sample.DBS78.all`                                                   | DBS78 doublet-substitution matrix (and DBS186/DBS1248/DBS2976 variants)                                                                            |
+| `matrices/output/ID/sample.ID83.all`                                                     | ID83 indel matrix (and ID28/ID96/ID415 variants)                                                                                                   |
+| `matrices/output/plots/*.pdf`                                                            | SigProfilerPlotting spectra of the matrices (with the default `--sigprofiler_matrix_args "--plot"`)                                                |
+| `matrices/output/vcf_files/`                                                             | Sorted input mutations with their SigProfilerMatrixGenerator classification (`seqInfo`)                                                            |
+| `matrices/output/logs/*`                                                                 | SigProfilerMatrixGenerator log and error files; the summary reports the number of analysed mutations and reference-base mismatches                 |
+| `assignment/COSMIC_v<version>/<context>/Assignment_Solution/Activities/*_Activities.txt` | Number of mutations attributed to every COSMIC signature                                                                                           |
+| `assignment/COSMIC_v<version>/<context>/Assignment_Solution/Activities/*.pdf`            | Activity bar plots and tumour mutational burden plot                                                                                               |
+| `assignment/COSMIC_v<version>/<context>/Assignment_Solution/Signatures/`                 | The reference signatures used for the fit and their spectra                                                                                        |
+| `assignment/COSMIC_v<version>/<context>/Assignment_Solution/Solution_Stats/`             | Per-sample reconstruction statistics (cosine similarity, L2 error) and the step-wise assignment log                                                |
+| `assignment/COSMIC_v<version>/<context>/JOB_METADATA_SPA.txt`                            | SigProfilerAssignment run metadata, including the genome build the reference signatures were normalised to                                         |
+
+</details>
+
 ### `wakhan`
 
 <details markdown="1">