Spatial spot coordinate registration

spatial-spot-coordinate-registration

License: restricted — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution. <!-- asb-license-banner -->

Summary

Register and align spot coordinates between spatial transcriptome and metabolome datasets using modified spatial morphological alignment to enable spot-to-spot data integration. This skill achieves high-resolution correspondence between two modalities' spatial coordinate systems for joint analysis.

When to use

When you have paired spatial transcriptome and metabolome datasets with spot-based coordinates that need to be aligned for multi-modal integration. Use this skill if your goal is to establish one-to-one spot correspondence between two modalities and you have already identified high-correlated feature pairs across them.

When NOT to use

• Input datasets are not spot-based or do not have explicit 2D/3D spatial coordinates
• High-correlated feature pairs have not yet been identified between modalities
• Spatial coordinates are already pre-aligned or from a single modality only

Inputs

• spatial transcriptome h5ad file with obsm['spatial'] coordinate matrix
• spatial metabolome h5ad file with obsm['spatial'] coordinate matrix
• feature matrix X (np.ndarray) for both modalities
• spatial coordinate matrix D (np.ndarray) for both modalities
• optional cluster label arrays for validation

Outputs

• aligned spot coordinate mappings between modalities
• integrated feature matrix combining aligned features from both datasets
• registration validation metrics (coordinate correspondence, spot overlap)

How to apply

Load both spatial datasets as Data objects containing feature matrices (X as np.ndarray), spatial coordinate matrices (D from obsm['spatial']), and optional cluster labels. Apply a sequence of three alignment methods in order: (1) manual_gross_alignment to establish initial coarse correspondence, (2) icp_3d_alignment to refine spatial registration using iterative closest point, and (3) direct_alignment to produce the final aligned feature predictions. Validate alignment accuracy by checking coordinate correspondence and computing spot overlap metrics between registered spot positions.

Related tools

• haCCA (Primary workflow tool implementing manual_gross_alignment, icp_3d_alignment, and direct_alignment methods for spatial spot coordinate registration) — https://github.com/LittleLittleCloud/haCCA

Examples

from hacca import *; a = Data(X=a_h5ad.X.toarray(), D=a_h5ad.obsm['spatial']); b_prime = Data(X=b_prime_h5ad.X.toarray(), D=b_prime_h5ad.obsm['spatial']); _b_prime = hacca.manual_gross_alignment(a, b_prime); _a, _b_prime = hacca.icp_3d_alignment(a, _b_prime); b_predict = hacca.direct_alignment(_a, _b_prime)

Evaluation signals

• Coordinate correspondence validated: aligned spot positions in modality A should map to nearest neighbors in modality B within expected tolerance
• Spot overlap metrics computed: quantify fractional overlap and distance statistics between registered spot coordinate sets
• Feature consistency check: high-correlated feature pairs used for alignment should maintain or improve correlation in aligned output
• Spatial structure preservation: relative neighborhood relationships in original coordinates should be maintained after alignment
• Output schema validation: aligned coordinate matrices and integrated feature matrix should have matching row counts and valid spatial ranges

Limitations

• Requires accurate initial coarse alignment (manual_gross_alignment step); poor initial alignment may cause ICP convergence to local minima
• Performance depends on quantity and quality of high-correlated feature pairs; sparse or noisy correlations may degrade registration accuracy
• Method assumes spots in both modalities correspond to the same tissue regions; global coordinate system mismatch may not be fully resolvable
• No changelog provided in repository; algorithm details and validation metrics not fully specified in available documentation

Evidence

• [readme] haCCA, a workflow utilizing high Correlated feature pairs combined with a modified spatial morphological alignment: "haCCA, a workflow utilizing high Correlated feature pairs combined with a modified spatial morphological alignment to ensure high resolution and accuracy of spot-to-spot data integration"
• [other] Modified spatial morphological alignment component operate to align spatial transcriptome and metabolome spots: "Modified spatial morphological alignment to achieve spot-to-spot data integration of spatial transcriptomes and metabolomes"
• [readme] Alignment methods applied in sequence: "manual_gross_alignment | icp_3d_alignment | direct_alignment"
• [readme] Data object structure requirements: "Data is a triplet of (X: np.ndarray, D: np.ndarray, Label: Optional[np.ndarray]), where X is the feature matrix, D is the spatial matrix that contains the location information"
• [other] Validation procedure for alignment accuracy: "Validate alignment accuracy by verifying coordinate correspondence and spot overlap metrics"