high-resolution-spot-to-spot-integration
Summary
This skill applies haCCA's modified spatial morphological alignment combined with high-correlated feature pair identification to integrate spatial transcriptome and metabolome spot coordinate systems with high accuracy. Use it when you have paired spatial omics datasets (transcriptomics and metabolomics) acquired on the same tissue section and need to align spots between modalities for multi-omics analysis.
When to use
You have two spatial omics datasets (e.g., spatial transcriptome and metabolome spot matrices) collected from the same or adjacent tissue sections, with both feature matrices (X: np.ndarray) and spatial coordinates (D: np.ndarray containing location information in .h5ad obsm['spatial'] format), and you need spot-to-spot correspondence to perform integrated downstream analysis across modalities.
When NOT to use
- Datasets are from different tissue sections or regions without spatial overlap — alignment will fail to find meaningful correspondences
- One or both datasets lack spatial coordinate information or are already pre-aligned — the alignment step would be redundant
- Feature matrices contain very sparse or low-quality data with insufficient correlated feature pairs for anchor identification
Inputs
- spatial transcriptome .h5ad file (X: feature matrix, obsm['spatial']: coordinate matrix)
- spatial metabolome .h5ad file (X: feature matrix, obsm['spatial']: coordinate matrix)
- Data object triplets: (feature_matrix: np.ndarray, spatial_coordinates: np.ndarray, optional_labels: np.ndarray)
Outputs
- aligned spatial coordinate mappings between modalities
- integrated feature matrix with spot-to-spot correspondence
- alignment validation metrics (coordinate correspondence, spot overlap)
How to apply
Load both datasets as Data objects (triplets of feature matrix X, spatial coordinate matrix D, and optional cluster labels). First, identify high-correlated feature pairs between the two modalities to establish cross-modal anchors. Second, apply the modified spatial morphological alignment algorithm in a three-stage pipeline: (1) manual_gross_alignment for coarse registration, (2) icp_3d_alignment for refined spatial registration, and (3) direct_alignment for final spot-to-spot mapping. Validate alignment accuracy by verifying coordinate correspondence and measuring spot overlap metrics between registered spots. The rationale is that high-correlation features provide biological signal for anchor selection, while progressive refinement from gross to fine alignment ensures robust convergence even with initial spatial misalignment.
Related tools
- haCCA (primary workflow implementation for correlated feature pair identification and modified spatial morphological alignment) — github.com/LittleLittleCloud/haCCA
- hacca Python package (pip-installable implementation providing manual_gross_alignment, icp_3d_alignment, and direct_alignment methods) — https://badge.fury.io/py/hacca
Examples
from hacca import *; import scanpy as sc; a = Data(X=sc.read_h5ad('transcriptome.h5ad').X.toarray(), D=sc.read_h5ad('transcriptome.h5ad').obsm['spatial']); b_prime = Data(X=sc.read_h5ad('metabolome.h5ad').X.toarray(), D=sc.read_h5ad('metabolome.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 between aligned spots meets spatial distance threshold (e.g., <1 spot diameter)
- Spot overlap metrics show high consistency across modality pairs (>0.8 overlap coefficient)
- High-correlated feature pairs (identified in first step) show consistent spatial localization post-alignment
- Integrated feature matrix dimensions match expected cardinality (rows = aligned spots, columns = combined features from both modalities)
- Visual inspection of aligned spot coordinates shows minimal systematic translation, rotation, or scaling artifacts
Limitations
- Requires both datasets to originate from the same or immediately adjacent tissue sections with biological overlap
- Alignment accuracy depends critically on the availability of high-correlated feature pairs; datasets with low cross-modal correlation will produce poor alignments
- Three-stage alignment pipeline may require manual parameter tuning for datasets with unusual spatial scaling or orientation differences
- No changelog provided in repository documentation, limiting reproducibility across versions
Evidence
- [other] haCCA integrates high correlated feature pairs with a modified spatial morphological alignment to achieve spot-to-spot data integration: "haCCA integrates high correlated feature pairs with a modified spatial morphological alignment to achieve spot-to-spot data integration of spatial transcriptomes and metabolomes"
- [intro] ensure high resolution and accuracy of spot-to-spot data integration of spatial transcriptomes and metabolomes: "ensure high resolution and accuracy of spot-to-spot data integration of spatial transcriptomes and metabolomes"
- [readme] 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: "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"
- [readme] Infer b_predict from (a, b_prime) using the following alignment methods: manual_gross_alignment | icp_3d_alignment | direct_alignment: "Infer b_predict from (a, b_prime) using the following alignment methods: manual_gross_alignment | icp_3d_alignment | direct_alignment"
- [other] Apply the modified spatial morphological alignment algorithm to register spots between modalities. Validate alignment accuracy by verifying coordinate correspondence and spot overlap metrics: "Apply the modified spatial morphological alignment algorithm to register spots between modalities. Validate alignment accuracy by verifying coordinate correspondence and spot overlap metrics"
1---2name: high-resolution-spot-to-spot-integration-23description: Use when you have two spatial omics datasets (e.g., spatial transcriptome and metabolome spot matrices) collected from the same or adjacent tissue sections, with both feature matrices (X: np.ndarray) and spatial coordinates (D: np.ndarray containing location information in .4license: CC-BY-4.05---67# high-resolution-spot-to-spot-integration89## Summary1011This skill applies haCCA's modified spatial morphological alignment combined with high-correlated feature pair identification to integrate spatial transcriptome and metabolome spot coordinate systems with high accuracy. Use it when you have paired spatial omics datasets (transcriptomics and metabolomics) acquired on the same tissue section and need to align spots between modalities for multi-omics analysis.1213## When to use1415You have two spatial omics datasets (e.g., spatial transcriptome and metabolome spot matrices) collected from the same or adjacent tissue sections, with both feature matrices (X: np.ndarray) and spatial coordinates (D: np.ndarray containing location information in .h5ad obsm['spatial'] format), and you need spot-to-spot correspondence to perform integrated downstream analysis across modalities.1617## When NOT to use1819- Datasets are from different tissue sections or regions without spatial overlap — alignment will fail to find meaningful correspondences20- One or both datasets lack spatial coordinate information or are already pre-aligned — the alignment step would be redundant21- Feature matrices contain very sparse or low-quality data with insufficient correlated feature pairs for anchor identification2223## Inputs2425- spatial transcriptome .h5ad file (X: feature matrix, obsm['spatial']: coordinate matrix)26- spatial metabolome .h5ad file (X: feature matrix, obsm['spatial']: coordinate matrix)27- Data object triplets: (feature_matrix: np.ndarray, spatial_coordinates: np.ndarray, optional_labels: np.ndarray)2829## Outputs3031- aligned spatial coordinate mappings between modalities32- integrated feature matrix with spot-to-spot correspondence33- alignment validation metrics (coordinate correspondence, spot overlap)3435## How to apply3637Load both datasets as Data objects (triplets of feature matrix X, spatial coordinate matrix D, and optional cluster labels). First, identify high-correlated feature pairs between the two modalities to establish cross-modal anchors. Second, apply the modified spatial morphological alignment algorithm in a three-stage pipeline: (1) manual_gross_alignment for coarse registration, (2) icp_3d_alignment for refined spatial registration, and (3) direct_alignment for final spot-to-spot mapping. Validate alignment accuracy by verifying coordinate correspondence and measuring spot overlap metrics between registered spots. The rationale is that high-correlation features provide biological signal for anchor selection, while progressive refinement from gross to fine alignment ensures robust convergence even with initial spatial misalignment.3839## Related tools4041- **haCCA** (primary workflow implementation for correlated feature pair identification and modified spatial morphological alignment) — github.com/LittleLittleCloud/haCCA42- **hacca Python package** (pip-installable implementation providing manual_gross_alignment, icp_3d_alignment, and direct_alignment methods) — https://badge.fury.io/py/hacca4344## Examples4546```47from hacca import *; import scanpy as sc; a = Data(X=sc.read_h5ad('transcriptome.h5ad').X.toarray(), D=sc.read_h5ad('transcriptome.h5ad').obsm['spatial']); b_prime = Data(X=sc.read_h5ad('metabolome.h5ad').X.toarray(), D=sc.read_h5ad('metabolome.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)48```4950## Evaluation signals5152- Coordinate correspondence between aligned spots meets spatial distance threshold (e.g., <1 spot diameter)53- Spot overlap metrics show high consistency across modality pairs (>0.8 overlap coefficient)54- High-correlated feature pairs (identified in first step) show consistent spatial localization post-alignment55- Integrated feature matrix dimensions match expected cardinality (rows = aligned spots, columns = combined features from both modalities)56- Visual inspection of aligned spot coordinates shows minimal systematic translation, rotation, or scaling artifacts5758## Limitations5960- Requires both datasets to originate from the same or immediately adjacent tissue sections with biological overlap61- Alignment accuracy depends critically on the availability of high-correlated feature pairs; datasets with low cross-modal correlation will produce poor alignments62- Three-stage alignment pipeline may require manual parameter tuning for datasets with unusual spatial scaling or orientation differences63- No changelog provided in repository documentation, limiting reproducibility across versions6465## Evidence6667- [other] haCCA integrates high correlated feature pairs with a modified spatial morphological alignment to achieve spot-to-spot data integration: "haCCA integrates high correlated feature pairs with a modified spatial morphological alignment to achieve spot-to-spot data integration of spatial transcriptomes and metabolomes"68- [intro] ensure high resolution and accuracy of spot-to-spot data integration of spatial transcriptomes and metabolomes: "ensure high resolution and accuracy of spot-to-spot data integration of spatial transcriptomes and metabolomes"69- [readme] 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: "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"70- [readme] Infer b_predict from (a, b_prime) using the following alignment methods: manual_gross_alignment | icp_3d_alignment | direct_alignment: "Infer b_predict from (a, b_prime) using the following alignment methods: manual_gross_alignment | icp_3d_alignment | direct_alignment"71- [other] Apply the modified spatial morphological alignment algorithm to register spots between modalities. Validate alignment accuracy by verifying coordinate correspondence and spot overlap metrics: "Apply the modified spatial morphological alignment algorithm to register spots between modalities. Validate alignment accuracy by verifying coordinate correspondence and spot overlap metrics"
HolobiomicsLab