Add a first-reconstruction tutorial and agent skills - #569
Add a first-reconstruction tutorial and agent skills#569talonchandler wants to merge 10 commits into
Conversation
Interactive CLI walkthrough for a first reconstruction: environment check, OME-Zarr conversion, config authoring, napari viewing, and parameter sweeps. Includes a QPI 2D-from-defocus worked example using the zenodo recOrder_session sample. Un-ignores .claude/skills/ so the skill ships with the repo.
Two-call skill: `wo compute-tf` on a config + input position, then `wo view` on the resulting transfer function (napari, backgrounded).
talonchandler
changed the title
For 2D reconstructions, the transfer function is stored as a singular system (U, S, Vh). `wo view` now reconstructs H = U @ diag(S) @ Vh at each lateral frequency and displays the resulting transfer function(s) — absorption and phase for 2D phase, the optical TF for 2D fluorescence — instead of the raw singular vectors. 3D display is unchanged.
Relocate skill content from .claude/skills/ to .skills/ as the single canonical, harness-agnostic source of truth. Add symlinks so existing discovery paths still resolve to it: - .claude/skills -> ../.skills (Claude Code project skill scan path) - .agents/skills -> ../.skills (Codex CLI/ChatGPT skill scan path) Update .gitignore: .claude/* still ignores session state, but !.claude/skills un-ignores the symlink so it's tracked. No content changes; checksums of all 8 skill files are unchanged.
…torial - Rewrite waveorder-tutorial SKILL.md around the staged onboarding workflow: suitability, data/metadata identification, ROI selection, draft reconstructions, manual sweeps, auto-tuning, and scaling - Add scripts/crop_roi.py for ROI cropping and extend scripts/sweep.py with two-parameter grid sweeps shown on two napari sliders - Add iohub convert route and ROI cropping to conversion reference; add optimization block, RL/RLGC, and expanded symptom table to config reference - Add human-readable tutorial at docs/guide/first-reconstruction.md and link it with the skill at the top of the README - Remove all em dashes; move imports to module top in tutorial scripts
…asets Two reconstructions of the same channel previously produced identically named layers, so users could not tell them apart in the layer list.
Gradient methods are local (travel ~lr per iteration); grid_search uses lr as the grid step centered on init. Add the coarse-to-fine recipe to the skill and config reference.
talonchandler
changed the title
srivarra
left a comment
srivarra
left a comment
There was a problem hiding this comment.
This was super cool!
Just a few small suggestions.
There was a problem hiding this comment.
I think this should be renamed to waveorder-visualize-otf-from-config or maybe a shorter version waveorder-visualize-otf. This is b/c it makes it easier to filter the waveorder specific skills
| def _wo_cmd() -> list[str]: | ||
| """Return the invocation prefix for the waveorder CLI.""" | ||
| if shutil.which("wo"): | ||
| return ["wo"] | ||
| return ["uv", "run", "wo"] |
There was a problem hiding this comment.
If the user is expected to have uv installed, it would be better to make these Python scripts PEP 723-compliant, with dependencies declared inline.
That would make each script self-contained, and then both the user and the agent can forego having to worry about creating extra python environments.
| p.add_argument("--yx-pixel-size", type=float, default=0.1, help="lateral pixel size (µm)") | ||
| p.add_argument("--z-pixel-size", type=float, default=1.0, help="axial pixel size (µm)") |
There was a problem hiding this comment.
we should probably allow for anisotropic YX pixels, so separate arguments for y and x.
| - `wo view` starts napari's event loop and **blocks the terminal until closed**. | ||
| When you run it, launch it in the background (`&`, or the Bash tool's | ||
| `run_in_background: true`), tell the user the window is open, and let them | ||
| inspect it. Do not render a static PNG. |
There was a problem hiding this comment.
run_in_background: true is specific to one agent tool. Other agent runtimes use options such as async, background, or a separate process manager. Could we describe the required behavior instead?
maybe?
Start wo view with the environment's long-running process facility. It must not block further commands or inherit interactive stdin. Confirm that the process does not exit immediately, then ask the user to confirm that the napari window is visible.
If only a POSIX shell is available:
wo view ./data.zarr ./recon.zarr </dev/null &This keeps the main instruction tool-independent.
| - Widefield: `confocal_pinhole_diameter: null`. | ||
| - Confocal: set `confocal_pinhole_diameter`. |
There was a problem hiding this comment.
We should flag that this only works for 3D flourescence
2 participants
Adds an onboarding path for first-time waveorder users: a written tutorial, an agentic skill that walks the same workflow interactively, and a small skill for inspecting transfer functions.
docs/guide/first-reconstruction.md: a six-stage guide from raw data to a tuned reconstruction: is waveorder right for you, what data and metadata do you have, draft reconstructions, manual sweeps, automatic tuning, and scaling up. Linked at the top of the README..skills/waveorder-tutorial: the agentic companion to the guide. The agent asks the stage questions, converts data to OME-Zarr, writes draft configs, runs sweeps, and shows everything in napari. Includes reference docs and scripts (example data fetch, TIFF/array converter, ROI cropper, and a 1D/2D sweep helper)..skills/visualize-otf-from-config: computes a transfer function from a config and opens it in napari.How to trial: check out this branch, open Claude Code in the repo root, and run
/waveorder-tutorial. With no data of your own it fetches a small sample and reconstructs 2D phase from a defocus stack; bring your own TIFF/zarr/array for a complete test.