# Anndata Object Integration And Metadata Mapping

> Use when you have preprocessed and filtered ST and SM AnnData objects with spatial coordinates and features, and you need to establish spot-level correspondence between the two modalities to enable downstream joint analysis.

- Skill: `holobiomicslab/anndata-object-integration-and-metadata-mapping` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/anndata-object-integration-and-metadata-mapping`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/anndata-object-integration-and-metadata-mapping/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/anndata-object-integration-and-metadata-mapping

---


# anndata-object-integration-and-metadata-mapping

## Summary

Combines preprocessed spatial transcriptomics (ST) and spatial metabolomics (SM) AnnData objects into a unified joint object by aligning spots via KNN-based coordinate mapping and storing correspondence metadata. This enables cross-modal spatial pattern analysis on integrated multi-omics data at a common resolution.

## When to use

You have preprocessed and filtered ST and SM AnnData objects with spatial coordinates and features, and you need to establish spot-level correspondence between the two modalities to enable downstream joint analysis. Specifically, when SM spots do not natively align to ST spots and you need to create a unified feature matrix indexed by a common set of spatial locations.

## When NOT to use

- ST and SM spots are already co-registered or come from the same coordinate system without alignment drift
- SM spatial coordinates are missing or unreliable (e.g., from low-resolution imaging)
- The analysis goal is modality-specific and does not require cross-modal spatial comparison

## Inputs

- Preprocessed ST AnnData object with .obsm['spatial'] coordinates and filtered genes
- Preprocessed SM AnnData object with .obsm['spatial'] coordinates and filtered metabolites
- k parameter (number of nearest neighbors to query; default typically 1 for assignment)

## Outputs

- Joint AnnData object integrating ST and SM with unified spot indexing
- Spot correspondence metadata mapping (SM spot index → ST spot index)
- Distance distribution statistics for alignment validation

## How to apply

Load preprocessed ST and SM AnnData objects containing spatial coordinates and filtered features. Build a KNN index on ST spot coordinates using scikit-learn's NearestNeighbors, then query this index with SM spot coordinates to identify k nearest ST neighbors for each SM spot. Assign each SM spot to its closest ST spot based on minimum Euclidean distance. Store the resulting spot correspondence (SM-to-ST index pairs) as metadata in a new joint AnnData object. Validate that all SM spots have been successfully assigned and that the distance distributions are reasonable (no anomalously large nearest-neighbor distances suggesting coordinate misalignment). The unified joint object becomes the input for downstream normalization and cross-modal analysis steps.

## Related tools

- **spatialMETA** (Provides the spot_align_byknn workflow step and joint_adata_sm_st integration function for KNN-based spot alignment and joint AnnData construction) — https://github.com/WanluLiuLab/SpatialMETA
- **scikit-learn NearestNeighbors** (Constructs the KNN index on ST coordinates and performs nearest-neighbor queries for SM spot assignment)

## Examples

```
from spatialmeta.pp import spot_align_byknn, joint_adata_sm_st; sm_st_index = spot_align_byknn(st_adata, sm_adata, k=1); joint_adata = joint_adata_sm_st(st_adata, sm_adata, spot_mapping=sm_st_index)
```

## Evaluation signals

- All SM spots have a valid assignment to an ST spot (no unmatched SM spots remain)
- Nearest-neighbor distances are within expected range for the tissue section geometry (e.g., no outliers >2–3× median distance suggesting coordinate errors)
- Spot correspondence metadata is present in joint AnnData object and contains no null or duplicate mappings
- Joint object dimensions match the expected union/intersection of ST and SM spot counts depending on assignment strategy (typically SM spots ≤ ST spots)
- Spatial coordinates in joint AnnData .obsm['spatial'] are consistent with original ST coordinates (alignment does not distort relative geometry)

## Limitations

- KNN assignment assumes ST spot density is sufficient to serve as reference; sparse ST data may cause multiple SM spots to map to single ST spot, losing spatial resolution
- Distance-based assignment is sensitive to coordinate scale and units; inconsistent or uncalibrated spatial coordinates (e.g., different magnification between modalities) will produce misalignments
- Method does not account for missing spots or tissue artifacts; contaminated or damaged regions in either modality may bias assignments
- k=1 assignment is hard; soft probabilistic assignment (e.g., based on distance weighting) is not described and may be necessary for overlapping spot patterns

## Evidence

- [other] Build a KNN index on ST spot coordinates using scikit-learn's NearestNeighbors.: "Build a KNN index on ST spot coordinates using scikit-learn's NearestNeighbors."
- [other] Assign each SM spot to its nearest ST spot based on minimum Euclidean distance.: "Assign each SM spot to its nearest ST spot based on minimum Euclidean distance."
- [other] Generate aligned coordinate mappings and store spot correspondence (SM-to-ST index pairs) in the joint AnnData object metadata.: "Generate aligned coordinate mappings and store spot correspondence (SM-to-ST index pairs) in the joint AnnData object metadata."
- [other] Validate that all SM spots have been assigned and distance distributions are reasonable.: "Validate that all SM spots have been assigned and distance distributions are reasonable."
- [intro] spatialMETA is a method for integrating spatial multi-omics data. SMOI aligns ST and SM to a unified resolution: "spatialMETA is a method for integrating spatial multi-omics data. SMOI aligns ST and SM to a unified resolution"
- [other] spatialmeta.pp.spot_align_byknn: "spatialmeta.pp.spot_align_byknn"
- [other] spatialmeta.pp.joint_adata_sm_st: "spatialmeta.pp.joint_adata_sm_st"