PyPhenix

A data loader and widget to visualize high-dimensional data collected on the Opera Phenix

This napari plugin was generated with copier using the napari-plugin-template (None).

Installation

Using napari's graphical plugin manager

Users can entirely avoid using a command prompt by using the package manager built in to the bundled napari app.

Follow the installation instructions to download and install the correct version of the bundled napari app for your operating systems (MacOS, Windows, or Linux).

Then following the instructions for installing plugins, search for PyPhenix in the Plugin Manager search bar and click "Install".

Using Python package installer (pip)

Reader only (no GUI, no napari required)

If you only need the OperaPhenixReader — for example on a server or in a headless analysis pipeline — install the base package:

pip install pyphenix

This installs only numpy and Pillow. napari, Qt, and pandas are not required and will not be installed.

from pyphenix import OperaPhenixReader

reader = OperaPhenixReader("/path/to/experiment")
data, metadata = reader.read_data(row="D", column=4)

Plate overview images (no napari required)

generate_plate_overview() produces one diagnostic PNG per channel combo (plus a JSON provenance sidecar) showing a downsampled thumbnail of every well in the plate. Plate-wide contrast is computed once per channel so wells are visually comparable.

from pyphenix import generate_plate_overview

generate_plate_overview(
    experiment_path="/path/to/experiment",
    output_dir="/path/to/overviews",
    # Optional overrides — all have sensible defaults:
    field=None,        # 'stitched', an int field index, or None (first field)
    channels=None,     # subset of channel IDs, or None (all acquired)
    timepoint=None,    # int, or None (first timepoint)
    z_slices=None,     # int / list / None (all Z planes, max-projected)
    well_px=300,       # per-well render size on the longest side
    apply_ffc=True,
)

For N selected channels the call writes 2**N − 1 PNGs (singletons + every merge subset) and a single *_overview.json sidecar capturing the input parameters, plate-wide contrast limits, channel→colormap assignments, and pyphenix version.

Full GUI install (napari widget)

To use the interactive napari widget, install with the napari extra:

pip install "pyphenix[napari]"

This additionally installs napari, qtpy, and pandas.

from pyphenix import launch_viewer

viewer, widget = launch_viewer("/path/to/experiment")

Alternatively, if napari is already installed in your environment, the base install is sufficient — pyphenix will detect napari at import time and make the widget available automatically:

pip install pyphenix

Latest development version

pip install git+https://github.com/ferrinm/pyphenix.git

Public API

The following names are part of pyphenix's stable public surface — signatures and return semantics will not shift between minor versions.

Top-level (from pyphenix import …):

• OperaPhenixReader — the reader class.
• FFCProfile — flat-field correction profile container. Stable members: has_correction(), generate_correction_image((Y, X)), channel_id, character, mean, quality, profile_type.
• FFCCoverageWarning — emitted on partial FFC coverage (also importable from pyphenix.errors).
• generate_plate_overview() — plate overview PNG generator.
• launch_viewer(), napari_get_reader() — napari entry points.

OperaPhenixReader methods that are part of the stable surface:

• apply_ffc(data, channel_ids, apply=True, verbose=True, *, dtype="float32" | "uint16") — apply flat-field correction to a (T, C, Z, Y, X) array. Returns float32 by default; dtype="uint16" re-scales each channel by profile.mean then clips/rounds/casts to uint16.
• ffc_correction_images(shape=None, channel_ids=None) -> dict[int, np.ndarray] — return per-channel illumination tiles (float32, shape (Y, X)) for chunk-wise FFC. Channels without a real profile are omitted from the dict. Defaults: shape = metadata.image_size, channel_ids = metadata.channel_ids.
• ffc_profiles: dict[int, FFCProfile] — per-channel correction profiles loaded from the FFC XML (empty dict if no FFC data is present).

Both apply_ffc and ffc_correction_images emit FFCCoverageWarning once per call when at least one requested channel lacks a real profile and ffc_profiles is non-empty.

Contributing

Contributions are very welcome. Tests can be run with tox, please ensure the coverage at least stays the same before you submit a pull request.

License

Distributed under the terms of the GNU GPL v3.0 license, "pyphenix" is free and open source software

Issues

If you encounter any problems, please file an issue along with a detailed description.