Skip to main content
Phenotypic Logo

PhenoTypic: A Python Framework for Bio-Image Analysis

Development Stage GUI checks Docs PyPI Python License GitHub release Pull requests Zenodo DOI

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


docs

exfab

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

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

CPU compatibility (polars build)

PhenoTypic installs the polars-lts-cpu build by default so it runs on older CPUs (e.g. pre-AVX2 HPCC nodes) without crashing. On AVX2-capable machines you can swap in the faster stock polars build for quicker measurement compilation — see Choosing the polars CPU build.

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 third-party tools

libvips (faster GUI deep-zoom preparation)

On macOS and Windows, the [gui] extra installs the official pyvips[binary] distribution, including a self-contained native libvips. No Homebrew install or loader-path configuration is needed for the normal GUI installation.

Linux and HPC installations keep the smaller pyvips binding and may provide native libvips through the operating system or an environment module:

# Debian or Ubuntu
sudo apt install libvips-dev --no-install-recommends

Verify that Python can load the native library from the same shell that will launch the GUI:

uv run python -c "import pyvips; print('pyvips', pyvips.__version__, 'libvips', '.'.join(str(pyvips.version(i)) for i in range(3)))"

The bundled build contains the common image loaders needed by the GUI but omits optional facilities such as PDF and OpenSlide. Users who intentionally prefer a fuller Homebrew libvips can install it with brew install vips. If vips --version then works but Python cannot find libvips.42.dylib, expose Homebrew's library directory before launching PhenoTypic:

export DYLD_FALLBACK_LIBRARY_PATH="$(brew --prefix vips)/lib${DYLD_FALLBACK_LIBRARY_PATH:+:$DYLD_FALLBACK_LIBRARY_PATH}"

If native libvips or its loader is unavailable on any platform, PhenoTypic automatically retains the Pillow fallback. Browse still works, but preparing large pyramids can be slower and use more memory.

ExifTool (RAW metadata)

To extract metadata from raw images, PhenoTypic uses the PyExifTool module. This requires the external ExifTool application. If it is unavailable, some RAW metadata may not be imported. See the PyExifTool dependency documentation.

Chrome or Chromium (PNG export of Plotly figures)

Plotly figures are rasterised by Kaleido, which drives a Chrome or Chromium browser. The browser is not installed by uv sync. Without it:

  • Pipeline plots (ImagePipeline(plots=[...])) still publish: Plotly plots write interactive .html pages and skip the .png. Matplotlib plots are unaffected. CLI validation logs one warning naming the affected plots before the run starts.
  • The results viewer's Scatter-tab PDF export reports the missing browser beside its button instead of exporting.

Install a browser Kaleido can use:

uv run plotly_get_chrome

or point the BROWSER_PATH environment variable at a Chrome/Chromium binary you already have. See Custom pipeline plot for what each backend publishes.

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. Start it with the phenotypic-gui console script:

uv run 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 /path/to/your/images --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.

Hyperparameter Tuning

Search an ImagePipeline's parameters to minimize a scorer-defined cost with the tuning engine:

uv run 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, a shared-journal SLURM worker array with terminal publication, and a /tune/ GUI co-pilot

Sponsors

Phenotypic Logo

Metadata

Release files for phenotypic 0.21.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for phenotypic 0.21.0
File Size Uploaded Provenance Actions
phenotypic-0.21.0.tar.gz 12.8 MB Without provenance Details for phenotypic-0.21.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for phenotypic 0.21.0
File Interpreter ABI Platform Actions
phenotypic-0.21.0-py3-none-any.whl Python 3 none any Details for phenotypic-0.21.0-py3-none-any.whl

Total release size: 26.2 MB

Release files / phenotypic-0.21.0.tar.gz

Download URL phenotypic-0.21.0.tar.gz
Size 12.8 MB
Tags Source
SHA-256 checksum
How to use checksums
cc3de90005ddb3f226f8611b21dfde5926d6ab37d69b3b7817caf2aff6421ac6
BLAKE2b-256 checksum
How to use checksums
a286a5723d8bf395f0a8d62570a69ddb862f39e16af92022cbf3f1d5e258a772
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.18

Release files / phenotypic-0.21.0-py3-none-any.whl

Download URL phenotypic-0.21.0-py3-none-any.whl
Size 13.4 MB
Tags Python 3
SHA-256 checksum
How to use checksums
fbad271c9e5196ebdf6170a260bc0080d7f0abde1918ff45a6caf7c2c1bb4331
BLAKE2b-256 checksum
How to use checksums
d222fd1414eb2a8b60893a45ba89e1228d5c668c368a7786380f932a23713e97
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.18

Security for phenotypic 0.21.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.21.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page