Quickstart
Score fifty public breast panels for Signature 3, APOBEC and mismatch-repair deficiency, and read the calls.
Before you begin, you need the package installed, the hg19 genome, the repeat-locus files for step 6; about 5 minutes.
Score Signature 3 on fifty MSK-IMPACT breast panels, read the result, and run two more classifiers on the same file. The environment the steps assume is on Example files and environment.
1. Install the package and a genome
pip install --pre sigma2
sigma2 data genome hg19
The genome is about 3 GB and is downloaded once. Install has the requirements.
2. Get the example file
SigMA (R) ships fifty breast panels from the MSK-IMPACT 2017 cohort as a MAF, 216 KB, under SigMA's license:
curl -LO https://raw.githubusercontent.com/parklab/SigMA/master/inst/extdata/examples/test_mutations_50sample.maf
3. Score Signature 3
import sigma2 as sg2
out = sg2.run(
input="test_mutations_50sample.maf",
ref_genome="hg19",
tumor_type="breast",
seq_type="msk",
soi="SBS3",
verbose=1,
)
| Parameter | Description | Default |
|---|---|---|
| inputpath, list of paths, folder or DataFrame | The mutations: a MAF path, a VCF path, a list of VCF paths, a folder of VCFs, a CSV, or a DataFrame of SBS-96 counts. | Required |
| ref_genomestr or path | The build of the coordinates (hg19, hg38, GRCh37, GRCh38) or a FASTA path; unused for a matrix input. | 'hg19' |
| tumor_typestr | A tumor type of the vocabulary, in any case (the package lists 39 names; msi and pole among them are signature sets, not tumor types); it sets the signature set, the reference spectra and the classifier. | Required |
| seq_typestr | The platform (msk, fo, op, seqcap, tcga_mc3, wgs); "auto" chooses by SNV burden and reports the choice. | 'auto' |
| soistr or CompositeSignature | The signature of interest: a COSMIC name, a composite preset (APOBEC, SBS7, SBS10, SBS17, CLOCK), an alias (UV, POLE), or HRD. | Required |
| verboseint | 0 prints errors and some warnings (a catalog other than the classifier's, a readjust without a table); 1 also prints the classifier, the sample counts and the other warnings, such as a legacy classifier's features passed as missing; 2 also lists the samples below the floor. | 0 |
verbose=1 prints what the run did:
[SigMA2|v0.0.16-alpha.20|run] Classifier: tumor_type="breast", soi="SBS3", seq_type="msk" (verified)
[SigMA2|v0.0.16-alpha.20|run] Input: 50 samples → 38 after filtering (12 dropped)
[SigMA2|v0.0.16-alpha.20|run] Using classifier: breast/SBS3/msk
[SigMA2|v0.0.16-alpha.20|run] Completed in 2.04s
Twelve samples have fewer than five SNVs, the floor this classifier was trained at, and are not scored. verbose=2 lists them with their counts.
4. Read the result
out.df[["total_snvs", "SBS3_mva", "pass_mva", "pass_mva_strict", "confidence"]].head()
total_snvs SBS3_mva pass_mva pass_mva_strict confidence
P-0008709-T01-IM5 18 0.916549 True True high
P-0010938-T01-IM5 41 0.991418 True True high
P-0010560-T01-IM5 5 0.082124 False False negative
P-0008385-T01-IM5 5 0.098018 False False negative
P-0007087-T01-IM5 43 0.780558 True False low
SBS3_mvais the classifier's score, between 0 and 1.pass_mvais the call at the released operating point, a false-positive rate of 10%.pass_mva_strictis the call at the strict operating point, 1%.confidencecombines the two:highclears both,lowclears the loose one only,negativeclears neither.
The whole cohort, as the package draws it: every scored panel as a stacked bar of its decomposition, sorted by the share of Signature 3:
from sigma2 import plot as sp
sp.exps(out.df, soi=sg2.resolve_signature("SBS3"), path="exposures.svg", show_sample_names=False)
The last sample has a loose call and no strict call. Read the output explains every column, and Floor, cutoffs and catalog explains the two operating points.
lite = out.to_lite()
lite.head()
5. Score another signature
The same panels, APOBEC:
out = sg2.run(input="test_mutations_50sample.maf", ref_genome="hg19",
tumor_type="breast", seq_type="msk", soi="APOBEC")
out.df[["total_snvs", "APOBEC_mva", "pass_mva", "confidence"]].head()
APOBEC combines SBS2 and SBS13 and has its own classifier. sg2.describe() prints every classifier the package has for breast and for every other tumor type.
6. Classify mismatch repair from the same file
A MAF carries indels, so the MMRD/POLE classifier can run on it. This step needs the repeat-locus files (sigma2 data fetch --all, or from the public SigMA (R) repository).
mm = sg2.predict_mmrd_ppd(input="test_mutations_50sample.maf", ref_genome="hg19",
tumor_type="breast", seq_type="msk")
mm.df[["total_snvs", "MMRD_category", "MMRD_prob", "POLE_prob", "MMRP_prob"]].head()
| Parameter | Description | Default |
|---|---|---|
| inputpath, list of paths, folder or DataFrame | The mutations with their indels: a MAF or VCF path, or a matrix with nins, ndel, nmsi_ins and nmsi_del columns. | Required |
| ref_genomestr or path | The build of the coordinates (hg19, hg38, GRCh37, GRCh38) or a FASTA path. | 'hg19' |
| tumor_typestr | A tumor type of the vocabulary (msi and pole are signature sets, not tumor types); the point-mutation features need its signature set. | Required |
| seq_typestr | The platform: a model exists for msk, tcga_mc3, seqcap, fo and op. | Required |
total_snvs MMRD_category MMRD_prob POLE_prob MMRP_prob
P-0008709-T01-IM5 18 MMRP 0.072480 0.000129 0.927391
P-0010938-T01-IM5 41 MMRP 0.000030 0.000020 0.999950
P-0010560-T01-IM5 5 MMRP 0.000023 0.000022 0.999955
P-0008385-T01-IM5 5 MMRP 0.000023 0.000016 0.999961
P-0007087-T01-IM5 43 MMRD 0.999076 0.000050 0.000874
Use MMRD_category: it is the most probable class, so a threshold of your own on one probability can disagree with it. P-0007087 was in this model's training set, labeled microsatellite-stable by MSK's clinical MSIsensor call; the MMRD call is the model's prediction and disagrees with that caller (Detect MMRD or POLE).