Software and system setup

Install Cells2Stats as a static binary or Docker container and configure the compute environment.

When you set up Cells2Stats on a system, you must install a static binary executable or use a Docker container that meets system requirements. Additionally, to handle remote input and outputs paths you must configure the compute environment to transfer files.

System requirements

Operating system

Cells2Stats is compatible with various operating systems (OS). To determine the appropriate Cells2Stats distribution for your OS, review the following compatibility matrix:

Operating System	Docker Compatibility	Static Binary Compatibility	OS Notes
Linux OS			The static binary executable is compatible with any Linux OS on an x86 architecture that uses glibc v2.19 or later. To verify the glibc version for static binary, run the following command: ldd --version
Windows OS			Windows OS is not directly compatible with the static binary executable. Install Docker and run using Docker. Review the system requirements. It is recommended that you enable the WSL 2 backend feature.
Windows OS with Windows Subsystem for Linux (WSL)			If you install WSL on Windows OS, you can use the static binary executable in the WSL environment.
Mac OS			MacOS is not compatible with the static binary executable. Install Docker and run using Docker.

Note:

Cells2Stats is not supported on ARM processors.

Memory and performance

Software performance is based on the resources that are dedicated to the processing environment and whether CellProfiler is enabled or not. For optimal performance, verify that you have at least 16 CPU cores available and enable threading Cells2Stats with the -j argument. The following memory requirements apply to both Docker and static binary distributions:

• If CellProfiler is enabled, Cells2Stats requires 2 GB RAM per concurrent thread.
• If CellProfiler is not enabled, Cells2Stats requires 200 MB RAM per concurrent thread.

Note:

To generate SpatialData outputs, it is recommended to have total system memory of at least 32 GiB.

The following table provides processing time estimates for Cells2Stats to generate output files with different optional arguments. These estimates are based on an Amazon m5dn.12xlarge EC2 instance with an onboard SSD:

Threads	--skip-cellprofiler	No optional arguments
8	34m	3h 29m
16	33m	2h 10m
32	33m	1h 43m

Temporary directory

When you use cloud storage, Cells2Stats downloads input files and stages output files in a temporary directory. Intermediate files that are generated during analysis are also stored in the temporary directory. After an execution completes, the temporary directory is cleared. The temporary directory uses approximately 50 GB for a typical cell screening run.

By default, Cells2Stats uses the temporary directory of the OS. To change the temporary directory location, set the environment variable TMPDIR. Use the following example command and replace /path/to/scratch with the desired directory:

Set TMPDIR in Linux env

export TMPDIR="/path/to/scratch"

File transfer and storage setup

To transfer files, Cells2Stats requires paths to input and output locations. You can store input and output files in a local location or the cloud. For cloud storage, the following providers are compatible:

• Amazon Simple Storage Service (Amazon S3)
• Google Cloud Storage (GCS)
• Any Rclone-compatible provider

Amazon S3 and GCS storage connections require a credential configuration for Cells2Stats executions. For more information, see Execute with Amazon S3 and Execute with GCS.

Rclone requirements

Rclone is a command-line program to manage files on cloud storage. Rclone provides the ability to mount any local, cloud, or virtual file system. Rclone allows Cells2Stats to access many cloud storage providers. However, Element Biosciences has not tested every available Rclone provider.

To download and install Rclone, follow the instructions at rclone.org/install. To communicate with your cloud storage, configure an Rclone remote setup. For more information, see the provider-specific instructions at rclone.org/#providers.

Cells2Stats installation

To set up Cells2Stats, use Docker or static binary. Docker is the recommended installation method because the Cells2Stats image includes every dependency that Cells2Stats requires:

• Python 3.11 with all required Python packages
• CellProfiler 4.2.6
• Cellpose and the Cellpose segmentation models
• Bases2Fastq™, Bowtie 1.3.1, and samtools for Guide RNA analysis

If you use the Cells2Stats static binary, you must install and configure these dependencies yourself. The following sections provide specific configuration information:

Note:

The static binary executable for Cells2Stats is only compatible with specific OS configurations. Review the OS requirements before attempting installation.

Docker

1. Follow the OS-specific instructions at docs.docker.com/get-docker/.

2. To pull the latest version of the Cells2Stats image from the Element public registry at DockerHub, run the following command:

   docker pull elembio/cells2stats

3. To confirm that Cells2Stats is operational, run the following commands to display the software version and help content:

   docker run elembio/cells2stats cells2stats --version

   docker run elembio/cells2stats cells2stats --help

Static Binary

1. To download the latest version of the static binary, use one of the following methods:

• Visit the Element website and follow the onscreen prompts.
• Run the following curl command:

curl  https://cells2stats-release.s3.amazonaws.com/cells2stats-latest.tar.gz -o cells2stats-latest.tar.gz

2. To extract the file, run the following tar command:

   tar -xvf cells2stats-latest.tar.gz

3. To confirm that Cells2Stats is operational and display the software version and help content, run the following commands:

   ./cells2stats --version

   ./cells2stats --help

General and CellProfiler dependencies

The following dependencies are required for general Cells2Stats use and includes CellProfiler. For additional options when you run CellProfiler with Cells2Stats, see --cellprofiler.

• Cells2Stats runs its Python-backed steps with the Python executable at /usr/bin/python3 by default. If your Python environment is in a different location, set the C2S_PYTHON environment variable or pass the path with --python. For more information, see --python.

Dependency	Version Requirement
python	3.11+
cellprofiler	4.2.6

If you need to run Cells2Stats with CellProfiler, install CellProfiler on your system and verify that the installation path is accessible to Cells2Stats. The following is an example Ubuntu installation that requires two versions of python to be managed:

export DEBIAN_FRONTEND=noninteractive
apt -y update && apt -y upgrade
apt install -y software-properties-common
add-apt-repository -y ppa:deadsnakes/ppa
apt install -y python3.8
apt install -y python3-virtualenv
apt install -y make gcc build-essential libgtk-3-dev
apt-get install -y python3-pip openjdk-11-jdk-headless default-libmysqlclient-dev libnotify-dev libsdl2-dev
apt-get install -y freeglut3 freeglut3-dev libgl1-mesa-dev libglu1-mesa-dev libgstreamer-plugins-base1.0-dev libgtk-3-dev libjpeg-dev libsm-dev libtiff-dev libwebkit2gtk-4.0-dev libxtst-dev
export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
export PATH=$PATH:/home/ubuntu/.local/bin
apt install -y python3.8-distutils
apt-get install -y python3.8-dev
virtualenv cellprofiler_env --python=python3.8
source cellprofiler_env/bin/activate
pip install --upgrade pip
pip install wheel cython==0.29.37 numpy scipy
pip install https://extras.wxpython.org/wxPython4/extras/linux/gtk3/ubuntu-22.04/wxPython-4.2.1-cp38-cp38-linux_x86_64.whl
pip install --no-build-isolation scikit-learn==0.24.2
pip install cellprofiler

Python dependencies

Cells2Stats uses Python for several analysis steps, including Spatial Data Object generation, data visualization files for CytoCanvas, and the QC report. The following dependencies are required in the Python environment that Cells2Stats uses:

Dependency	Version requirement
anndata	>=0.12.10
dask	>=2026.1.1
duckdb	>=1.4.2
geopandas	>=1.1.1
matplotlib	>=3.10.0
numpy	>=2.2.6
ome-zarr	==0.13.0
opencv-python	>=4.12.0.88
pandas	>=2.3.3
polars	==1.38.1
pyarrow	>=23.0.1
pydantic	==2.12.5
scikit-image	>=0.26.0
scikit-learn	>=1.6.0
scipy	>=1.16.3
spatialdata	>=0.7.2,<0.8.0
tifffile	>=2026.1.28
xarray	>=2025.6.1
xxhash	>=3.6.0
zarr	>=3.1.5
zstandard	>=0.23.0

The static binary download includes a requirements.txt file that lists these dependencies and the segmentation dependencies. To install every Python dependency, complete the following steps:

1. Install Python 3.11 or later, pip, and the OpenGL library that opencv-python requires:

   • Debian-based systems:

     sudo apt install -y python3 python3-pip libgl1

   • RHEL-based systems:

     sudo yum install -y python3 python3-pip mesa-libGL

2. From the directory where you extracted the static binary, install the dependencies:

   python3 -m pip install -r requirements.txt

3. If the Python executable that has the dependencies is not at /usr/bin/python3, set C2S_PYTHON to its path or pass the path with --python.

Segmentation dependencies

Cells2Stats can run Cellpose cell and nuclear segmentation from the projection images in a run directory, instead of using the segmentation masks that the instrument generates. Segmentation runs with the process_segmentation subcommand, or with the --process-segmentation option of the analyze subcommand. Segmentation writes new masks to a separate directory and does not modify the CellSegmentation directory of the run.

The following dependencies are required to run segmentation with Cells2Stats, in addition to the Python dependencies:

Dependency	Version Requirement
python	3.11+
cellpose	3.0.7
torch	Any version compatible with Cellpose 3.0.7

The requirements.txt file included with the static binary installs both packages. Cells2Stats runs segmentation on a GPU when PyTorch detects a compatible GPU, and otherwise runs segmentation on the CPU.

Cellpose models

Cells2Stats uses Element-trained Cellpose models for cell and nuclear segmentation. Cells2Stats does not download models during analysis, so the models must be available in a local directory. The Docker image includes the models at /cellpose_models, which is the default models directory.

For the static binary, download the models from the Element cytoprofiling repository on GitHub:

1. Download the repository archive:

   curl -fsSL https://codeload.github.com/Elembio/cytoprofiling/tar.gz/main -o cytoprofiling.tar.gz

2. Extract the models into a directory named cellpose_models:

   tar -xzf cytoprofiling.tar.gz --wildcards --strip-components=2 '*/src/segmentationModels'
   mv segmentationModels cellpose_models

3. When you run segmentation, pass the absolute path of the models directory with --cellpose-models-directory and an output directory with -S:

   ./cells2stats process_segmentation /path/to/run_directory -S /path/to/output_segmentation --cellpose-models-directory /path/to/cellpose_models

The models directory must be a local path. The models require approximately 750 MB of disk space.

Guide RNA dependencies

Cells2Stats performs Guide RNA analysis on runs with target cell assignment enabled for at least one target site. During Guide RNA analysis, Cells2Stats generates FASTQ files and aligns the reads to the expected guide sequences. To add a Target Cell Assignment manifest, see Prepare a Target Cell Assignment Manifest. For the options that apply to Guide RNA analysis, see Guide RNA in the CLI reference.

The following dependencies are required to run Guide RNA analysis with Cells2Stats:

Dependency	Version Requirement
bases2fastq	2.4.0+
bowtie (with bowtie-build)	1.3.1
samtools	1.13+