Integrate subject mapping and exact replay

[fepegar]

[Generated by a coding agent]

---

What

Integrate subject-wise mapping, exact parameter replay, and MONAI/Cornucopia adapters with the simplified batch model.

Why

Non-vectorizable operations need a supported per-subject path, and exact replay must retain the normal copy/wrap/history lifecycle. Adapters previously duplicated unbatch/rebatch code and silently ignored unsupported outputs.

How

• add SubjectsBatch.map_subjects(copy=...)
• add Transform.apply_with_params() through the shared execution path
• validate transient batched params without persisting private keys
• reject replay for transforms without a compatible exact kernel
• migrate MONAI/Cornucopia adapters to mapping with explicit result validation
• standardize strict p=0 behavior, including lazy CropOrPad

Validation

• full test suite
• Ruff format/lint and ty
• documentation tests and build
• full prek hook suite, including Xenon

Replacement stack

0. #1500 — padding type prerequisite
1. #1501 — batch factories, prototypes, and schema
2. #1502 — exact per-element batch history
3. This PR — mapping, replay, and adapters
4. #1504 — documentation and benchmarks

[github-actions]

📖 Docs Preview

Preview of the documentation for this PR:

🔗 https://smokeshow.helpmanual.io/6j3t43153s2y2a1g066r/

_{Built from 1c8b785}

[Copilot]

Pull request overview

This PR extends TorchIO’s batching/transform infrastructure to support exact parameter replay and per-subject mapping within batches, and updates adapter implementations to use the new batch mapping lifecycle while tightening probability semantics (p=0 is always a no-op).

Changes:

• Add Transform.apply_with_params() and refactor Transform.forward() through a shared execution path that supports exact replay without sampling.
• Add SubjectsBatch.map_subjects() to apply per-subject callbacks (with optional tensor cloning) and rebuild batches with schema validation.
• Update MONAI/Cornucopia adapters and select transforms to reject exact replay where it’s incompatible, and standardize strict p=0 behavior (including lazy CropOrPad).

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tests/test_transforms_base.py	Adds coverage for apply_with_params() replay, history behavior, and batched-param validation.
tests/test_monai_adapter.py	Adds adapter tests for metadata updates, history/annotation preservation, strict p=0, and in-place behavior.
tests/test_crop_or_pad.py	Updates probability test to ensure p=0 is a strict no-op even when RNG draws 0.
tests/test_cornucopia_adapter.py	Adds adapter tests for history/annotations, strict p=0, result validation, and in-place behavior.
tests/test_batch.py	Adds coverage for SubjectsBatch.map_subjects() schema, history retention, and copy semantics.
src/torchio/transforms/transform.py	Introduces apply_with_params(), shared _execute() lifecycle, and batched-param validation helpers.
src/torchio/data/batch.py	Implements SubjectsBatch.map_subjects() built on unbatch() + rebuild with schema checks.
src/torchio/transforms/monai_adapter.py	Refactors adapter to use map_subjects() and validates dict-transform outputs/metadata updates.
src/torchio/transforms/cornucopia_adapter.py	Refactors adapter to use map_subjects() and validates result arity/types.
src/torchio/transforms/spatial/crop_or_pad.py	Makes lazy probability check strict (>=) and disables apply_with_params().
src/torchio/transforms/spatial/ensure_shape_multiple.py	Disables apply_with_params() for this spatial transform.
src/torchio/transforms/compose.py	Disables apply_with_params() for composition/transforms with incompatible replay semantics.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

src/torchio/transforms/transform.py:480

• In _build_history_traces, _batched_keys being present implicitly means batched bookkeeping is active, but _batch_size is only read via params.get(...). If a custom transform returns _batched_keys without a valid _batch_size, the current error becomes Parameter batch size None does not match input batch size ..., which is misleading and doesn’t catch non-int/bool values. Consider validating _batch_size here (similar to _get_expected_batch_size) to produce a clear error for transform authors.

        expected_size = params.get("_batch_size")
        if expected_size != batch_size:
            msg = (
                f"Parameter batch size {expected_size} does not match"
                f" input batch size {batch_size}"

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.