Headless and cluster runs
The runner's tools run without a browser. sigscape-daemon run takes the path the studio's Run button takes, with the same validation, the same tool version from the registry, and the same run folder: sigscape-runs/<id>/ with the outputs, job.json, recipe.json and daemon.log. Open the workspace in the studio afterwards and the runs are listed under their step, choosable and exportable like any other.
One run
sigscape-daemon run sigma2 --workspace ~/sigscape \
--input mutations=data/cohort.maf --param stage=score --param tumor_type=breast \
--param soi=SBS3 --param seq_type=msk
--input ROLE=PATH binds a file to one of the tool's input roles, by a path relative to the workspace (or absolute inside it); --param KEY=VALUE sets a parameter (numbers and true/false are read as such); --label names the run as the studio would. The log streams to the terminal; the exit code is 0 when the run succeeded.
The roles and parameters are the ones GET /api/tools lists and the studio's inputs box shows:
| Tool | Roles | Parameters |
|---|---|---|
sigma2 | mutations, exposures, object, curation, matrix, segments, model_dir | stage (build, simulate, tune, score), tumor_type, seq_type, soi, catalog, model, … |
mutopia | vcf, ref_fasta | tumor_type, sample, pass_only |
tau | snv_table, cn_table, ref_fasta, exposures | sample, purity, sex, signatures, tumor_type |
musical | matrix, denovo, signatures | stage (discover, match, refit), min_k, max_k, replicates, method, thresh, ncpu |
liftover | vcf | from, to |
spa | matrix | cosmic, exome |
A cohort: one run per file
sigscape-daemon run mutopia --workspace ~/sigscape \
--each vcf=data/pcawg/breast --match .vcf.gz --input ref_fasta=data/hg38.fa \
--param tumor_type=Breast-AdenoCa \
--jobs 4 --skip-done
--each ROLE=FOLDER runs the tool once per file of the folder with that file bound to the role (--match SUFFIX keeps only files ending in it); --jobs N is how many run at once. At the end a table names every file's run, state and seconds, and the exit code is 0 only when all succeeded.
Ctrl-C or SIGTERM cancels every run the command started, queued ones included, each with its process group (a container client does not outlive the command), and the records of the interrupted runs read as canceled or failed afterwards. --skip-done is how a cohort resumes: a file that already has a succeeded run with the same inputs and parameters in the workspace is left out and its earlier run named, so a stopped loop continues where it was and only the samples that failed are run again. The daemon's workspace is the checkpoint; nothing has to be tracked beside it.
A run again
sigscape-daemon recipe run ~/sigscape/sigscape-runs/mutopia-1793320505-2/recipe.json
A run's recipe.json names the tool, every parameter and every input by path with its sha256. recipe run starts the same run again in the same workspace; the new run's recipe can be compared with the old one, and the reporting block under the tool cites the recipe it was written from.
On a cluster, or in a container
The daemon is one static binary with no service to install, so a job script calls it directly: one run \ --each per node over a folder of that node's samples, or one run per array task with the task's file. The tools' environments are built on first use under the cache directory (SIGSCAPE_CACHE to put it on shared storage); MuTopia runs from its published container image through Docker or Podman, and under Apptainer the daemon's own container image (the docker run command on the install page) is the route for a node without a container daemon: apptainer exec the image with the workspace bound and call sigscape-daemon run inside it. Everything runs where the data is; nothing leaves the machine but the release downloads and registry fetches the daemon makes on its own, the same as with a browser attached.
What the studio shows afterwards
The runs are the daemon's job list: open the workspace in the studio (the runner connected, the records from data/) and each run sits under its tool's step with the label it was given (the file's name under --each), its parameters, its log, its export and its reporting block. A headless run is filed under the records of the same names as a studio run would be (the file's name without its extension, joined with the other inputs' names the way the tool joins them), so selecting those records and opening the tool lists it. A headless run and a studio run are the same kind of thing; meta.headless on the record is the only difference.