SigMA v1 tools
SigMA v1's functions around a shipped classifier, ported: the simulation of panels like a cohort, the cutoff at a chosen rate, and the matching of tumors to the training genomes and clusters. Migrate from SigMA v1 shows them in a workflow.
quick_simulation
Simulate panels like a cohort from the package's whole genomes of known Signature 3 status, SigMA v1's quick_simulation.
sg2.quick_simulation(input=None, tumor_type=None, seq_type=None, ref_genome="hg19", catalog="cosmic_v2_inhouse",
remove_msi_pole=True, run=True, snv_ctf=None, seed=None, soi="SBS3", maf_percent=None,
verbose=0, **kwargs) -> DataFrame
| Parameter | Description | Default |
|---|---|---|
| inputpath, list of paths or DataFrame | The cohort to imitate: a MAF or VCF path, a list of VCF paths, or a 96-channel matrix. | Required |
| tumor_typestr | The tumor type whose built-in whole genomes are brought to the cohort's depth. | Required |
| seq_typestr | The platform the cohort was sequenced with; the whole genomes are brought to its depth. | Required |
| ref_genomestr | The build of the coordinates (hg19, hg38) or a FASTA path; unused for a matrix input. | 'hg19' |
| catalogstr | The catalog the cohort is matched to before the simulation; SigMA v1's by default. | 'cosmic_v2_inhouse' |
| remove_msi_polebool | SigMA v1's MSI/POLE step, whose Signature 3 likelihoods are added to the main step's. | True |
| runbool | False takes the output of a legacy run without the classifier as input instead of running it. | True |
| snv_ctfint | The SNV floor of the first run; left out, the tumor type's applies (R used 5 everywhere). | None |
| seedint | Makes the random subsampling reproducible. | None |
| soistr | The signature simulated; only Signature 3, since SigMA v1 tabulated its prevalence alone. | 'SBS3' |
| maf_percentfloat | Not supported: any value is refused, because the germline-contaminated matrices it needs are not in SigMA2's data store. | None |
| verboseint | Passed to the first run: 0 prints errors and some warnings, 1 also prints its log. | 0 |
Returns A DataFrame, one row per simulated panel: the 96 channels, tumor (the source genome), is_sig3 (its whole-genome Signature 3 status, the truth), scale and main (False for a genome borrowed from another tumor type).
The cohort is first matched to the tumor type's catalog without the classifier; from that run SigMA v1 estimates how many tumors carry Signature 3 and their SNV counts, and brings the whole genomes to that depth. Score the result with a classifier and read a cutoff off the negatives at a false-positive rate.
sim = sg2.quick_simulation(
input="test_mutations_50sample.maf",
ref_genome="hg19",
tumor_type="breast",
seq_type="msk",
seed=1,
)
Used in Reproduce SigMA v1, Migrate from SigMA v1
get_threshold
The score cutoff at a chosen false-positive rate, false-discovery rate or sensitivity, SigMA v1's get_threshold.
sg2.get_threshold(df, limits, var="prob", signal="is_sig3", cut_var="fpr") -> DataFrame
| Parameter | Description | Default |
|---|---|---|
| dfDataFrame | A scored cohort: one row per tumor, with a score column and a column of known labels. | Required |
| limitslist of float | The rates to read the cutoff at, one row of the result per limit. | Required |
| varstr | The score column. | 'prob' |
| signalstr | The column of known labels: 1 or True for a positive. | 'is_sig3' |
| cut_varstr | "fpr" or "fdr" for an upper bound on that rate, "sen" for a lower bound on sensitivity. | 'fpr' |
Returns A DataFrame, one row per limit in the order given: limit, cutoff, sen, fpr, fdr.
For cut_var="fpr" or "fdr" each limit is an upper bound, and the cutoff is the lowest score at which the rate is at most the limit; for "sen" it is a lower bound, and the cutoff is the highest score at which sensitivity is at least the limit. A limit no score reaches gives a cutoff of inf (fpr, fdr) or -inf (sen), as in R.
sg2.get_threshold(scored, limits=[0.1, 0.01], var="SBS3_mva", signal="is_sig3", cut_var="fpr")
Used in Migrate from SigMA v1
sen_fpr
Sensitivity, false-positive rate and false-discovery rate at every score, SigMA v1's sen_fpr.
sg2.sen_fpr(df, var, signal) -> DataFrame
| Parameter | Description | Default |
|---|---|---|
| dfDataFrame | A scored cohort: one row per tumor, with a score column and a column of known labels. | Required |
| varstr | The score column; rows without a score are dropped. | Required |
| signalstr | The column of known labels: 1 or True for a positive. | Required |
Returns A DataFrame with sen, fpr, fdr and value (the scores, ascending), one row per scored tumor.
At each score, the tumors from it upward are called: sen is the share of positives among them, fpr the share of negatives, fdr the share of false calls among the calls. Ties keep their input order and a rate whose denominator is 0 is NaN, as in R.
curve = sg2.sen_fpr(scored, var="SBS3_mva", signal="is_sig3")
cluster_characteristics
The signature exposures of each tumor's most likely cluster, SigMA v1's llh_max_characteristics.
sg2.cluster_characteristics(out, tumor_type, catalog="cosmic_v2_inhouse", clusters=None, exp_thresh=-1) -> DataFrame
| Parameter | Description | Default |
|---|---|---|
| outDataFrame | A run's output table, from which each tumor's most likely cluster is read. | Required |
| tumor_typestr | The tumor type whose clusters and signatures are used. | Required |
| catalogstr | The signature catalog of the decomposition; SigMA v1's by default. | 'cosmic_v2_inhouse' |
| clustersDataFrame | Cluster spectra to use instead of the tumor type's, such as a SigMA2 classifier's model.centroids. | None |
| exp_threshfloat | Signatures with an exposure above this are listed; the default keeps all. | -1 |
Returns The run's table with max_clust (the most likely cluster), cluster_sigs_all and cluster_exps_all (the signatures of that cluster's spectrum and their exposures, . and _ separated) added.
The cluster's spectrum, the median of the tumor type's reference cluster, is decomposed by non-negative least squares on the tumor type's signatures. On a run that assessed MSI the cluster is read from its MSI step.
cc = sg2.cluster_characteristics(v1.df, tumor_type="breast")
Used in Migrate from SigMA v1
match_training_genomes
Match each tumor to the single whole genomes of the tumor type's training set, SigMA v1's llh_max_characteristics_wgs_data.
sg2.match_training_genomes(data, tumor_type, catalog="cosmic_v2_inhouse", check_msi=False, average=False,
likelihoods=False) -> DataFrame
| Parameter | Description | Default |
|---|---|---|
| dataSamples, DataFrame or path | The tumors: a Samples object, a 96-channel DataFrame (tumors as rows) or a path. | Required |
| tumor_typestr | The tumor type whose training genomes are matched against. | Required |
| catalogstr | The signature catalog of the decomposition; SigMA v1's by default. | 'cosmic_v2_inhouse' |
| check_msibool | Also match against the MSI and POLE training genomes. | False |
| averagebool | Also return the likelihood-weighted mean exposures over all genomes, as ave_ml_exp_<signature>. | False |
| likelihoodsbool | Also return the tumors-by-genomes likelihood matrix, as the second element of a tuple. | False |
Returns A DataFrame, one row per tumor: max_ml_sample (the training genome of maximum likelihood), max_ml_sample_ml (its likelihood), max_ml_sample_is_sig3 (whether that genome carries Signature 3), sig3_genomes_ml (the likelihood summed over the Signature 3 genomes), max_ml_sample_sigs_all and max_ml_sample_exps_all; with average, the ave_ml_exp_* columns; with likelihoods, a tuple of that table and the likelihood matrix.
match = sg2.match_training_genomes(spectra, tumor_type="breast")
Used in Migrate from SigMA v1