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/162c5808510w275s1w5o/

_{Built from 88d4d99}

[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.

[fepegar]

[Generated by a coding agent]

---

Superseded by the simpler replacement stack:

• Redesign batch construction and schema #1501 — batch factories, mandatory private prototypes, and typed schema validation
• Store exact history per batch element #1502 — exact per-element batch histories
• Integrate subject mapping and exact replay #1503 — mapping, exact replay, and adapter integration
• Document the simplified batching model #1504 — documentation and benchmarks

Exact replay is retained in #1503, while #1502 removes private batching metadata from persisted histories.