spaCR

Spatial phenotype analysis of CRISPR screens.

spaCR segments and measures single cells in microscopy images, integrates per-object phenotypes with sequencing-derived guide abundance, and estimates which genes are associated with phenotypic changes. Starting from plate images and FASTQ reads, it produces per-object measurements, trained classifiers, per-guide and per-gene effect estimates, and a ranked hit list.

The segmentation, measurement, annotation and classification modules also run without a sequencing arm.

Make Masks corrects segmentation masks and annotates independent, class-labelled rectangles with the Box tool for YOLO export. Boxes keep their own labels and history without changing source images or masks.

See the feature guide for each tool.

Images, masks, crops, measurements, annotations, predictions, barcodes and well identifiers live in one SQLite project.

Runs as a desktop application or headlessly on a workstation, server or cluster.

Try spaCR

conda create -n spacr python=3.12 -y
conda activate spacr
python -m pip install spacr
spacr

Use Load test data… in Import, Make Masks, Annotate or an assay screen to download example data. From a terminal, use spacr-download.

Hardware support

Hardware	Cellpose 4	Torch	UMAP / clustering
NVIDIA (CUDA)	🟢 GPU	🟢 GPU	🟢 GPU
AMD on Linux (ROCm)	🟣 GPU	🟣 GPU	🔴 CPU
AMD in an Intel Mac (Metal)	🟣 GPU	🟣 GPU	🔴 CPU
Apple Silicon (Metal)	🟣 GPU	🟣 GPU	🔴 CPU
Intel Arc/Xe (XPU)	🟣 GPU	🟣 GPU	🔴 CPU
No GPU	🟢 CPU	🟢 CPU	🟢 CPU

🟢 supported (stable) 🟣 implemented (beta) 🔴 CPU support only

Install spaCR

Desktop application

The installers bundle their own Python. Conda is not required.

On Linux, make the downloaded file executable and run it:

chmod +x SpaCR-*-Linux-x86_64-Online.run
./SpaCR-*-Linux-x86_64-Online.run

On macOS, open the .pkg. The current beta is not notarized; if Gatekeeper blocks it, choose System Settings → Privacy & Security → Open Anyway.

See the installer guide for update, uninstall, offline and troubleshooting instructions, and system requirements for workstation and server recommendations and the GPU compatibility tables.

PyPI installation

For the PyPI release, install spaCR with pip inside a Conda environment. Python 3.12 has the widest choice of optional scientific packages:

conda create -n spacr python=3.12 -y
conda activate spacr
python -m pip install --upgrade pip
python -m pip install spacr
spacr

spaCR supports Python 3.9 through 3.14, except Python 3.14.1, which torchvision excludes. Linux is recommended for the heaviest CUDA and ROCm workflows; macOS and Windows are also supported, and both use their GPUs — macOS through Metal, which covers Apple Silicon and the AMD cards in Intel Macs, and Windows through CUDA or DirectML.

The standard installation includes the Qt desktop interface. For a server, cluster or CI runner, run the command-line pipelines without opening it:

python -m pip install spacr
spacr-run --list

Optional integrations are installed separately, for example spacr[zarr], spacr[omero], spacr[napari] and spacr[czi,nd2,lif]. See the installation guide for the complete extras and Python-version compatibility table.

Conda-forge installation

The official conda-forge package installs spaCR and its desktop dependencies into the active environment:

conda create -n spacr python=3.12 -y
conda activate spacr
conda install conda-forge::spacr
spacr

Docker installation

Run spaCR’s command-line pipelines in a container using the published Docker images on GHCR. Install Docker, then list the available pipelines with this published CPU image:

docker run --rm ghcr.io/einarolafsson/spacr:1.5.1.0 spacr-run --list

The matching NVIDIA GPU image is ghcr.io/einarolafsson/spacr:1.5.1.0-cuda12.4. Both images target Linux x86-64 containers. See the Docker installation guide for GPU prerequisites, data and model mounts, settings files, and complete pipeline commands.

Install from source

Clone the repository and install it in editable mode, so your working copy is the installed package and edits take effect without reinstalling:

git clone https://github.com/EinarOlafsson/spacr.git
cd spacr
conda create -n spacr python=3.12 -y
conda activate spacr
pip install -e .
spacr

This clones main, the default branch, which carries the latest release. Development happens on nightly; add --branch nightly to clone it instead. For a specific release:

git clone --branch v1.5.0.5 https://github.com/EinarOlafsson/spacr.git

To pull later changes, from inside the clone:

git pull
pip install -e .

Reinstall when dependencies or entry points change. Python edits take effect directly; spacr-doctor identifies the active installation.

Install from source (light)

Contributors need history; to run spaCR, choose below. Measurements: nightly at 05302fd5c on 2026-10-07, using packaging/measure_clone_forms.sh:

# One commit instead of every version: 2048 MB downloaded, 140 s.
# No history, so no git log, no git blame and no git bisect.
# git pull still works, but stays shallow until git fetch --unshallow.
git clone --depth 1 --branch nightly https://github.com/EinarOlafsson/spacr.git
cd spacr && pip install -e .

# Runtime files: 104 MB on disk, 6 s (Git: 38 MB; files: 66 MB).
# No history, docs, tests, tools, features or example data.
# --with-docs, --with-tests and --with-translations put those back;
# --dir, --branch, --no-install and --help do the obvious things.
# packaging/source_install_excludes.txt lists every skipped path.
curl -fsSL https://raw.githubusercontent.com/EinarOlafsson/spacr/nightly/packaging/install_from_source.sh -o install_spacr.sh
sh install_spacr.sh --branch nightly

The full nightly clone downloaded 9.25 GiB. Adding --filter=blob:none to the shallow clone does not help shrink the checkout: its object store still weighs 2032 MB. Quiet lazy fetches prevent a complete measured download total. The nightly tracked tree is a 3416 MB checkout (measured 2026-10-08), excluding Git history. Download sizes and times vary with the branch.

Command-line entry points

spacr                                      # launch the Qt application
spacr-doctor                               # diagnose the installation
spacr-run --list                           # list headless modules
spacr-run --describe MODULE                # inspect a module contract
spacr-run MODULE --settings settings.csv   # execute a module
spacr-run validate --module MODULE \
    --settings settings.csv                # validate before running
spacr-repro RUN_DIR                        # replay a recorded run
spacr-download --list                      # what example data exists
spacr-download measure annotate            # fetch example sets by name
spacr-make-masks --folder DIR              # curate masks as a resumable queue
spacr-make-masks --folder DIR --order easy --limit 50

spacr-run --list lists modules with headless command-line entry points. GUI-only annotation, curation, comparison and exploration modules are omitted.

Core workflow

The primary workflow comprises six modules:

Mask segments cells, nuclei, pathogens and organelles with Cellpose.
Measure writes morphology, intensity, texture, spatial and colocalization features, together with object crops, to SQLite.
Annotate labels crops in a keyboard-driven grid and supports active-learning queues.
Classify trains image or measurement-based models and records held-out performance with each checkpoint.
Map Barcodes maps FASTQ reads to wells and gRNAs, with abundance, collision and coverage QC.
Regression estimates guide, gene, condition and control effects with model families suited to continuous, fractional and count responses.

spaCR modules

Core

Core sequence from microscopy images through segmentation, measurements, annotations, classification, barcode mapping and regression.

Data

Import images and tables into spaCR projects and execute reproducible multi-plate workflows.

Tools

Point these at a project: edit masks by hand, stitch tiles, read an embedding, draw a gate, build a plot, check quality.

Organism

Organism-specific image analysis and quantitative assay readouts.

Every module with a Home tile, in Home’s order: the six pipeline modules first, then the rest. Select a tile to open that module’s API page.

Other resources

Interactive tutorials — guided workflows from installation through hit investigation.
Python API quickstart — run and validate pipelines from scripts, notebooks or a cluster.
Feature guide — capabilities, maturity and optional integrations.
Curated API reference — supported entry points by task, with the complete module reference one level deeper.
Language & translation guide — interface languages, contextual help and scientific-output policy.

Language & translation

The interface supports ten languages across navigation and Preferences. AI and LIVE controls, module descriptions and reviewed contextual help are also translated. Change the language under spaCR → Preferences → Language without restarting. Logs, paths, database values and measurements are never translated; scientific output remains canonical English. See the contextual-help policy.

The nine non-English catalogs are machine-drafted and technically reviewed rather than read end to end by a native speaker. The review scope records which languages have had a human pass and every term left in English by decision.

Animated setting guidance

Settings with a visual explanation offer an Animation control in their tooltip. Browse the setting animation gallery or the Setting animation registry.

Data

Reference datasets

Model zoo

spaCR ships a catalogue of trained models and fetches them on demand. Open Model Zoo from the home screen to browse and install them, or name a key in a settings file – pathogen_model: toxoplasma_pv_v1 – and the model is downloaded and checksum-verified the first time it is needed. Every published entry carries a SHA-256; an entry without one is refused rather than installed, because a truncated or substituted checkpoint cannot be told from the real one.

Model	Training data	Hold-out performance
toxoplasma_pv_v1 (Cellpose-SAM (cpsam_v2))	anti-Toxoplasma-biotin and DsRed PV lumen; 229 images from 2 datasets, 104 round-1 and 125 newly curated	F1 0.864 against 0.713 for stock cpsam on 11 held-out in-house wells, at IoU 0.5; literature hold-out pending
toxoplasma_plaque_v1 (Cellpose-SAM (cpsam))	crystal violet plaque wells; 184 wells from 3 datasets, 95 in-house and 89 literature	F1 0.856 in-domain; 0.806 on literature (3-fold cross-validated, SD 0.020)
toxoplasma_plaque_v2 (Cellpose-SAM (cpsam_v2))	488 curated fields across four domains – 298 wells cropped from published figures, 96 phone-camera wells, 67 PFA and 27 methanol-fixed whole-well microscope scans; 27,582 plaques	not scored against stock; on 81 held-out fields it ties round 3 on literature (0.819 vs 0.820) and beats it by 0.166 on phone-camera wells (0.415 vs 0.249)
toxoplasma_well_detector_v1 (YOLO11n)	whole-plate and multi-well crystal violet images; 562 images from 1 dataset, 190 of them with no well in them	mAP50 0.993 on its own held-out split; on the test set shared with v2 it scores mAP50 0.8838, against v2’s 0.9457
toxoplasma_well_detector_v2 (YOLO26n (ultralytics 8.4.155))	plate images and literature figures; 1,070 train / 254 val / 129 test, split by PMC article so no paper is in two sets; training data at einarolafsson/toxoplasma-plaque-well-detector-dataset	mAP50 0.9457 and mAP50-95 0.8341 against v1’s (yolo_welldetect_v3.pt) 0.8838 and 0.7630 on the SAME test set; stock YOLO has no plaque-well class, so v1 is the baseline
toxoplasma_from_cellmask_v1 (Cellpose-SAM (cpsam_v2))	Toxoplasma PV masks predicted from the HOST CELL MASK channel alone; 2567 training and 463 held-out fields, split by well, hosts HFF/HeLa/THP1	F1 0.606 against 0.021 for stock cpsam_v2 on 463 well-grouped held-out fields, at IoU 0.5
toxoplasma_pv_v2 (Cellpose-SAM (cpsam_v2))	anti-Toxoplasma-biotin and DsRed PV lumen; 556 curated images accumulated over five rounds	F1 0.817 +/- 0.036 by 5-fold cross-validation over 619 pairs; ~0.86 against 0.713 for stock on the 11 in-house held-out wells
toxoplasma_pv_v3 (Cellpose-SAM (cpsam_v2))	the 556 curated PV fields of round 5, split 437 train / 108 validation / 11 test; training data at einarolafsson/toxoplasma-pv-segmentation-dataset	F1 0.860 against stock cpsam_v2’s 0.765 on the 11 anchor wells at IoU 0.5; AJI 0.803 against 0.505
toxoplasma_pv_v4 (Cellpose-SAM (cpsam_v2))	round 6’s 556 curated fields plus 80 hand-curated fields of a new plate (Anu revision, Replication09182026 plate 1); 502 train / 123 validation / 11 test; training data at einarolafsson/toxoplasma-pv-segmentation-dataset-r7	F1 0.854 against stock cpsam_v2’s 0.765 on the 11 anchor wells at IoU 0.5; AJI 0.776 against 0.505
live_cell_v1 (Cellpose-SAM (cpsam_v2))	11,007 transmitted-light fields from 14 public datasets, split by acquisition 6,778 train / 2,030 validation / 2,199 test; training data at einarolafsson/live-cell-segmentation-dataset	on the datasets stock cpsam_v2 never trained on, F1 0.960 against 0.885 at IoU 0.5; over all 2,199 test fields, 0.694 against 0.738, because stock trained on LIVECell and YeaZ and wins on LIVECell
nuclei_from_cellmask_v1 (Cellpose-SAM (cpsam_v2))	nuclei predicted from the HOST CELL MASK channel alone; 453 well-grouped held-out fields, hosts HFF/HeLa/THP1	F1 0.888 against 0.201 for stock cpsam_v2 on 453 well-grouped held-out fields, at IoU 0.5
cell_from_hoechst_v1 (Cellpose-SAM (cpsam_v2))	the HOST CELL outline predicted from the Hoechst (nuclear) channel alone; 2,578 training fields and 451 held-out test fields, split by well so no well is on both sides	F1 0.870 against stock cpsam_v2’s 0.301 on 451 held-out fields at IoU 0.5 – a delta of 0.569
toxoplasma_from_hoechst_v1 (Cellpose-SAM (cpsam_v2))	Toxoplasma PV masks predicted from the HOECHST channel alone; 2567 training and 463 held-out fields, split by well, hosts HFF/HeLa/THP1	F1 0.569 against 0.002 for stock cpsam_v2 on 463 well-grouped held-out fields, at IoU 0.5
toxoplasma_plaque_v3 (Cellpose-SAM (cpsam, Cellpose 4.0.9))	496 curated plaque fields, including 34 reviewed empty negatives and 71 Gel Doc wells; 100 epochs; fixed physical-plate/source groups	Stock was not evaluated in this run; see the named incumbent comparison on the model card
toxoplasma_well_detector_v3 (YOLO11n (fine-tuned from detector v3))	452 reviewed training images; 124 validation images; physical plate and figure groups; 150 epochs; YOLO11n v3 initialization	Stock was not evaluated in this run; see the named incumbent comparison on the model card

Every figure above is measured on images the model never saw in training.

Precision is how many of the objects a model reported are real; recall is how many of the real objects it found. They fail in opposite directions: poor precision invents plaques, poor recall misses them.

F1 is the two combined, and is quoted because each alone is trivially gamed – report one unmistakable plaque for near-perfect precision, or every dark blob for near-perfect recall. Which you would rather lose depends on the assay, and counting is usually better served by over-calling: the plaque model was accepted at precision 0.858 with recall 0.811 over an earlier round at 0.939 and 0.631.

IoU, intersection over union, divides the overlap between predicted and reference objects by their combined area. Read scores with their threshold: “F1 0.864 at IoU 0.5” counts a vacuole as found when that overlap reaches half the combined area.

mAP50 and mAP50-95 belong to the detector. The first asks whether the wells were found; the second repeats it across ten thresholds from 0.5 to 0.95, so it also asks how tightly each box is drawn. The gap between them is placement, not detection.

Cross-validated, with an SD, means the score is the mean of three runs on different splits and the SD is how far they moved apart. One split can be lucky: this model’s literature figure is 0.834 on a single 19-well split and 0.806 across all three.

Models are hosted on each author’s own Hugging Face account; spacr.model_zoo.publish_model uploads one and prints the catalogue row to add.

Diagnosing performance

Generate a hardware report and attach it to a performance-related issue:

python tools/spacr_hardware_report.py

Saves to ~/.spacr/reports and prints the path. --quick skips the longer benchmarks; --out PATH sets the location.

Reads no project data. Times imports, numeric libraries, window construction and animation, and reports x86_64 emulation on Apple Silicon and NumPy’s BLAS.

Command-line reference

Every command below is installed by pip install spacr. All of them accept --help.

Launching the application

spacr              # the desktop application
spacr-tutorial     # the interactive tutorial library
spacr-server       # no first-run setup screen, for unattended launches

spacr-qt and spacr-nightly are aliases of spacr.

When spaCR will not start

spacr-doctor       # diagnose the installation and say how to fix it
safespacr          # the least spaCR that can still change a setting

spacr-doctor prints one line per check, with a command to run for each failure. It also reports which spacr is on the path, which is what an old editable install shadows.

safespacr reads every preference as its default and forces the backdrop, animations, verbose logging and preloading off. Use it when a saved preference breaks the launch. It changes nothing permanently.

Running modules headlessly

No Qt, no display — for clusters, servers and CI.

spacr-run --list                              # modules with a headless entry
spacr-run --describe MODULE                   # what a module consumes and produces
spacr-run validate --module MODULE \
    --settings settings.csv                   # check settings before spending the run
spacr-run MODULE --settings settings.csv      # execute
spacr-remote --help                           # submit and monitor SSH, Slurm or cloud jobs

validate reads the same settings the run would and reports what is missing, contradictory or pointing at nothing.

Inspecting a run afterwards

Every run is journalled to ~/.spacr/runs with its settings, hashed inputs, outputs, warnings, versions and seeds.

spacr-repro RUN_DIR        # replay a recorded run from its journal
spacr-workspace RUN_DIR    # what that run had open: databases, montages, views

Auditing data and installation

spacr-db-audit DB      # SQLite health, integrity, locking, reader/writer probe
spacr-leakage          # classifier train/test leakage audit
spacr-plugins          # installed plugin registry and failure diagnostics

Environment

SPACR_LOG_LEVEL=DEBUG spacr      # verbose logging for one launch

Rotating logs are written to ~/.spacr/logs/spacr.log. Attach that file to a bug report.

Contributing and support

Submit bug reports and focused feature requests through GitHub Issues. When reporting a failure, include the spaCR version, operating system, Python version, module settings and the relevant log excerpt. spacr-doctor collects most of this information; include the hardware report when reporting performance problems.

Licensing

spaCR is released under the BSD 3-Clause License.

If spaCR contributed to published work, a citation is appreciated and is not a condition of the licence — see Citing spaCR below.

Tutorials

The interactive spaCR tutorial library provides installation and module walkthroughs. Available narration and languages are listed for each lesson.

Citing spaCR

If spaCR contributes to your research, cite:

Olafsson EB, et al. A pooled image-based CRISPR screen identifies EAF1 as a T. gondii modulator of ESCRT subversion.

bioRxiv preprint · software archive

Other work citing spaCR

Acknowledgments

spaCR builds on open scientific software including NumPy, pandas, scikit-image, scikit-learn, Cellpose, PyTorch and Qt. See the translation model attribution for the models used to prepare the multilingual documentation and interface catalogs.

dev headless embeddings trackastra ultrack attribution gpu rapids intel-gpu directml boosting plaque papers umap anndata databases dinocell samcell napari full sweep qt flowview fractal tutorial czi nd2 lif zernike btrack numpyro pymc pyfixest glum gpytorch zarr omero cloud survival search foundation notify chem microscope all

Metadata

Release files for spacr 1.5.1.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for spacr 1.5.1.4
File	Size	Uploaded
spacr-1.5.1.4.tar.gz	51.9 MB	Oct 9, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for spacr 1.5.1.4
File	Interpreter	ABI	Platform	Reset
spacr-1.5.1.4-py3-none-any.whl 43.3 MB Oct 9, 2026	Python 3	none	any	Details

Total release size: 95.2 MB

Release files / spacr-1.5.1.4.tar.gz

Download URL	spacr-1.5.1.4.tar.gz
Size	51.9 MB
Tags	Source
SHA-256 checksum How to use checksums	`32113621263f931862d5ab63fb507819d2172276edb3bfdf42210bf3e7eea7bb`
BLAKE2b-256 checksum How to use checksums	`cc049e4d06dea4713bcb4f5a3396490efa3dcf199561afda3b875f1944c735c2`
Upload date	Oct 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/EinarOlafsson/spacr
Publishing commit: github.com/EinarOlafsson/spacr/tree/f89f089481a9dfbd8dc4ffaaebddb24b279f1672

Workflow

Publishing configuration: github.com/EinarOlafsson/spacr/blob/f89f089481a9dfbd8dc4ffaaebddb24b279f1672/.github/workflows/release.yml
Publishing logs: github.com/EinarOlafsson/spacr/actions/runs/37941159752/attempts/1

Artifact

Subject: spacr-1.5.1.4.tar.gz
SHA-256 checksum: 32113621263f931862d5ab63fb507819d2172276edb3bfdf42210bf3e7eea7bb Verifying attestations

Release files / spacr-1.5.1.4-py3-none-any.whl

Download URL	spacr-1.5.1.4-py3-none-any.whl
Size	43.3 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`46f40bcd3146b824646bd5eb95c88956c80aa1af01178da2913f7be392850a11`
BLAKE2b-256 checksum How to use checksums	`4e32c4773a6f63b1abe5ab3f2fec8273a9d7d98e5a00f0526e0453470dc687ad`
Upload date	Oct 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/EinarOlafsson/spacr
Publishing commit: github.com/EinarOlafsson/spacr/tree/f89f089481a9dfbd8dc4ffaaebddb24b279f1672

Workflow

Publishing configuration: github.com/EinarOlafsson/spacr/blob/f89f089481a9dfbd8dc4ffaaebddb24b279f1672/.github/workflows/release.yml
Publishing logs: github.com/EinarOlafsson/spacr/actions/runs/37941159752/attempts/1

Artifact

Subject: spacr-1.5.1.4-py3-none-any.whl
SHA-256 checksum: 46f40bcd3146b824646bd5eb95c88956c80aa1af01178da2913f7be392850a11 Verifying attestations