[ieivanov]

Re-opens the tracking work after #280 was merged then reverted on main (see revert commit on main). Same content as #280, with Taylla Theodoro credited as co-author. To be merged after testing.

Summary

This tracking-only PR is preferred over #260 — splitting tracking out of the combined track + rename-channels PR lets it be tested and merged on its own. Rename-channels stays in #260 (needs further discussion).

• Track CLI: add --init and --cluster (slurm/local/debug) to the unified biahub track, plus --input-images-path for Nextflow to override config input paths. Factor _init_output_plate following the deskew/flat-field/reconstruct pattern.
• CLI consistency: type hints match the option callbacks (list[Path]/Path), provenance written to each output position's zattrs (biahub-track), canonical slurm_args (job name, slurm_mem preserving total node memory, parallelism comment) and docstring, focus-based z-resolution, and a cellpose segmentation backend.
• Monkey-patch: port _patch_ultrack_readonly_buffer() (scikit-image #6378 — Cython _map_array rejects the read-only memoryviews numpy 2.x produces). Remove when scikit-image >= 0.27 is available.
• Nextflow: add nextflow/modules/tracking.nf (biahub track --init / --cluster debug); update example_track_settings.yml.
• Settings: correct ProcessingInputChannel.path and TrackingSettings.blank_frames_path annotations to Path | None to match their validators.

Scope

Tracking only — 5 files. Excludes everything rename-channels, which remains in #260.

Test results

• pytest tests/test_cli/test_track_cli.py — 6 passed (init, debug single-position, local, blank-frames).
• ruff check / ruff format clean.

Test plan

• Unit tests (init, debug, local, blank-frames)
• CLI integration on real data
• Nextflow subworkflow end-to-end (GPU, multiple positions)

🤖 Generated with Claude Code

[tayllatheodoro]

Real-data integration test: passing

Tracked 2026_07_14_A549_MAP4_ZIKV (input (67, 6, 86, 1664, 1193) float32, cellpose nuclei, z_slicing.method: all) on SLURM GPU.

The first attempt OOM-killed a 64 GB worker. Root cause was three sites eagerly calling .compute() on a whole (T, Z, Y, X) channel — a 42.6 GB single allocation — none of which needed the full stack at once. Fixed in 0ef2eec:

Site	Was
run_preprocessing_pipeline	materialised 42.6 GB before np.mean; array_apply already slices per timepoint and dask reductions stream chunk-wise
apply_focus_slicing	materialised the focus channel, though _median_focus_plane already indexes per timepoint
cellpose_segmentation	computed then mean-projected
fill_empty_frames_from_csv	mutates in place, so it does need concrete arrays — now materialises only when there are frames to fill

Worth calling out: apply_focus_slicing was a regression this PR introduced. Pre-refactor, focus resolved to a read-time slice, so load_data only ever read window_size planes; a58bcd3 changed it to load-everything-then-window. So method: focus would have OOM'd identically to method: all — the earlier DENV run survived only because its 40-plane window was applied at read time.

Results

	Before	After
Outcome	OOM-killed	COMPLETED
Elapsed	—	1:55
Peak RSS	>64 GB	10.2 GB

Isolating the load+projection under a 16 GB cap: peak RSS 2.52 GB on the FOV that previously OOM'd at 64 GB.

Output: (67, 1, 1, 1664, 1193) uint32 nuclei_labels, labels present in all 67/67 timepoints, ~24 nuclei/frame, 78 track labels, biahub-track provenance written.

No resource-estimation change was needed — 64 GB now has ~6x headroom.

• Unit tests (init, debug, local, blank-frames) — 20 passed
• CLI integration on real data
• Nextflow subworkflow end-to-end (GPU, multiple positions)

[tayllatheodoro]

Full nf pipeline and tracking working, tested with dataset /hpc/projects/intracellular_dashboard/organelle_dynamics/2026_03_26_A549_CAAX_H2B_DENV_ZIKV

[ieivanov]

Thanks for testing and merging this PR!