feat(transform): resample onto a reference grid, and warp in one pass

[vboussot]

Stacked on #82.

A cohort has to be on one grid before it can be folded, and until now that meant a separate
resampling pass before the transform. Two stages close it:

• ResampleToReference puts a case on the grid of a declared reference case — extents, spacing,
  origin and direction — so the members of a Reduce meet on a grid that is one of their own
  rather than an invented one.
• The same stage takes an optional field:, which composes the grid change and the displacement
  into a single resampling. Two passes over a volume become one, and the intermediate — a case
  resampled onto the reference but not yet warped — never has to exist on disk.

The plan grew a notes column for what the stages know about themselves: a nested inference whose
memory nothing can bound, a case that meets only part of the grid it is being resampled onto.
A verdict and a byte count are what the plan computes about a chain; this is what a chain says
about itself.

Rebased onto the tip of the stack. The Warp bound reading moved into a _DisplacementSource
shared with the new stage, and the guard fix from #80 was carried into the moved copy — its test
(an unreadable entry in a directory-backed field group) passes against the relocated code.

1342 unit tests pass on this branch.

Summary by CodeRabbit

• New Features

  • Added ResampleToReference for resampling data onto a stored reference grid.
  • Added support for displacement-field warping, affine offsets, fill values, streaming, and inverse processing.
  • Added plan notes that highlight memory and coverage considerations.

• Documentation

  • Expanded guidance for regridding, validation, streaming behavior, overlap handling, and global statistics.
  • Clarified locality distinctions between rescaling and regridding.

• Bug Fixes

  • Improved geometry, bounds, overlap, and displacement-field validation.
  • Removed the obsolete ShapeUpdate transform.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: db954044-1828-426f-a85d-eafb1e90e217

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The PR adds ResampleToReference with physical-grid mapping, displacement-field support, fill handling, validation, streaming, and inverse processing. It adds REGRID locality and planner notes, shares displacement handling with Warp, removes ShapeUpdate, and updates documentation and tests.

Changes

Regridding and planning

Layer / File(s)	Summary
Regridding locality and offset sampling konfai/data/transform.py, konfai/data/data_manager.py, konfai/data/patching.py, docs/source/config_guide/transform.md	Adds REGRID locality. Extends resampling with affine offsets, out-of-bounds fill values, and region-streaming support.
Shared displacement-field source konfai/data/transform.py	Shares displacement-field lookup, bounds validation, and region reads between Warp and reference resampling.
Reference-grid resampling flow konfai/data/transform.py, tests/unit/test_resample_to_reference.py, tests/unit/test_transform_locality_contract.py, tests/integration/test_transform_doc_examples.py, docs/source/config_guide/transform.md	Adds ResampleToReference with reference-grid metadata, geometry validation, displacement-field composition, streaming, coverage handling, and inverse mapping.
Plan notes and statistic migration konfai/transformer.py, konfai/data/transform.py, tests/unit/test_per_component_statistic.py, docs/source/config_guide/transform.md	Adds transform-provided plan notes and reporting. Removes ShapeUpdate and updates per-component statistic guidance and tests.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related PRs

• fideus-labs/KonfAI#41: Extends the locality and patch-streaming framework used by this change.
• fideus-labs/KonfAI#60: Shares physical-space and displacement-field resampling functionality.
• fideus-labs/KonfAI#77: Introduces the displacement-field handling that this PR shares with ResampleToReference.

Sequence Diagram(s)

sequenceDiagram
  participant TransformPlan
  participant ResampleToReference
  participant ReferenceDataset
  participant SourceDataset
  TransformPlan->>ResampleToReference: plan target grid and locality
  ResampleToReference->>ReferenceDataset: read reference geometry
  ResampleToReference->>SourceDataset: read source regions and displacement field
  ResampleToReference-->>TransformPlan: return streamed resampled regions

Loading

Poem

A rabbit hops across the grid,
While fields bend paths where pixels hid.
Reference points now guide the way,
Notes tell planners what to say.
REGRID streams through burrows bright.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description explains the feature and test result but omits the required template sections, checklist confirmations, testing command, and breaking-change status.	Use the required sections and state related issues, change type, test command and result, checklist status, and whether breaking changes require migration guidance.
Docstring Coverage	⚠️ Warning	Docstring coverage is 8.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the main feature: resampling onto a reference grid and applying displacement-field warping in one pass.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/resample-to-reference

---

_{Comment @coderabbitai help to get the list of available commands.}

[vboussot]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[vboussot]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/source/config_guide/transform.md`:
- Around line 460-475: Remove the duplicate “Statistics a stage may ask for”
subsection and fold only its fallback rule into the existing “Statistics a stage
can ask for” section near the statistics table. Preserve the table’s complete
per-component statistics list, and state that when a stage receives the whole
volume through a fallback path, it should compute the statistic from that tensor
and record it so both execution paths produce the same state.

In `@konfai/data/transform.py`:
- Around line 2380-2385: Update the bound-discovery loop around group_for and
root._root_for so it scans every root that contains the group instead of using
only the root returned for None. For each matching root, enumerate its entries
and collect the maximum bound across all fields, while preserving the existing
handling for unreadable fields and roots without the group.

In `@konfai/transformer.py`:
- Around line 550-552: Update the stage-planning flow around plan_note() to pass
each stage its effective input geometry rather than manager.base_shape and
manager.stored_attributes. Walk the chain using copied shape and Attribute
state, applying each preceding stage’s transform_shape() before planning the
next stage, and preserve the draw-specific geometry when an Expand stage is
present.

In `@tests/unit/test_per_component_statistic.py`:
- Around line 40-61: Implement an identity transform_shape() method on
_CentreAndScale that returns the input shape unchanged, preserving all spatial
geometry metadata while retaining the existing __call__ behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: fc094c4b-c232-40c1-9868-be4c08e97cd0

📥 Commits

Reviewing files that changed from the base of the PR and between 1632550 and e511de0.

📒 Files selected for processing (9)

• docs/source/config_guide/transform.md
• konfai/data/data_manager.py
• konfai/data/patching.py
• konfai/data/transform.py
• konfai/transformer.py
• tests/integration/test_transform_doc_examples.py
• tests/unit/test_per_component_statistic.py
• tests/unit/test_resample_to_reference.py
• tests/unit/test_transform_locality_contract.py

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

tests/integration/test_transform_doc_examples.py (1)

147-147: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Use the repository text-I/O policy.

Remove the isolated encoding="utf-8" arguments. The generated configuration is read later with the platform-default encoding. Keep the test and workflow on the same policy.

Based on learnings, use the repository's platform-default text encoding consistently for text I/O and do not add isolated encoding="utf-8" usage.

Also applies to: 158-160, 169-169

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/integration/test_transform_doc_examples.py` at line 147, Update the
text I/O calls in the test around DOC.read_text and the additionally referenced
lines to remove isolated encoding="utf-8" arguments, using the repository’s
platform-default text encoding consistently for both the test input and
generated configuration reads.

Source: Learnings

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tests/unit/test_transformer_workflow.py`:
- Around line 372-374: Update the test description docstring in the resampling
workflow test to state that the complementary output fill fraction is 32.5%,
matching the 67.5% reference coverage expected near line 386; remove the
inaccurate “two thirds” wording without changing test behavior.

---

Nitpick comments:
In `@tests/integration/test_transform_doc_examples.py`:
- Line 147: Update the text I/O calls in the test around DOC.read_text and the
additionally referenced lines to remove isolated encoding="utf-8" arguments,
using the repository’s platform-default text encoding consistently for both the
test input and generated configuration reads.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 2c6fbd6b-f82f-42ea-8368-24fdf3664af9

📥 Commits

Reviewing files that changed from the base of the PR and between e511de0 and 32a93c7.

📒 Files selected for processing (10)

• docs/source/config_guide/transform.md
• konfai/data/data_manager.py
• konfai/data/patching.py
• konfai/data/transform.py
• konfai/transformer.py
• tests/integration/test_transform_doc_examples.py
• tests/unit/test_per_component_statistic.py
• tests/unit/test_resample_to_reference.py
• tests/unit/test_transform_locality_contract.py
• tests/unit/test_transformer_workflow.py

🚧 Files skipped from review as they are similar to previous changes (5)

• konfai/data/data_manager.py
• tests/unit/test_per_component_statistic.py
• tests/unit/test_transform_locality_contract.py
• tests/unit/test_resample_to_reference.py
• konfai/data/transform.py