Scoring
run
Score one signature of interest with one classifier.
sg2.run(*, input, tumor_type, soi, seq_type="auto", ref_genome="hg19", model="auto", catalog=None, snv_ctf=None,
readjust=False, force=False, verbose=0, mxw=1, name=None,
segments=None, gis=None, indels=None, beds=None, hrd_model=None, hrd=None,
mva=True, assign=True, msi=False, wcf=False) -> Output
| 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 |
| 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 |
| modelstr or GBMModel | Which classifier runs: "auto" for the released cell, "legacy" for SigMA v1's, or a model loaded with sg2.model(). | 'auto' |
| snv_ctfint | The SNV floor below which a sample is not scored; left out, the classifier's recorded floor applies. | None |
| mvabool | False skips the classifier and returns the features only. | True |
| assignbool | False skips the likelihood assignment. | True |
| msibool | SigMA v1's MSI features on a signature run; for MMRD/POLE calls use predict_mmrd_ppd. | False |
| wcfbool | SigMA v1's msk_cf classifier with the cluster-size prior, on msk with model="legacy". | False |
| readjustbool | Re-derive the cutoffs for the batch's sequencing depth from the classifier's held-out negatives; for cohorts only. | False |
| 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 |
| mxwint or str | The worker count for the decomposition and the HRD pre-step; "max" uses every core. | 1 |
| ref_genomestr or path | The build of the coordinates (hg19, hg38, GRCh37, GRCh38) or a FASTA path; unused for a matrix input. | 'hg19' |
| catalogstr | The signature catalog for the decomposition; left out, the classifier's own is used, and a different one warns or refuses. | None |
| forcebool | Score with an experimental classifier; the scores rank the cohort and every call column is NA. | False |
| namestr | A label for the run, carried on the output. | None |
| segmentspath or DataFrame | Copy-number segments for HRD: a path or DataFrame in a recognized format, with a sample column. | None |
| gisSeries or dict | Precomputed genomic instability per sample for HRD, as a Series or dict, when segments are not available. | None |
| indelspath, VCF, MAF or DataFrame | Indels from a separate source for HRD: a path, a VCF or MAF object, or a DataFrame. | None |
| bedslist of BED | Repeat-locus BED files of another build for the microsatellite indel counts. | None |
| hrd_modelstr or HRDModel | Another HRD model than the platform's, by name or as an HRDModel. | None |
| hrdbool | Add the HRD features to a signature run. | None |
Internal parameters (4)
| min_del_sizeint | Internal: the smallest deletion counted for the indel features. | None |
| min_mh_sizeint | Internal: the smallest microhomology counted as microhomology-mediated. | None |
| tumor_catalogDataFrame | Internal: the reference spectra the likelihoods are computed against; a loaded model passes its own. | None |
| cluster_fractionsDataFrame | Internal: SigMA v1's cluster-size prior table. | None |
Returns Output: .df is the result table, one row per scored sample (5. Read the output); .input_matrix.df every sample read; .snv_floor, .catalog_name, .seq_type, .soi and .model what ran; .to_lite() the short table.
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,
)
Used in Quickstart, 2. Detect a signature (SBS3, APOBEC, any other), 3. Detect HRD, 5. Read the output
predict_mmrd_ppd
MMRD, POLE or MMRP per sample (Detect MMRD or POLE).
sg2.predict_mmrd_ppd(*, input, tumor_type, seq_type, ref_genome="hg19", model="auto", indels=None, beds=None,
snv_ctf=None, verbose=0) -> Output
| 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 |
| 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 |
| modelstr or GBMModel | "auto" for SigMA2's model of the platform, "legacy" for SigMA v1's (msk and tcga_mc3 only). | 'auto' |
| snv_ctfint | The SNV floor below which a sample is not classified and is left out of the table; left out, the tumor type's floor applies. | None |
| verboseint | 0 prints errors and some warnings; 1 also prints the run and the other warnings; 2 also lists the samples below the floor. | 0 |
| mxwint or str | The worker count; "max" uses every core. | 1 |
| ref_genomestr or path | The build of the coordinates (hg19, hg38, GRCh37, GRCh38) or a FASTA path. | 'hg19' |
| indelspath, VCF, MAF or DataFrame | Indels from a separate source: a path, a VCF or MAF object, or a DataFrame. | None |
| bedslist of BED | Repeat-locus BED files of another build for the microsatellite indel counts. | None |
Returns Output: .df with MMRD_category, the three class probabilities, the indel counts and SigMA v1's subtype columns, one row per sample above the floor; samples below it are left out.
model is "auto" or "legacy". The function sets catalog, soi and mva itself; the input must carry indels (a MAF or VCF, indels=, or the four indel-count columns of a matrix).
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()
Used in Quickstart, 4. Detect MMRD or POLE, Worked example: fifty breast panels, Reproduce SigMA v1
describe
Print every installed classifier as one table per tumor type, rows classifiers and columns platforms, each cell its status, the SNV floor in the heading.
sg2.describe(root_dir=None, format=None, verbose=0) -> None
| Parameter | Description | Default |
|---|---|---|
| root_dirstr | A store of your own to list instead of the data directory's; HRD and MMRD/POLE models ship with the package. | None |
| formatstr | "text" or "html"; detected from the console when left out. | None |
| verboseint | 1 or 2 add each model's training date to its cell. | 0 |
Returns Nothing; the tables are printed.
format is "text" or "html" (auto-detected); verbose 1 or 2 adds training dates; root_dir lists another store's signature classifiers. On a console without the glyphs it prints *, o and ^.
import sigma2 as sg2
sg2.describe()
Used in Install, Manage models and the store
resolve_signature
Turn a name into a signature object: sg2.resolve_signature("apobec").
sg2.resolve_signature(s) -> Cosmic | CompositeSignature
| Parameter | Description | Default |
|---|---|---|
| sstr or signature | A signature name, composite preset or alias, in any case. | Required |
Returns A signature object: a COSMIC signature, or a CompositeSignature for a preset or alias.
from sigma2 import plot as sp
sp.exps(out.df, soi=sg2.resolve_signature("SBS3"), path="exposures.svg", show_sample_names=False)
Used in Quickstart, 2. Detect a signature (SBS3, APOBEC, any other), 6. Plot spectra and exposures
CompositeSignature
A signature made of several COSMIC signatures.
sg2.CompositeSignature.PRESETS # {"APOBEC": ["SBS2", "SBS13"], "SBS7": [...], "SBS10": [...], "SBS17": [...], "CLOCK": ["SBS1", "SBS5"]}
sg2.CompositeSignature.ALIASES # {"UV": "SBS7", "POLE": "SBS10"}
sg2.CompositeSignature.register_preset(name, components)
Returns A signature object that run(soi=) and the training functions accept in place of a name.
A preset is scored by the classifier trained for it; a composite you register has none until you train one.