For AI agents

An agent drives SigMA2 in three places: the Python package, the command line, and sigscape studio through the local runner. This page is the entry point for a model.

The agent document

/sigma2/llms.txt is the whole knowledge base as one plain-text file: the API with every argument, the input contracts, the output glossary, the rules for floor, cutoffs and catalog, the status model, the known limits, the worked examples with their expected outputs, and the vocabulary. Load it before writing code against sigma2. It describes release 0.0.16-alpha.20 and names that release at the top.

The site's own guide for the studio is /llms.txt; it names the SigMA2 Score step's hooks and parameters.

Rules an agent must keep

Pass tumor_type, seq_type and soi explicitly. seq_type="auto" chooses by burden and cannot tell panels of similar size apart.
Leave catalog and snv_ctf out unless the user asked for a specific value. The classifier's own apply, and run() warns or refuses when a different catalog is passed.
Read calls from pass_mva and pass_mva_strict, never from a threshold of your own on <soi>_mva. Read MMRD/POLE from MMRD_category, never from the _prob columns.
NA means no call, not negative. pass_mva_strict NA means the classifier has only a loose operating point; every call column NA means a score-only classifier was forced.
force=True gives scores without calls. State that in anything you report from it.
Report the status and the evidence word with any call: Card.status for the cell, call_evidence per row. Do not report performance numbers from a card as if they were the documentation's claims.
Filter VCFs to PASS before scoring. Every record counts otherwise.
Record the release (sg2.__version__), the platform, the tumor type, the floor and the catalog with any table you write.
Import classifiers by name (from sigma2 import classifiers); it is not an attribute of the package until imported.

Discover what exists, as data

Input — Pythonpython

import sigma2 as sg2
from sigma2 import classifiers

# Card(tumor_type, classifier, seq_type, kind, status, verified, trained, snv_cutoff)
cards = classifiers.cards(tumor_type="breast")
released = [c for c in cards if c.kind == "signature" and c.status != "experimental"]
names = sg2.models(tumor_type="breast", seq_type="msk")
covered = sg2.hrd_model("msk").covered_tumor_types()
platforms = classifiers.mmrd_platforms()
# ['fo', 'msk', 'op', 'seqcap', 'tcga_mc3']
tumor_types = sg2.get("indices/tumor_types")
seq_types = sg2.SeqType.options()

Parameter	Description	Default
tumor_typestr	Keep the cards of this tumor type.	`None`

All parameters of classifiers.cards

Parameter	Description	Default
tumor_typestr	Keep the models of this tumor type.	`None`
seq_typestr	Keep the models of this platform.	`None`

All parameters of models

hrd_model is called with its defaults. All parameters of hrd_model

get is called with its defaults. All parameters of get

sg2.describe() prints the same for a person; prefer cards() in code.

A complete call and its checks

Input — Terminalbash

curl -LO https://raw.githubusercontent.com/parklab/SigMA/master/inst/extdata/examples/test_mutations_50sample.maf

test_mutations_50sample.mafMAF (tab-separated mutations, hg19) · 216 KB

Input — Pythonpython

out = sg2.run(
    input="test_mutations_50sample.maf",
    ref_genome="hg19",
    tumor_type="breast",
    seq_type="msk",
    soi="SBS3",
    verbose=1,
)
df = out.df
assert "SBS3_mva" in df.columns
# read - scored samples were below the floor
scored, read = len(df), len(out.input_matrix.df)
calls = df.index[df["pass_mva"] == True]                          # loose calls
# strict calls; empty if the column is all NA
strict = df.index[df["pass_mva_strict"] == True]
weak = (df["call_evidence"] == "weak").any()                      # the cell is a weak-evidence cell

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`

All parameters of run

A refusal raises ValueError with a message that names the fix (force=True, a platform to pass, the catalog to leave out). Catch it and read the message; do not retry with other arguments blindly.

In sigscape studio

The studio's SigMA2 tool exposes a Score step and the Build, Simulate and Tune steps. Its hooks: [data-studio="sigma2"] with data-stage, [data-studio="sigma2-score"] with data-ready, data-samples, data-called, data-model and data-model-status, rows of [data-studio="sigma2-score-table"] with data-sample, data-score, data-call and data-below-floor, [data-studio="sigma2-score-summary"] with data-scored, data-below-floor, data-floor and data-catalog, [data-studio="sigma2-model-card"] with data-status. window.sigscapeStudio.openTool("sigma2") opens it; the run's score.json records catalogSource and snvFloorSource. In sigscape studio and the studio's agent page.

What not to do

Do not invent a seq_type for a custom panel; score as the closest bundled platform and report that platform.
Do not call HRD without segments and present the result as a copy-number-aware call; the nogis variant ran.
Do not readjust cutoffs on a single sample or a small batch.
Do not quote performance numbers from this documentation; it contains none.

For AI agents

An agent drives SigMA2 in three places: the Python package, the command line, and sigscape studio through the local runner. This page is the entry point for a model.

The agent document

The site's own guide for the studio is /llms.txt; it names the SigMA2 Score step's hooks and parameters.

Rules an agent must keep

Pass tumor_type, seq_type and soi explicitly. seq_type="auto" chooses by burden and cannot tell panels of similar size apart.
Leave catalog and snv_ctf out unless the user asked for a specific value. The classifier's own apply, and run() warns or refuses when a different catalog is passed.
Read calls from pass_mva and pass_mva_strict, never from a threshold of your own on <soi>_mva. Read MMRD/POLE from MMRD_category, never from the _prob columns.
NA means no call, not negative. pass_mva_strict NA means the classifier has only a loose operating point; every call column NA means a score-only classifier was forced.
force=True gives scores without calls. State that in anything you report from it.
Report the status and the evidence word with any call: Card.status for the cell, call_evidence per row. Do not report performance numbers from a card as if they were the documentation's claims.
Filter VCFs to PASS before scoring. Every record counts otherwise.
Record the release (sg2.__version__), the platform, the tumor type, the floor and the catalog with any table you write.
Import classifiers by name (from sigma2 import classifiers); it is not an attribute of the package until imported.

Discover what exists, as data

Input — Pythonpython

import sigma2 as sg2
from sigma2 import classifiers

# Card(tumor_type, classifier, seq_type, kind, status, verified, trained, snv_cutoff)
cards = classifiers.cards(tumor_type="breast")
released = [c for c in cards if c.kind == "signature" and c.status != "experimental"]
names = sg2.models(tumor_type="breast", seq_type="msk")
covered = sg2.hrd_model("msk").covered_tumor_types()
platforms = classifiers.mmrd_platforms()
# ['fo', 'msk', 'op', 'seqcap', 'tcga_mc3']
tumor_types = sg2.get("indices/tumor_types")
seq_types = sg2.SeqType.options()

Parameter	Description	Default
tumor_typestr	Keep the cards of this tumor type.	`None`

All parameters of classifiers.cards

Parameter	Description	Default
tumor_typestr	Keep the models of this tumor type.	`None`
seq_typestr	Keep the models of this platform.	`None`

All parameters of models

hrd_model is called with its defaults. All parameters of hrd_model

get is called with its defaults. All parameters of get

sg2.describe() prints the same for a person; prefer cards() in code.

A complete call and its checks

Input — Terminalbash

curl -LO https://raw.githubusercontent.com/parklab/SigMA/master/inst/extdata/examples/test_mutations_50sample.maf

test_mutations_50sample.mafMAF (tab-separated mutations, hg19) · 216 KB

Input — Pythonpython

out = sg2.run(
    input="test_mutations_50sample.maf",
    ref_genome="hg19",
    tumor_type="breast",
    seq_type="msk",
    soi="SBS3",
    verbose=1,
)
df = out.df
assert "SBS3_mva" in df.columns
# read - scored samples were below the floor
scored, read = len(df), len(out.input_matrix.df)
calls = df.index[df["pass_mva"] == True]                          # loose calls
# strict calls; empty if the column is all NA
strict = df.index[df["pass_mva_strict"] == True]
weak = (df["call_evidence"] == "weak").any()                      # the cell is a weak-evidence cell

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`

All parameters of run

A refusal raises ValueError with a message that names the fix (force=True, a platform to pass, the catalog to leave out). Catch it and read the message; do not retry with other arguments blindly.

In sigscape studio

What not to do

Do not invent a seq_type for a custom panel; score as the closest bundled platform and report that platform.
Do not call HRD without segments and present the result as a copy-number-aware call; the nogis variant ran.
Do not readjust cutoffs on a single sample or a small batch.
Do not quote performance numbers from this documentation; it contains none.