Add representative image/channel QC with safe notebook visualization #169

Goal

After the folder/header check, show a small, safe visual sample of the experiment so the user can verify that the data look sensible before preprocessing.

This should also become the basis of a lightweight channel-order consistency QC.

Existing code

The notebook already has a manual axis preview, but it is one selected image/plane at a time. read_sample_plane() already reduces preview planes to a bounded display size, and plane_png() applies a percentile display range.

NucleiSky has a stronger display pattern in imshow_safe / imshow_safe3d:

• downsample before normalization/rendering;
• avoid loading unnecessarily large arrays;
• normalize display contrast by stable percentiles;
• use float32 for display;
• handle grayscale and RGB safely.

Use the same principles here rather than importing NucleiSky as a dependency.

Suggested notebook feature

Add a compact Representative images / channel QC card after the folder/header check and once channel/axis interpretation is known.

For fluorescence data:

• show the same representative FOV as one panel per channel;
• label panels with the recorded/stated channel name when available, otherwise C0, C1, ...;
• allow the user to change the representative FOV;
• provide a small deterministic montage across biological repeats/conditions when useful, capped to a small number of images so the notebook stays responsive.

Do not call an arbitrary first file statistically “representative”: label it as a sample unless the selection algorithm really defines representativeness.

For Z/T data, choose a deterministic preview plane (e.g. middle Z, first T) and state exactly which plane is shown.

Safe visualization requirements

• Never materialize a full large image solely for display.
• Downsample/stride before normalization and PNG creation.
• Percentile normalization is for display only; source pixels are unchanged.
• Handle non-finite data and constant images safely.
• Bound displayed width/height and memory.
• TIFF and OME-Zarr follow the same display contract.
• Do not silently make MIPs: if a projection is shown, state it explicitly.

Channel-order QC

Metadata-first

The existing channel_names_differ error remains authoritative when metadata names channels. If image A says channel 0 = DAPI and image B says channel 0 = Actin, preprocessing must continue to refuse the dataset rather than trying to infer a correction.

Unnamed channels

Pixel content may be used only as QC evidence, never as channel identity.

A useful optional check could compare sampled/downsampled channel images across FOVs/repeats and flag a repeat/FOV when the observed channel pattern is much more consistent with a permutation than with the declared/index order.

Possible implementations to benchmark:

1. cheap deterministic image signatures / texture + histogram features;
2. an optional embedding backend such as DINO/MorphoEmbed;
3. no automated content model if visual QC performs better or the model is too confounded by biology.

DINO should not become a required preprocessing dependency. If used, make it an optional provider/plugin and benchmark it against the cheap baseline.

Biological perturbations can strongly change morphology or marker intensity, so the output must say e.g. “channel order looks unusual; please check”, never automatically rename or reorder channels.

Acceptance

• Notebook shows at least one safe sample image after input interpretation.
• Multichannel fluorescence data can be inspected channel-by-channel.
• Representative/sample images are labelled with condition, biological repeat, FOV and Z/T plane.
• Large TIFF/OME-Zarr data are downsampled before display allocations.
• Metadata-based channel-name mismatch remains an error.
• Optional content-based channel QC never changes channel identity/order.
• Content-based QC reports evidence/confidence and affected repeats/FOVs.
• DINO or another model is optional, not a core dependency.
• Tests cover constant images, floats/non-finite pixels, large images, multichannel data and OME-Zarr.

Reference

NucleiSky's imshow_safe uses the intended safe-display pattern: downsample first, percentile-normalize for display, then render.