spacr

spaCR

Spatial phenotype analysis of CRISPR screens.

spaCR segments and measures single cells in high-content 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.

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.

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.

The first three icons download the current release. The spaCR icon opens the complete installer archive. Installer links and versioned filenames are updated by the release workflow; earlier installers remain in the same release archive.

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.

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[qt]"
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.

For a server, cluster or CI runner, omit Qt:

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

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

The default branch is nightly. 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 .

The second line is only needed when dependencies or entry points changed; Python code is picked up without it. If a command still runs old code after pulling, spacr-doctor reports which spacr is actually on your path, which is the usual cause.

Install from source (light)

Full clone: 427 MB. Core clone: 76 MB.

curl -fsSL https://raw.githubusercontent.com/EinarOlafsson/spacr/nightly/packaging/install_from_source.sh -o install_spacr.sh
sh install_spacr.sh --branch nightly

Skips docs/, tests/, Cellpose checkpoints, archived figures and the extended translation catalogs. The result is a normal checkout.

Options: --dir, --branch (default main), --with-tests, --with-docs, --with-translations, --no-install.

packaging/source_install_excludes.txt lists every skipped path.

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

Set SPACR_LOG_LEVEL=DEBUG when troubleshooting. Rotating logs are written to ~/.spacr/logs/spacr.log.

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.

Assays

Quantitative readouts for biological assays.

Every module spaCR ships, in the order the home screen lists them: the six pipeline modules first, then everything else. Select a tile to open that module’s API page.

Make Masks

Make Masks appears under Tools for manual correction of segmentation masks; its masthead opens the Cellpose workflows. Nine tools: Brush, Erase, Erase object, Wand +, Wand −, Draw, Divide, Zoom and Recrop. Draw makes one filled label from a closed outline, Divide separates a merged object along a drawn line, Recrop turns one object in a crowded field into its own field.

See the feature guide for each tool.

Other resources

Interactive tutorials — 73 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; 115 images, 1 dataset	F1 0.867 against 0.713 for stock cpsam, at IoU 0.5
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_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, mAP50-95 0.886, precision and recall both 0.987

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, is how much a predicted object and the real one overlap, divided by the area they cover together. It is the ruler the rest are read against, so a score means nothing without its threshold: “F1 0.867 at IoU 0.5” counts a vacuole as found when the two outlines agree over half their 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 their author’s own Hugging Face account, so contributing one does not mean handing write access to anyone else’s. spacr.model_zoo’s publish_model performs the upload 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. Reports processor-architecture emulation (an x86_64 Python build on Apple Silicon) and NumPy’s BLAS implementation.

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-server skips the modal setup screen, which would otherwise block an unattended job.

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.

spacr-run --list shows only modules with a headless entry point; annotation, curation and exploration are interactive and omitted.

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 contains narrated, captioned walkthroughs of installation and of each application workflow, in 73 lessons with 50 voices across eight languages.

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

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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

spacr-1.5.0.6.tar.gz (44.6 MB view details)

Uploaded Sep 10, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

spacr-1.5.0.6-py3-none-any.whl (37.5 MB view details)

Uploaded Sep 10, 2026 Python 3

File details

Details for the file spacr-1.5.0.6.tar.gz.

File metadata

Download URL: spacr-1.5.0.6.tar.gz
Upload date: Sep 10, 2026
Size: 44.6 MB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for spacr-1.5.0.6.tar.gz
Algorithm	Hash digest
SHA256	`3654060d0b729bd212430a7fda0f2ee8b7b0686f0da840389debfc3f41925b10`
MD5	`250303f3962536fb3459803b9efa7275`
BLAKE2b-256	`fc6cb06476f4a72d409d17e0eaf633805b1fa85422b4bb6629e9e42e2a6aac90`

See more details on using hashes here.

Provenance

The following attestation bundles were made for spacr-1.5.0.6.tar.gz:

Publisher: release.yml on EinarOlafsson/spacr

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: spacr-1.5.0.6.tar.gz
- Subject digest: 3654060d0b729bd212430a7fda0f2ee8b7b0686f0da840389debfc3f41925b10
- Sigstore transparency entry: 2785387072
- Sigstore integration time: Sep 10, 2026
Source repository:
- Permalink: EinarOlafsson/spacr@1b4b07611bd62236aecc306f4135500277f82582
- Branch / Tag: refs/heads/main
- Owner: https://github.com/EinarOlafsson
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@1b4b07611bd62236aecc306f4135500277f82582
- Trigger Event: workflow_dispatch