Known limits

What SigMA2 0.0.16-alpha.20 cannot do, does differently from what a reader might expect, or does only with a caveat.

When a call is possible, and when it is not

A classifier reads a panel's few mutations and asks whether they look like the tumor type's genomes that carry the signature. What decides the answer is how many mutations of the signature the panel holds, not how clearly the signature is defined:

The count is the signature's share times the panel's SNVs. A tumor with Signature 3 in half its mutations and 10 SNVs on the panel gives the classifier about five Signature 3 mutations; one with the same share and 5 SNVs gives it two or three. The package calls this count the burden, λ.
Each cell has a detection law. On its own cross-validation, the probability of a call rises with λ as a logistic curve; LoD50 is the burden at which a call is as likely as not, LoD90 where it becomes dependable. Below LoD50, a true positive is more often missed than called, whichever classifier runs.
The floor is not the limit. The floor cuts on total SNVs; λ is a share of them. A panel with 8 SNVs clears the floor of 5 and, at a share of a fifth, carries under two Signature 3 mutations: scorable, and below the limit.
A spread-out signature needs more of its own mutations than a concentrated one. A mutation counts as evidence for a signature in proportion to how much more often that signature produces it than the tumor's other processes do. In the catalog SigMA2's classifiers use, SBS3's five most frequent channels hold 12% of its mutations, while SBS2's, half of APOBEC, hold 98%; so on the same panel Signature 3 needs more of its own mutations than APOBEC before a call is likely.
The platform's depth sets what reaches the law. An exome delivers ten to twenty times a panel's count, so the same tumor can be far below LoD50 on MSK-IMPACT and above LoD90 on TCGA MC3; this is why a cell holds at its platform's depth and seq_type="auto" chooses by burden.
A cell has a ceiling. The share of its positives below LoD50 bounds the sensitivity it can reach and, with it, the AUC; more training genomes do not lift it, a deeper assay or copy number for HRD does.

The detection law and a cell's ceiling derives this with the figure; Check what the panel delivered is the practical check on a cohort.

Inputs

Every SNV in a VCF counts, whatever its FILTER. Filter to PASS before scoring. Indels are read only when PASS or ..
Custom panel names are not accepted. seq_type takes the vocabulary only. Score a custom panel as the closest bundled platform, and report it as such.
seq_type="auto" cannot tell panels of similar size apart (msk, fo, op): it chooses by SNV burden and reports the choice. Pass seq_type when you know the platform.
Several resources are hg19 only: the repeat loci behind microsatellite indel counts (MMRD/POLE, and the MMRD/POLE step of an HRD run), the msk HRD model's gene grid, and the bundled panel regions used in training. SNV spectra and allele-specific copy number work on hg38.
Germline is not handled. SigMA2 expects somatic calls.

Classifiers

A classifier exists only for a trained cell. Without one there is no call; the refusal names the platforms that have one and SigMA v1's classifier when it covers the case.
A cell holds at its platform's depth. The MSK-IMPACT cells were trained at panel burden; a sample with an exome's count belongs to the exome's cell. Above the floor, what a cell can call is bounded by where its positives' burdens fall on its detection law (the detection law and a cell's ceiling).
Nothing below the SNV floor is scored, by any classifier. The floor is the classifier's (5; prostate 4; osteosarcoma and pancreatic neuroendocrine 3).
Some classifiers have a loose operating point only: pass_mva_strict is NA. It means "no strict tier", not a failed strict call.
A weak cell's positive call changes the odds little. call_evidence="weak" marks every row.
An experimental cell gives scores, not calls, and only with force=True.
39 breast, lung and skin cells were released before the release gate: their calls carry no evidence grade, and nothing says how much a positive call raises the odds of the signature (release status).
A negative call is weak evidence of absence. The cutoffs hold the false-positive rate, not the sensitivity; on a panel a count of calls is not a signature's prevalence.
A signature run does not check for hypermutation. Run predict_mmrd_ppd() beside it; a call on a tumor called MMRD or POLE is read off a spectrum another process shaped.
Breast SBS3 on msk and tcga_mc3 was trained on strong SBS3 and is not meant to call weak SBS3.
Breast SBS3 on tcga_mc3 was trained on exome panels simulated at hg19 coordinates from genomes aligned to hg38, a mismatch its card records as a known limit (config["known_limit"]), to be corrected by retraining.
Colorectal SBS8 on fo, msk and op is experimental. Colorectal SBS18 calls the summed SBS18 and SBS36 process.
Medulloblastoma SBS3 follows the SBS3 exposure of its training genomes. Their positives carry no more genomic scars than their negatives (a median genomic instability score of 6 against 5, where breast's are 60 against 22), so its calls do not indicate HRD.
Composite signatures other than the presets (APOBEC, SBS7, SBS10, SBS17, CLOCK) have no classifier until you train one.

SigMA v1 features without a counterpart

No add_sig3. SigMA v1 could add Signature 3 to a tumor type whose reference spectra lack it and borrow breast's Signature 3 clusters for the likelihood. SigMA2 scores a signature only against the tumor type's own signature set and reference spectra.
No trinucleotide normalization for a custom panel. SigMA v1's get_trinuc_norm(bed) and norm96 reweighted the catalog to a panel's own territory for scoring. A custom panel is scored as the closest bundled platform; its own BED enters only training, as a SeqType for simulation.
No cutoff at a chosen false-positive rate on a shipped classifier. SigMA v1's get_threshold() set a cutoff at any rate from a quick simulation. A SigMA2 cell has its loose and strict operating points; readjust=True moves them with the cohort's depth, and Add.export_threshold_table() re-scores your own training at other floors.
No matching to single whole genomes. SigMA v1's max_ml_sample_* columns named the most likely training genome and its exposures; SigMA2 matches reference spectra, the cluster centroids, and reports their likelihoods.

HRD and MMRD/POLE

A pooled HRD call rests on other tumor types' training data; hrd_group says when that is the case.
The exome-derived HRD platforms (fo, op, seqcap, tcga_mc3) share one training cohort.
Without copy number the weaker nogis variant runs. On msk, whose gis variant reads the three scar components, a GIS sum alone (gis=) also sends the run to nogis.
A tumor below the SNV floor gets an HRD call that is not an assessment: from copy number and deletion counts alone with segments, from no feature of its own without them. Leave such tumors out of an HRD prevalence.
Copy number from a panel is coarser than what the fo, op and seqcap HRD models learned from: they were trained on SNP-array segments of TCGA tumors. Only the msk model learned copy number at panel resolution.
An own HRD model can rest on as few as three BRCA1/2-deficient tumors; bundled classifiers gives the count per model.
On msk, germline BRCA1/2 carriers sit among the HRD model's negatives: germline status is not in the public MSK-IMPACT data (what each HRD model was trained on).
HRD refuses tumor types it saw in training but cannot score (sarc on every platform; paraganglioma, testicular, thymoma, uveal on the exome-derived ones), and the types never trained.
HRD-low is indeterminate. The pan-cancer and the tumor-type model disagree. Confirm with an orthogonal assay.
An HRD run costs about a second per tumor on one worker, most of it the MMRD/POLE pre-step. Pass mxw="max" for a cohort. segments= restricts nothing: tumors without segments are scored without copy number.
MMRD_category is the most probable class. The per-class cutoffs never overrule it; read the category, not a threshold of your own.
An MMRD call does not exclude a pathogenic POLE mutation: tumors with both were labeled MMRD in training.
Microsatellite indel counts need the repeat-locus files, which sigma2 data fetch downloads only for a GitHub account the maintainers have given access while the manuscript is in preparation; the same six files are in the public SigMA (R) repository. Without them nothing stops: MMRD/POLE is scored as if no tumor had microsatellite indels and an HRD run skips its MMRD/POLE step, without a message at the default verbosity. Check for the nmsi_ins, nmsi_del and MMRD_category columns.
tune_hrd models are cross-validated only. No release gate, no experimental tier.

Readjust

readjust=True enforces no minimum batch size. A batch of one shifts the cutoff to its own depth. Whole cohorts off the training depth only; never a single patient; about 30 samples at least.

Training

Panel simulation needs pybedtools and the bedtools binary, and the bundled regions are hg19. Custom BEDs and hg38 regions were not verified.
The release gate needs at least 30 distinct negatives to certify a 10% false-positive rate, and the operating point must be stable under resampling; small cohorts stall here. Fewer than ten positives releases a model graded weak.
Supplementing a cohort with donor genomes (supplement_from) harmed more often than it helped in the authors' measurements, and nothing predicts when it helps. Run a seed sweep and a negative-donor control if you use it.
The curation vocabulary (strict, weakneg, floor, merge, …) lives in the release scripts and on the cards as label_curation, not in a package API. Hand curation is the studio editor plus Add.apply().
The Add JSON export has no schema version yet. Its core blocks are stable in practice; the tuning block is provisional.

Platform and environment

Windows needs the Microsoft C++ Build Tools at install and a plain-text reference FASTA; the package's own readers replace the dependency that has no Windows wheel there.
scikit-learn is pinned to 1.4 up to, not including, 1.8: the signature classifiers are pickles.
The data directory must be writable for training, saving an Add object and the caches; classifier lookup alone falls back to the package.
The decomposition cache (SIGMA2_DECOMP_CACHE) holds pickles. Share it only with people you would run code from.
The repository is private while the manuscript is in preparation, so the Repository link in the package metadata returns 404 to outsiders.

In the daemon and the studio

The studio's SigMA2 Score step passes the SNV floor and the catalog only when you set them, so the classifier's own apply; the result states both with their source. Older daemon releases passed a flat floor of 5 and the v3.2 catalog; update the runner if the result does not name a source.

When a call is possible, and when it is not

The count is the signature's share times the panel's SNVs. A tumor with Signature 3 in half its mutations and 10 SNVs on the panel gives the classifier about five Signature 3 mutations; one with the same share and 5 SNVs gives it two or three. The package calls this count the burden, λ.

Each cell has a detection law. On its own cross-validation, the probability of a call rises with λ as a logistic curve; LoD50 is the burden at which a call is as likely as not, LoD90 where it becomes dependable. Below LoD50, a true positive is more often missed than called, whichever classifier runs.

The floor is not the limit. The floor cuts on total SNVs; λ is a share of them. A panel with 8 SNVs clears the floor of 5 and, at a share of a fifth, carries under two Signature 3 mutations: scorable, and below the limit.

A spread-out signature needs more of its own mutations than a concentrated one. A mutation counts as evidence for a signature in proportion to how much more often that signature produces it than the tumor's other processes do. In the catalog SigMA2's classifiers use, SBS3's five most frequent channels hold 12% of its mutations, while SBS2's, half of APOBEC, hold 98%; so on the same panel Signature 3 needs more of its own mutations than APOBEC before a call is likely.

The platform's depth sets what reaches the law. An exome delivers ten to twenty times a panel's count, so the same tumor can be far below LoD50 on MSK-IMPACT and above LoD90 on TCGA MC3; this is why a cell holds at its platform's depth and seq_type="auto" chooses by burden.

A cell has a ceiling. The share of its positives below LoD50 bounds the sensitivity it can reach and, with it, the AUC; more training genomes do not lift it, a deeper assay or copy number for HRD does.

Inputs

Every SNV in a VCF counts, whatever its FILTER. Filter to PASS before scoring. Indels are read only when PASS or ..

Custom panel names are not accepted. seq_type takes the vocabulary only. Score a custom panel as the closest bundled platform, and report it as such.

seq_type="auto" cannot tell panels of similar size apart (msk, fo, op): it chooses by SNV burden and reports the choice. Pass seq_type when you know the platform.

Several resources are hg19 only: the repeat loci behind microsatellite indel counts (MMRD/POLE, and the MMRD/POLE step of an HRD run), the msk HRD model's gene grid, and the bundled panel regions used in training. SNV spectra and allele-specific copy number work on hg38.

Germline is not handled. SigMA2 expects somatic calls.

Classifiers

A classifier exists only for a trained cell. Without one there is no call; the refusal names the platforms that have one and SigMA v1's classifier when it covers the case.

A cell holds at its platform's depth. The MSK-IMPACT cells were trained at panel burden; a sample with an exome's count belongs to the exome's cell. Above the floor, what a cell can call is bounded by where its positives' burdens fall on its detection law (the detection law and a cell's ceiling).

Nothing below the SNV floor is scored, by any classifier. The floor is the classifier's (5; prostate 4; osteosarcoma and pancreatic neuroendocrine 3).

Some classifiers have a loose operating point only: pass_mva_strict is NA. It means "no strict tier", not a failed strict call.

A weak cell's positive call changes the odds little. call_evidence="weak" marks every row.

An experimental cell gives scores, not calls, and only with force=True.

39 breast, lung and skin cells were released before the release gate: their calls carry no evidence grade, and nothing says how much a positive call raises the odds of the signature (release status).

A negative call is weak evidence of absence. The cutoffs hold the false-positive rate, not the sensitivity; on a panel a count of calls is not a signature's prevalence.

A signature run does not check for hypermutation. Run predict_mmrd_ppd() beside it; a call on a tumor called MMRD or POLE is read off a spectrum another process shaped.

Breast SBS3 on msk and tcga_mc3 was trained on strong SBS3 and is not meant to call weak SBS3.

Breast SBS3 on tcga_mc3 was trained on exome panels simulated at hg19 coordinates from genomes aligned to hg38, a mismatch its card records as a known limit (config["known_limit"]), to be corrected by retraining.

Colorectal SBS8 on fo, msk and op is experimental. Colorectal SBS18 calls the summed SBS18 and SBS36 process.

Medulloblastoma SBS3 follows the SBS3 exposure of its training genomes. Their positives carry no more genomic scars than their negatives (a median genomic instability score of 6 against 5, where breast's are 60 against 22), so its calls do not indicate HRD.

Composite signatures other than the presets (APOBEC, SBS7, SBS10, SBS17, CLOCK) have no classifier until you train one.

SigMA v1 features without a counterpart

No add_sig3. SigMA v1 could add Signature 3 to a tumor type whose reference spectra lack it and borrow breast's Signature 3 clusters for the likelihood. SigMA2 scores a signature only against the tumor type's own signature set and reference spectra.

No trinucleotide normalization for a custom panel. SigMA v1's get_trinuc_norm(bed) and norm96 reweighted the catalog to a panel's own territory for scoring. A custom panel is scored as the closest bundled platform; its own BED enters only training, as a SeqType for simulation.

No cutoff at a chosen false-positive rate on a shipped classifier. SigMA v1's get_threshold() set a cutoff at any rate from a quick simulation. A SigMA2 cell has its loose and strict operating points; readjust=True moves them with the cohort's depth, and Add.export_threshold_table() re-scores your own training at other floors.

No matching to single whole genomes. SigMA v1's max_ml_sample_* columns named the most likely training genome and its exposures; SigMA2 matches reference spectra, the cluster centroids, and reports their likelihoods.

HRD and MMRD/POLE

A pooled HRD call rests on other tumor types' training data; hrd_group says when that is the case.

The exome-derived HRD platforms (fo, op, seqcap, tcga_mc3) share one training cohort.

Without copy number the weaker nogis variant runs. On msk, whose gis variant reads the three scar components, a GIS sum alone (gis=) also sends the run to nogis.

A tumor below the SNV floor gets an HRD call that is not an assessment: from copy number and deletion counts alone with segments, from no feature of its own without them. Leave such tumors out of an HRD prevalence.

Copy number from a panel is coarser than what the fo, op and seqcap HRD models learned from: they were trained on SNP-array segments of TCGA tumors. Only the msk model learned copy number at panel resolution.

An own HRD model can rest on as few as three BRCA1/2-deficient tumors; bundled classifiers gives the count per model.

On msk, germline BRCA1/2 carriers sit among the HRD model's negatives: germline status is not in the public MSK-IMPACT data (what each HRD model was trained on).

HRD refuses tumor types it saw in training but cannot score (sarc on every platform; paraganglioma, testicular, thymoma, uveal on the exome-derived ones), and the types never trained.

HRD-low is indeterminate. The pan-cancer and the tumor-type model disagree. Confirm with an orthogonal assay.

An HRD run costs about a second per tumor on one worker, most of it the MMRD/POLE pre-step. Pass mxw="max" for a cohort. segments= restricts nothing: tumors without segments are scored without copy number.

MMRD_category is the most probable class. The per-class cutoffs never overrule it; read the category, not a threshold of your own.

An MMRD call does not exclude a pathogenic POLE mutation: tumors with both were labeled MMRD in training.

Microsatellite indel counts need the repeat-locus files, which sigma2 data fetch downloads only for a GitHub account the maintainers have given access while the manuscript is in preparation; the same six files are in the public SigMA (R) repository. Without them nothing stops: MMRD/POLE is scored as if no tumor had microsatellite indels and an HRD run skips its MMRD/POLE step, without a message at the default verbosity. Check for the nmsi_ins, nmsi_del and MMRD_category columns.

tune_hrd models are cross-validated only. No release gate, no experimental tier.

Training

Panel simulation needs pybedtools and the bedtools binary, and the bundled regions are hg19. Custom BEDs and hg38 regions were not verified.

The release gate needs at least 30 distinct negatives to certify a 10% false-positive rate, and the operating point must be stable under resampling; small cohorts stall here. Fewer than ten positives releases a model graded weak.

Supplementing a cohort with donor genomes (supplement_from) harmed more often than it helped in the authors' measurements, and nothing predicts when it helps. Run a seed sweep and a negative-donor control if you use it.

The curation vocabulary (strict, weakneg, floor, merge, …) lives in the release scripts and on the cards as label_curation, not in a package API. Hand curation is the studio editor plus Add.apply().

The Add JSON export has no schema version yet. Its core blocks are stable in practice; the tuning block is provisional.

Platform and environment

Windows needs the Microsoft C++ Build Tools at install and a plain-text reference FASTA; the package's own readers replace the dependency that has no Windows wheel there.

scikit-learn is pinned to 1.4 up to, not including, 1.8: the signature classifiers are pickles.

The data directory must be writable for training, saving an Add object and the caches; classifier lookup alone falls back to the package.

The decomposition cache (SIGMA2_DECOMP_CACHE) holds pickles. Share it only with people you would run code from.

The repository is private while the manuscript is in preparation, so the Repository link in the package metadata returns 404 to outsiders.