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 the GPU Detection Setup guide for a self-service recipe that combines PhenoTypic and micro_sam in a single pixi environment.

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

Note

phenotypic gui (no hyphen, as a subcommand) is not supported. Use phenotypic-gui or python -m phenotypic.gui. The existing phenotypic CLI is reserved for batch pipeline execution with explicit path options, not subcommands.