Skip to main content

Cells2Stats release notes

v2.0.0​

October 5, 2026

Cells2Stats 2.0.0 is a major release. The command-line interface is reorganized into subcommands, the MultiQC report is replaced by the QC report, and Cellpose segmentation is available as a new subcommand. Commands and pipelines written for Cells2Stats 1.x require updates before they run on this version. For the required changes, see Migrating from Cells2Stats 1.x.

The following changes are not backward compatible:

  • Every command now requires a subcommand. A command that passes a run directory directly to cells2stats no longer runs. Use cells2stats analyze RUN_DIRECTORY instead.
  • The analyze subcommand accepts exactly one positional argument. Commands that passed both an input and an output path as positional arguments must pass the output path with --output.
  • MultiQC is no longer executed, and multiqc_report.html is no longer generated. The QC report, qc_report.html, replaces it.
  • The --skip-html-report and -H options are replaced by --skip-qc-report.
  • The --build-viz-from-SDO option is replaced by the visualize subcommand.
  • The --viz-points-sort-memory-gb and --viz-points-sort-threads options are removed. Use --visualization-workers to tune visualization concurrency.
  • The --viz-shape-smoothing-workers option now applies to the visualize subcommand only.
  • The Metrics directory is no longer written to the output directory.

New Features​

  • Reorganized the command-line interface into five subcommands, each with its own positional argument and options: analyze, visualize, process_imaging_targets, process_segmentation, and generate_qc_report.
  • Added hierarchical help. Running cells2stats --help lists the subcommands, and running cells2stats <subcommand> --help lists only the options that apply to that subcommand, grouped into categories such as Input, Filters, and Imaging targets.
  • Added the QC report, qc_report.html, an interactive HTML quality control report that covers run-level and well-level quality, per-target intensity and segmentation metrics, detected spatial artifacts, and a flow cell summary image.
  • Added the generate_qc_report subcommand to generate the QC report from an existing Spatial Data Object archive.
  • Added the --skip-qc-report option to skip QC report generation during an analysis.
  • Added the process_segmentation subcommand to generate new cell and nuclear segmentation masks from projection images with Cellpose. The run's CellSegmentation/ directory is never modified, and the masks are written to the directory set with --segmentation. For details, see process_segmentation.
  • Added the --process-segmentation option to analyze to chain Cellpose segmentation and downstream analysis into a single execution.
  • Added segmentation options to select the Cellpose model by cell type or model file, override the cell boundary, nuclear, and supplementary cell boundary targets, and override the cell diameter. The Docker image includes Cellpose and the Cellpose models.
  • Added the process_imaging_targets subcommand to reprocess retained _Raw projection tiles into corrected canonical projection TIFF files, applying illumination correction and a per-tile affine warp. The original projections in the run directory are never modified, and the destination is set with the required --projection-out-dir option.
  • Added the --process-imaging-targets option to analyze to chain projection reprocessing and downstream analysis into a single execution.
  • Added the --projection-dir option to analyze to source projection images from an alternate local path, symbolic link, s3:// URL, or gs:// URL. Any imaging target missing a {batch}_{target}.json transform file in that directory is populated from the run directory.
  • Added the --enable-illumination-correction and --disable-illumination-correction options to override the panel and recipe IlluminationCorrection settings during projection reprocessing.
  • Added the --target option to process_imaging_targets to restrict reprocessing to named imaging targets.
  • Added the --filter-mask option to apply a custom, batch-scoped pass-filter mask computed from quality scores, for example B01:N4Y*-B02:YN*.
  • Added the --spatialdata-metadata-file option to archive additional files in the metadata/ directory of the Spatial Data Object. The option is repeatable.
  • Added the --generate-specialized-targeted-bams option to output concatenated BAM files from Guide RNA alignment, one per well per target site.
  • Added the --disable-per-batch-background option to analyze, visualize, and process_imaging_targets to omit the per-batch background targets Bkg_RED and Bkg_GRN.
  • Added per-batch and per-target background quantification. Per-batch background is processed by default, and per-target background is reported as Bkg_{target} when RecipeValues.SavePerTargetBkgImages is true in RunParameters.json.
  • Added cytoplasmic and above-threshold intensity columns to RawCellStats.csv and RawCellStats.parquet, using the suffixes _Cytoplasmic, _FractionAboveThreshold, and _MeanIntensityOfFractionAboveThreshold, each with nuclear and cytoplasmic variants.
  • Added the _NuclearRatio intensity column, which reports the share of the above-threshold area of a cell that lies within the nucleus.
  • Added segmentation metrics to RunStats.json and to the Spatial Data Object.
  • Added per-cell and per-assay spatial artifact status to the Spatial Data Object.
  • Added support for a GAPDH control target in Guide RNA analysis.

Improvements​

  • Updated Guide RNA alignment to a unified, more sensitive strategy that handles G-tail trimming across target sites.
  • Updated the --target-mismatch-threshold option to accept integers from 0 to 4, applied as a G-tail-adjusted NM acceptance cap across all target sites.
  • Updated the --specialized-targeted-min-query-length default to 60% of the guide sequence length, floored at 12. When the requested value exceeds the mask sequence length of a target, Cells2Stats logs a warning and clamps the value.
  • Updated Guide RNA assignment so that a target marked with IsControl receives polony assignment but no guide assignment. Control targets therefore do not appear as cell-assigned guides.
  • Added a trailing polony index to cell screening read identifiers, a 7-digit integer that resets for each z-tile, to prevent duplicate read identifiers caused by negative x and y locations. The field appears in FASTQ headers and cyto points parquet files.
  • Added support for reading segmentation masks stored as Zarr v3 stores, where cell masks are uint32 and nuclear masks remain uint8. Cells2Stats reads both Zarr and TIFF masks and copies them without conversion.
  • Updated the read statistics schema for consistency with Bases2Fastq™.
  • Updated pass-filter statistics reporting and renamed the specialized targeted assay type.
  • Improved Spatial Data Object generation performance.
  • Improved handling of 3′ transcriptome batches in the QC report.
  • Updated the QC report to use friendly names for panels and targets.
  • Hardened the execution of shell commands.
  • Added logging for each Guide RNA job that indicates the target sites being processed.

Resolved Issues​

  • Cells2Stats no longer overrides local cell segmentation masks when a remote set of masks is specified.
  • Visualization no longer fails when a run has no nuclear segmentation.
  • Cells2Stats no longer produces a visualization for a run that has no images.
  • Internal stain only runs no longer fail QC report generation.
  • Spatial artifacts are no longer calculated for run types where the calculation does not apply.
  • Addressed a race condition in the generation of per-well Spatial Data Objects.
  • Addressed a statistics aggregation error that produced incorrect run-level values.
  • Addressed a fence post error in the calculation of per-cell background.
  • The spatial data build no longer produces empty parquet files, and an empty row group is no longer appended to read parquet files.
  • Read parquet files now contain no more than one row for each polony.
  • RawReadStats now reports a read count of -999 when no data is present.
  • Corrected the misspelled AssignedOnTargetCountPerMM2 field in the ControlTargets section of RunStats.json.
  • Cells2Stats now returns exit code 1 when Spatial Data Object generation fails.
  • Cells2Stats now reports an error when a Guide RNA batch has no target sites configured across all wells.
  • Corrected confluency mask generation.
  • 48-well plate labels now display correctly in CytoCanvas™.

v1.4.0-beta​

June 5, 2026

Improvements​

  • Added generation of SpatialData files in execution output.
    • SpatialData must be regenerated when cell segmentation is updated or when updating for an OPS batch.
    • The static binary now includes an additional dependency to support SpatialData generation.
  • Added new flag --build-viz-from-SDO to regenerate visualization files from an existing Spatial Data Object (SDO) where visualization generation previously failed.
  • Added three new flags --viz-points-sort-memory-gb, --viz-points-sort-threads, and --viz-shape-smoothing-workers to support as-needed memory and CPU usage adjustments for SpatialData generation.
  • Removed --visualization and --visualization-only optional arguments. Visualization files are now generated by default.
  • Updated MultiQC to v1.35.
  • MultiQC reports for Teton™ Custom Screen runs now generate successfully.
  • Included requirements.txt file in the Cells2Stats static binary.
  • Updated extracellular-ratio metric calculation to ignore the outer edge of the tile.
  • Visualization is now generated as a SpatialData/ output directory containing a zipped Spatial data object, accompanied by visualization index and cyto.zip file. SpatialData visualizations are compatible with CytoCanvas Studio™ and CytoCanvas 1.4.9 and greater.
  • Updated the output file structure to enable CytoCanvas support:
    • cyto.viz is now in the Cells2Stats output directory instead of generated within the visualization folder.
    • RawCellStats.parquet is no longer copied into the visualization directory.
  • Added PercentCellularAssigned to RunStats.json.
  • This is a beta release. Some features, such as 3' untargeted transcriptome support, are included for future implementations and are not yet available on current on-market products.

v1.3.1​

April 14, 2026

Improvements​

  • --visualization and --viz-only options fixed to utilize alternate segmentation masks when provided.
  • --visualization and --viz-only options updated to accurately calculate the pixel to micron ratio for the CytoCanvas Flow Cell View scale bar.
  • Addressed an issue with copying RunStats.json when running the cells2stats Docker distribution.

v1.3.0​

July 30, 2025

Improvements​

  • Support is now available for cytoprofiling runs that are executed with the new Teton Custom Screen cartridge and three assay options that are available in AVITI OS 3.4.0.
  • Added a new AntibodyScreeningKitReport.csv file for Teton Custom Screen runs, that includes cell, control, and target antibody information. This file can be used when evaluating the run to review the target counts or negative control counts per cell (normalized values).
  • Support is now available for cytoprofiling runs that are executed with the new Teton Atlas™ cartridge in AVITI OS 3.4.0.
  • When Target Cell Assignment is enabled for any target in the run, TargetCounts.json, TargetCellAssignment.csv, and TargetCellAssignmentManifest.json output files are included.
  • Added new optional arguments:
    • --bases2fastq, -B: The path to Bases2Fastq binary that is used for fastq generation during Optical Poolded Screen analysis.
    • --bowtie: The path to bowtie (v1) binary that is used in Optical Pooled Screen analysis.
    • --bowtie-build: The path to bowtie build binary that is used in Optical Pooled Screen analysis.
    • --samtools: The path to samtools binary that is used in Optical Pooled Screen analysis.
    • --tca-manifest, -M: The local or remote path to target cell assignment manifest. Must have CSV or JSON extension.
    • --skip-html-report, -H: Used to skip the creation of MultiQC HTML reports.
  • A new MultiQC HTML report, which is an interactive HTML quality control summary that is generated from the RunStats.json summary, can now be generated. This report also supports combining results of other bioinformatics tool outputs across one or more runs into a single report, which provides an efficient method to compare results across tools or runs.
  • Added new fields to the RunStats.json file for improved spatial analysis and to support Teton Atlas and Teton Custom Screen cytoprofiling run types.
  • Added new columns to the RawCellStats file.
  • Updated the visualization output files to improve the CytoCanvas display:
    • RawCellStats.parquet copies into the visualization output directory to support Optical Pooled Screen run visualization in CytoCanvas 1.2.0-beta.
    • Included image information in the cyto.viz file to support Optical Pooled Screen run visualization in CytoCanvas.
  • New segmentation boundary smoothing algorithm to improve smoothing and reduce jagged edges.

v1.2.0​

April 8, 2025

Improvements​

  • Enhanced the RawCellStats file - Added the following fields for improved spatial analysis:
    • NuclearArea (nuclear area in pixels)
    • AreaUm (cellular area in microns)
    • NuclearAreaUm (nuclear area in microns)
    • Xum (X position in microns)
    • Yum (Y position in microns)
  • Expanded the barcodes.parquet** file - Added the following spatial data for each polony:
    • Xum (X position in microns)
    • Yum (Y position in microns)
    • Zum (Z position in microns relative to the Z00 slice)
    • Z (String label of the Z-slice, such as 00 or 01)
  • Added NucleatedRate (percent of cells with a nucleus) to the RunStats.json file
  • New visualization pre-processing outputs - The following files are generated to support future CytoCanvas well visualization:
    • WellInformation.json
    • TileInformation.json
  • Improved segmentation boundary smoothing algorithm - Enhancements retain small cells, small nuclei, and intricate features of neuronal cells, such as axons.

v1.1.0​

February 13, 2025

Improvements​

  • Added target count per area metric to the run statistics file content.
  • Added the --verbose-transfer command, which prints file names to the terminal when logs are copied

v1.0.0​

December 4, 2024

This is the initial release of Cells2Stats. Cells2Stats processes Teton Cytoprofiling data to generate detailed statistics and outputs that enable downstream analysis, including visualization using the CytoCanvas tool. 

New Features​

  • Performs target to cell assignment (including RNA and protein targets) and generation of associated raw and normalized metrics files
  • Performs morphology feature extraction from projection images with CellProfiler
  • Prepares run outputs for visualization in CytoCanvas
  • Optional arguments allow customization of processing, such as specifying batches, wells, whether to generate morphology features with CellProfiler, whether to generate files for CytoCanvas, and more.
Last updated on