HolobiomicsLab spatial-spot-coordinate-registration
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"