Document the simplified batching model

[fepegar]

[Generated by a coding agent]

---

What

Document the simplified batching model and add a reproducible CPU/CUDA batching benchmark.

Why

The public model changes from optional templates and shared batch traces to factory construction, private prototypes, and exact per-element histories. Users and transform authors need executable guidance, and performance claims need a repeatable measurement tool.

How

• update data-model, transform, and migration documentation
• add a custom-transform how-to for image tensors, metadata, mapping, and replay
• add the requested batching-redesign.md architecture overview
• add benchmarks/batching.py for construction, unbatching, transforms, inversion, and metadata-only batches
• document every public argument introduced or changed by the stack

Validation

• full test suite
• Ruff format/lint and ty
• 21 documentation code blocks
• Zensical documentation build
• full prek hook suite, including Xenon
• benchmark smoke run on CPU and CUDA

Replacement stack

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

[github-actions]

📖 Docs Preview

Preview of the documentation for this PR:

🔗 https://smokeshow.helpmanual.io/05555t0d066w526l3a6c/

_{Built from aca0d66}

[Copilot]

Pull request overview

This PR updates TorchIO’s documentation to describe the redesigned batching/transform execution model (factories, prototypes, exact per-element histories, replay/mapping), and adds a small benchmark script to measure core batching operations on CPU/CUDA.

Changes:

• Added a new “Write a custom transform” how-to with executable examples for batched tensors, metadata, subject-wise mapping, and exact replay.
• Updated core conceptual docs and migration guidance to reflect schema requirements, exact per-element histories, and annotation limitations in spatial transforms.
• Added an architecture overview (batching-redesign.md) and a reproducible batching benchmark script (benchmarks/batching.py).

Reviewed changes

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

Show a summary per file

File	Description
zensical.toml	Adds the new custom-transform how-to page to the docs navigation.
docs/how-to/custom-transform.md	New how-to page with custom-transform patterns and replay/mapping examples.
docs/get-started/migration.md	Migration guidance updated for schemas, annotations, mapping, and exact replay.
docs/concepts/transforms.md	Documents exact replay via apply_with_params() and exact per-element batch histories.
docs/concepts/data-model.md	Documents prototypes/factories and per-element histories in the data model.
benchmarks/batching.py	Adds a CPU/CUDA batching benchmark script.
batching-redesign.md	Adds an architecture/decision overview for the batching redesign.

---

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

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (3)

benchmarks/batching.py:67

• The benchmark wraps the transform call in an extra copy.deepcopy(batch), but Transform already deep-copies the input when copy=True (the default). This double-copy can dominate the measured time and make the results less representative.

        "vectorized transform": _measure(
            lambda: transform(copy.deepcopy(batch)),
            _ITERATIONS,
        ),

benchmarks/batching.py:41

• Calling torch.cuda.synchronize() whenever CUDA is available can initialize CUDA during the CPU benchmark and skew timings. Consider synchronizing only if CUDA has already been initialized (i.e., you're actually benchmarking CUDA work).

    if torch.cuda.is_available():
        torch.cuda.synchronize()

benchmarks/batching.py:46

• Same as above: synchronizing whenever CUDA is available can introduce overhead into CPU benchmarks. Guarding on torch.cuda.is_initialized() avoids triggering CUDA initialization on CPU-only runs.

    if torch.cuda.is_available():
        torch.cuda.synchronize()

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

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (1)

benchmarks/batching.py:82

• In the CUDA run, the "metadata-only" operation doesn’t perform any CUDA work (it builds a batch of Python ints), but _measure(..., device) will still call torch.cuda.synchronize(). That adds unrelated sync overhead to the timing and can skew the reported CUDA numbers for this row.

Pass a CPU device here (since synchronization is the only device-dependent behavior) so the measurement reflects just the metadata-only batching cost.

        "metadata-only": _measure(
            lambda: tio.SubjectsBatch.from_subjects(metadata_subjects),
            _ITERATIONS,
            device,
        ),

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

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

[Copilot]

Pull request overview

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