Add exact transform parameter replay

[fepegar]

[Generated by a coding agent]

---

Summary

• add Transform.apply_with_params() for exact parameter application
• share copy, wrapping, type restoration, annotation safety, and history handling with normal execution
• validate per-instance _batch_size, _batched_keys, and _keep dimensions
• bypass probability and sampling while preserving normal history semantics
• explicitly reject replay for composition, adapters, and lazy-only spatial transforms

Validation

• full test suite and cross-platform GitHub Actions
• Ruff lint and formatting
• ty type checking
• documentation tests and Zensical build
• pre-commit.ci, including Xenon complexity checks

Stack (merge bottom-up)

1. ✅ #1493 — documentation corrections — merged
2. #1494 — lossless subject batching — next to merge
3. Add exact transform parameter replay #1495 — exact transform parameter replay (this PR)
4. #1496 — subject mapping adapters and examples

[github-actions]

📖 Docs Preview

Preview of the documentation for this PR:

🔗 https://smokeshow.helpmanual.io/454c2e0c26592v3m3y3v/

_{Built from 6124888}

[Copilot]

Pull request overview

This PR introduces an “exact replay” pathway for TorchIO transforms by adding Transform.apply_with_params(), enabling callers to reapply a transform using a previously recorded parameter dict while preserving the standard execution lifecycle (wrapping/unwrapping, copy semantics, type restoration, and history recording).

Changes:

• Added Transform.apply_with_params() plus shared internal execution via _execute() to avoid duplicating lifecycle logic.
• Implemented validation for reserved per-instance batching fields (_batch_size, _batched_keys, _keep) when replaying parameters.
• Explicitly disabled parameter replay for composition-style transforms and opaque adapter transforms, and added targeted tests covering replay semantics.

Reviewed changes

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

Show a summary per file

File	Description
tests/test_transforms_base.py	Adds comprehensive tests for exact-parameter replay behavior, history semantics, copying, and batched-param validation.
src/torchio/transforms/transform.py	Implements apply_with_params(), refactors execution into _execute(), and validates batched replay metadata.
src/torchio/transforms/monai_adapter.py	Marks MonaiAdapter as not supporting apply_with_params() due to lack of a single param kernel.
src/torchio/transforms/cornucopia_adapter.py	Marks CornucopiaAdapter as not supporting apply_with_params() for the same reason.
src/torchio/transforms/compose.py	Marks Compose/OneOf/SomeOf as not supporting replay and simplifies rebatching error handling to align with current batch-schema validation.

---

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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