[ieivanov]

What

Closes #362: the projected plate is the DCA companion store that issue asks for (every assembled channel, Z=1, the source's T/C/Y/X), written by the pipeline beside the assembled plate as <N>-assemble/<DATASET>_proj.zarr, with the projection method, Z selection and focus plane per timepoint recorded in each position's biahub-project metadata. Pyramid levels (#359), labels and tracks.geff per FOV (#360/#361, via #413) and the dca metadata and normalization statistics (#357/#358) stay with their issues. The per-timepoint focus record is also the focus metadata #400 asks for.

A new biahub project command turns a 3D plate into a 2D (Z=1) plate with one projection per output channel, and takes over all Z selection and projection from segment and track. Planned ahead of #413, which then writes labels into the plate track reads (the projected plate for A549) and can drop its plane-placement helpers (tracked_z_window / write_tracking_labels).

biahub project

Config (settings/example_project_settings.yml):

channels:                      # one entry per OUTPUT channel, in output order
  membrane_prediction:
    method: max                # whole stack
  nuclei_prediction:
    method: max
    z: {start: 10, stop: 50, step: 2}          # absolute, half-open
  GFP:
    method: sum
    z: {center: 30, below: 10, above: 11}      # planes 20 .. 40
  RFP:
    method: mean
    z: {center: focus, below: 20, above: 40}   # the A549 60-plane window
  mCherry:
    method: slice
    z: {center: 42}
  Phase3D:
    method: slice
    z: {center: focus}
focus:                         # required with center: focus; FocusSettings subclass
  channel: Phase3D
  per: fov                     # fov (median over T) | timepoint
  center_crop_xy: [800, 800]
  na_det: 1.35
  lambda_ill: 0.5
chunks_czyx: null              # as in concatenate; null = iohub defaults
shards_ratio: null

• method: max | mean | sum | slice. The plate is float32 whenever any channel uses max, mean or sum; an all-slice plate keeps the input dtype.
• start/stop are absolute planes (half-open like concatenate's time_indices); below/above count planes around center, selecting [center - below, center + above). Selections past the stack are clipped.
• focus subclasses the engine's FocusSettings (same criterion, crop and defaults) and adds channel and per. The focus is found once per position, in a spawned process pool sized by the job's workers (the timepoints are independent), then the record focus: {channel, per, z, z_per_t} goes into the output position's biahub-project metadata (z is the per-FOV median, null for per: timepoint; z_per_t is always the per-timepoint measurement). The projection itself runs through iohub's process_single_position, so the per-position job is the focus pre-pass followed by the shard-batched projection.
• chunks_czyx / shards_ratio have concatenate's semantics (shard = chunks * ratio, C not sharded).
• Unlisted input channels are dropped (the command names them); a listed channel the plate lacks fails --init. Standard CLI stack (-i -c -o -sb --cluster -m --init --resume), provenance block, preempted partition.

Segment and track

• Segment: z_slice_2D is removed. A model without do_3D (or a stitch threshold) segments in 2D and needs a Z=1 input; a 2D model on a stack, or a 3D model on a Z=1 plate, is an error at --init. Labels take the input's Z.
• Track: ZSlicing / z_slicing, the focus window and the implicit mean projection are removed. output_mode is checked against the input Z (2D needs Z=1, 3D needs Z>1). Z=1 inputs are squeezed, so configs need no np.mean step.
• Old keys (z_slice_2D, z_slicing) are rejected with a message pointing at biahub project.

Nextflow

• modules/project.nf, --project_config. The projected plate is the 2D companion of the assembled plate and is written beside it as 4-assemble/<DATASET>_proj.zarr, so project has no step directory and track stays 5-track; track reads the projected plate when project runs. The projected plate is a deliverable: cleanup removes only the shared slurm_output/ and .iohub-progress/, as for the assembled plate. Skill docs and the run template updated.
• nextflow/configs/a549/project.yml projects every channel of a typical assembled plate under the pre-rename names: the in-focus plane of BF and Phase3D, the full-stack max of the raw fluorescence channels, and the mean of the two predictions over the 60-plane focus window (feat(nextflow): A549 track config segments a 60-plane phase-focus window #418), with the focus found per timepoint on Phase3D (Add inference-readiness preprocessing for focus and intensity metadata #400). Output layout after the Dynamic Cell Atlas array standard where a 2D float32 plate can follow it: one-frame 256 x 256 chunks (the grid the assembled and tracking stores share) and shards_ratio: [16, 1, 1, 7, 5], 16-timepoint full-frame shards (~150 MB, 30 files per position instead of 400). track.yml drops z_slicing and the np.mean step.
• The reconstruct-with-nextflow check script validates project.yml against the assembled plate both ways and track.yml against the projected plate; the skill carries unprojected channels into the pre-run plan for the user to decide, and suggests the BF - Oblique edit in both reconstruct.yml and project.yml for the older acquisitions.

Behaviour differences vs track's old focus window

• The focus is measured on the 800x800 centre crop (track used the full field), and the A549 config finds it per timepoint rather than once per FOV.
• Windows are clipped, not shifted, at the stack edge: with the focus at plane 19 of 86 the window is 0..58 instead of 0..59.

Testing

• Full suite passes; new tests/test_project_settings.py and tests/test_cli/test_project_cli.py (max/mean/sum/slice against numpy, focus per fov and per timepoint with find_focus stubbed, parallel vs serial pre-pass, dropped-channel warning, config errors at init, configured chunks/shards, resume). Segment and track tests moved to Z=1 plates and gained dimensionality-mismatch cases.
• nextflow lint passes on mantis-v2.nf and modules/project.nf.
• Smoke run of biahub project --cluster debug with an earlier A549 config on one position of 2026_09_25_A549_PCNA_DENV_ZIKV (91 x 86 x 1664 x 1193): Z=1 float32 plate, focus plane 19 (per-timepoint 15..22, two blank frames fall back to the middle plane and stay zero).
• The channel check script run against the raw stores of 2026_09_08_A549_PEX3_DENV_ZIKV and 2026_08_11_A549_SEC61B_DENV flags exactly the per-dataset edits (absent mCherry entry; BF vs BF - Oblique).

Not yet done: a pipeline run with --project_config through mantis-v2.nf, and a tracking benchmark of the projected input against the previous track-side window on the TrackEdit FOVs.

🤖 Generated with Claude Code

[ieivanov]

@edyoshikun @tayllatheodoro it would be great if you can just quickly read the PR description and give it a thumbs up or let me know if you have any comments.

[Copilot]

🟡 Changes recommended

Output reuse and resume can compromise data correctness, while memory sizing and focus provenance also need correction.

4 open issues

• Validate existing output layout before reuse · New
• Preserve focus configuration metadata · New
• Include channel order in settings fingerprint · New
• Account for grouped channel memory in RAM estimates · New

What changed in this PR

Adds biahub project to create Z=1 companion plates for downstream analysis, moving projection out of segmentation and tracking.

Changes:

• Adds per-channel projections, focus selection, configuration validation and tests.
• Requires segment and track inputs to match their configured dimensionality.
• Integrates projection into Nextflow and updates A549 configs and run guidance.

File	Description
tests/​test_segment_settings.py	Tests dimensionality and removed settings.
tests/​test_project_settings.py	Tests projection schema and Z selection.
tests/​test_example_settings.py	Validates updated example configs.
tests/​test_cli/​test_track_cli.py	Tests projected inputs and dimensionality checks.
tests/​test_cli/​test_segment_cli.py	Adapts CLI tests to Z=1 inputs.
tests/​test_cli/​test_project_cli.py	Covers projections, focus, storage and resume.
tests/​test_cli/​test_cli.py	Checks command registration.
tests/​test_cellpose_inputs.py	Tests revised Cellpose input shapes.
settings/​example_track_settings.yml	Removes tracking-side projection settings.
settings/​example_segmentation_settings.yml	Documents required input dimensionality.
settings/​example_project_settings.yml	Provides projection configuration examples.
README.md	Lists the project command.
nextflow/​modules/​segment.nf	Updates input documentation comments.
nextflow/​modules/​project.nf	Adds projection initialization and execution.
nextflow/​modules/​common.nf	Clarifies shared log-directory documentation.
nextflow/​mantis-v2.nf	Wires projection before tracking.
nextflow/​configs/​a549/​track.yml	Uses projected nuclei directly.
nextflow/​configs/​a549/​segment.yml	Removes plane selection; documents projected inputs.
nextflow/​configs/​a549/​project.yml	Defines A549 projections and storage layout.
biahub/​track.py	Removes projection and checks dimensionality.
biahub/​settings.py	Adds projection schemas and migration errors.
biahub/​segment.py	Matches model dimensionality to input Z.
biahub/​project.py	Implements projection CLI and processing.
biahub/​cli/​main.py	Registers project.
.claude/​skills/​reconstruct-with-nextflow/​templates/​run_mantis_v2.sh	Enables the optional projection stage.
.claude/​skills/​reconstruct-with-nextflow/​templates/​check_qc_channels.py	Checks projection and tracking channel compatibility.
.claude/​skills/​reconstruct-with-nextflow/​SKILL.md	Updates planning and execution guidance.
.claude/​skills/​reconstruct-with-nextflow/​references/​datasets.md	Documents companion-store locations.
.claude/​skills/​reconstruct-with-nextflow/​references/​caveats.md	Updates migration and configuration guidance.

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Numeric correctness, focus metadata preservation, configuration round trips, and shard-aware memory sizing need correction.

No open issues 🎉

4 previously missed issues

In code that hasn't changed since last review

Promote float16 inputs before reduction

biahub/​project.py:101

Promote float16 inputs before reducing them. biahub/stitch.py:425 writes float16 plates, and these reductions return float16 before the cast runs. Summing 86 planes at intensity 1000 overflows to infinity even though 86000 fits in the float32 output; mean also loses precision by rounding to float16 first. Set an explicit reduction dtype and add float16 coverage.

Preserve focus metadata when reinitializing completed projections

biahub/​project.py:225

Re-running project --init on a completed focus-based projection replaces biahub-project with the settings dump, removing focus.z and focus.z_per_t while leaving the projected pixels intact. The existing provenance regression test (tests/test_cli/test_init_provenance.py:99–123) establishes that create_empty_plate refreshes its own extra metadata on existing positions. Preserve the per-position focus results when the configuration is unchanged, and add a regression test for initialization of a completed projection.

Include time-shard buffers in projection RAM estimates

biahub/​project.py:416

Include time-shard output buffers in the RAM estimate. The request ignores shards_ratio[0], although projection batches a shard's timepoints across all output channels. For float32 data shaped (512, 6, 2, 4096, 4096) with 64-timepoint shards, the estimate requests 32 GiB total, while one output batch alone occupies 24 GiB. Concurrent batches can therefore exceed the allocation. Account for the effective output batch size and dtype, and limit workers to the available batches; concatenate already accounts for time batching in its resource estimate.

Exclude internal axes field from ProjectionSettings serialization

biahub/​settings.py:411

axes is included in model_dump(), but reject_axes rejects it on input. Saving a focus-enabled ProjectionSettings with model_to_yaml() therefore produces a configuration that biahub project cannot reload. Exclude this fixed internal field from serialization while continuing to reject explicitly supplied axes.

4 resolved since last review

• Account for grouped channel memory in RAM estimates
• Include channel order in settings fingerprint
• Preserve focus configuration metadata
• Validate existing output layout before reuse

_{Review effort: Balanced}

[aofei-liu]

hi! thanks for tagging me! Here's a few things I caught comparing stuff to the specs:

• not an issue at the moment, but the max setting currently writes as float32 by default, while the spec requires that the projection match the source store. not an issue for the pipeline because the source store is already float32, but maybe match dtypes instead of hardcoding float32?
• i think we name all our stores with the suffix .ome.zarr and stores named with .zarr are implicitly passed for projection stores. i think this can either be a spec-side fix to also check stores with .zarr, or a suffix swap for stores here to be with the ome.zarr suffix. we can discuss on the PR on dynamic-cell-atlas-specs with mikala how to resolve this
• i think currently when a focus plane is not found the center slice is recorded and the plane is recorded as not found. the spec doesn't allow for a null rn; we probably also want to fix it on that end.
• this is a non issue if you use the nextflow version of the pipelines here (since it currently does not do this), but I think biahub's CLI technically allows you to select/project a subset of the FOVs. if the subset projection is paired with the non-subsetted store, it will fail the check on the specs that the projection matches the source.

that's all i caught for now. I'll tag you on the dca specs store as well!

[ieivanov]

@aofei-liu very helpful, thank you! I'll implement the max/float32 fix. I agree we can fix the rest on either end, depending on what makes most sense.

[aofei-liu]

yeah sounds good! looks like you already pushed the fix, so hopefully we hear back on the PR in dca specs from mikala on which side to resolve the .zarr naming thing.

oh and maybe one more check that would be good to make sure you can fulfil is the shard > 1GB when array > 1GB requirement, Idk if 16 timepoints / 60 timepoints will be an issue for that check (i'd pin the validator to v0.2.10 for your checks)

[tayllatheodoro]

For the record on the A549 Z projection in project.yml (mean over the 60-plane window around the Phase3D focus): we benchmarked the alternatives on our annotated A549 data, and the window mean is the right default. All rows use the same template track.yml (cellpose cpsam_v2 + ultrack + min_sibling_length: 3).

2026_04_28 (4 TrackEdit FOVs, 78 divisions; division F1, matched within 2 frames / 10 um):

projection	all FOVs	mock	DENV	predicted divisions	tracks (GT 287)
window mean (this config)	0.67	0.69	0.64	104	378
window max	0.65	0.68	0.59	104	385
all planes, mean	0.63	0.65	0.58	107	396
all planes, max	0.51	0.56	0.45	139	532

2026_04_21 (5 DENV FOVs, 38 divisions from mitosis labels):

projection	mitotic cells detected	real divisions found	predicted divisions	tracks
window mean	0.95	19	81	388
window max	0.93	20	92	445
all planes, mean	0.95	19	92	422
all planes, max	0.90	20	131	643

2026_08_11 v8 (4 FOVs, no annotations, counts): max adds divisions and tracks in the infected wells (DENV divisions: window mean 91, window max 135, all-planes max 156).

• Max is worst in infected wells: it takes the brightest value along Z, so every out-of-focus "ghost" or hallucinated VS structure becomes a full-strength object. A visual check on 08_11 agreed: the window mean shows the fewest ghost structures, all-planes max the most.
• Window size (track-side window, mean, 2026-10-09): 40 planes scored higher on 04_28 (whose annotations were curated from a 40-plane run) but lost mitotic cells that drift in Z on independent 04_21 data (0.89 vs 0.95); 60 keeps them; 70 is no better.
• Focus per timepoint vs per FOV (this PR's projection): equivalent on 04_28 (F1 0.67 vs 0.69); per timepoint recovers mitotic detection on 04_21 (0.95 vs 0.92), possibly because windows are clipped at the stack edge (focus near plane 17 leaves 57 planes) and the per-timepoint focus shifts with the cells.