Tasks

Six tasks, one command each, plus an advisory check of the input. They share an input contract, a command shape and an output layout, so learning one teaches you most of the others.

Note

Run scfoundry commands from inside a workspace created by scfoundry init (any subdirectory works — the workspace is found by walking upwards, like a git repository), or pass --workspace DIR. Weights, the image cache, results and run logs all live there. See The workspace.

The command shape

scfoundry <task> --method <method> --<input flag> <path> [options]

--method selects both the model and the container image it runs in. The input flag differs by task — --data, --reference/--query, or --embedding — but nothing else about the invocation changes between methods.

Task	Required arguments	Runs on	Methods
download	--method	CPU	16
check	--data	CPU	n/a
embed	--method, --data	GPU (CPU for pca, genept, Harmony, Seurat)	22
transfer	--method, --reference and/or --query	GPU	15
finetune	--method, --reference and/or --query	GPU	9
benchmark	--embedding	CPU	n/a
geometry	--embedding, --data	CPU	n/a

Method coverage differs because not every model exposes every capability. scfoundry list methods prints the matrix; scfoundry list methods --task finetune narrows it to one task. The same table, with containers and checkpoints, is in the method reference.

The two-stage tasks

transfer and finetune both have a fit stage and a predict stage, and the arguments you pass decide which run:

--reference ref.h5ad --query q.h5ad     fit on the reference, then predict the query
--reference ref.h5ad                    fit only; the model is saved for later
--query q.h5ad --fitted <model dir>     predict only, with a model fitted earlier

Splitting the stages is what you want when the fit is expensive and you will apply it to several query sets — fine-tune once, predict many times.

What every task needs from your data

Warning

Input must be raw counts over the full transcriptome. Passing log-normalised values, or an object already subset to highly variable genes, does not raise an error — it produces a plausible-looking embedding that is silently wrong. See Input data format.

Beyond raw counts, each task reads specific columns:

Task	obs columns
embed	barcode; batch_id (or --batch-key) for the integration methods; obsm["spatial"] for novae
transfer, finetune	barcode; cell_type (or --label-key) on the reference
benchmark	cell_type (or --label-key); batch_id (or --batch-key) for batch metrics
geometry	cell_type (or --label-key); batch_id (or --batch-key), one batch if absent

Where output goes

results/
├── embeddings/<method>/<dataset>.h5ad
├── transfer/
│   ├── models/<method>/<classifier>/<reference>/
│   └── predictions/<method>/<classifier>/<query>_predicted_{labels,probs}.tsv
├── finetune/
│   ├── finetuned_models/<method>/<reference>/
│   └── prediction/<method>/<query>_predicted_{labels,probs}.tsv
├── benchmark/
│   ├── <method>_bio_conservation_leiden_metrics_{long,wide}.csv
│   └── <method>_batch_mixing_leiden_metrics_{long,wide}.csv
├── geometry/<method>/<dataset>_<method>.csv
└── <method>_geometry.csv

Filenames come from the input basename: colon_1000.h5ad in gives colon_1000.h5ad, colon_1000_scgpt.csv, colon_50_predicted_labels.tsv, and so on. Directory names are the method ids you typed. Two inputs with the same basename would collide; give them distinct names or a distinct --outdir.

Options that apply everywhere

Option	Effect
--outdir DIR	Results root for this run (default <workspace>/results).
--gpu N	GPU index (or comma-separated list) exposed to the container.
--weights-dir DIR, --cache-dir DIR	Use a shared weight store or image cache instead of the workspace’s own.
--run-name NAME, --resume [RUN]	Name the run directory; resume the newest matching run (or a named one).
--profile NAME, --config FILE	Activate a Nextflow profile from nextflow.config (for example slurm); layer an extra configuration file.
--dry-run	Print the parameters and the Nextflow command without running anything.
--<param> value	Any other --option is forwarded to Nextflow as a pipeline parameter, for example --batch_size 32 or --scfoundation_pool_type max.

Note

Every launch gets its own run directory under runs/<task>/, and the workspace nextflow.config sets cleanup = true, so the task work directory is deleted once the run succeeds. After a failure it is kept: fix the cause, add --resume to the same command, and Nextflow reuses every task that already completed. scfoundry runs lists the run directories with their status; scfoundry runs --task <task> narrows the list.

See also

• Command reference — every option of every command.

• Parameter reference — the pipeline parameters behind them.