[ieivanov]

Closes #360. Closes #361. Part of #363. Builds on #424 (biahub project): the PR is based on feat/project-cli until that merges.

In draft until royerlab/ultrack#290 merges and the tracking results are validated (see the comments below). The iohub side (#489, #496) is merged and pinned from main.

What changes

Segmentation moves out of biahub track into biahub segment, and both write into the plate they read — with #424 the projected plate 4-assemble/<ds>_proj.zarr for 2D work, or the assembled plate for 3D. The pipeline becomes assemble → project → segment → track → QC. Per position:

Output	Written by	Details
<fov>/labels/<model>	biahub segment	cellpose instance labels, one OME-NGFF label image per model, named after it (A549: labels/nuclei). uint32, shape (T, 1, Z, Y, X): the image's axes with one channel, with the plate's Z (the DCA array standard wants every array 5D; iohub refuses a label with more than one channel). Written through iohub's process_single_position(output_label=...) (Biohub/iohub#489), so --resume works as for every other step.
<fov>/labels/tracks_<model>	biahub track	the same objects after ultrack's re-segmentation and the sibling filter, painted with track_id (A549: labels/tracks_nuclei). Chunks (16,1,1,128,128) (1 MB: the DCA 512 KB MUST and 1 MB SHOULD); shards from iohub's shards="200MB" size target (Biohub/iohub#461), which on the A549 frame is one 16-timepoint chunk by the full plane; same for segment's.
<fov>/tracks.geff	biahub track	GEFF 1.3 (zarr v3) from ultrack's Tracker.to_geff. seg_id (= track_id) links nodes to labels/tracks_<model> via related_objects. Tracklet/lineage props are declared. Axes are pixel coordinates with physical scale.
<fov>/tracks_<row>_<col>_<fov>.csv	biahub track	Same tracks as before, kept for now for downstream readers.

biahub segment. -o and the separate label plate are gone: the labels go into the -i positions as label images, one per model, named after it. Segmentation strategies accumulate in a plate as differently named models, and a name is only rewritten by the model that made it: --init refuses a label image whose recorded settings (or shape) differ from the current model's, pointing at a new model name. --init creates the empty label images and warms the cellpose weights; output_ome_zarr_version is rejected, since the labels take the plate's version. nextflow/configs/a549/segment.yml takes the cellpose values tracking was validated with (cpsam_v2, diameter 80, min_size 2500), as one model nuclei.

biahub track. segmentation_method: labels (the default) names the label image to track, labels: <model>, with labels_sigma (ultrack's contour smoothing, formerly cellpose_config.labels_sigma); the output name is derived, tracks_<labels>. An optional output_label names it instead, for several tracking runs of one segmentation side by side; then the GEFF and CSV are tracks_<output_label>.geff / tracks_<output_label>_<fov>.csv, while the default stays tracks.geff / tracks_<fov>.csv, the names the downstream readers (VisCy#525, biocurator#997) expect. cellpose_config, segmentation_method: cellpose and target_channel on this path are rejected with a pointer to the segment config. foreground_contour stays as the legacy path and keeps target_channel and input_images. Blank frames in the CSV are filled with the nearest frame's labels, as the images were before, so a dropped timepoint does not break every track. All cellpose code leaves track.py; track needs no GPU and runs on the preempted partition with the other per-position steps: ultrack cannot resume, but a position now tracks in a minute or two, so a preemption costs that much and the retry covers it.

No Z placement. 2D work writes (T, Y, X) labels into the projected plate's one plane and 3D fills the stack; the plane-placement logic of earlier revisions (tracked_z_window, the z_window/z_index provenance) is gone, since #424 records the source window and focus plane on the projected plate itself. Each label image records its settings under biahub-segment / biahub-track (track's with the full resolved Ultrack config).

Sibling filter and the GEFF. min_sibling_length (#415) edits the tracks table and the labels after tracking; the GEFF is exported from that same table through ultrack's to_geff(tracks_df=...) (royerlab/ultrack#290), so the labels, tracks.geff and the CSV agree. biahub is pinned to the fork commit carrying #290 until it merges.

CLI details.

• track --init checks the plate's Z against output_mode and that labels/<labels> exists in every position (so a pipeline missing its segment step fails in the init phase), then creates the empty tracked label images with iohub's create_empty_labels, which also records the settings on the label group.
• track -o is optional: without it each worker builds its Ultrack database in a per-FOV scratch directory under its $TMPDIR and deletes it after export, and SLURM logs go to ./slurm_output; with it the databases are kept in {-o}/{row}_{col}_{fov}/. ultrack's own temporary zarr arrays used to leak into $TMPDIR too; Fix create_zarr deleting and then leaking its temporary store royerlab/ultrack#289 (in the pin) removes them.
• TrackingSettings.output_ome_zarr_version is removed, since the labels take the plate's version.
• The DCA label chunk sizing (label_layout) lives in biahub.utils.ngff, shared by both commands; the scaffolding itself is iohub's.

Nextflow.

• New --segment_config (a549/segment.yml) between project and track: segment's init runs after project's and creates the label images, track's init after segment's. Segment runs on gpu_preempted with --resume, track on the cpu label (the preempted partition). Neither has a step directory: A549 runs end at 4-assemble (with <ds>.zarr and <ds>_proj.zarr in it) like neuromast runs. A run naming --track_config without --segment_config fails at track --init with the message above.
• --qc_track_config / qc_track.yaml are removed; passing the param errors. The instance counts move to --qc_project_config (a549/qc_project.yaml) on the projected plate: instance_count.label: tracks_nuclei (imaging-qc#243) plus blank on the anchor channel. It is planned after the last of project/segment/track's inits and computed after the last of them runs; qc.yaml is pixel metrics on the assembled store and runs concurrently. Both stores are tabs of one report.
• Cleanup: segment's resume markers live under the projected plate's .iohub-progress/ entry, which cleanup already removes; the label images are inside the deliverable plates and are never targets.
• The reconstruct-with-nextflow skill: step lists, the run template (--segment_config), the schema notes and the pre-launch check script, which now checks segment.yml's channels against the projected plate, track.yml's labels against the segment models, and qc_project.yaml's label and anchor against both.

Dependencies

• iohub pinned to main at the feat(ngff)!: label images have the image's axes with one channel iohub#496 merge (0cb3e35): label images are (T, 1, Z, Y, X), the image's axes with one channel, and a label with more than one channel is refused. Main also has #489 (process_single_position(output_label=...), create_empty_labels), #486 (create_empty_plate(label_names=...)) and #485 (the labels list goes on labels/zarr.json). All merged; none in a PyPI release yet.
• ultrack pinned to ieivanov/ultrack@69e7589 = royerlab main at afbe2d6 (virtual-stain output channels drop the _prediction suffix (regression vs. viscy) #288 to_geff, fix(virtual-stain): suffix output channels with _prediction #289 temp-store fix) plus Export GEFF from a tracks DataFrame (consistent with filter_short_sibling_tracks) royerlab/ultrack#290 (to_geff(tracks_df=...)). Repoint at royerlab main once feat(tile_stitch): honour monarch.recon_dtype as the stored output dtype #290 merges.
• imaging-qc pinned at f5ae656 (Audit ram_multiplier in estimate_resources for each recon step (post #215) #243); upstream_qc_dir is dropped from the QC configs (removed upstream in Phase 1 biahub refactor: Merge outstanding PRs and switch to uv scaffolding #235).
• geff>=1.3, geff-spec>=1.3: geff 1.3 only caps geff-spec, and geff-spec 1.1 silently drops related_objects[].node_prop.
• Paired downstream PR: feat(dynaclr): read per-FOV tracks from in-plate tracks.geff VisCy#525 (DynaCLR reads tracks.geff, falls back to the CSV).

Testing

• Unit tests on the branch (with the pinned iohub and ultrack): segment (label images in the input plate with resume, one image per model, strategies accumulating under different names, the settings and shape refusals), track (labels input, blank-frame filling, missing-label error at init, output_label naming the label and the tracks files, the legacy foreground+contour path, the GEFF's link to labels/tracks_<model>, the sibling filter, no GPU request), the settings rejections, and the A549 configs. nextflow lint passes.
• Real data, end to end: on position C/2/000000 of 2026_08_11_A549_SEC61B_DENV_debug/v8's full-stack-mean projected plate, biahub segment (47 s, 1.6 GB on a GPU node) then biahub track (73 s, 9.4 GB, 16 CPUs) with the matched settings reproduce the earlier in-track run on the same plate exactly: 220 tracks, 58 divisions, 27.6 cells per frame in both, foreground IoU 0.9994 between the two tracked label images, every old object matched. The GEFF validates and points at ../labels/tracks_nuclei. Run script and configs: v8/run_segment_track.sh, configs/segment_projall.yml, configs/track_projall_labels.yml.
• The 54-position comparison of the in-track revision against 5-track/ is in the comment below (matched run equal within solver noise; the current template keeps 72 % of the tracks and 59 % of the divisions).

Follow-ups

• biahub concatenate should carry over labels/, tracks.geff and the CSV, cropping the labels and shifting coordinates when Y/X are cropped. It's how curated datasets are built.
• feat(track): choose the tracker: ultrack, tracksdata, HOCT or Trackastra #427's tracksdata/HOCT/Trackastra link the same labels: image (image channel from input_images); HOCT/Trackastra will flag the GPU back on for track.
• Repoint the iohub and ultrack pins once #489 and Export GEFF from a tracks DataFrame (consistent with filter_short_sibling_tracks) royerlab/ultrack#290 merge. The general DataFrame-driven GEFF export (edits that add or move nodes, e.g. close_tracks_gaps) is Export GEFF from an edited tracks DataFrame in general (added or moved nodes) royerlab/ultrack#291.

🤖 Generated with Claude Code

[tayllatheodoro]

@ieivanov 2026_08_11 has no tracking annotations, so I can't score your two stores directly. We did run the same comparison (old setup vs the template) on our annotated A549 datasets, and there the divisions the template drops are mostly false ones.

2026_04_28 (4 TrackEdit-curated FOVs, 2 mock + 2 DENV, 78 divisions; division matching within 2 frames / 10 µm):

	division recall	division precision	division F1	real divisions found	predicted divisions	tracks (GT 287)
old: mean over all planes, no sibling filter	0.84	0.44	0.58	~65	155	491
template: biahub project @ 88f363e (60-plane window, per-timepoint focus) + min_sibling_length: 3	0.79	0.59	0.67	~61	104	378

• The template keeps 77 % of the tracks and 67 % of the divisions, close to your 72 % / 59 % on 08_11.
• Of the ~51 divisions it drops, ~4 were real and ~47 false. Most false divisions were a daughter that lives 1-3 frames: a virtual-staining hallucination for a frame, a neighbour linked as a daughter, or a lobed nucleus split for a frame. The sibling filter removes those.
• Detection is unchanged (0.99), and the mock and DENV wells both improve.

2026_04_21 (5 independent DENV FOVs, 38 divisions from mitosis labels; the old run here already had the sibling filter, so this isolates the projection):

	mitotic cells detected	real divisions found	predicted divisions	tracks
old: mean over all planes	0.95	19	92	422
template projection	0.95	19	81	388

Same divisions found with fewer predicted, so the dropped ones were false there too.

The per-change breakdown is in #415 (sibling filter: F1 0.58 -> 0.63) and #418 (focus window: 0.63 -> 0.68); with #424's projection, tracking matches the old track-side window on both datasets.

To check 08_11 itself, I'll annotate a few of its FOVs, which also adds a dataset to the benchmark. In the meantime, the annotated results support deploying the template.

[aofei-liu]

hmm I think labels/ needs to output tczyx as well and this reads to me that it seems to be tzyx? so just change to (t, 1, z, y, x) I think

[ieivanov]

@aofei-liu good catch, I brought this up with the team here: https://github.com/chanzuckerberg/biocurator/issues/1103#issuecomment-6049741709

@srivarra tells me that labels shouldn't have a Channel dimension based on OME spec since labels are "channels" themselves. It makes more sense to have multiple labels rather than one "label" with multiple channels within in. With this reasoning, I think labels here should stay tzyx rather than (t, 1, z, y, x).

[aofei-liu]

@ieivanov I think the NGFF spec as written allows for both shapes:
"Each dimension of the label should be either the same as the corresponding dimension of the image, or 1 if that dimension of the label is irrelevant." So (t, 1, z, y, x) under a tczyx image is what the spec describes, and a missing c axis is also legal. I think dca chose to adopt (t, 1, z, y, x). it would probably require a broader discussion around the team on whether or not we want to also allow t, z, y, x. I believe that the ops pipeline also writes to t1zyx ?

[ieivanov]

@aofei-liu I did some digging on the label array shape, I agree with you, implementing now.