Python API

The public functions of sigma2 0.0.16-alpha.20, one section per function: its signature as the package defines it and what each argument does. The package also exports mmrd_model, mmrd_models, AnnotatedFrame, logger and LEGACY, which have no section here, and the internal modules api, steps and tools (what is public). import sigma2 as sg2 throughout. Names (tumor_type, seq_type, soi, catalog, model names) match in any case.

The reference is one page per section, and every function is presented the same way: one sentence on what it does, its signature as the package defines it, its parameters, what it returns, a call as a guide runs it, and the guides that use it.

Scoring

Function	Does
`run`	Score one signature of interest with one classifier.
`predict_mmrd_ppd`	MMRD, POLE or MMRP per sample (Detect MMRD or POLE).
`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.
`resolve_signature`	Turn a name into a signature object: `sg2.resolve_signature("apobec")`.
`CompositeSignature`	A signature made of several COSMIC signatures.

Manage models and the store

Function	Does
`models`	Installed model names (`'breast/SBS3/msk'`, `'experimental/prost/SBS3/op'`), optionally filtered; `root_dir` reads another store.
`model`	Load a classifier by name or by parts.
`verify_model`	`True` when the model's files match the SHA-256 in its `meta.json`; `ValueError` on a mismatch.
`delete_model`	Remove one of your own models from the store.
`models.migrate`	Move a store that still holds weights a release retired (`retired.json`).
`classifiers.cards`	Every installed cell as data.
`classifiers.mmrd_platforms`	The platforms with a SigMA2 MMRD/POLE model: `fo`, `msk`, `op`, `seqcap`, `tcga_mc3`.

HRD

Function	Does
`hrd_features`	The HRD feature table, one row per sample: `sig3_score`, `sig3_ml`, `sig3_exp`, `gis`, `hrd_loh`, `tai`, `lst`, `fga`, `lst_lr`, `mmej`, `nhej`, `tumor_type`.
`score_hrd`	Score a feature table: `hrd_group`, `hrd_variant`, `hrd_score_pan`, `hrd_score_type`, `hrd_score`, `hrd_call`.
`genomic_instability`	HRD-LOH, TAI, LST and their sum `gis` from allele-specific segments.
`copy_number_instability`	Fraction of genome altered (`fga`) and log-ratio LST (`lst_lr`) from log-ratio segments.
`indel_features`	`mmej`, `nhej`, `nins`, `ndel`, `nmsi_ins`, `nmsi_del` per sample from indels, against the repeat loci.
`hrd_model`	Load an HRD model.
`hrd_models`	The installed HRD models: `fo`, `msk`, `op`, `seqcap`, `tcga_mc3`, plus yours.
`hrd.hrd_summary`	Own or pooled per tumor type and platform, and the variants each model has.
`tune_hrd`	Train an HRD model.

Training

Function	Does
`Add`	The training object (Train a classifier).
`Add.annotate`	Bin each signature's exposures into labels: `0` negative, the other bins positive bands.
`Add.cluster`	Cluster samples within each band and take the centroids.
`Add.simulate`	Downsample every genome to each platform's capture regions, topped up by `scaling_factor` from `addition_source` (default: the genome's own spectrum).
`Add.tune`	Train one classifier per signature and platform in nested cross-validation and write the result tree.
`Add.publish`	Write the models into the data directory's store behind the release gate; a withheld cell goes to `experimental/`.
`Add.export`	Write every model to `output_dir` in the store layout, with no gate.
`Add.save`	`.pkl` saves the full state at any stage; `.json` saves the editor export (spectra, exposures, bins, clusters, optional simulations and tuning).
`Add.load`	Restore from a `.pkl`, a `.json` (clusters applied; `simulate()` unavailable), or an `(H, W)` pair of exposure and signature matrices (spectra reconstructed as W·H; `simulate()` and `tune()` on it are invalid).
`Add.apply`	Apply a cluster-editor JSON back into the object: bins and clusters replaced, simulations and models invalidated.
`Add.inject_simulations`	Simulations made elsewhere: `{panel}.csv` files or a `{panel: path}` dict, sample × 96 with the object's sample IDs.
`Add.extend`	Add a signature to a built object, with its own annotation.
`Add.split`	Hold out a split; its scores land in `eval_scores.tsv`.
`Add.merge`	Merge two objects of the same tumor type.
`Add.drop_duplicates`	Removes genomes that are present twice.
`Add.label_report`	Positives, negatives, exact zeros and prevalence per signature, with a warning for negative classes under 30.
`Add.sparse_report`	Simulated samples below the floor, per signature, platform and bin.
`Add.filter_sparse`	Drop simulated samples below a floor, optionally resimulating.
`Add.fractional_exposures`	Exposures as fractions of the catalog total.
`Add.export_threshold_table`	Re-score a finished run at several SNV floors without retraining; writes `threshold_auc_table.tsv`, `threshold_curve.tsv`, `sigma2_thresholds.json` and, with `stratifier`, `stratified_auc.tsv`.
`Add.record_provenance`	Write the provenance files of a result tree.
`Add.label_definition`	How each signature's labels were defined, as data.
`Add.supplement_from`	Add donor genomes from another cohort.
`Add.contaminate`	Mix germline calls into the simulations at a rate, for robustness checks.
`tools.simulator.calibrate_scaling_factor`	Fit the scaling factor that matches a real cohort's burden distribution on the panel: `f_star`, the distance curve, and whether the optimum sits on the grid's edge.

Inputs and data

Function	Does
`Samples`	Read mutations into a 96-channel table (`.df`, with `total_snvs`): a MAF, a VCF, a list or folder of VCFs, or a matrix.
`MAF, VCF, CSV, BED, SeqType`	The file objects behind `input`.
`get`	Read-only access to the package's tables: `"sig_catalogs/cosmic_v3p2_inhouse"`, `"indices/tumor_types"`, `"sigs_per_tissue"`, `"cosmic_catalogs/<catalog>"`, `"snv_counts"`, `"mva_cutoffs"`, `"tumor_sig_catalogs/<tumor type>"`.
`set and clear`	Your own tables in `sysdata/custom.h5`, for advanced use.
`legacy_store.available`	SigMA v1's grid as a table.

Removed and deprecated lists what earlier releases had.

SigMA v1 tools

Function	Does
`quick_simulation`	Simulate panels like a cohort from whole genomes of known Signature 3 status.
`get_threshold`	The score cutoff at a chosen false-positive rate, false-discovery rate or sensitivity.
`sen_fpr`	Sensitivity, false-positive rate and false-discovery rate at every score.
`cluster_characteristics`	The signature exposures of each tumor's most likely cluster.
`match_training_genomes`	The training genome each tumor matches best, and whether it carries Signature 3.