sopa
nf-core/sopa
Technology-invariant pipeline for spatial omics analysis that scales to millions of cells
Key tools
Run it
nfclaw run sopa --input samplesheet.csv --outdir results -profile dockernextflow run pipelines/sopa/upstream -profile docker --input samplesheet.csv --outdir resultsnfclaw run sopa --demo --outdir results # adds the upstream test profile (-profile test,docker)Inputs
| column | type | required | allowed values | constraints |
|---|---|---|---|---|
sample | string | no | matches ^\S+$ | |
id | string | no | matches ^\S+$ | |
data_path | string (file or directory path) | no | matches ^\S+$ | |
fastq_dir | string (file or directory path) | no | matches ^\S+$ | |
cytaimage | string (file or directory path) | no | matches ^\S+(tif|tiff)$ | |
colorizedimage | string (file or directory path) | no | matches ^\S+(tif|tiff|jpg|jpeg|btf)$ | |
darkimage | string (file or directory path) | no | matches ^\S+(tif|tiff|jpg|jpeg|btf)$ | |
image | string (file or directory path) | no | matches ^\S+(tif|tiff|jpg|jpeg|btf)$ | |
slide | string | no | matches ^\S+$ | |
area | string | no | matches ^\S+$ | |
manual_alignment | string (file or directory path) | no | matches ^\S+json$ | |
slidefile | string (file or directory path) | no | matches ^\S+json$ |
--input must match ^\S+\.csv$.
The samplesheet is a CSV with this header; fill each value per the table above and reference.md (no example value is invented here):
sample,id,data_path,fastq_dir,cytaimage,colorizedimage,darkimage,image,slide,area,manual_alignment,slidefileFrom data files. nfclaw cannot generate this samplesheet: the samplesheet declares no file type nfclaw could match files against (no column's pattern names a file extension).
Resources
Resource requests follow the pipeline's configs and selected profiles. nf-core's resource labels often assume a server — a single step can request far more memory than a workstation has, and retry rules can increase requests. If a run fails with Process requirement exceeds available memory (or CPUs), cap every request, and every retry, at what this machine actually has:
nfclaw run sopa --input samplesheet.csv --outdir results -profile docker \ --limit-cpus 4 --limit-memory 15.GBnfclaw turns those into Nextflow's process.resourceLimits and passes them as a -c config — the mechanism nf-core prescribes for exactly this (docs). Set them to the machine's real capacity. --limit-time DURATION also caps how long any one task may run: a task that needs longer is stopped, and so is every retry, so set it only as a deliberate ceiling, never as a guess at how long the analysis takes. The generated config is kept in <outdir>/provenance/, so commands.sh replays the run under the same ceiling.
Nextflow engine
This release declares nextflowVersion = '!>=25.10.4'.
To pin this release's declared minimum engine — useful when a newer Nextflow has incompatible config parsing:
nfclaw run sopa ... --nxf-ver 25.10.4--nxf-ver is recorded in <outdir>/provenance/, so the replay uses the same engine. See known-issues.
Demo
nfclaw run sopa --demo --outdir results # adds the upstream test profile (-profile test,docker)Samplesheet
A CSV with this header (the columns the schema requires). Fill each value per the constraints below.
sample,id,data_path,fastq_dir,cytaimage,colorizedimage,darkimage,image,slide,area,manual_alignment,slidefile| Column | Type | Required | Allowed / constraints |
|---|---|---|---|
sample | string | optional | matches ^\S+$ |
id | string | optional | matches ^\S+$ |
data_path | string (file or directory path) | optional | matches ^\S+$ |
fastq_dir | string (file or directory path) | optional | matches ^\S+$ |
cytaimage | string (file or directory path) | optional | matches ^\S+(tif|tiff)$ |
colorizedimage | string (file or directory path) | optional | matches ^\S+(tif|tiff|jpg|jpeg|btf)$ |
darkimage | string (file or directory path) | optional | matches ^\S+(tif|tiff|jpg|jpeg|btf)$ |
image | string (file or directory path) | optional | matches ^\S+(tif|tiff|jpg|jpeg|btf)$ |
slide | string | optional | matches ^\S+$ |
area | string | optional | matches ^\S+$ |
manual_alignment | string (file or directory path) | optional | matches ^\S+json$ |
slidefile | string (file or directory path) | optional | matches ^\S+json$ |
Required parameters
--inputstring (file path)Path to comma-separated file containing information about the samples in the experiment.
Constraint · matches ^\S+\.csv$
--outdirstring (directory path)The output directory where the results will be saved. You have to use absolute paths to storage on Cloud infrastructure.
--technologystringTechnology used for the spatial data, e.g., 'xenium', 'merscope', ...
xeniummerscopecosmxvisium_hdmolecular_cartographymacsimaphenocyclerhyperionome_tiftoy_datasetParameter explorer
91 parameters · 18 groupsEvery parameter from the pinned nextflow_schema.json. nfclaw checks explicit values before launch; complex rules use the pinned pipeline's runtime validation. Search, filter by group, and expand any parameter for its default, allowed values and constraints.
77 parameters · 14 hidden
Aggregation3
Whether to aggregate the channels (intensity) inside each cell
Whether to aggregate the genes (counts) inside each cell
Cells polygons will be expanded by expand_radius_ratio * mean_radius for channels averaging only. This help better aggregate boundary stainings
Baysor9
Baysor scale parameter
Baysor scale_std parameter
Baysor confidence_nn_id parameter
Baysor force_2d parameter
Baysor min_molecules_per_cell parameter
Baysor min_molecules_per_gene parameter
Baysor min_molecules_per_segment parameter
Baysor prior_segmentation_confidence parameter
Whether to run baysor segmentation
Cellpose9
Channel name(s) to use for cellpose segmentation. If multiple, separate by space, comma or pipe characters.
Cellpose diameter parameter
Additional cellpose parameters as a python dict string
Cellpose model type to use
Cellpose major version (3 or 4). Defaults to Cellpose v3. The 'gpu' profile selects the pytorch/CUDA image of the chosen version.
Cellpose cellprob_threshold parameter
Cellpose flow_threshold parameter
Cellpose pretrained_model parameter
Whether to run cellpose segmentation
Comseg7
Comseg allow_disconnected_polygon parameter
Comseg alpha parameter
Comseg max_cell_radius parameter
Comseg mean_cell_diameter parameter
Comseg min_rna_per_cell parameter
Comseg norm_vector parameter
Whether to run comseg segmentation
Explorer3
If True, will not load the full images in memory (except if the image memory is below ram_threshold_gb)
Number of microns in a pixel. Invalid value can lead to inconsistent scales in the Explorer.
Threshold (in gygabytes) from which image can be loaded in memory.
Filtering4
Cells with an area less than this value will be filtered. The unit is in microns^2, and used by Baysor/Comseg. Not used by Proseg.
Cells with an area less than this value will be filtered. The unit is in pixels^2, and used by Stardist/Cellpose.
Cells whose mean channel intensity is less than min_intensity_ratio * quantile_90 will be filtered.
Cells with less transcripts than this value will be filtered.
Fluorescence Annotation3
Key of sdata.obs containing the cell-types
Dictionary mapping whose keys are marker channel names and values are the cell types associated to each marker. Should be provided as a string representation of a python dictionary.
Whether to run cell-type annotation based on a marker-to-cell dictionary
Generic options3
Display the help message.
Display the full detailed help message.
Display hidden parameters in the help message (only works when --help or --help_full are provided).
Image Preprocessing3
Parameter for skimage.exposure.equalize_adapthist (applied before running the segmentation method)
Parameter for skimage.exposure.equalize_adapthist (applied before running the segmentation method)
Parameter for scipy gaussian_filter (applied before running the segmentation method)
Input Output options3
Email address for completion summary.
Path to comma-separated file containing information about the samples in the experiment.
The output directory where the results will be saved. You have to use absolute paths to storage on Cloud infrastructure.
Patches7
The scale to be used for the image patches (e.g., "scale1"). By default, uses the highest resolution scale.
Number of overlapping microns between the patches. We advise to choose approximately twice the diameter of a cell
Number of overlapping pixels between the patches. We advise to choose approximately twice the diameter of a cell
Width (and height) of each patch in microns
Width (and height) of each patch in pixels
Optional name of the boundaries element to use as a segmentation prior. Either a column name for the transcript dataframe, or a key of sdata containing the shapes names. If combining cellpose with proseg/baysor/comseg, it will be set automatically to 'cellpose_boundaries'.
If prior_shapes_key is provided, this is the value given to transcripts that are not inside any cell (if it's already 0, don't provide this argument)
Proseg4
String suffix to add to the proseg command line. This can be used to add extra parameters to the proseg command line.
Whether to infer the proseg presets based on the columns of the transcripts dataframe.
Whether to run proseg segmentation
Only for Visium HD data. Key of sdata containing the prior cell boundaries. If 'auto', use the latest performed segmentation (e.g., stardist or the 10X Genomics segmentation). If combining stardist with proseg, it will be set automatically to 'stardist_boundaries'.
Reader3
Additional keyword arguments for the sopa reader, written as an inline python dictionary.
Technology used for the spatial data, e.g., 'xenium', 'merscope', ...
Optional page for the imageio reader
Scanpy Preprocessing4
Whether to check that adata.X contains counts
Whether to compute highly variable genes before computing the UMAP and clustering
Resolution parameter for the leiden clustering
Whether to run scanpy preprocessing
Spaceranger options2
Location of Space Ranger probeset file.
Location of Space Ranger reference directory. May be packed as tar.gz file.
Stardist6
Stardist nms_thresh parameter
Stardist prob_thresh parameter
Optional channel name(s) to use for stardist segmentation. If multiple, separate by space, comma or pipe characters.
Additional stardist parameters as a python dict string
Name of stardist model to use
Whether to run stardist segmentation
Tissue Segmentation4
Level of the image pyramid to use for tissue segmentation
Mode for the tissue segmentation: 'staining' or 'saturation' (for H&E images).
Additional tissue segmentation parameters as a python dict string
Whether to run tissue segmentation
Outputs
Results land in --outdir; the files and directory layout depend on the selected workflow, parameters and publication settings. Run metadata is normally placed in <outdir>/pipeline_info/ (execution report, software versions), when those outputs are enabled. nfclaw run also writes <outdir>/provenance/ with the exact params file and the run log, <outdir>/provenance/logs/run.log — the whole launch, whose last line states the outcome (Nextflow's own log is <outdir>/.nextflow.log); unless --no-provenance it adds a run manifest (pinned version, commit and exact command), input/output SHA-256 checksums, and a replayable commands.sh.
The exact output files and directory layout for this release are documented upstream: github.com/nf-core/sopa/blob/1.0.2/docs/output.md
Check a run — in the foreground or the background — with nfclaw status <outdir>: success, still running, how it ended (with the error), or stopped without an outcome; exit 0 success, 3 running, 1 otherwise.