Skip to main content

Executing Cells2Stats

Learn how to execute the Cells2Stats CLI

Execute Cells2Stats on a local compute environment by entering a command in the CLI terminal. The command varies based on cloud storage setup and execution type, either Docker or static binary. Append options to the command to specify file generation settings.

The command has the following parts:

  • The cells2stats executable
  • A subcommand that selects the stage of analysis to run
  • Optional arguments to manipulate the output
Note:

Cells2Stats 2.0.0 requires a subcommand. The examples on this page use analyze, which performs the full analysis that the top-level command performed in Cells2Stats 1.x. For the other subcommands, see Run a single stage.

Run a single stage​

Cells2Stats splits its work into five subcommands. Use analyze for a full execution, and use the others to repeat one stage without reprocessing the whole run.

SubcommandUse it to
analyzeProcess a run directory into a Spatial Data Object, cell statistics, and the QC report
visualizeRebuild CytoCanvas™ visualization files from an existing Spatial Data Object archive
generate_qc_reportRegenerate qc_report.html from an existing Spatial Data Object archive
process_imaging_targetsReprocess raw projection tiles into corrected projection images without running a full analysis
process_segmentationGenerate new cell and nuclear segmentation masks from projection images with Cellpose
Note:

To resegment a run, use process_segmentation to generate new masks with Cellpose, then pass the output directory to analyze with --segmentation. To segment and analyze in a single execution, run analyze with --process-segmentation. Segmentation writes masks to a new directory and does not modify the CellSegmentation directory of the run. Segmentation requires Cellpose and the Cellpose models, which the Docker image includes. For static binary requirements, see Segmentation dependencies.

For example, to regenerate visualization files for an archive whose visualization step previously failed, run the following command:

./cells2stats visualize path/to/RunName.zarr.zip -j 8

To see the options for any subcommand, place --help after the subcommand name:

./cells2stats analyze --help

For every option on every subcommand, see the CLI reference.

Execute the software​

  1. Copy the template execution command for your storage type from one of the following subsections:

  2. Adjust the optional arguments in the run command.

    • To add arguments, replace {options} with any of the options listed in the analyze CLI reference.
    • To execute Cells2Stats without any arguments, delete {options}.

  3. Execute the command in the terminal.

  4. The execution is completed successfully when the terminal displays the following log lines.

    <timestamp> [info]: Analysis completed successfully.
    <timestamp> [info]: Output written to </output>

  5. Access the output files in the run directory. By default they go to the Cytoprofiling/<timestamp> folder.

Execute with local storage​

Copy the template execution command for Docker or static binary. Update the template command and execute Cells2Stats as described in steps 2–5 of the execution instructions.

When using Docker, the general execution command automatically pulls the image to the local environment if it is not already there. The command uses the following structure:

  • docker run invokes the Docker daemon to start the specified image.
  • --rm removes the image after the execution completes. Element Biosciences recommends using this argument to keep your system clean.
  • elembio/cells2stats identifies the image that you want to pull. By default, this image is the latest. For a specific a version, include a tag, such as elembio/cells2stats:1.0.0.
  • -j threads Cells2Stats for faster parallel execution. The value depends on your system setup. The example command has a value of 8, which requires at least 8 CPUs.
  • {options} defines the analyze options.
  • {directory} defines the path to the directory for input and output files.

Executing in local environments might require mounting the directory to Docker:

  • -v mounts the local path to Docker as a volume.

  • :/input binds the mounted path to a variable for use by Cells2Stats.

    docker run --rm  elembio/cells2stats cells2stats analyze {directory} -j 8 {options}

Execute with AWS S3​

AWS S3 requires Uniform Resource Identifiers (URIs) to serve as paths to the Amazon S3 buckets that contain the input and output files. Accessing the buckets requires AWS credentials configured for the setup. If both input and output locations are AWS, they must use the same credentials.

  • For AWS S3 within an EC2 instance, Cells2Stats detects the credentials or Identity and Access Management (IAM) role associated with the instance.
  • For AWS S3 access without an EC2 instance, define AWS credentials with the following environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_DEFAULT_REGION.
Note:

If Cells2Stats fails to detect credentials attached to an AWS storage location with an EC2 instance, the environment variable might be incorrect. Make sure this variable is set correctly in the EC2 instance: export AWS_DEFAULT_REGION=$aws_region.

  1. Run the following export command in terminal to set the credentials as environment variables.

    export AWS_ACCESS_KEY_ID=ExampleAccessKey
    export AWS_SECRET_ACCESS_KEY=EXAMPLEnhMUUOhQF/T51c6A5+DtQas9ghebs
    export AWS_DEFAULT_REGION=us-west-2

  2. Copy the following template execution command for Docker or static binary.

For Docker, the execution command includes -e to pull in the credentials set as environment variables.

docker run --rm -e AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY -e AWS_DEFAULT_REGION=$AWS_DEFAULT_REGION elembio/cells2stats cells2stats analyze s3://bucket/input -o s3://bucket/output -j 8 {options}
  1. Update the template command and execute Cells2Stats as described in steps 2–5 of the execution instructions.

Execute with GCS​

GCS storage requires URLs to serve as preconfigured paths to the Cloud Storage buckets that contain the input and output files. Accessing the buckets requires configuring GCS credentials for the setup. If both input and output locations are GCS, they must use the same credentials.

The environment variable GOOGLE_APPLICATION_CREDENTIALS must link to the file that contains the application credentials. For more information, see the Google documentation.

  1. Run the following export command in terminal to set the credential as an environment variable.

    export CREDENTIALS="/path/to/GCP-creds.json"

  2. Copy the following template execution command for Docker or static binary.

For Docker, the execution command includes -e to pull in the credential set as an environment variable.

docker run --rm -e GOOGLE_APPLICATION_CREDENTIALS=$CREDENTIALS elembio/cells2Stats cells2stats analyze gs://bucket/input -o gs://bucket/output -j 8 {options}
  1. Update the template command and execute Cells2Stats as described in steps 2–5 of the execution instructions.

Execute with Rclone-compatible cloud​

Before executing Cells2Stats with rclone, review the rclone requirements for system setup.

If you are using rclone, Element recommends executing with static binary. For execution, use the --input-remote and --output-remote options as shown in the following code example. Then update the template command and execute Cells2Stats as described in steps 2–5 of the execution instructions.

./cells2stats analyze path/to/input/remote -o path/to/output/remote --input-remote "input-name" --output-remote "output-name" -j 8 -s {options}
Last updated on