Add subject mapping adapter examples

[fepegar]

[Generated by a coding agent]

---

Summary

• refactor MONAI and Cornucopia adapters onto SubjectsBatch.map_subjects()
• preserve copy semantics, prior histories, annotations, and deterministic metadata order
• validate adapter result types and arity instead of silently dropping or misassigning outputs
• add executable custom-transform examples for vectorized images, batched metadata, text mapping, and exact replay

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. #1495 — exact transform parameter replay
4. Add subject mapping adapter examples #1496 — subject mapping adapters and examples (this PR)

[github-actions]

📖 Docs Preview

Preview of the documentation for this PR:

🔗 https://smokeshow.helpmanual.io/1h4l0m671q3q0v2d215w/

_{Built from 8e30d6e}

[Copilot]

Pull request overview

This PR updates TorchIO’s MONAI and Cornucopia adapter transforms to apply per-subject logic via SubjectsBatch.map_subjects() (preserving batching semantics like history/annotations), tightens adapter output validation to avoid silently dropping unsupported outputs, and adds/links new documentation examples for writing batch-native and subject-mapped custom transforms.

Changes:

• Refactor MonaiAdapter and CornucopiaAdapter to use SubjectsBatch.map_subjects() and fix probability gating edge case when p=0 and the random draw is exactly 0.
• Make adapter output handling stricter (e.g., explicit rejection of new tensor keys / non-tensor outputs) and add tests covering metadata updates, history/annotation preservation, and the p=0 edge case.
• Add a new “Write a custom transform” how-to and update conceptual/migration docs + nav to reference the new batching/mapping and replay APIs.

Reviewed changes

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

Show a summary per file

File	Description
zensical.toml	Adds the new custom transform how-to page to site navigation.
tests/test_monai_adapter.py	Adds coverage for metadata updates, explicit rejection of new tensor fields, preserved history/annotations, and p=0 edge case.
tests/test_cornucopia_adapter.py	Adds coverage for preserved history/annotations, p=0 edge case, and non-tensor output rejection.
src/torchio/transforms/monai_adapter.py	Switches to map_subjects(), fixes p=0 edge case, and makes dict-transform outputs explicit/validated (no silent drops).
src/torchio/transforms/cornucopia_adapter.py	Switches to map_subjects(), fixes p=0 edge case, and enforces tensor outputs.
docs/how-to/custom-transform.md	New executable examples for vectorized image ops, batched metadata ops, subject-wise mapping, and exact replay.
docs/get-started/migration.md	Updates migration guidance to use map_subjects() and clarifies schema/annotation constraints.
docs/concepts/transforms.md	Updates schema rules, clarifies spatial+annotation behavior, and documents apply_with_params() replay with links to the new how-to.

---

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 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

The adapter and custom-transform features remain, now built on the simplified exact-history model.