# Anndata Object Annotation

> Use when after loading or merging spatial metabolomics data into an AnnData object (via read_sm_csv_as_anndata, read_sm_imzml_as_anndata, or merge_sm_pos_neg), and before filtering or normalization steps.

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

---


# anndata-object-annotation

## Summary

Embed computed quality control metrics into AnnData objects at per-spot and per-metabolite resolution for spatial metabolomics data. This skill enables systematic QC tracking and downstream filtering by storing derived metrics in standardized AnnData slots (adata.obs and adata.var).

## When to use

After loading or merging spatial metabolomics data into an AnnData object (via read_sm_csv_as_anndata, read_sm_imzml_as_anndata, or merge_sm_pos_neg), and before filtering or normalization steps. Use this skill when you need to compute intensity-based QC metrics (total intensity per spot, detection frequency per metabolite) and embed them as columns in the AnnData object for downstream quality control decisions.

## When NOT to use

- AnnData object is not derived from spatial metabolomics data (e.g., it is from spatial transcriptomics only or bulk metabolomics without spatial coordinates)
- QC metrics have already been computed and stored in adata.obs and adata.var by a prior workflow step
- Input data is not in AnnData format or lacks proper spot/metabolite dimensional structure

## Inputs

- Spatial metabolomics AnnData object (adata) with .X matrix populated and spot/metabolite identifiers in .obs_names and .var_names

## Outputs

- Annotated AnnData object with per-spot QC metrics in adata.obs columns (e.g., total_intensity, n_detected_metabolites)
- Annotated AnnData object with per-metabolite QC metrics in adata.var columns (e.g., detection_frequency, mean_intensity)

## How to apply

Load a spatial metabolomics AnnData object prepared by SpatialMETA's input functions. Apply spatialmeta.pp.calculate_qc_metrics_sm to compute per-spot metrics (e.g., total intensity, number of detected metabolites) and per-metabolite metrics (e.g., detection frequency, average intensity). The function automatically stores per-spot metrics as new columns in adata.obs and per-metabolite metrics as new columns in adata.var. Inspect the resulting annotated AnnData object to verify that QC metric columns are present and populated with numeric values before proceeding to filter_cells_sm or filter_metabolites_sm steps.

## Related tools

- **spatialMETA** (Provides the calculate_qc_metrics_sm function and integrated preprocessing workflow for spatial metabolomics quality control metric computation on AnnData objects) — https://github.com/WanluLiuLab/SpatialMETA

## Examples

```
import spatialmeta as sm; adata = sm.pp.read_sm_csv_as_anndata('metabolomics.csv'); adata = sm.pp.calculate_qc_metrics_sm(adata); print(adata.obs.head())
```

## Evaluation signals

- adata.obs contains new numeric columns (e.g., 'total_intensity', 'n_detected_metabolites') with non-null values for all spots
- adata.var contains new numeric columns (e.g., 'detection_frequency', 'mean_intensity') with non-null values for all metabolites
- Per-spot total intensity is non-negative and sums match the row-wise sum of adata.X
- Per-metabolite detection frequency is between 0 and 1 (or 0 and 100 if percentages), and correlates with sparsity patterns in adata.X
- Spot and metabolite metric columns are queryable and filterable for downstream QC workflows (e.g., filter_cells_sm or filter_metabolites_sm)

## Limitations

- Metrics are computed in-place on the full AnnData object; if metrics must be recomputed with different parameters or on subsets, the function must be re-run
- The function assumes the input AnnData object is well-formed with proper dimensionality; malformed or incomplete objects may produce NaN or misleading metric values
- Metrics are additive (total intensity, detection counts) and do not account for metabolite mass, retention time, or other chemical properties that may be relevant for domain-specific QC decisions

## Evidence

- [other] Apply spatialmeta.pp.calculate_qc_metrics_sm to compute QC metrics at the spot level (e.g., total intensity, number of detected metabolites per spot) and metabolite level (e.g., detection frequency, average intensity per metabolite).: "Apply spatialmeta.pp.calculate_qc_metrics_sm to compute QC metrics at the spot level (e.g., total intensity, number of detected metabolites per spot) and metabolite level (e.g., detection frequency,"
- [other] Store computed metrics in adata.obs (per-spot) and adata.var (per-metabolite) columns.: "Store computed metrics in adata.obs (per-spot) and adata.var (per-metabolite) columns."
- [other] SpatialMETA includes a calculate_qc_metrics_sm preprocessing function that computes quality control metrics at the per-spot and per-metabolite level on spatial metabolomics AnnData objects as part of the integrated workflow.: "SpatialMETA includes a calculate_qc_metrics_sm preprocessing function that computes quality control metrics at the per-spot and per-metabolite level on spatial metabolomics AnnData objects as part of"