Getting Started#

Prerequisites#

Before installing Phenotypic, ensure you have the following prerequisites:

Python 3.10 or higher
pip (Python package installer)
uv (recommended; see https://docs.astral.sh/uv/)

Installation Methods#

From PyPi#

Using uv (recommended)#

uv add phenotypic

Using pip#

pip install phenotypic

From Source#

To install from source:

git clone https://github.com/exfab/PhenoTypic.git
cd PhenoTypic && uv sync

Optional Extras#

PhenoTypic provides optional extras for different use cases:

[gui] — Browser-based GUI hub: Plotly dashboards, Dash apps, and Jupyter integration. Does not include napari.
[napari] — The interactive napari desktop viewers (pulls napari + PyQt6). Required for image.rgb.napari() and related viewer methods, the point picker, and the napari sweep viewer (python -m phenotypic.gui.sweep).
[torch] — PyTorch + SAM2 for Sam2Detector (Linux/macOS only).

# Browser GUI hub (Plotly, Dash, Jupyter)
uv add "phenotypic[gui]"

# napari desktop viewers
uv add "phenotypic[napari]"

# SAM2 GPU detector (Linux/macOS)
uv add "phenotypic[torch]"

micro_sam (used by MicroSamDetector) is only published on conda-forge and is not included in any PhenoTypic extra. See Deep Learning Detectors below for a self-service recipe that combines PhenoTypic and micro_sam in a single pixi environment.

Deep Learning Detectors#

PhenoTypic ships several deep-learning colony detectors — Sam2Detector, Sam3Detector, DinoSam2Detector, Insid3Detector, FssDinoDetector, and the conda-only MicroSamDetector. This section covers installing the detector packages and pre-downloading their model weights. For detector usage, parameter tuning, device selection, and SLURM staging, see the GPU Detection Setup how-to guide.

Installing the detector packages#

The PyPI-published detectors are grouped into optional extras:

Extra	Detectors	Notes
`[torch]`	`Sam2Detector`	PyTorch + `sam2` from PyPI. Linux/macOS only — no Windows wheels (use WSL2).
`[foundation]`	`Sam3Detector`, `DinoSam2Detector`, `Insid3Detector`, `FssDinoDetector`	`transformers` (>=5.2.0) + `huggingface_hub` (pulls `torch`).
`[gpu]`	all of the above	Umbrella extra — every GPU detector at once (recommended for a dev env).

# SAM2 only
uv add "phenotypic[torch]"

# SAM3 + DINO-based foundation detectors
uv add "phenotypic[foundation]"

# Everything, inside a uv-managed checkout
uv sync --extra gpu

MicroSamDetector depends on micro_sam, which is published only on conda-forge and so is not part of any PhenoTypic extra. Manage the combined stack yourself — for example with pixi, which resolves conda-forge and PyPI in one lockfile, or with conda:

pip install phenotypic                   # or phenotypic[torch] on non-Windows
conda install -c conda-forge micro_sam   # adds MicroSamDetector

Model weights and licenses#

PhenoTypic does not redistribute model weights — each is downloaded from its upstream source under that model’s license. Most weights are ungated (SAM2, DINOv2), but SAM3 and DINOv3 weights are gated and need a one-time license handshake on the Hugging Face Hub:

Create a Hugging Face account.
Accept the gate on the model page (this is the license acceptance): SAM3 → https://huggingface.co/facebook/sam3, DINOv3 → https://huggingface.co/facebook/dinov3-vitb16-pretrain-lvd1689m.
Authenticate locally once: uv run hf auth login (or export HF_TOKEN).

Downloading and caching checkpoints#

Every detector downloads its weights automatically on first use, but you can pre-download them with the phenotypic.detect.nn CLI — essential on SLURM clusters whose compute nodes have no internet access:

# SAM2 (default tiny; --all for every size)
uv run python -m phenotypic.detect.nn download --model-type sam2 --model-size tiny

# micro-sam
uv run python -m phenotypic.detect.nn download --model-type microsam --model-name vit_b_lm

# Gated foundation weights — --accept-license acknowledges the model license
uv run python -m phenotypic.detect.nn download --model-type sam3 --accept-license
uv run python -m phenotypic.detect.nn download --model-type dinov3 --dino-size base --accept-license

# Ungated DINOv2 (no token needed)
uv run python -m phenotypic.detect.nn download --model-type dinov2 --dino-size base

# Inspect or clear the cache
uv run python -m phenotypic.detect.nn list
uv run python -m phenotypic.detect.nn clear --model-type sam2

Cache locations are controlled by environment variables — point them at shared storage so SLURM compute nodes can read pre-staged weights:

Variable	Controls
`TORCH_HOME`	SAM2 checkpoint cache (default `~/.cache/torch/hub/checkpoints/`).
`MICROSAM_CACHEDIR`	micro-sam checkpoint cache.
`HF_HOME` / `HF_HUB_CACHE`	Hugging Face cache for SAM3 + DINO weights.
`HF_HUB_OFFLINE=1` / `TRANSFORMERS_OFFLINE=1`	Force load-from-cache on offline compute nodes.
`HF_TOKEN` / `HUGGING_FACE_HUB_TOKEN`	Auth for gated downloads (alternative to `hf auth login`).
`PHENOTYPIC_ACCEPT_MODEL_LICENSE`	Non-interactive license acknowledgement for batch/SLURM jobs (e.g. `sam3,dinov3`).

Note

On a cluster, accept the gates and pre-stage weights on the login node (which has internet), then run the compute job offline with the same HF_HOME plus HF_HUB_OFFLINE=1 and PHENOTYPIC_ACCEPT_MODEL_LICENSE. Acceptance never happens silently inside a batch job. See the GPU Detection Setup guide for the full SLURM staging workflow.

Development Installation#

For development of new modules, sync with the dev (and optionally docs) dependency groups:

git clone https://github.com/exfab/PhenoTypic.git
cd PhenoTypic
uv sync --group dev --group docs

Verification#

To verify the installation, run:

import phenotypic
print(phenotypic.__version__)

Launching the GUI#

The unified GUI hub bundles the pipeline builder, results viewer, and run console under one URL. Two equivalent entry points:

# Console script (preferred)
uv run phenotypic-gui --root ./images --port 8050

# Module entry (works in environments without the console script on PATH)
uv run python -m phenotypic.gui --root ./images --port 8050

--root freezes the sandbox the GUI’s file browser is allowed to see (defaults to the current working directory). --host 127.0.0.1 (the default) keeps the server loopback-only — pair with SSH port forwarding for remote workstations:

ssh -L 8050:localhost:8050 user@cluster

Then open http://localhost:8050/ in your browser. If you launch the GUI from inside a Slurm allocation (srun/salloc), the server binds to the compute node rather than the login node, and the single-hop tunnel above will return connect failed: Connection refused. See Running the GUI on a Slurm compute node in the GUI hub guide for the two-hop tunnel pattern. That guide also covers the file browser, pipeline builder, run console, and results viewer.

For Open OnDemand-style proxies, pass the browser path as a prefix, not the full URL:

uv run phenotypic-gui --root /rhome/ejaco020 --host 0.0.0.0 --port 30099 --url-prefix /node/hz01/30099/

Then open the full proxy URL, for example https://ondemand.hpcc.ucr.edu/node/hz01/30099/.