Opera Phenix plates

Find Nuclei Viewer opens plates exported by Harmony from an Opera Phenix, straight from their index. Nothing is converted and nothing is uploaded. The Opera Phenix plates of the Cell Painting Gallery open this way, such as the JUMP Cell Painting pilot plate CPJUMP1. Opera Phenix Plates in the Browser tells the story on our blog.

Plates from a Yokogawa CellVoyager open too: see Yokogawa CellVoyager Plates. Other formats the viewer opens are listed in Supported Formats.

What opens

A Harmony export is an index file next to one TIFF per field, plane, timepoint and channel. The viewer reads the index and loads the TIFFs as you look at them. Both index formats open:

• Harmony V5: Index.idx.xml.
• Harmony V6: Index.xml, the current Harmony export. V6 keeps the channel details, such as names, image size and wavelengths, in a <Maps> section near the top of the index. The viewer reads them from there.

The files can sit at any web address that lets the browser read them, such as a public S3 bucket, or in a folder on your disk.

Opening a plate from the web

Open the Open dialog, choose From URL and paste one of these:

• the folder that holds the plate (the measurement folder),
• the folder that holds the index (often Images/),
• or the address of Index.idx.xml or Index.xml itself.

Given a folder, the viewer looks for Index.idx.xml first, then Index.xml.

An https:// address and an s3:// address both work. Here is a JUMP Cell Painting plate in both forms:

https://cellpainting-gallery.s3.amazonaws.com/cpg0000-jump-pilot/source_4/images/2020_11_04_CPJUMP1/images/BR00116991__2020-11-05T19_51_35-Measurement1/

s3://cellpainting-gallery/cpg0000-jump-pilot/source_4/images/2020_11_04_CPJUMP1/images/BR00116991__2020-11-05T19_51_35-Measurement1/

A Harmony V6 measurement opens the same way. Here is one from the Cell Painting Gallery's cpg0002-jump-scope:

s3://cellpainting-gallery/cpg0002-jump-scope/source_4/images/2020_11_16_Scope1_PE/images/CPBroadPhenixC1PlaneP1__C_BIN2_1P_2020-11-09T10_37_04-Measurement1/

Two V6 measurements are in the Example Gallery under Cell Painting Gallery.

The viewer looks in the folder you give it and its Images/ folder, not deeper. Some measurements sit inside a grouping folder. Open the measurement folder itself.

A bucket name with a dot in it works as s3:// in us-east-1. In any other region, paste its regional https address instead: https://s3.<region>.amazonaws.com/<bucket>/....

Opening a plate from disk

Open the Open dialog, go to Local Files and click Choose Data Folder. Pick the measurement folder or the folder that holds the index, whatever its name. Nothing leaves your computer.

Folders open in Chrome and Edge, as for any dataset folder. Safari and Firefox cannot open folders. See Local Files for the details.

What to expect

The plate opens as soon as the viewer has read the start of the index, about 1 MB. The whole index can be tens of megabytes. A progress line counts the megabytes while it reads.

The second time, the plate opens at once. The viewer keeps what it learned in the browser's storage. Clear All Data on the start screen removes it.

The viewer reads only the start of the index. If an image is missing or cannot be read, that channel is left out of that field and the other channels still show.

When every channel of a field is missing, the canvas says so instead of showing black. From the web it reads "Images for B/3, field 0 could not be loaded." From disk it reads "No images for B/3, field 0 in this folder."

Moving through the plate

The plate opens in field view on the first well that holds images. The panel is titled with the plate name from the index, such as BR00116991. The well navigator steps through the wells that are present, and the well picker below it jumps to any of them. Wells with no images are skipped.

Opened from disk, the viewer also checks which images the folder holds. A well the index lists with no images in the folder is grey in the well picker, with the tooltip "No images in this folder". Its fields read "(no images)" in the field dropdown.

When the plate has several fields, Z planes or timepoints, the field dropdown and the Z and T sliders move between them. The HCS Plates guide covers the navigator and picker.

Why there is no plate or well view

Fast overviews come from a resolution pyramid. OME-Zarr stores each image several times: at full resolution, then at half, a quarter, and smaller, each cut into small tiles. A plate overview reads only the small levels, a tiny part of the data, and zooming in fetches the detail tiles just for what is on screen.

A Harmony export has no pyramid. Each field and channel is one TIFF at full resolution, about 2.5 MB on CPJUMP1. An overview of that plate would mean downloading all 27,648 TIFFs, around 70 GB, and shrinking them in the browser. So these plates open one field at a time: eight channels for a field of CPJUMP1, about 20 MB.

Want plate and well views? Convert the plate to OME-Zarr. How to Convert Any Microscopy File to OME-Zarr shows how.

Field view works as for any image: zoom, pan, channels, contrast.

Channels and colours

Channels take their names from the index. Each one is coloured by its emission wavelength. Brightfield channels are grey and start switched off, so the first view shows the fluorescence. Turn them on in the channel panel. The Channels guide covers the rest.

The plate manifest

Behind every Harmony plate the viewer builds a plate manifest: a small JSON file that names the plate, its wells, fields, planes, timepoints and channels, the image size and pixel size, and the file name of every image.

To keep one, open Info in the toolbar and click Save plate manifest. The viewer first reads the whole index, which can take a minute on a large plate, and then saves a complete manifest.

A saved manifest opens the plate on its own, from its web address in From URL. The plate opens at once, with no index to read.

• A manifest saved from a web plate names its images folder, so it can sit anywhere on the web.
• A manifest saved from a folder on disk names no images folder. Put it in the Images/ folder next to the TIFFs, then open its address. A manifest file does not open from disk; open the folder instead.

The format is published as a JSON Schema: https://find-nuclei.github.io/schemas/plate-manifest/v1.json.

Publishing a plate

Showing a plate with a paper, a figure or a blog post? Publish its manifest. A published manifest opens the plate without reading its index, so your readers see it at once.

1. Build the manifest. In the viewer, open the plate and click Save plate manifest in Info. Or build it from the command line in find-nuclei-viewer-js:

   npm run build:plate-manifest -- s3://cellpainting-gallery/cpg0000-jump-pilot/source_4/images/2020_11_04_CPJUMP1/images/BR00116991__2020-11-05T19_51_35-Measurement1/

   Give it the measurement folder or the address of the index, https:// or s3://. It reads the whole index once and writes BR00116991.plate-manifest.json. Add --out <file> to pick the name.

2. Host the file next to your page, on any web server or on GitHub. The images stay where they are. The manifest points at them by their full address.

3. Open it in the viewer by its URL, in From URL. A link to the viewer works too: https://find-nuclei.github.io/?url=<manifest URL>.

The bucket that holds the images must let browsers read it, as for any plate on the web.

Limits

• No flat-field correction yet. Images show as recorded.
• Treatment names from Harmony's assay layout are not shown yet. Wells show their position only.
• Zipped Harmony exports do not open. Unzip them into a folder first.
• The embedded viewer does not open these plates. Use the full viewer.