phenotypic 0.17.1

An image processing framework created for Ex-FAB NSF BioFoundry that aims to streamline the development of image processing pipelines for images analysis of phenotypes.

PhenoTypic: A Python Framework for Bio-Image Analysis

A modular image processing framework developed at the NSF Ex-FAB BioFoundry, focused on arrayed colony phenotyping on solid media.

---

Links:

Overview

PhenoTypic provides a modular toolkit designed to simplify and accelerate the development of reusable bio-image analysis pipelines. PhenoTypic provides bio-image analysis tools built-in, but has a streamlined development method to integrate new tools.

Installation

uv (recommended)

See more on installing uv

Regular Install (recommended when deploying on a cluster)

uv add phenotypic

Interactive / GUI Install (Plotly dashboards, Jupyter, Dash hub)

uv add phenotypic --extra gui

napari Desktop Viewer Install (for image.*.napari(), point picker, sweep viewer)

uv add phenotypic --extra napari

Pip

Regular Install

pip install phenotypic

Interactive / GUI Install

pip install "phenotypic[gui]"

napari Desktop Viewer Install

pip install "phenotypic[napari]"

Note: may not always be the latest version. Install from repo when latest update is needed

Manual Installation (For latest updates)

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

Dev Installation

For extending PhenoTypic.

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

GPU-Accelerated Detection (SAM2, micro-sam)

PhenoTypic ships optional deep-learning detectors backed by Meta's Segment Anything Model 2 and micro-sam.

See GPU Detection Setup for model downloads and SLURM deployment instructions.

Optional Installation

To extract metadata from raw images, PhenoTypic uses the PyExifTool module. This requires an external software called ExifTool. You can install ExifTool here: https://exiftool.org/install.html. If you don't use it, some metadata from raw files may not be able to be imported. Read more here: https://pypi.org/project/PyExifTool/#pyexiftool-dependencies

Run the CLI

Process a directory of plate images through a saved pipeline:

uv run python -m phenotypic --mode full --pipeline pipeline.json --input ./images --output ./out

Use --mode process --layer {rgb|gray|detect_mat|objmap} for an apply-only export run that writes a single image layer per input (mirroring the input tree) and skips the measurement/analysis suite — handy for previewing detection or enhanced layers.

Launch 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

Open http://localhost:8050/ in your browser. The GUI hub guide walks through the file browser, builder, run console, and results viewer.

For Open OnDemand-style proxies, pass only the browser-visible path prefix:

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.

Hyperparameter Tuning

Search an ImagePipeline's parameters to maximize a scorer with the tuning engine:

uv run python -m phenotypic.tune run spec.json -i ./plates -o ./out

Grid and random search work out of the box; the Optuna samplers (tpe/cmaes/gp/nsga2) need the tune extra. See the tuning how-to for an end-to-end walkthrough.

Module Overview

Module	Description
phenotypic.analysis	Tools for downstream analysis of the data from phenotypic in various ways such as growth modeling or statistical filtering
phenotypic.correction	Different methods to improve the data quality of an image such as rotation to improve grid finding
phenotypic.data	Sample images to experiment your workflow with
phenotypic.detect	A suite of operations to automatically detect objects in your images
phenotypic.enhance	Preprocessing tools that alter a copy of your image and can improve the results of the detection algorithms
phenotypic.grid	Modules that rely on grid and object information to function
phenotypic.measure	The various measurements PhenoTypic is capable of extracting from objects
phenotypic.detect.nn	GPU-accelerated detectors (SAM2, micro-sam) with checkpoint management — see setup guide
phenotypic.refine	Different tools to edit the detected objects such as morphology, relabeling, joining, or removing
phenotypic.prefab	Various premade image processing pipelines that are in use at ExFAB
phenotypic.tune	Hyperparameter-tuning engine: grid/random search plus Optuna samplers (behind the tune extra), pluggable scorers, robust held-out evaluation, distributed search over HPCC SLURM/Postgres, and a /tune/ GUI co-pilot

Sponsors