📐 Spatial Register

You are Spatial Register, the OmicsClaw skill for aligning spatial coordinates across serial sections or related slices. The wrapper now keeps method-specific alignment behavior intact while exposing a shared gallery, figure-ready exports, and optional downstream R styling.

Why This Exists

• Without it: users have to manually handle slice labels, coordinate systems, and method-specific alignment APIs.
• With it: one command aligns slices, exports aligned coordinates to spatial_aligned, writes registration diagnostics, and emits a stable visualization / figure-data contract.
• Why OmicsClaw: method-specific controls are preserved, slice-key handling is explicit, and the output contract is stable across registration methods.

Core Capabilities

1. PASTE registration: optimal-transport alignment using expression dissimilarity plus spatial distance.
2. STalign registration: pairwise diffeomorphic alignment through LDDMM.
3. Explicit slice handling: the wrapper can auto-detect common slice columns or accept --slice-key.
4. Expression-aware alignment: PASTE always uses expression; STalign can optionally use a wrapper-generated expression signal.
5. Aligned coordinate export: aligned coordinates are written to adata.obsm["spatial_aligned"].
6. Shift diagnostics: OmicsClaw annotates per-observation coordinate displacement as adata.obs["registration_shift_distance"].
7. Standard Python gallery: emits a recipe-driven registration gallery with before/after slice overlays, shift diagnostics, and per-slice summaries.
8. Figure-ready exports: writes figure_data/ CSVs plus a manifest so downstream tools can restyle the same registration result without recomputing PASTE or STalign.
9. Structured outputs: writes report.md, result.json, tabular metrics, and reproducibility helpers including an optional R visualization entrypoint.

Input Formats

Format	Extension	Required Fields	Example
AnnData (multi-slice)	.h5ad	X, obsm["spatial"] or obsm["X_spatial"], real slice labels in obs[...]	serial_sections.h5ad
Demo	n/a	--demo flag	runs spatial-preprocess --demo, then synthesizes two shifted slices

Method-Specific Input Requirements

Method	Input requirements	Notes
paste	expression matrix, spatial coordinates, slice labels, shared genes	current wrapper aligns all non-reference slices to a chosen reference
stalign	exactly 2 slices, spatial coordinates, optional expression-derived signal	current wrapper rasterizes coordinates into images and calls STalign LDDMM

Important:

• PASTE is not a coordinates-only method; expression matters.
• STalign in the current wrapper requires exactly two slices.
• OmicsClaw does not fabricate synthetic slice labels for real input data; a real slice column is required.

Workflow

1. Load: read the multi-slice AnnData.
2. Validate: confirm spatial coordinates and a real slice-label column exist.
3. Run the selected backend.
4. Store aligned coordinates: write adata.obsm["spatial_aligned"].
5. Annotate shift metrics: compute registration_shift_distance and mark the reference slice in adata.obs.
6. Render the standard gallery: build the OmicsClaw registration gallery with before/after slice maps, shift diagnostics, and uncertainty panels.
7. Export figure-ready data: write figure_data/*.csv and figure_data/manifest.json.
8. Report and export: write summary tables, report.md, result.json, processed.h5ad, and reproducibility outputs.

Visualization Contract

OmicsClaw treats spatial-register visualization as a two-layer system:

1. Python standard gallery: the canonical registration result layer.
2. R customization layer: an optional styling layer that reads figure_data/ and does not rerun PASTE or STalign.

The standard gallery is declared as a recipe instead of hard-coded plotting branches. It reuses the shared skills/spatial/_lib/viz feature-map layer for slice overlays and shift projections, while skill-local renderers handle registration-specific summaries such as per-slice displacement bars and shift distance distributions.

Current gallery roles include:

• overview: slice labels before and after registration
• diagnostic: shift magnitude projected onto the aligned coordinate frame
• supporting: per-slice shift summary and method-reported disparity plots
• uncertainty: shift-distance distribution across slices

CLI Reference

# Default alias used by OmicsClaw
oc run spatial-registration \
  --input <multi_slice.h5ad> --output <dir>

# PASTE with explicit reference and alpha
oc run spatial-registration \
  --input <multi_slice.h5ad> --method paste \
  --slice-key slice --reference-slice slice_1 \
  --paste-alpha 0.1 --paste-dissimilarity kl --output <dir>

# PASTE with GPU backend when available
oc run spatial-registration \
  --input <multi_slice.h5ad> --method paste \
  --paste-use-gpu --output <dir>

# STalign pairwise registration
oc run spatial-registration \
  --input <two_slices.h5ad> --method stalign \
  --slice-key slice --reference-slice slice_1 \
  --stalign-niter 3000 --stalign-a 800 --stalign-image-size 600 \
  --use-expression --output <dir>

# Demo mode
oc run spatial-registration --demo --output /tmp/register_demo

# Direct script entrypoint
python skills/spatial/spatial-register/spatial_register.py \
  --input <multi_slice.h5ad> --method paste --output <dir>

Every successful standard OmicsClaw wrapper run, including oc run and conversational skill execution, also writes a top-level README.md and reproducibility/analysis_notebook.ipynb to make the output directory easier to inspect and rerun. Direct script execution primarily produces the skill-native outputs plus reproducibility/commands.sh.

Example Queries

• "Align my serial tissue sections using PASTE and explain alpha first."
• "Register these two slices with STalign and tell me what a changes."
• "Use batch as the slice key and align everything to sample A."

Algorithm / Methodology

PASTE

1. detect the slice column and choose a reference slice
2. intersect genes across slices
3. normalize each slice with normalize_total and log1p
4. run paste.pairwise_align() from each source slice to the reference
5. map source coordinates into the reference frame using the transport plan

Core exposed controls:

• slice_key: wrapper control selecting the obs column that defines slices
• reference_slice: fixed slice
• paste_alpha: public PASTE weight balancing expression dissimilarity and spatial distance
• paste_dissimilarity: public expression dissimilarity choice
• paste_use_gpu: public backend switch

STalign

1. require exactly 2 slices
2. choose the reference slice and source slice
3. optionally derive a 1-D expression signal from PC1 of shared genes
4. rasterize the point clouds into images
5. run STalign LDDMM and warp source coordinates onto the target

Core exposed controls:

• slice_key
• reference_slice
• stalign_niter: public optimization-iteration control
• stalign_a: public smoothness / kernel bandwidth control
• stalign_image_size: wrapper-level rasterization resolution
• use_expression: wrapper-level switch using PC1 intensity instead of uniform intensity

Output Structure

output_dir/
├── README.md
├── report.md
├── result.json
├── processed.h5ad
├── figures/
│   ├── slices_before.png
│   ├── slices_after.png
│   ├── registration_shift_map.png
│   ├── registration_shift_by_slice.png
│   ├── registration_disparities.png       # when method-reported disparities exist
│   ├── registration_shift_distribution.png
│   └── manifest.json
├── figure_data/
│   ├── registration_points.csv
│   ├── registration_shift_by_slice.csv
│   ├── registration_disparities.csv       # when method-reported disparities exist
│   ├── registration_run_summary.csv
│   └── manifest.json
├── tables/
│   ├── registration_summary.csv
│   └── registration_metrics.csv
└── reproducibility/
    ├── analysis_notebook.ipynb
    ├── commands.sh
    ├── environment.txt
    └── r_visualization.sh

The bundled optional R templates live under:

skills/spatial/spatial-register/r_visualization/
├── README.md
└── register_publication_template.R

Safety

• Local-first: all registration stays local.
• Real slice labels required: the wrapper fails fast if no slice label column can be detected.
• Audit trail: reports, result.json, figures/manifest.json, and figure_data/manifest.json record only the parameters relevant to the selected backend plus the gallery outputs.
• Method-aware explanation: PASTE and STalign are not interchangeable and should not be described as such.
• Canonical output boundary: Python gallery is canonical; optional R styling consumes figure_data/ and must not rerun registration.

Dependencies

Required:

• scanpy
• anndata
• scipy
• numpy, pandas, matplotlib

Optional (Python):

• paste-bio + POT
• STalign + torch

Optional (R):

• ggplot2

Integration with Orchestrator

Trigger conditions:

• spatial registration
• slice alignment
• coordinate alignment
• paste
• stalign

Chaining partners:

• spatial-preprocess — preprocessing before registration
• spatial-integrate — downstream integration after coordinate alignment

Citations

• PASTE — Zeira et al., Nature Methods 2022
• STalign — Clifton et al., Nature Communications 2023