Setup

This document details how to create a local copy of this pub’s codebase, setup your compute environment, and reproduce the pub itself. This will enable you to experiment with the analysis in the pub and, optionally, contribute revisions to it.

Obtain local copy

The codebase is hosted on GitHub and can be found here.

To obtain a local copy of this repo, you can either clone it directly or fork it to your own GitHub account, then clone your fork. If you aren’t sure what’s best, our suggestion is to clone directly unless you both (1) want to propose a revision for the publication and (2) are not an employee of Arcadia Science.

To clone:

git clone https://github.com/Arcadia-Science/cloud-scaled-cell-phenotyping.git

Installation

Important

The publication is rendered with Quarto. If you don’t have it installed (check with quarto --version), you can install it here.

This repository uses uv to manage the computational and build environment. If you don’t have it installed (check with uv --version), you can find operating system-specific instructions for installing it here. After installing, run the following command to create the environment and install all dependencies (including the repository’s internal packages, in editable mode):

uv sync

This creates a .venv/ and installs everything pinned in uv.lock, using Python 3.12 as specified in .python-version.

The notebook picks a segmentation backend automatically:

• Scaled (Modal + S3): used when the Modal client is authenticated and the aws-s3-access-secret is available. This is the internal path.
• Local: used otherwise. The published dataset (raw ND2s and derived artifacts) downloads from Zenodo (10.5281/zenodo.23377605) and Cellpose-SAM runs on CPU. Install that stack with uv sync --extra demo.

To force the local path in an environment that also has Modal, set CSCP_FORCE_LOCAL=1 or pass backend="local" to run_demo.

And finally, if you plan to submit a pull request, install the pre-commit hooks:

uv run pre-commit install

What’s next?

With a copy of the code and compute environment set up on your local machine, you can now reproduce or modify a local copy of the publication however you see fit. Read on to get started.

Reproduce

The best way to ensure you’ve correctly set up your code and compute environment is to reproduce this work. Fortunately, the analysis, and therefore the publication itself, can be reproduced with the following command:

make execute

(The make targets run through uv run, so they automatically use the environment created above.)

This will execute and render the notebook index.ipynb, then build the publication site. To preview the site, use

make preview

This will open a local instance of the publication in your default browser.

Modify

To modify or extend any analyses, open up index.ipynb with Jupyter or your favorite IDE. To preview changes as you modify the notebook, run make preview again and leave the command running. As you make changes to the notebook, the preview site will automatically reload.

Publish

If you’ve improved the publication, consider contributing so we can update the hosted publication with your edits (big or small!). To get started, see our contributing guide.