/spatial-register

name: spatial-register
description: Load when aligning multiple spatial slices into a common coordinate frame with PASTE or STalign. Skip single-slice data; for expression-space batch correction use spatial-integrate.
trigger: spatial registration, slice alignment, PASTE, STalign
tags:
- spatial
- registration
- alignment

spatial-register

Use from a step

from skills._sdk.notebook import load_skill, read_input, write_output
library = load_skill("spatial-register")
adata = library.register(read_input("data/slices.h5ad"), slice_key="slice")
write_output(adata, "intermediate/registered.h5ad")

When to use

Align slice coordinates while preserving the original spatial coordinates. PASTE uses expression and spatial distances; STalign supports two slices. For expression-space correction use spatial-integrate instead.

Inputs & Outputs

Input: AnnData with expression, spatial coordinates and a slice-label column. The default reference is the first sorted label, not the largest slice. Functions return the same AnnData, shift tables and figures without writing files.

CLI writes `processed.h5ad`, `report.md`, `result.json`, registration tables and the before/after gallery. See [references/output_contract.md](references/output_contract.md) for the complete file inventory. Registered coordinates are `obsm["spatial_aligned"]`; `spatial` and `X_spatial`, if present, remain unchanged.

Key CLI

python skills/spatial/spatial-register/spatial_register.py --input slices.h5ad --output results/registration --slice-key slice --method paste
python skills/spatial/spatial-register/spatial_register.py --demo --output /tmp/spatial_register

`examples/example_step.py` aligns unequal-size simulated slices through the step runner. [references/parameters.md](references/parameters.md) lists backend flags.

Gotchas

• `spatial_aligned` is a separate coordinate basis; downstream skills do not

automatically switch from `spatial`.

• PASTE transports source spots with the transpose of its reference-by-source

coupling. The old `_lib/register.py:run_paste` direction was incorrect; unequal slice sizes now work, and solver failures raise instead of reporting success.

• The historical `disparities` summary is sum of squared transport weights,

not the optimal-transport objective or a calibrated fit statistic.

• The tested PASTE 1.4.0 combination needs POT 0.9.4. POT 0.9.5 and 0.9.6 changed

the line-search call and fail inside PASTE. Use an isolated compatible environment.

• STalign is optional and was not executed in this migration environment.

It has no exposed seed control here; do not claim deterministic GPU results.

• `tables/registration_metrics.csv` has NaN disparity where the backend

does not report it. Inspect shifts without treating smaller displacement as better alignment.

API

<!-- api:begin generated from _api.py; regenerate with run.py api <skill dir> --write -->

`register(adata, *, method: str='paste', slice_key: str | None=None, reference_slice: str | None=None, **parameters)`

Add aligned coordinates in place without overwriting the input coordinates.

:param adata: AnnData with expression, spatial coordinates and slice labels. :param method: paste (default) for transport or stalign for two-slice LDDMM. :param slice_key: Observation column; None detects slice, sample, section or batch. :param reference_slice: Target label; None uses the first sorted label. :param parameters: PASTE alpha=0.1, dissimilarity='kl', use_gpu=False; STalign image_size=(400,400), niter=2000, a=500, use_expression=False. PASTE is deterministic on CPU; STalign has no seed control and may vary. :returns: The same AnnData with spatial_aligned and JSON run diagnostics. :raises ValueError: Invalid labels, coordinates, method or method parameters. :raises ImportError: Missing backend; use install_skill_deps for paste-bio/POT or STalign/torch as appropriate. :raises RuntimeError: A slice cannot be aligned; partial success is not returned.

`run_info(adata, *, keep: bool=True) -> dict`

Read the last registration summary.

:param adata: Registered AnnData. :param keep: True retains diagnostics; False removes them for CLI serialization. :returns: Summary with reference, slices and effective parameters, or an empty dict.

`shift_table(adata) -> pd.DataFrame`

Measure Euclidean displacement from original to registered coordinates.

:param adata: AnnData with spatial_aligned and original spatial coordinates. :returns: observation and shift_distance columns, in observation order. :raises KeyError: Aligned coordinates are absent. :raises ValueError: Original coordinates are absent.

`registration_figure(adata, *, slice_key: str | None=None)`

Plot original and registered slice coordinates side by side.

:param adata: Registered AnnData. :param slice_key: Slice label column; None detects the column from the data. :returns: A matplotlib Figure; the caller saves and closes it. :raises KeyError: Aligned coordinates or labels are absent.

<!-- api:end -->

Dependencies

`anndata`, `matplotlib`, `numpy`, `pandas`, `paste-bio`, `POT`, `scanpy`, `scikit-learn`, `scipy`, `seaborn`, `STalign`, `torch`

The CLI dependency list covers both methods; install only the chosen backend.