xenium-ccf-registration

Registers 10x Xenium spatial transcriptomics sections to the Allen Brain CCFv3 atlas using STalign LDDMM alignment.

Updated May 28, 2026
One-click install
npx skills add https://github.com/cpanse/skills --skill xenium-ccf-registration-cpanse
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: xenium-ccf-registration
Source: https://github.com/cpanse/skills/tree/main/single-cell-spatial-general/skills/xenium-ccf-registration
Command: npx skills add https://github.com/cpanse/skills --skill xenium-ccf-registration-cpanse

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires torch, numpy, pandas, matplotlib, scipy, scikit-image, pynrrd, plotly, STalign, and includes references (resource) and assets (resource) components.

What problem does it solve? Mapping cells from 10x Xenium mouse brain sections to standardized Allen Brain CCFv3 regions requires cross-modal diffeomorphic alignment that is fragile: AP slice drift, axis flips, and EM loss collapse routinely produce wrong region assignments. This Skill encodes a validated pipeline with known pitfalls, tuned parameters, and a source patch so each cell gets a correct Allen ontology annotation. ## Core Features & Use Cases - End-to-end registration pipeline: Load Xenium cell coordinates, rasterize sections, match the best CCF coronal slice via edge-based Dice/NCC scoring, run GPU-accelerated LDDMM 3D-to-slice alignment, and warp atlas annotations into Xenium space. - Per-cell brain region annotation: Map every cell to Allen regions with ontology hierarchy traversal, depth-based rollups, and official Allen colors, exported as CSV/JSON plus overlay, parcellation, scatter, and bar-chart visualizations. - Battle-tested troubleshooting guidance: Documents the freeze_ap source patch, negative scale_x DV-flip fix, sigmaM tuning, and atlas brain-mask construction to avoid common failure modes. - Use Case: A researcher with a fresh-frozen mouse brain Xenium run needs per-cell brain region labels for a hippocampal study; this Skill produces the aligned annotation table and publication-ready figures on a GPU server via Pixi and Quarto. ## Quick Start Ask the agent to register your Xenium cells.csv.gz to the Allen CCFv3 atlas and generate a brain region annotation report using the provided Pixi environment and Quarto template.

Frequently Asked Questions about xenium-ccf-registration

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I register Xenium spatial transcriptomics data to the Allen Brain CCF atlas?

Use STalign's LDDMM_3D_to_slice alignment: rasterize Xenium cell coordinates at 10µm, match the best CCF coronal slice with edge-based Dice/NCC scoring, then run diffeomorphic alignment and warp the annotation volume into Xenium space. Cells are annotated via analyze3Dalign.

What GPU and environment are required for STalign CCF registration?

A CUDA 12+ GPU such as L40S is required, with PyTorch CUDA builds, numpy<2, and STalign installed via pip --no-deps. The provided pixi.toml defines the full environment including post-install and verification tasks.

Why does STalign drift away from the selected CCF slice during alignment?

LDDMM_3D_to_slice freely optimizes the AP translation and affine row, causing slice drift. Apply the freeze_ap source patch, which zeros T.grad[0] and L.grad[0,:] before each update step to lock the AP position.

Why are Xenium cells assigned to wrong brain regions after alignment?

Mismatched scale_x and scale_y between LDDMM_3D_to_slice and analyze3Dalign cause wrong assignments; pass identical values to both. Also ensure scale_x is negative because the atlas DV axis runs opposite to Xenium Y.

What causes the STalign EM loss to flatline early during optimization?

A sigmaM that is too tight (e.g., 0.3 in some setups) collapses EM to a local minimum around iteration 100. Use sigmaM=1.0 with diffeo_start=500, and build the atlas brain mask from annotation > 0 rather than a Nissl intensity threshold.

Can Xenium to CCF slice matching be done automatically without manual inspection?

Edge-based Dice plus NCC scoring selects a candidate slice automatically, but cross-modal matching is unreliable for nearby AP slices with similar outlines. Visual inspection of the CCF gallery and setting SLICE_OVERRIDE is recommended when anatomy matters.