# sigscape.org

> Tools for mutational signatures: MuTopia (signature and topography inference) and SigMA2
> (panel-sequencing signature detection), plus sigscape studio, a browser workbench that runs
> entirely client-side on the home page. Nothing is uploaded; data stays in the browser session.

## sigscape studio (home page)

The studio is built to be operated by people and by AI agents alike. Three ways in:

- Accessibility tree: regions are marked `data-studio="bar|data|canvas|explorer|status"` and
  carry aria-labels; every control has an accessible name; records are `role=checkbox` rows with
  `data-record`; tabs are `role=tab` with `data-tab`.
- Machine-readable state: `<script type="application/json" id="sigscape-studio-state">` holds the
  current records, tabs, selection, open tool and its inputs, panels and warnings.
- Scripting: `window.sigscapeStudio` — `help()`, `state()`, `commands()`, `run(id)`,
  `select(recordId, on)`, `openTool(capId)`, `addFiles(files)`, `removeRecord(id)`.

Keyboard: ⌘K / Ctrl+K opens the command palette, which reaches every function, record, example and
panel. ⌘B toggles the data panel, ⌘J the explorer. Nothing is hover-only: tooltip content is
repeated in a panel.

Functions: `plot-spectrum` (SBS-96 spectra from matrices, VCF or MAF), `exposure-compare`
(exposure tables H against a signature matrix W), `sigma2` (the SigMA2 pipeline: curate, simulate,
tune, compare, over an Add-object JSON, tuning results folders, or H + W), `mutopia` (the MuTopia
package: `mutopia-sbs annotate-vcf` with the tumor type's pre-trained model over a VCF and a
reference FASTA; the stages read the annotated VCF: exposures, genome topography at 10 kb, Shapley
feature drivers and strand asymmetry, placement in the 208-component atlas and its eight topotypes),
`musical` (the MuSiCal package: DenovoSig discovery with minimum-volume NMF, catalog matching and
sparse likelihood refitting against COSMIC v3.2, validation), `tau` (the Tau package: timing
copy-number gains from mutation multiplicity, every gain route enumerated, pooled into doublings).

A tool on the runner is a pipeline of steps (MuSiCal: discover, match, refit; Tau and MuTopia: one
run; SigMA2: build, simulate, tune when bound to mutations + an exposure table, tune alone on a
bound Add object). Each step has one Run button with its parameters beside it and lists every run it
has made, with its parameters as the label; the chosen run feeds the next step, earlier runs are
kept, and a run from another lineage is listed dimmed. Every run is a checkpoint in the daemon's
workspace (`sigscape-runs/<id>/`) and downloads as a zip from its row; the last stage downloads the
chosen chain as one zip. The DOM carries `[data-studio="step"][data-step][data-phase]`, one
`[data-run][data-state][aria-current]` per run, and `[data-studio="export"]` on the chain link.

Big inputs stay on the runner: whatever is put in the daemon workspace's `data/` folder is listed
as records (a folder of VCFs is one record of format "VCF folder"; a table small enough is parsed
like a drop), grouped under the folder's name with a "runner" tag, and passed to a tool by path.
SigMA2 from mutations + exposures reads them there: `build` runs sigma2's annotate and cluster
(tumor type, signatures of interest, panels, reference genome as parameters), the object it wrote
opens for curation under Curate, `simulate` downsamples the chosen build into panels and applies
that curation first, `tune` trains on the chosen simulation.

Input kinds: every function names its inputs by a shared kind (sigscapeStudio.inputs(): id, what it
is, what the file must look like, formats); a slot in the Start board pane carries data-kind, the
same id in every tool, so a VCF asked by MuTopia is the VCF Tau asks for. The Start board marks a
function that computes on the runner with the studio mark ("runner", data-runner on the row); such a
function is locked until a compatible runner answers (data-locked="runner" on the row, its standing
reads "Needs the local runner" / "Runner stopped" / "Runner outdated", Run and the tool:<id> command
are disabled, [data-studio="catalog-lock"] in the pane carries the way in).

Sessions: with the runner connected the studio saves this tab's session (records, tabs, selections,
files already on the runner) to the daemon and loads the newest back when the page is opened again;
state().session names it; [data-studio="session"] in the bar opens the menu ([data-studio=
"session-menu"]): New session, Rename, the saved ones (open here or in a new tab, /?session=<id>),
delete. Each browser tab holds one session.

Variants to spectra: openTool("tally") with a VCF, MAF or table selected (an indexed FASTA or .2bit
record is optional). Without one, contexts come from UCSC's hg19/hg38 2bit files by range request and the
build is read off 200 REF alleles. [data-studio="tally"] carries data-phase (idle|reading|checking|
tallying|done|error); [data-studio="tally-result"] carries data-values (SBS-96 of the shown sample) and
data-dbs; [data-studio="tally-build"] carries data-build; [data-studio="tally-attach"] puts the spectra
on the record; tally-export-sbs and tally-export-dbs download SigProfiler matrices.

Utilities (in the page): openTool("compare-spectra" | "signature-diff" | "crosswalk" | "artifact-screen").
Each root carries data-ready="true" when computed. Compare: [data-pair="i-j"] cells with data-verdict
(within|beyond|proportions); [data-studio="compare-pair"] has data-a, data-b, data-cosine, data-p05,
data-verdict. Diff: data-matched; [data-studio="diff-pairs"] buttons carry data-a, data-b, data-cosine.
Crosswalk: data-from, data-to; [data-studio="crosswalk-notes"] li carry data-from, data-how.
Artifacts: data-artifact-share; [data-studio="artifact-list"] li carry data-signature, data-lower.
Every utility: [data-studio="share-link"] (then [data-studio="share-url"] holds the link),
[data-studio="recipe"] downloads the recipe JSON, [data-studio="figure"] the SVG. A link
https://sigscape.org/#d=<token> opens the tool with its inputs; the token is deflate-raw JSON in base64url:
{v:1, tool, files:[{name,text}], view}.

De novo workbench: openTool("denovo") with a SigProfilerExtractor folder record (format "SigProfilerExtractor
output") or a signature matrix selected, plus optionally an SBS-96 sample matrix; MuSiCal discovery runs on the
runner are listed as sources in its first select. [data-studio="denovo"] has data-k and data-source;
[data-studio="novelty-list"] buttons carry data-signature and data-verdict (known | mixture | tissue variant |
likely artifact | candidate novel | unresolved); [data-studio="lineage"] nodes carry data-k, data-signature,
data-split, data-new; [data-studio="missing-run"] fits the missing signature and [data-studio="missing-result"]
carries data-verdict and data-nearest. A tool that throws shows [data-studio="tool-error"] instead of blanking the page.

Assays: Tally reads the assay off the SNV positions ([data-studio="tally-assay"] data-assay = wgs|exome|panel|unknown)
and puts it on the record (records carry assay.kind/territory); the artifact screen and the de novo missing-signature
refit correct COSMIC to that territory by default ([data-studio="assay-mismatch"] appears when another is chosen).
Reference data: /reference/pcawg-v1/{manifest.json, slice.json.gz, opportunity_hg19.json, territories_hg19.json.gz}.

Refit confidence: openTool("trust-report") with SBS-96 spectra. [data-studio="trust-report"] has data-ready and
data-method (full|type); rows of [data-studio="trust-table"] carry data-signature, data-verdict (confident | trade-off |
possible false positive | uncertain | minor) and data-share. [data-studio="trust-run"] refits on the runner with MuSiCal
and SigProfilerAssignment (daemon tool sigprofiler-assignment); the "Methods detecting" cells carry data-agree.

Mapping: openTool("map-pcawg"); [data-studio="map-pcawg"] carries data-call (the voted tumor type);
[data-studio="map-votes"] li carry data-type and data-count; [data-studio="map-neighbors"] rows carry data-aliquot.

Sample explorer: openTool("explorer") with one hg38 VCF/MAF (a reference optional); [data-studio="explorer-run"]
starts it; [data-studio="explorer-report"] data-phase (idle|running|done|error), data-model, data-exact-run (the id
of MuTopia's exact run on the runner for these records and this model, when there is one). Components are reported
by spectrum group: [data-studio="explorer-processes"] li carry data-component (the atlas ids, joined by +),
data-members and data-weight; a group of several carries [data-studio="explorer-split"] data-source (runner|none).
Process states come only from the exact run: [data-studio="explorer-exact"] data-run; [data-studio="explorer-state"]
carries data-process, data-share-b and data-source="runner"; [data-studio="explorer-exact-add"] adds MuTopia as the
step below. [data-studio="explorer-topotypes"] children carry data-topotype and data-share; [data-studio="explorer-export"]
downloads every posterior by group. Models that failed the pre-registered gate are listed "(runner only)".

Timing: openTool("timing") with one PURPLE-annotated VCF; the "Run Tau" step runs Tau on the runner;
[data-studio="timing"] data-ready; [data-studio="timing-summary"] names the events; [data-studio="timing-table"] rows
carry data-signature, data-early and data-late (shares before and after the gain).

Dossier: openTool("dossier") needs no records; [data-studio="dossier"] carries data-signature and data-artifact;
[data-studio="dossier-prevalence"] rows carry data-type; [data-studio="dossier-forms"] cards carry data-component and
data-topotype. Methods text: [data-studio="methods"] in any function's toolbar copies a paragraph from its recipe.

Builds and recipes: a VCF or reference record reports its build (state().records[].build is not
yet in the snapshot; the data panel shows "hg19 · chr" etc.); MuTopia refuses an hg19 VCF with a
diagnostic, and the Liftover function (tool id liftover, kind somatic-vcf) moves a VCF between
builds and adds the lifted file as a record ([data-studio="liftover-add"]). Every daemon run has
recipe.json beside its outputs. Catalogs live under /catalogs/ (manifest.json names versions and
licenses; crosswalk.json maps names between catalogs).

MuTopia, MuSiCal, Tau and SigMA2 run as the real packages on the user's machine through
the local runner, sigscape-daemon (github.com/sigscape/sigscape-daemon). It is installed with one
command (`curl -fsSL https://sigscape.org/daemon/install.sh | sh`, or
`irm https://sigscape.org/daemon/install.ps1 | iex` on Windows), which takes the latest GitHub
release and checks its checksum; `sigscape-daemon --workspace ~/sigscape --open` then opens this
site already connected (the link it prints carries `?runner=…&token=…`). The releases are private; the
installer and the daemon use the machine's GitHub CLI login or SIGSCAPE_GITHUB_TOKEN. The runner
sits at the left of the status bar like Docker Desktop's engine: [data-studio="runner-indicator"]
with data-state (ok|attention|problem|empty) reads "Runner running 0.2.0", "Runner stopped",
"No runner"; clicking it opens the flyout [data-studio="runner-panel"] with the workspace, runs,
tools, updates ([data-studio="runner-update"][data-phase]) and the actions "Check for updates",
"Update to X and restart" ([data-studio="runner-apply-update"]), "Restart runner", "Show log"
([data-studio="runner-log"]), "Install or connect…", "Disconnect". An available release is also
a warning-center entry. State is in `sigscapeStudio.state().runner` (version, compatible, update).
Tools are installed per version, the way Docker lists images: "Manage tools…" in the flyout or
run("runner-tools") opens [data-studio="runner-tools"], one [data-tool][data-state] row per tool
(installed|update|absent|running) with [data-version][data-installed] lines (Install, Update to X,
Remove) and a "Runs" select for the version runs use. The runner's API has the same:
GET /api/registry, POST|DELETE /api/registry/<tool>/<version>, POST /api/registry/refresh; a run
asks for a version with params.tool_version, and its recipe.json names it (toolVersion). The list
of versions is /runner/tools.json on this site.
A step that cannot run says why in the footer's words next to its Run button, with the way in as
a link: "No runner · Install the local runner…", "Runner stopped · How to start it…", "Runner
refused the token · Connect again…" (the daemon makes a new token each start), "Runner outdated ·
Install the current release…" (a daemon older than the studio needs cannot update itself). The
tool's checks carry the same finding under the id "runner". The Software page /packages/studio
is the way in for people; the documentation is at /docs/studio (install, connect, run, runs,
data, updates, troubleshooting, agents, daemon reference). /?tool=<id> opens a tool on arrival. A tool's first run provisions its
environment as a visible job phase; the job's log streams into the tool, its artifacts are read
back. Without a runner those tools open, bind inputs and explain what is missing in their checks,
but cannot run.

Accepted inputs: SBS-96 matrices (TSV/CSV), VCF (with AD or t_alt_count for Tau), MAF, SNV tables
with tumor read counts, CN segment tables (Major_CN, Minor_CN), BED, bedGraph, bigWig, FASTA,
chromsizes, SigMA2 Add-object JSON (tuned or not), SigMA2 tuning results folders, exposure tables.

## Pages

- /: the studio
- /docs: package documentation, one card per package
- /packages/mutopia, /packages/sigma: package pages (install, citation, tutorials)
- /about: the labs and contributors

## Stacks and workflows
A tab is a stack: the function it was opened with is step 1, and "Add a step" (or sigscapeStudio.addStep("<capId>"), or the palette's "Add … as a step") puts another function below it, bound to the same records and to what the steps above published (Refit confidence publishes the called exposures, Compare spectra the pair's difference, Timing the before and after spectra). state().tabs[].steps lists them with what each reads; [data-studio="stack"] holds [data-studio="step-frame"][data-step-index][data-tool]; [data-studio="stack-add"] is the way in. "Save as a workflow…" (sigscapeStudio.saveWorkflow(name)) keeps the stack under a name in the browser; the Start board lists built-in and saved workflows ([data-studio="workflows"], run("workflow:<id>")), and a workflow opens as a new tab with its steps on the selection, ready to edit or extend.

Preview access: the studio is in preview. Functions declared open (plot-spectrum, exposure-compare, tally) run for
everyone; every other function needs an invitation, a signed token "sigscape1.<payload>.<signature>" issued by the team
to one e-mail address, verified in the page with a public key (nothing is sent anywhere) and kept in localStorage
sigscape.access.v1. state().access = { level: "checking"|"basic"|"invited", email }; sigscapeStudio.enterInvitation(
tokenOrLink) resolves to null when it is in, else the reason; command "access" opens the dialog. Hooks:
[data-studio="access"] (status bar) data-level; [data-studio="access-dialog"] data-level; [data-studio="access-input"];
[data-studio="access-enter"]; [data-studio="access-error"]; [data-studio="access-holder"]; [data-studio="access-leave"].
Without an invitation, a function that needs one is not listed anywhere: not on the Start board, not in commands(),
not as a step, and no workflow containing one; openTool and addStep return false for it. The runner's word in the
status bar appears only for the invited.