Make subject batching lossless

[fepegar]

[Generated by a coding agent]

---

Summary

• validate complete Subject and Image schemas before stacking
• preserve metadata, annotations, image subclasses, and shared/per-element histories
• support metadata-only and annotation-only batches
• add SubjectsBatch.map_subjects() for safe subject-wise processing
• reject spatial transforms on annotations until coordinate updates are supported

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. Make subject batching lossless #1494 — lossless subject batching (this PR; next to merge)
3. #1495 — exact transform parameter replay
4. #1496 — subject mapping adapters and examples

[github-actions]

📖 Docs Preview

Preview of the documentation for this PR:

🔗 https://smokeshow.helpmanual.io/113u4m4m4d1y4e2f4a0t/

_{Built from 8fa6c2e}

[Copilot]

Pull request overview

This PR makes batching/unbatching of Subject/Image data lossless by validating schemas before stacking and preserving per-element payload (metadata, annotations, subclasses) and transform histories. It also introduces safer subject-wise processing via SubjectsBatch.map_subjects() and explicitly rejects spatial transforms when annotations are present (until coordinate updates are supported).

Changes:

• Add full schema validation for subjects/images before stacking, and preserve nested metadata/annotations + image subclass identity across batch round-trips.
• Track and round-trip both shared and per-element transform histories for ImagesBatch and SubjectsBatch, including during wrapping/unwrapping in Transform.
• Add SubjectsBatch.map_subjects() and enforce annotation restrictions for spatial transforms (including lazy spatial forwards).

Reviewed changes

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

Show a summary per file

File	Description
tests/test_transforms_base.py	Adjust tests to use a subject containing multiple images + metadata.
tests/test_batch.py	Add coverage for payload/history round-trips, schema validation, metadata/annotation-only batching, and map_subjects().
src/torchio/transforms/transform.py	Preserve histories when wrapping/unwrapping batches and reject spatial transforms with annotations.
src/torchio/transforms/spatial/ensure_shape_multiple.py	Apply spatial-annotation rejection in the lazy forward path.
src/torchio/transforms/spatial/crop_or_pad.py	Apply spatial-annotation rejection in the lazy forward path.
src/torchio/data/batch.py	Implement lossless batching for images/subjects: schema validation, payload templates, annotation stores, and history helpers.

---

💡 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 8 out of 8 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 3 comments.

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 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 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 replacement keeps the same features while removing optional template state, shared/per-element history duality, and persisted private batching keys.