[guijacquemet]

CP-3 of the CellPatcher v0.2.0 plan (design v0.4 §6, §8 and §9 on MorphoFeature claude/restart-doc), built on CP-1 (#68), CP-2a (#69) and CP-2b (#70). This PR does not tag. v0.2.0rc1 is tagged only after the CP-3b follow-up (see "Not in this PR").

At the coordinator's request it also re-pins to preprocessing v0.4.0rc2 (44971bc) and wires in rc2's check for files the run did not record.

Commits

Implementation:

1. d2b8d20 Code standards (tooling only):
   • tools/code_rules.py is an identical copy of preprocessing's shared file (SHA-256 cc04a420…, tested; the same as preprocessing main at 6711b48).
   • tools/check.py and --rules.
   • tools/code_rules_baseline.json holds today's debt. It can only shrink, and it has a # noqa ratchet.
   • Guard fixtures, a CI rules job, and Ruff 0.17.3 pinned in the test extra.
2. 09d668a Mechanical move: refuse_transposed_mask_axes moves from io to axes.
3. 87c696b In-memory images with X before Y are refused, as masks already are (§6).
4. b357297 Pin preprocessing v0.4.0rc2 (core and zarr extra).
5. 0f08b0d rc2's unrecorded-files check is surfaced: unrecorded_files and zarr_extra_missing.
6. 88c539d The preprocessing command names rc2's design step.
7. d7b89a9 The notebook is rewritten for v0.2.
8. 878614f Installers: construct.yaml lists every module; CI and the test extra run the notebook.
9. 1d47a6d Docs, CHANGELOG and migration notes.

Independent review (fixes):
10. a58a5fb The object scan refuses X-before-Y in-memory axes. scan_cell_patch_size and scan_cell_objects refuse them, and so does CellSegmentationStrategy(mask_axes=…). Before this fix, a square mask declared XY was measured as if it were transposed: an object 7 high and 3 wide was reported as bbox_height 3 and bbox_width 7.
11. f26c471 A # noqa comment no longer hides a Ruff finding from the baseline.
- The shared ratchet counts only C901, PLR0913, PLR0915 and ANN. A new # noqa: F401 therefore hid a new finding, and check.py stayed green (shown with a mutation).
- Ruff now runs with --ignore-noqa.
- The 2 findings that were already suppressed are now recorded in the baseline, and 3 unused noqa comments are removed.
12. 5cc1c52 No installer is built for a release candidate (owner decision 4).
- .tools/python/bump_version.py refuses a pre-release version with a clear message, before it changes any file. The release workflow runs it first.
- This is tested.
- It is documented in docs/developer_notes.md.
13. 87d9924 The CP-3b follow-ups and the embedded-preprocessing plan are recorded in docs/plan.md and the CHANGELOG ("Not yet").
- Step 1 of the notebook now says plainly to run the preprocessing notebook or CLI first (tested).
14. 9f68c59 The preview equals the export with normalization (image scope), and the preview has exactly the image's exported patches.
15. ac3606b PatchTorchDataset refuses X-before-Y axes when it is built. Before, the refusal came only when an item was loaded, in a DataLoader worker. Tested with CPU torch.
16. bb51001 A file refused while it is read (RunInputsError during the preview or export) is shown as a refused run, not as "Please change the settings".
17. e45b823 CHANGELOG updated for these fixes; the notebook's docs link is now absolute (the relative one does not open on Colab).
18. 706accf Health snapshot.

Behaviour changes

• Notebook (notebooks/CellPatcher/CellPatcher.ipynb):
  • It asks for the preprocessing run's output folder. It asks where the experiment and masks folder are now only if they were moved since preprocessing.
  • Every file is read through RunInputs.
  • It has four steps: the run, the settings, the preview and the export.
  • The code lives in cellpatcher.notebook_session (orchestration), notebook_ui and notebook_form (ui). The old notebook's 2,357-line inline class and 0.8 MB of widget state are gone.
  • It follows LabConstrictor portability, as preprocessing PR #118 does:
    • # @title Run to … starts every cell, and the code is hidden.
    • The Colab guard holds Drive, the widget manager and the zarr extra.
    • It uses no magics, and /content appears only in the guard.
    • RELEASE_TAG = "v0.2.0rc1", and no GITHUB_TOKEN.
    • The version index agrees.
    • It has Colab and JupyterLab callouts.
  • Refusals are shown with their code, files and action, and the step stops there.
• Breaking: in-memory common.image_axes with X before Y (XY, CXY, XYZ) is refused by:
  • run_patching;
  • lazy delivery;
  • PatchTorchDataset;
  • the object scan (masks too).
• Since rc2:
  • An unrecorded image or mask is unrecorded_files.
  • OME-Zarr images without zarr give zarr_extra_missing.
  • An rc1 mask record without axes gives preprocessing_run_refused.
  • No refusal is caught and continued.
• no_preprocessing_run names check → design --confirm … → run (checked against rc2's cli_design.py).
• Installers:
  • construct.yaml lists every module, and test_installers.py keeps it complete.
  • setup.py and __version__ are 0.2.0rc1.
  • Release candidates get no installer.

Not in this PR (owner decisions, 2026-11-02)

CP-3b, a follow-up PR before tagging v0.2.0rc1:

• CellPatcher_Pytorch.ipynb and CellPatcher_Strategy_Examples.ipynb get the same LabConstrictor treatment. They still use the old GITHUB_TOKEN install of main.
• The old notebook's "show parameters per group" table and its before/after normalization histograms come back. They will be computed in the package, never in notebook cells.

Before the final v0.2.0 installers:

• LabConstrictor's construct.yaml copies the package to CellPatcher/src/cellpatcher/cellpatcher/.
• In that layout, setup.py (find_packages(where="src")) finds no package, so the installed app has no cellpatcher.
• The reviewer reproduced this by copying the files as construct.yaml lists them and pip-installing them.
• This is pre-existing (main has the same layout). It is not fixed here because no installer is built for an rc. It needs fixing in the template or setup.py before the final installers.

After preprocessing v0.4.0 is final:

• The notebook will include the preprocessing steps through preprocessing's declared embedding API: PreprocessingNotebook and notebook_style, pinned by its tests/test_embedding_api.py.
• It will never copy their code.
• Until then, it sends users to the preprocessing notebook or CLI first.

Accepted debt: Ruff findings are kept in the shrink-only baseline; ruff format is not enforced yet.

Gate (Python 3.11, uv venvs, preprocessing v0.4.0rc2, head 706accf)

Environment	Passed	Skipped
.[test,zarr], tools/check.py (exit 0)	1057	11 (7 torch, 4 notebook extra)
.[test], tools/check.py (exit 0)	1036	32 (21 zarr, 7 torch, 4 notebook extra)
.[test,zarr,notebook], tools/check.py (exit 0; includes the nbclient kernel run)	1068	7 (torch)

• With CPU torch added, test_torch_dataset.py, test_delivery.py and test_biological_repeat.py passed: 57 tests.
• tools/check.py --rules is clean. Ratcheted # noqa: 0.

§9 figures (measured on the new and rewritten code)

• Files: notebook_ui.py 379 lines, notebook_form.py 307, notebook_session.py 284, tools/check.py 206.
• Largest values in new code:
  • complexity 5 (check.main);
  • parameters 4 (export_patches_of_run);
  • executable lines 27 (run_open._refusal_issue);
  • statements 20 (CellPatcherNotebook.__init__).
• Touched pre-existing functions (baselined debt, not grown):
  • PatchTorchDataset.__init__: 10 parameters, 46 executable lines;
  • scan_cell_objects: 45 executable lines, 6 parameters.
• ruff --isolated --select C901,PLR0913,PLR0915,ANN,D (NumPy convention) passes on the new modules. Every module declares its layer.

Colab hand-check list (after tagging v0.2.0rc1, since the notebook installs that tag)

1. Run Step 0 in Colab. Drive mounts at /content/drive. pip installs cellpatcher[notebook,zarr] @ …@v0.2.0rc1 (with preprocessing rc2). The ready card shows 0.2.0rc1.
2. The widgets render. Browse… shows the "paste the path" card.
3. Step 1 with a run on Drive shows the green card. Ticking "moved" reads from the copy. Adding a .tif gives a red [unrecorded_files] card.
4. In Step 2, only the chosen mode's controls show. The dataset size comes from Scan the object sizes of the dataset.
5. The Step 3 preview draws inline.
6. The Step 4 export writes patches.csv, images.csv and run_config.json on Drive.
7. With an OME-Zarr experiment there is no zarr_extra_missing.
8. After a disconnect, run Step 0 and Step 1 again: there is no stale state.

https://claude.ai/code/session_01G3qp9AxjpGPw9xfWAUJNqc

---

Generated by Claude Code

[guijacquemet]

Independent review: merged as 3b42093 (merge commit; branch kept)

Findings fixed on the branch

1. a58a5fb: the object scan accepted X-before-Y axes. scan_cell_patch_size and scan_cell_objects took mask_axes='XY' on a square mask and reported the transposed sizes: an object 7 high and 3 wide came out as bbox_height 3 and bbox_width 7. Both now refuse X-before-Y image and mask axes. CellSegmentationStrategy(mask_axes=…) refuses them too.
2. ac3606b: PatchTorchDataset refused X-before-Y axes too late. The refusal came only when an item was loaded, inside a DataLoader worker. It now comes when the dataset is built. Tested with CPU torch.
3. f26c471: a # noqa comment could hide a new Ruff finding.
   • A new # noqa: F401 hid a new Ruff finding, and check.py --rules stayed green (shown with a mutation). The shared ratchet only counts C901, PLR0913, PLR0915 and ANN.
   • Ruff now runs with --ignore-noqa, so no comment can silence a finding past the baseline.
   • The 2 findings that were already suppressed are now in the baseline. 3 unused noqa comments are removed.
4. 5cc1c52: no installer for release candidates (owner decision 4).
   • bump_version.py refuses a pre-release version with a clear message, before it changes anything. A test checks this, including after a template sync.
   • Documented in docs/developer_notes.md.
5. 87d9924: owner decisions recorded.
   • The CP-3b follow-ups and the embedded-preprocessing plan are in docs/plan.md and the CHANGELOG ("Not yet").
   • Step 1 of the notebook now says plainly to run the preprocessing notebook or CLI first (tested).
6. 9f68c59: the preview-equals-export test was one-way. It now checks set equality of the image's patches, and also a normalized (image-scope) run, comparing pixels with the exported files.
7. bb51001: wrong error card. A RunInputsError raised while reading (for example, a file changed after Step 1) was shown as "Please change the settings". It is now shown as a refused run.
8. e45b823: smaller fixes.
   • The CHANGELOG now covers these fixes.
   • The notebook's docs link is absolute, because the relative link breaks on Colab.
   • The CHANGELOG no longer claims that the module list made the installed app importable (see the installer finding below).

Verified

• tools/code_rules.py is the shared copy. Its SHA-256 cc04a420… matches preprocessing main (6711b48) and v0.4.0rc2.
• The baseline can only shrink. Proved by mutation; tools/check.py --rules exits 1 in each case:
  • a new finding → new violation;
  • pipeline.py grown by 2 lines → grew from 1029 to 1031;
  • an added # noqa: C901 → noqa: C901 grew from 0 to 1;
  • a blanket noqa;
  • after the fix, a # noqa: F401.
• The rc2 refusals reach the user.
  • Every except around RunInputs.open and the read_* calls re-raises with a code: unrecorded_files, zarr_extra_missing or preprocessing_run_refused.
  • The notebook's guarded stops the step and shows the card.
  • Nothing is caught and continued.
• No in-memory transposition anywhere. move_axes is not called internally. normalization._channel_planes only moves C.
• The notebook calls only the package and follows the portability guide.
  • It does no reading or computing in its cells.
  • It follows the LabConstrictor guide and is consistent with preprocessing's tests/test_notebook_file.py.
  • RELEASE_TAG v0.2.0rc1 matches the version index and __version__.
• The headless nbclient run really runs in CI. The notebook job ran 1068 tests with 7 skipped, all of them torch.
• The migration notes match the other repositories' heads:
  • MorphoRelate ea19bb0: check_image_axes, read_patch_table;
  • MorphoEmbed a8e88df: PatchTorchDataset, CYX/YX;
  • fiberfeatures 362f1ba: the reference patch_config.json with mask_source set to the default tiff_tree.
• The regression tests fail on old main. Run against main's source: 36 fail. These are all the new X-before-Y cases, 4 of the 6 unrecorded-file tests, the notebook-file tests, and the installer tests.

Gate (Python 3.11, uv venvs, head 706accf; CI green with the same counts)

Environment	Passed	Skipped
.[test,zarr], check.py (exit 0)	1057	11 (7 torch, 4 notebook extra)
.[test], check.py (exit 0)	1036	32 (21 zarr, 7 torch, 4 notebook extra)
.[test,zarr,notebook], check.py (exit 0)	1068	7 (torch)

With CPU torch: test_torch_dataset.py, test_delivery.py and test_biological_repeat.py gave 57 passed.

§9 figures

• Files: notebook_ui.py 379 lines, notebook_form.py 307, notebook_session.py 284, tools/check.py 206.
• Largest values in new code:
  • complexity 5 (check.main);
  • parameters 4 (export_patches_of_run);
  • executable lines 27 (run_open._refusal_issue);
  • statements 20 (CellPatcherNotebook.__init__).
• Touched pre-existing debt (baselined, not grown):
  • PatchTorchDataset.__init__: 10 parameters, 46 executable lines;
  • scan_cell_objects: 45 executable lines.
• Ratchet: ratcheted # noqa is 0. ruff --isolated --select C901,PLR0913,PLR0915,ANN,D is clean on the new modules.

For CP-3b (before tagging v0.2.0rc1)

• The other two notebooks: apply the LabConstrictor treatment to CellPatcher_Pytorch and CellPatcher_Strategy_Examples.
• The two dropped notebook views: bring back the per-group parameters table and the before/after normalization histograms, computed in the package.
• Installer layout (pre-existing, must be fixed before the final v0.2.0 installers):
  • LabConstrictor's construct.yaml places the package at src/cellpatcher/cellpatcher/.
  • There, setup.py (find_packages(where="src")) finds no package. I reproduced this: the installed app has no cellpatcher module.
  • The fix needs the template or setup.py.

Not tagged.

---

Generated by Claude Code