Metadata-Version: 2.4
Name: spacr
Version: 1.5.0.5
Summary: Spatial phenotype analysis of CRISPR screens (spaCR)
Author-email: Einar Birnir Olafsson <olafsson@med.umich.com>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/EinarOlafsson/spacr
Project-URL: Documentation, https://einarolafsson.github.io/spacr/
Project-URL: Source, https://github.com/EinarOlafsson/spacr
Project-URL: Issues, https://github.com/EinarOlafsson/spacr/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Python: !=3.14.1,<3.16,>=3.9
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: numpy<3.0,>=1.26.4
Requires-Dist: pandas<4.0,>=2.2.1
Requires-Dist: scipy<2.0,>=1.12.0
Requires-Dist: cellpose<5.0,>=4.0.7
Requires-Dist: scikit-image<0.28,>=0.22.0
Requires-Dist: scikit-learn<2.0,>=1.5.0
Requires-Dist: scikit-posthocs<0.20,>=0.10.0
Requires-Dist: trackpy<1.0,>=0.6.2
Requires-Dist: statsmodels<0.15,>=0.14.0
Requires-Dist: patsy<2.0,>=0.5.6
Requires-Dist: shap<1.0,>=0.47.0
Requires-Dist: torch<3.0,>=2.0; sys_platform != "darwin" or platform_machine != "x86_64" or python_version < "3.13"
Requires-Dist: pyfixest<1,>=0.40.1; python_version >= "3.10"
Requires-Dist: glum<4,>=3.1.2; python_version >= "3.10"
Requires-Dist: gpytorch<2,>=1.11; python_version >= "3.10"
Requires-Dist: tensorboard<3.0,>=2.21
Requires-Dist: numba<1.0,>=0.60; sys_platform != "darwin" or platform_machine != "x86_64"
Requires-Dist: llvmlite<1.0,>=0.43; sys_platform != "darwin" or platform_machine != "x86_64"
Requires-Dist: numba<0.63,>=0.60; sys_platform == "darwin" and platform_machine == "x86_64"
Requires-Dist: llvmlite<0.46,>=0.43; sys_platform == "darwin" and platform_machine == "x86_64"
Requires-Dist: torchvision<1.0,>=0.15; sys_platform != "darwin" or platform_machine != "x86_64" or python_version < "3.13"
Requires-Dist: captum<1.0,>=0.7.0
Requires-Dist: seaborn<1.0,>=0.13.2
Requires-Dist: matplotlib<4.0,>=3.8.3
Requires-Dist: matplotlib_venn<2.0,>=1.1
Requires-Dist: pypdf<7.0,>=6.16.1
Requires-Dist: cycler<1,>=0.10
Requires-Dist: PySide6<7,>=6.6
Requires-Dist: qtawesome<2,>=1.3
Requires-Dist: pyqtgraph<1,>=0.13.3
Requires-Dist: mpmath<2,>=1.3
Requires-Dist: vispy<1.0,>=0.14
Requires-Dist: win10toast>=0.9; platform_system == "Windows"
Requires-Dist: adjustText<2.0,>=1.2.0
Requires-Dist: bottleneck<2.0,>=1.3.6
Requires-Dist: numexpr<3.0,>=2.8.4
Requires-Dist: opencv-python-headless<5.0,>=4.9.0.80
Requires-Dist: pillow<13,>=10.2.0
Requires-Dist: tifffile>=2023.4.12
Requires-Dist: nd2reader<4.0,>=3.3.0
Requires-Dist: czifile
Requires-Dist: readlif
Requires-Dist: openpyxl<4.0,>=3.1
Requires-Dist: imageio<3.0,>=2.34.0
Requires-Dist: umap-learn<1.0,>=0.5.11
Requires-Dist: xgboost<4,>=2.0.3
Requires-Dist: biopython<2.0,>=1.80
Requires-Dist: lxml>=5.1.0
Requires-Dist: psutil<8,>=5.9.8
Requires-Dist: gputil<2.0,>=1.4.0
Requires-Dist: nvidia-ml-py<14,>=11.450.51
Requires-Dist: tables<4.0,>=3.8.0
Requires-Dist: screeninfo<1.0,>=0.8.1
Requires-Dist: fastremap>=1.14.1
Requires-Dist: tqdm>=4.65.0
Requires-Dist: requests<3.0,>=2.28
Requires-Dist: joblib<2.0,>=1.2
Requires-Dist: natsort<9.0,>=8.0
Requires-Dist: sympy<2.0,>=1.12
Requires-Dist: IPython<10,>=8.18.1
Requires-Dist: ipywidgets<9.0,>=8.1.2
Requires-Dist: huggingface-hub<1.0,>=0.25
Requires-Dist: protobuf>=5.28.3
Provides-Extra: dev
Requires-Dist: pytest<9,>=8.0; extra == "dev"
Requires-Dist: pytest-qt<5,>=4.4; extra == "dev"
Requires-Dist: pytest-xdist<4,>=3.6.1; extra == "dev"
Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "dev"
Requires-Dist: hypothesis<7,>=6.100; extra == "dev"
Requires-Dist: docutils<0.24,>=0.20.1; extra == "dev"
Requires-Dist: pyarrow<26,>=14.0.2; extra == "dev"
Requires-Dist: ruff<1,>=0.9; extra == "dev"
Requires-Dist: mypy<2,>=1.11; extra == "dev"
Requires-Dist: xenon<1,>=0.9; extra == "dev"
Requires-Dist: pingouin<2.0,>=0.5.5; extra == "dev"
Provides-Extra: headless
Requires-Dist: opencv-python-headless<5.0,>=4.9.0.80; extra == "headless"
Provides-Extra: trackastra
Requires-Dist: trackastra<1.0,>=0.5; (python_version >= "3.10" and (sys_platform != "darwin" or platform_machine != "x86_64" or python_version < "3.13")) and extra == "trackastra"
Provides-Extra: ultrack
Requires-Dist: ultrack<1.0,>=0.6; (python_version >= "3.10" and python_version < "3.14" and (sys_platform != "darwin" or platform_machine != "x86_64" or python_version < "3.13")) and extra == "ultrack"
Provides-Extra: attribution
Requires-Dist: torchcam<1.0,>=0.4.0; extra == "attribution"
Provides-Extra: rapids
Requires-Dist: cuml-cu12>=25.2; (python_version >= "3.11" and python_version < "3.13") and extra == "rapids"
Requires-Dist: cupy-cuda12x>=13.0; (python_version >= "3.11" and python_version < "3.13") and extra == "rapids"
Provides-Extra: intel-gpu
Requires-Dist: intel-extension-for-pytorch>=2.1; platform_system != "Darwin" and extra == "intel-gpu"
Provides-Extra: directml
Requires-Dist: torch-directml>=0.2; platform_system == "Windows" and extra == "directml"
Provides-Extra: boosting
Requires-Dist: catboost<2.0,>=1.2; extra == "boosting"
Requires-Dist: lightgbm<5.0,>=4.0; extra == "boosting"
Provides-Extra: plaque
Requires-Dist: ultralytics<9,>=8.0; extra == "plaque"
Provides-Extra: umap
Requires-Dist: umap-learn<1.0,>=0.5.11; extra == "umap"
Provides-Extra: anndata
Requires-Dist: anndata<0.13,>=0.10; extra == "anndata"
Provides-Extra: napari
Requires-Dist: napari<1.0,>=0.5; extra == "napari"
Provides-Extra: full
Requires-Dist: opencv-python; extra == "full"
Provides-Extra: sweep
Requires-Dist: threadpoolctl<4,>=3.0; extra == "sweep"
Provides-Extra: qt
Requires-Dist: PySide6<7,>=6.6; extra == "qt"
Requires-Dist: qtawesome<2,>=1.3; extra == "qt"
Requires-Dist: pyqtgraph<1,>=0.13.3; extra == "qt"
Requires-Dist: win10toast>=0.9; platform_system == "Windows" and extra == "qt"
Provides-Extra: flowview
Requires-Dist: PySide6<7,>=6.6; extra == "flowview"
Provides-Extra: fractal
Requires-Dist: vispy<1.0,>=0.14; extra == "fractal"
Provides-Extra: tutorial
Requires-Dist: PySide6<7,>=6.6; extra == "tutorial"
Requires-Dist: qtawesome<2,>=1.3; extra == "tutorial"
Requires-Dist: win10toast>=0.9; platform_system == "Windows" and extra == "tutorial"
Requires-Dist: piper-tts<2,>=1.2; (sys_platform != "darwin" or platform_machine != "x86_64" or python_version < "3.14") and extra == "tutorial"
Provides-Extra: czi
Requires-Dist: pylibCZIrw<7.0,>=5.0.0; python_version < "3.14" and extra == "czi"
Requires-Dist: czifile; extra == "czi"
Provides-Extra: nd2
Requires-Dist: nd2reader<4.0,>=3.3.0; extra == "nd2"
Provides-Extra: lif
Requires-Dist: readlif; extra == "lif"
Provides-Extra: zernike
Requires-Dist: mahotas<2.0,>=1.4.13; python_version < "3.13" and extra == "zernike"
Provides-Extra: btrack
Requires-Dist: btrack<1.0,>=0.7.0; extra == "btrack"
Provides-Extra: numpyro
Requires-Dist: numpyro<1.0,>=0.13; extra == "numpyro"
Requires-Dist: jax<1.0,>=0.4; extra == "numpyro"
Provides-Extra: pymc
Requires-Dist: pymc<6.0,>=5.10; extra == "pymc"
Provides-Extra: pyfixest
Requires-Dist: pyfixest<1,>=0.40.1; python_version >= "3.10" and extra == "pyfixest"
Provides-Extra: glum
Requires-Dist: glum<4,>=3.1.2; python_version >= "3.10" and extra == "glum"
Provides-Extra: gpytorch
Requires-Dist: gpytorch<2,>=1.11; python_version >= "3.10" and extra == "gpytorch"
Provides-Extra: zarr
Requires-Dist: zarr<4,>=2.16; extra == "zarr"
Requires-Dist: numcodecs<1,>=0.12; extra == "zarr"
Provides-Extra: omero
Requires-Dist: omero-py<6,>=5.17; extra == "omero"
Provides-Extra: all
Requires-Dist: PySide6<7,>=6.6; extra == "all"
Requires-Dist: qtawesome<2,>=1.3; extra == "all"
Requires-Dist: pyqtgraph<1,>=0.13.3; extra == "all"
Requires-Dist: vispy<1.0,>=0.14; extra == "all"
Requires-Dist: win10toast>=0.9; platform_system == "Windows" and extra == "all"
Requires-Dist: piper-tts<2,>=1.2; (sys_platform != "darwin" or platform_machine != "x86_64" or python_version < "3.14") and extra == "all"
Requires-Dist: trackastra<1.0,>=0.5; (python_version >= "3.10" and (sys_platform != "darwin" or platform_machine != "x86_64" or python_version < "3.13")) and extra == "all"
Requires-Dist: ultrack<1.0,>=0.6; (python_version >= "3.10" and python_version < "3.14" and (sys_platform != "darwin" or platform_machine != "x86_64" or python_version < "3.13")) and extra == "all"
Requires-Dist: catboost<2.0,>=1.2; extra == "all"
Requires-Dist: lightgbm<5.0,>=4.0; extra == "all"
Requires-Dist: ultralytics<9,>=8.0; extra == "all"
Requires-Dist: pylibCZIrw<7.0,>=5.0.0; python_version < "3.14" and extra == "all"
Requires-Dist: czifile; extra == "all"
Requires-Dist: nd2reader<4.0,>=3.3.0; extra == "all"
Requires-Dist: readlif; extra == "all"
Requires-Dist: mahotas<2.0,>=1.4.13; python_version < "3.13" and extra == "all"
Requires-Dist: btrack<1.0,>=0.7.0; extra == "all"
Requires-Dist: anndata<0.13,>=0.10; extra == "all"
Dynamic: description
Dynamic: description-content-type
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: summary

|Docs| |Tutorials| |PyPI| |Conda| |Python| |Tests| |Qt| |Source| |Issues| |License| |Preprint| |DOI|

.. |Docs| image:: https://github.com/EinarOlafsson/spacr/actions/workflows/pages/pages-build-deployment/badge.svg
   :target: https://einarolafsson.github.io/spacr/
   :alt: Documentation
.. |Tutorials| image:: https://img.shields.io/badge/Tutorials-Interactive%20walkthrough-4A9EFF
   :target: https://einarolafsson.github.io/spacr/tutorials/
   :alt: Interactive tutorials
.. |PyPI| image:: https://img.shields.io/pypi/v/spacr
   :target: https://pypi.org/project/spacr/
   :alt: PyPI version
.. |Python| image:: https://img.shields.io/badge/Python-3.9%E2%80%933.14-3776AB?logo=python&logoColor=white
   :target: https://pypi.org/project/spacr/
   :alt: Python 3.9 through 3.14
.. |Tests| image:: https://github.com/EinarOlafsson/spacr/actions/workflows/tests.yml/badge.svg?branch=nightly
   :target: https://github.com/EinarOlafsson/spacr/actions/workflows/tests.yml
   :alt: Test suite
.. |Qt| image:: https://img.shields.io/badge/GUI-Qt%20%28PySide6%29-41CD52
   :target: https://einarolafsson.github.io/spacr/
   :alt: Qt interface
.. |Source| image:: https://img.shields.io/badge/GitHub-Source-181717?logo=github
   :target: https://github.com/EinarOlafsson/spacr
   :alt: GitHub source
.. |Issues| image:: https://img.shields.io/github/issues/EinarOlafsson/spacr
   :target: https://github.com/EinarOlafsson/spacr/issues
   :alt: GitHub issues
.. |License| image:: https://img.shields.io/github/license/EinarOlafsson/spacr
   :target: https://github.com/EinarOlafsson/spacr/blob/main/LICENSE
   :alt: BSD 3-Clause license
.. |Preprint| image:: https://img.shields.io/badge/bioRxiv-2026.07.08.737057-BF2636
   :target: https://www.biorxiv.org/content/10.64898/2026.07.08.737057v1
   :alt: bioRxiv preprint
.. |DOI| image:: https://img.shields.io/badge/DOI-10.5281%2Fzenodo.21343316-blue
   :target: https://doi.org/10.5281/zenodo.21343316
   :alt: Zenodo DOI
.. |Release| image:: https://img.shields.io/github/v/release/EinarOlafsson/spacr?label=Installers
   :target: https://github.com/EinarOlafsson/spacr/releases/latest
   :alt: Latest installers
.. |Conda| image:: https://anaconda.org/conda-forge/spacr/badges/version.svg
   :target: https://anaconda.org/conda-forge/spacr
   :alt: conda-forge version

.. image:: spacr/resources/icons/logo_spacr_readme.png
   :alt: spaCR
   :width: 920

spaCR
=====

.. spacr-language-picker-begin

Languages: `🌐 English ▾ <docs/i18n/readme/README.md>`_

.. spacr-language-picker-end

**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
~~~~~~~~~~~~~~~~

.. spacr-hardware-begin

.. list-table::
   :header-rows: 1
   :widths: 32 18 18 22

   * - 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

.. spacr-hardware-end


Install spaCR
-------------

Desktop application
~~~~~~~~~~~~~~~~~~~

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

.. spacr-installer-links-begin

|InstallerLinux| |InstallerMacOS| |InstallerWindows| |InstallerLegacy|

.. |InstallerWindows| image:: spacr/resources/icons/platforms/windows.png
   :width: 64
   :alt: Download spaCR 1.5.0.4 for Windows 10/11
   :target: https://github.com/EinarOlafsson/spacr/releases/download/v1.5.0.4/SpaCR-1.5.0.4-Windows-Online-Setup.exe
.. |InstallerMacOS| image:: spacr/resources/icons/platforms/macos.png
   :width: 64
   :alt: Download spaCR 1.5.0.4 for macOS 11+ (Intel and Apple silicon)
   :target: https://github.com/EinarOlafsson/spacr/releases/download/v1.5.0.4/SpaCR-1.5.0.4-macOS-Universal-Online.pkg
.. |InstallerLinux| image:: spacr/resources/icons/platforms/linux.png
   :width: 64
   :alt: Download spaCR 1.5.0.4 for 64-bit Linux
   :target: https://github.com/EinarOlafsson/spacr/releases/download/v1.5.0.4/SpaCR-1.5.0.4-Linux-x86_64-Online.run
.. |InstallerLegacy| image:: spacr/resources/icons/platforms/legacy.png
   :width: 64
   :alt: Earlier spaCR installers
   :target: docs/source/installers.rst

.. spacr-installer-links-end

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:

.. code-block:: bash

   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 <docs/source/installer_guide.rst>`_ 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:

.. code-block:: bash

   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:

.. code-block:: bash

   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
<docs/source/installer_guide.rst>`_ 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:

.. code-block:: bash

   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
~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   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
-------------

.. spacr-workflow-begin

Core
^^^^

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

| |Module_mask|\ |Module_measure|\ |Module_annotate|\ |Module_classify_merged|\ |Module_map_barcodes|\ |Module_regression|

Data
^^^^

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

| |Module_foreign|\ |Module_run_compare|\ |Module_experiment_design|\ |Module_power|\ |Module_dose_response|\ |Module_qc_dashboard|

Tools
^^^^^

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

| |Module_make_masks|\ |Module_align|\ |Module_umap|\ |Module_gate_editor|\ |Module_graph_builder|

Assays
^^^^^^

Quantitative readouts for biological assays.

| |Module_analyze_plaques|\ |Module_recruitment|\ |Module_invasion|\ |Module_replication|

.. |Module_mask| image:: spacr/resources/icons/workflow/mask.png
   :width: 16.0%
   :alt: Open the Mask API
   :target: https://einarolafsson.github.io/spacr/api/spacr/core/index.html#spacr.core.preprocess_generate_masks
   :align: middle
.. |Module_measure| image:: spacr/resources/icons/workflow/measure.png
   :width: 16.0%
   :alt: Open the Measure API
   :target: https://einarolafsson.github.io/spacr/api/spacr/measure/index.html
   :align: middle
.. |Module_annotate| image:: spacr/resources/icons/workflow/annotate.png
   :width: 16.0%
   :alt: Open the Annotate API
   :target: https://einarolafsson.github.io/spacr/api/spacr/qt/screens/annotate/index.html
   :align: middle
.. |Module_classify_merged| image:: spacr/resources/icons/workflow/classify_merged.png
   :width: 16.0%
   :alt: Open the Classify API
   :target: https://einarolafsson.github.io/spacr/api/spacr/classify/index.html
   :align: middle
.. |Module_map_barcodes| image:: spacr/resources/icons/workflow/map_barcodes.png
   :width: 16.0%
   :alt: Open the Map Barcodes API
   :target: https://einarolafsson.github.io/spacr/api/spacr/sequencing/index.html
   :align: middle
.. |Module_regression| image:: spacr/resources/icons/workflow/regression.png
   :width: 16.0%
   :alt: Open the Regression API
   :target: https://einarolafsson.github.io/spacr/api/spacr/ml/index.html
   :align: middle
.. |Module_foreign| image:: spacr/resources/icons/workflow/apps/foreign.png
   :width: 16.0%
   :alt: Open the Import API
   :target: https://einarolafsson.github.io/spacr/api/spacr/foreign/index.html
   :align: middle
.. |Module_run_compare| image:: spacr/resources/icons/workflow/apps/run_compare.png
   :width: 16.0%
   :alt: Open the Run Compare API
   :target: https://einarolafsson.github.io/spacr/api/spacr/qt/screens/run_compare/index.html
   :align: middle
.. |Module_experiment_design| image:: spacr/resources/icons/workflow/apps/experiment_design.png
   :width: 16.0%
   :alt: Open the Experiment Design API
   :target: https://einarolafsson.github.io/spacr/api/spacr/qt/screens/experiment_design/index.html
   :align: middle
.. |Module_power| image:: spacr/resources/icons/workflow/apps/power.png
   :width: 16.0%
   :alt: Open the Power / Design API
   :target: https://einarolafsson.github.io/spacr/api/spacr/qt/screens/power/index.html
   :align: middle
.. |Module_dose_response| image:: spacr/resources/icons/workflow/apps/dose_response.png
   :width: 16.0%
   :alt: Open the Dose–Response API
   :target: https://einarolafsson.github.io/spacr/api/spacr/qt/screens/dose_response/index.html
   :align: middle
.. |Module_qc_dashboard| image:: spacr/resources/icons/workflow/apps/qc_dashboard.png
   :width: 16.0%
   :alt: Open the QC API
   :target: https://einarolafsson.github.io/spacr/api/spacr/qt/screens/qc_dashboard/index.html
   :align: middle
.. |Module_make_masks| image:: spacr/resources/icons/workflow/apps/make_masks.png
   :width: 16.0%
   :alt: Open the Make Masks API
   :target: https://einarolafsson.github.io/spacr/api/spacr/qt/screens/make_masks/index.html
   :align: middle
.. |Module_align| image:: spacr/resources/icons/workflow/apps/align.png
   :width: 16.0%
   :alt: Open the Align & Stitch API
   :target: https://einarolafsson.github.io/spacr/api/spacr/align/index.html
   :align: middle
.. |Module_umap| image:: spacr/resources/icons/workflow/apps/umap.png
   :width: 16.0%
   :alt: Open the Image UMAP API
   :target: https://einarolafsson.github.io/spacr/api/spacr/core/index.html#spacr.core.generate_image_umap
   :align: middle
.. |Module_gate_editor| image:: spacr/resources/icons/workflow/apps/gate_editor.png
   :width: 16.0%
   :alt: Open the Gate Editor API
   :target: https://einarolafsson.github.io/spacr/api/spacr/qt/screens/gate_editor/index.html
   :align: middle
.. |Module_graph_builder| image:: spacr/resources/icons/workflow/apps/graph_builder.png
   :width: 16.0%
   :alt: Open the Graph Builder API
   :target: https://einarolafsson.github.io/spacr/api/spacr/qt/screens/graph_builder/index.html
   :align: middle
.. |Module_analyze_plaques| image:: spacr/resources/icons/workflow/apps/analyze_plaques.png
   :width: 16.0%
   :alt: Open the Plaque Assay API
   :target: https://einarolafsson.github.io/spacr/api/spacr/submodules/index.html#spacr.submodules.analyze_plaques
   :align: middle
.. |Module_recruitment| image:: spacr/resources/icons/workflow/apps/recruitment.png
   :width: 16.0%
   :alt: Open the Recruitment API
   :target: https://einarolafsson.github.io/spacr/api/spacr/submodules/index.html#spacr.submodules.analyze_recruitment
   :align: middle
.. |Module_invasion| image:: spacr/resources/icons/workflow/apps/invasion.png
   :width: 16.0%
   :alt: Open the Invasion Assay API
   :target: https://einarolafsson.github.io/spacr/api/spacr/submodules/index.html#spacr.submodules.analyze_invasion
   :align: middle
.. |Module_replication| image:: spacr/resources/icons/workflow/apps/replication.png
   :width: 16.0%
   :alt: Open the Replication Assay API
   :target: https://einarolafsson.github.io/spacr/api/spacr/submodules/index.html#spacr.submodules.analyze_replication
   :align: middle

.. spacr-workflow-end

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 <docs/source/features.rst>`_ for each tool.

Other resources
~~~~~~~~~~~~~~~

- `Interactive tutorials <https://einarolafsson.github.io/spacr/tutorials/>`_
  — 73 guided workflows from installation through hit investigation.
- `Python API quickstart <docs/source/python_api.rst>`_ — run and validate
  pipelines from scripts, notebooks or a cluster.
- `Feature guide <docs/source/features.rst>`_ — capabilities, maturity and
  optional integrations.
- `Curated API reference
  <https://einarolafsson.github.io/spacr/api/index.html>`_ — supported entry
  points by task, with the complete module reference one level deeper.
- `Language & translation guide <docs/source/localization.rst>`_ — 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 <docs/source/localization.rst#contextual-help>`_.

The nine non-English catalogs are machine-drafted and technically reviewed
rather than read end to end by a native speaker. The
`review scope <docs/i18n/REVIEW_SCOPE_2026-09-04.md>`_ 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
<https://einarolafsson.github.io/spacr/setting_animations.html>`_ or the
`Setting animation registry
<https://einarolafsson.github.io/spacr/api/spacr/setting_animations/index.html>`_.

Data
----

Reference datasets
~~~~~~~~~~~~~~~~~~

|DataBioStudies| |DataHuggingFace| |DataNCBI| |DataSpaCRPower| |DataBioRxiv|

.. |DataBioStudies| image:: spacr/resources/icons/databanks/biostudies_button.png
   :width: 72
   :alt: Open the BioStudies microscopy dataset
   :target: https://doi.org/10.6019/S-BIAD2135
.. |DataHuggingFace| image:: spacr/resources/icons/databanks/huggingface_button.png
   :width: 72
   :alt: Open the Hugging Face testing dataset
   :target: https://huggingface.co/datasets/einarolafsson/toxo_mito
.. |DataNCBI| image:: spacr/resources/icons/databanks/ncbi_button.png
   :width: 72
   :alt: Open the NCBI sequencing dataset
   :target: https://www.ncbi.nlm.nih.gov/bioproject/?term=PRJNA1261935
.. |DataSpaCRPower| image:: spacr/resources/icons/databanks/spacrpower_button.png
   :width: 72
   :alt: Open spaCRPower
   :target: https://github.com/maomlab/spaCRPower
.. |DataBioRxiv| image:: spacr/resources/icons/databanks/biorxiv_button.png
   :width: 72
   :alt: Open the bioRxiv preprint
   :target: https://www.biorxiv.org/content/10.64898/2026.07.08.737057v1

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.

.. spacr-model-zoo-begin

.. list-table::
   :header-rows: 1
   :widths: 24 34 42

   * - 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

.. spacr-model-zoo-end

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
~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   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
~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   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.

.. code-block:: bash

   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.

.. code-block:: bash

   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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   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
~~~~~~~~~~~

.. code-block:: bash

   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 <https://github.com/EinarOlafsson/spacr/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
<https://github.com/EinarOlafsson/spacr/blob/main/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
<https://einarolafsson.github.io/spacr/tutorials/>`_ contains narrated,
captioned walkthroughs of installation and of each application workflow, in
73 lessons with 50 voices across eight languages.

Contributing and support
------------------------

Bug reports and focused feature requests are welcome through
`GitHub Issues <https://github.com/EinarOlafsson/spacr/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 that for you.

Licensing
~~~~~~~~~

spaCR is released under the `BSD 3-Clause License
<https://github.com/EinarOlafsson/spacr/blob/main/LICENSE>`_. Released
versions through spaCR 1.4.9.9 remain available under the MIT License that
accompanied those releases, and the PolyForm Noncommercial License that
briefly applied between them has been withdrawn in favour of BSD 3-Clause.

Tutorials
~~~~~~~~~

The `interactive spaCR tutorial library
<https://einarolafsson.github.io/spacr/tutorials/>`_ contains narrated,
captioned walkthroughs of installation and of each application workflow, in
69 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 <https://www.biorxiv.org/content/10.64898/2026.07.08.737057v1>`_ ·
`software archive <https://doi.org/10.5281/zenodo.21343316>`_

Acknowledgments
~~~~~~~~~~~~~~~

spaCR builds on open scientific software including NumPy, pandas,
scikit-image, scikit-learn, Cellpose, PyTorch and Qt. See the
`translation model attribution <docs/i18n/TRANSLATION_MODELS.md>`_ for the
models used to prepare the multilingual documentation and interface catalogs.
