CLI reference

Review every Cells2Stats subcommand, global option, and subcommand option.

Cells2Stats organizes its command-line interface into subcommands. Each subcommand performs one stage of multiomic analysis, accepts its own positional argument, and exposes only the options that apply to it. For installation and system requirements, see Set up Cells2Stats. For the command templates used with each storage type, see Executing Cells2Stats.

Every command uses the following shape:

cells2stats <subcommand> [OPTIONS] [POSITIONAL]

Note:

Cells2Stats 2.0.0+ requires a subcommand. Commands written for Cells2Stats 1.x that pass a run directory directly to cells2stats no longer run. See Migrating from Cells2Stats 1.x.

Subcommands

Subcommand	Positional argument	Purpose
analyze	RUN_DIRECTORY	Process multiomic run data into a spatial data object, detailed cell statistics, and an HTML QC report
visualize	SDO_ARCHIVE	Build CytoCanvas™ visualization files from an existing Spatial Data Object archive
process_imaging_targets	RUN_DIRECTORY	Reprocess raw projection tiles into corrected canonical projection TIFF files
process_segmentation	RUN_DIRECTORY	Generate new cell and nuclear segmentation masks from projection images with Cellpose
generate_qc_report	SDO_ARCHIVE	Generate the QC HTML report from an existing Spatial Data Object archive

Get help

Cells2Stats provides help at two levels. Use the top level to discover subcommands, then use a subcommand to see only the options that apply to it.

To list the subcommands and the options shared across them, run the following command:

cells2stats --help

Cells2Stats names each subcommand, then groups the shared options into categories:

Usage:
        cells2stats <subcommand> [OPTIONS] [POSITIONAL]

subcommands:
        analyze                         Process run data to generate a spatial data object, detailed cell statistics, and html qc reports
        visualize                       Build visualization from an existing SpatialData archive zip
        process_imaging_targets         Reprocess _Raw projection tiles (illumination correction + affine warp) into corrected canonical projection TIFFs
        process_segmentation            Run Cellpose segmentation from projection images
        generate_qc_report              Generate QC HTML report from an existing SpatialData archive zip

common options (availability varies by subcommand):

General:
        --help, -h                      Print usage statement and exit
        --version, -v                   Display cells2stats version and exit
        ...

Output:
        ...

Remote I/O:
        ...

The preceding output is abbreviated. For the complete set of options and their defaults, see Global options and the subcommand sections in this reference.

To list the positional argument and every option for one subcommand, place --help after the subcommand name:

cells2stats analyze --help

Each subcommand groups its options under category headings, such as Input, Filters, and Imaging targets, that match the sections in this reference. To display the version and exit, run the following command:

cells2stats --version

Global options

The following options are available to more than one subcommand. Availability varies by subcommand, as noted in each table.

General

Every subcommand accepts these options.

Flag	Type	Required	Default	Description
-h, --help	boolean	No	false	Print the usage statement and exit
-v, --version	boolean	No	false	Display the Cells2Stats version and exit
-l, --log-level	string	No	info	Minimum log level. Valid values are debug, info, warning, and error
-j, --num-threads	integer	No	1	Number of threads to use
-P, --python	path	No	/usr/bin/python3	Path to the python executable used for python-backed steps. Overridden by C2S_PYTHON

Output

The analyze, visualize, and generate_qc_report subcommands accept --output. The process_imaging_targets subcommand writes to --projection-out-dir instead, and the process_segmentation subcommand writes to --segmentation instead.

Flag	Type	Required	Default	Description
-o, --output	path	Conditional	Varies by subcommand, as described following	Directory to write output into

The default depends on the subcommand:

• For analyze, the default is RUN_DIRECTORY/Cytoprofiling/<timestamp>, where <timestamp> is the UTC start time of the execution.
• For visualize and generate_qc_report, the default is the directory that contains the Spatial Data Object archive.

--output is required when the Spatial Data Object archive is in remote storage, because there is no local directory to default to.

Remote input and output

Every subcommand accepts these options. For credential setup, see Executing Cells2Stats.

Flag	Type	Required	Default	Description
-i, --input-remote	string	No	—	Rclone remote name for remote input paths
-r, --output-remote	string	No	—	Rclone remote name for remote output paths
-T, --verbose-transfer	boolean	No	false	Print the name of every file downloaded or uploaded during a remote transfer

analyze

The analyze subcommand processes run data to generate a Spatial Data Object, detailed cell statistics, and the QC HTML report. This is the subcommand that replaces the top-level Cells2Stats 1.x command. For a description of what it produces, see Output files.

cells2stats analyze [OPTIONS] RUN_DIRECTORY

Positional	Description
RUN_DIRECTORY	Location of the run directory

analyze accepts every global option, plus the options in the following sections.

Input

Flag	Type	Required	Default	Description
-p, --panel	path	No	Panel in the run directory	Local or remote path to a panel JSON file
-R, --run-manifest	path	No	Manifest in the run directory	Local or remote path to a run manifest. The file extension must be .csv or .json
-M, --tca-manifest	path	No	—	Local or remote path to a target cell assignment manifest. The file extension must be .csv or .json
-S, --segmentation	path	No	See description	Without --process-segmentation, an alternate directory of existing masks to read, default RUN_DIRECTORY/CellSegmentation. With --process-segmentation, the directory to write new masks into, default OUTPUT_DIRECTORY/CellSegmentation. A remote path is staged into a temporary directory, and the run directory is never modified
--spatialdata-metadata-file	path (repeatable)	No	—	Additional file to archive in the metadata/ directory of the Spatial Data Object. Repeat the flag once per file

Filters

Use these options to restrict an execution to part of a run, for example when reanalyzing a single well.

Flag	Type	Required	Default	Description
-b, --batch	string	No	All batches	Restrict analysis to the batches in a comma-delimited list, for example B01,B02,B03
-w, --well	string	No	All wells	Restrict analysis to the well locations in a comma-delimited list, for example A1,A2,B2
-t, --tile	regex	No	All tiles	Restrict analysis to the tiles that match a regular expression
--filter-mask	string	No	BaseCalling/Filter/	Custom pass-filter mask with batch-scoped segments, for example B01:N4Y*-B02:YN*

For --filter-mask, a batch named in the mask has its pass-filter status computed from quality scores, where at most one cycle falls below a quality threshold of 6. Batches that the mask does not name continue to use the filter files in BaseCalling/Filter/.

File handling

Flag	Type	Required	Default	Description
-m, --error-on-missing	boolean	No	false	Terminate the execution when a file is missing. When off, Cells2Stats skips missing files and continues
-n, --no-error-on-invalid	boolean	No	false	Skip invalid files and continue the execution. When off, Cells2Stats terminates the execution for an invalid file

CellProfiler

Flag	Type	Required	Default	Description
-c, --cellprofiler	path	No	—	Path to the CellProfiler utility
-s, --skip-cellprofiler	boolean	No	false	Skip the execution of CellProfiler

If you do not want to specify a CellProfiler utility and do not have CellProfiler installed, run with --skip-cellprofiler. For dependency details, see Set up Cells2Stats.

Reporting

Flag	Type	Required	Default	Description
-u, --max-unassigned	integer	No	30	Limit on the number of unassigned sequences to report. Valid values are integers from 1 to 10,000
--skip-qc-report	boolean	No	false	Skip generation of the qc_report.html QC report

Imaging targets

These options control where projection images come from and whether Cells2Stats reprocesses them before analysis. To reprocess projections as a standalone step instead, use process_imaging_targets.

Flag	Type	Required	Default	Description
--process-imaging-targets	boolean	No	false	Reprocess _Raw projection tiles into corrected canonical projection TIFF files before analysis
--projection-dir	path	No	RUN_DIRECTORY/Projection	Alternate directory of projection images to analyze
--disable-per-batch-background	boolean	No	false	Do not quantify or export the per-batch background intensity features Bkg_RED and Bkg_GRN
--enable-illumination-correction	boolean	No	false	Force illumination correction on for every imaging target and enabled background
--disable-illumination-correction	boolean	No	false	Force illumination correction off for every target

--process-imaging-targets applies illumination correction and a per-tile affine warp, writes the corrected tiles to OUTPUT_DIRECTORY/Projection, and uses them for the rest of the execution. The Projection/ directory in the run directory is read but never modified. The resolved projection destination must not already exist.

--projection-dir accepts a local path, a symbolic link, an s3:// or gs:// URL, or a path used with --input-remote. It takes the place of RUN_DIRECTORY/Projection for every downstream consumer. Cells2Stats uses the per-target JSON transform file, such as CP01_Actin.json, to reconcile which targets the alternate directory serves. Any imaging target missing that file is populated by copying the projections for that target from RUN_DIRECTORY/Projection. When you combine --projection-dir with --process-imaging-targets, the directory is the resolved projection destination and must not already exist.

Per-batch background is processed by default. Per-target background, written as Bkg_{target}, is enabled separately when RecipeValues.SavePerTargetBkgImages is true in RunParameters.json.

The illumination correction options override the IlluminationCorrection settings in the panel and recipe. They apply to all targets, including backgrounds. The two options are mutually exclusive, and both require --process-imaging-targets.

Segmentation

Use --process-segmentation to generate new cell and nuclear segmentation masks with Cellpose and analyze the run with them in a single execution. To generate masks as a standalone step instead, use process_segmentation.

Flag	Type	Required	Default	Description
--process-segmentation	boolean	No	false	Run Cellpose segmentation before analysis

With --process-segmentation, Cells2Stats writes the new masks to the --segmentation directory, or to OUTPUT_DIRECTORY/CellSegmentation when you omit --segmentation, and uses them for the rest of the execution. The destination must not be, or be nested inside, the run's own CellSegmentation/ directory.

analyze also accepts every segmentation option of process_segmentation. These options require --process-segmentation, and Cells2Stats terminates the execution when you set one without it.

Guide RNA

These options apply to Guide RNA analysis. In --help output, they appear under the OPS category. The binaries listed here are external dependencies. For installation guidance, see Set up Cells2Stats.

Flag	Type	Required	Default	Description
-B, --bases2fastq	path	No	bases2fastq	Path to the Bases2Fastq™ binary used for FASTQ generation during Guide RNA analysis
--bowtie	path	No	bowtie	Path to the Bowtie v1 binary used in Guide RNA analysis
--bowtie-build	path	No	bowtie-build	Path to the Bowtie-build binary used in Guide RNA analysis
--samtools	path	No	samtools	Path to the Samtools binary used in Guide RNA analysis
--generate-specialized-targeted-bams	boolean	No	false	Output concatenated BAM files from Guide RNA alignment, one per well per target site
--specialized-targeted-min-query-length	integer	No	Derived, as described following	Minimum query-length gate, in bases, for Guide RNA alignments
--target-mismatch-threshold	integer	No	Derived, as described following	Override the Guide RNA adjusted-NM acceptance cap for all target sites

--specialized-targeted-min-query-length applies to all target sites. Valid values are integers from 12 to the mask sequence length of the target site. When the value exceeds the mask sequence length for a given target, Cells2Stats logs a warning per tile and clamps the value to that mask sequence length. The default for each site is 60% of the guide, or spacer, sequence length, floored at 12. For a guide shorter than 12 bases, the default is the guide length itself.

For --target-mismatch-threshold, the G-tail-adjusted NM value must be less than or equal to the value you supply. Valid values are integers from 0 to 4. When the target cell assignment manifest leaves TargetMismatchThreshold unset, the default is derived as the lesser of one fifth of the guide length and 4.

Note:

When a target is marked as a control with IsControl, Cells2Stats assigns polonies for that target but does not perform guide assignment for it. IsControl overrides normal Guide RNA assignment, so control targets do not appear as cell-assigned guides in SpecializedTargetedCounts.json.

Visualization tuning

Visualization builds the files in the SpatialData/ output directory, including cyto.viz and the cell and nuclear boundary parquet files. The compute resources it requires scale with the size of the run and with the environment that runs it, so use this option to match visualization concurrency to the available CPU and memory.

Flag	Type	Required	Default	Description
--visualization-workers	integer	No	--num-threads	Process worker count for the visualization scan and encode stages

Valid values are integers from 1 upward.

visualize

The visualize subcommand builds CytoCanvas visualization files from an existing Spatial Data Object archive. Use it to regenerate visualization files for an archive where visualization generation previously failed, without repeating the full analysis.

cells2stats visualize [OPTIONS] SDO_ARCHIVE

Positional	Description
SDO_ARCHIVE	Path to the Spatial Data Object archive zip file. Local or remote

visualize accepts every global option, plus the following options.

Visualization tuning

Visualization builds the files in the SpatialData/ output directory, including cyto.viz and the cell and nuclear boundary parquet files. The compute resources it requires scale with the size of the run and with the environment that runs it, so use the worker counts to match visualization concurrency to the available CPU and memory. Use --disable-per-batch-background to control which channels cyto.viz contains.

Flag	Type	Required	Default	Description
--visualization-workers	integer	No	--num-threads	Process worker count for the visualization scan and encode stages
--viz-shape-smoothing-workers	integer	No	--num-threads divided by 3, minimum of 1	Shape smoothing worker count for the visualization build
--disable-per-batch-background	boolean	No	false	Do not include the per-batch background channels Bkg_RED and Bkg_GRN in cyto.viz

Valid values for the worker counts are integers from 1 upward. By default, Cells2Stats includes per-batch backgrounds when they are present in the Spatial Data Object archive.

process_imaging_targets

The process_imaging_targets subcommand reprocesses retained _Raw projection tiles into corrected canonical projection TIFF files, applying optional illumination correction and a per-tile affine warp. Use it when you want corrected projections without running a full analysis, for example to inspect the result before committing to reanalysis.

cells2stats process_imaging_targets [OPTIONS] RUN_DIRECTORY

Positional	Description
RUN_DIRECTORY	Location of the run directory

Cells2Stats reads the original Projection/ images in the run directory but never modifies them. It writes corrected tiles to a separate directory along with a {batch}_{target}.json file that marks each completed target, and writes invocation and worker logs to the Logs/ subdirectory of that destination.

process_imaging_targets accepts the general and remote global options, plus the following options. It does not accept --output.

Imaging targets

Flag	Type	Required	Default	Description
--target	string (repeatable)	No	All targets	Restrict processing to the named imaging target
--projection-out-dir	path	Yes	—	Destination root for corrected canonical projection TIFF files and Logs/
--disable-per-batch-background	boolean	No	false	Do not reprocess the per-batch background projections Bkg_RED and Bkg_GRN
--enable-illumination-correction	boolean	No	false	Force illumination correction on for every selected target and enabled background
--disable-illumination-correction	boolean	No	false	Force illumination correction off for every selected target

Cells2Stats matches --target by target name across all batches, including the per-batch backgrounds Bkg_RED and Bkg_GRN and the per-target Bkg_{target} . When you omit --target, Cells2Stats processes all imaging targets and enabled background targets.

Warning:

--projection-out-dir must not be nested inside, the Projection/ directory of the run. Cells2Stats resolves symbolic links before it checks, and terminates the execution when the destination would land inside the original projections. This prevents data loss by preventing overwriting the original run outputs.

The illumination correction options ignore the panel Analyses and recipe values.

Exit behavior

process_imaging_targets never copies _Raw files to the output directory. The following conditions produce a non-zero exit code:

Condition	Result
Missing _Raw tiles for a target	Cells2Stats writes a corrected output for the tiles that are present, writes the JSON transform file, and exits non-zero
Missing transform JSON for a target	Cells2Stats writes a placeholder JSON file containing "Synthesized": true, writes no corrected output for that target, and exits non-zero
Projection destination not empty	Cells2Stats terminates before processing

process_segmentation

The process_segmentation subcommand generates new cell and nuclear segmentation masks from the projection images of a run with Cellpose. Use it to evaluate a different segmentation model, target, or cell diameter before you analyze the run with the new masks.

cells2stats process_segmentation [OPTIONS] RUN_DIRECTORY

Positional	Description
RUN_DIRECTORY	Location of the run directory

Cells2Stats reads the run's projection images but never modifies the run's CellSegmentation/ directory. It writes masks to {segmentation}/{well}/{tile}_Cell.zarr and {segmentation}/{well}/{tile}_Nuclear.zarr, where {well} is the well folder name, such as WellA1, and writes logs to the Logs/ subdirectory of that destination. To analyze the run with the new masks, pass the destination to analyze --segmentation.

process_segmentation requires Cellpose, its Python dependencies, and the Cellpose models. The Docker image includes all of them. For installation outside Docker, see Segmentation dependencies. Runs with overlapping tiles are not supported.

process_segmentation accepts the general and remote global options, plus the following options. It does not accept --output.

Input and output

Flag	Type	Required	Default	Description
-S, --segmentation	path	Yes	—	Directory to write the new masks into. May be shared across invocations that cover disjoint tiles. Must not be, or be nested inside, the run's CellSegmentation/ directory
--projection-dir	path	No	RUN_DIRECTORY/Projection	Alternate directory of projection images to segment
-p, --panel	path	No	Panel in the run directory	Local or remote path to a panel JSON file
-R, --run-manifest	path	No	Manifest in the run directory	Local or remote path to a run manifest. The file extension must be .csv or .json
-w, --well	string	No	All wells	Restrict segmentation to the well locations in a comma-delimited list, for example A1,A2,B2
-t, --tile	regex	No	All tiles	Restrict segmentation to the tiles that match a regular expression
-m, --error-on-missing	boolean	No	false	Exit with an error when a tile is missing a projection image. When off, Cells2Stats skips the tile and continues

Segmentation options

These options are also available to analyze when you set --process-segmentation.

Flag	Type	Required	Default	Description
--cell-segmentation-model	string	No	Resolved from the run manifest, as described following	Cell type, model file name in the models directory, local model file path, or fully qualified s3:// or gs:// URL of a model file
--nuclear-segmentation-model	string	No	20250212_cellpose_nuc_8diam	Nuclear model file name in the models directory, local model file path, or fully qualified s3:// or gs:// URL of a model file
--cellpose-models-directory	path	No	/cellpose_models	Local directory that contains the Cellpose models
--cell-boundary-target	string	No	AnalysisSettings.CellBoundaryTarget in the panel	Imaging target to segment cell boundaries from
--nuclear-target	string	No	AnalysisSettings.NuclearTarget in the panel	Imaging target to segment nuclei from
--supplementary-cell-boundary-target	string	No	AnalysisSettings.SupplementaryCellBoundaryTarget in the panel	Optional additional imaging target for cell boundary segmentation. NA or none disables it
--use-corrected-projections-for-segmentation	boolean	No	false	Segment corrected projections instead of raw projections
--use-cellpose-normalization	boolean	No	false	Skip regional tile normalization and let Cellpose normalize the images internally
--cell-diameter	float	No	From the run manifest, otherwise 75	Expected cell diameter, in pixels, for all wells. Must be greater than 0

When you omit --cell-segmentation-model, Cells2Stats selects a model for each well from the cell type in the run manifest. A well with no cell type, a cell type of Other, or more than one cell type uses the general model. When you set --cell-segmentation-model, the model applies to every well. The following cell types are valid, case-insensitive:

DEFAULT, FIBROBLAST, HCT116, HEK293, HELA, HEPG2, HUVEC, IPSCWT, JURKAT, MCF7, PBMC, PC3, SHSY5Y

A cell type resolves to a model file in the models directory. Cells2Stats uses the two-channel version of the model, or the three-channel version when a supplementary cell boundary target is set.

The cell boundary, nuclear, and supplementary cell boundary targets must be imaging targets in the panel. Cells2Stats requires both a cell boundary target and a nuclear target.

--cellpose-models-directory must be a local path, even when a model option names a remote file. Cells2Stats always resolves named models from this directory and does not download models from the internet. The directory must exist and must not be empty. The Docker image includes the models at the default location. For a model download procedure, see Cellpose models.

By default, Cells2Stats segments the raw projection images, aligned with the per-target transform file. Use --use-corrected-projections-for-segmentation to segment the corrected projection images instead.

generate_qc_report

The generate_qc_report subcommand generates the QC HTML report from an existing Spatial Data Object archive. Use it to produce the report for an archive created with --skip-qc-report, or to regenerate a report without repeating the analysis.

cells2stats generate_qc_report [OPTIONS] SDO_ARCHIVE

Positional	Description
SDO_ARCHIVE	Path to the Spatial Data Object archive zip file, with extension .zarr.zip. Local or remote

generate_qc_report accepts every global option and no additional options. Cells2Stats writes qc_report.html to the --output directory, or beside the archive when you omit --output.

Migrating from Cells2Stats 1.x

Cells2Stats 2.0.0 changes the command-line interface in ways that require updates to existing scripts and pipelines.

Commands require a subcommand

Add analyze to any command that passed a run directory directly to cells2stats:

# Cells2Stats 1.x
./cells2stats /input -j 8 -s

# Cells2Stats 2.0.0
./cells2stats analyze /input -j 8 -s

Replaced and removed options

Cells2Stats 1.x option	Cells2Stats 2.0.0 equivalent
--build-viz-from-SDO	The visualize subcommand
--skip-html-report, -H	--skip-qc-report, which skips the HTML QC report
--viz-points-sort-memory-gb	Removed. No replacement
--viz-points-sort-threads	Removed. Use --visualization-workers
--viz-shape-smoothing-workers on the top-level command	The same option on the visualize subcommand

The MultiQC report is no longer generated. The HTML QC report, qc_report.html, replaces it. See Output files.