# Annotation Complexity Comparison

> Use when you have MS imaging or LC-MS data with pre-annotated m/z values that include multiple isomer or metabolite names per m/z (stored as semicolon-delimited or multi-record strings), and you want to measure whether a refinement step (e.

- Skill: `holobiomicslab/annotation-complexity-comparison` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/annotation-complexity-comparison`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/annotation-complexity-comparison/raw
- Safety review: pending
- 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/annotation-complexity-comparison

---


# annotation-complexity-comparison

## Summary

Quantify and compare the reduction in annotation complexity (count of isomer/metabolite assignments per m/z) before and after applying lipid nomenclature simplification. This skill validates whether refinement strategies like RefineLipids successfully collapse redundant or over-specific lipid annotations into standardized categories.

## When to use

Apply this skill when you have MS imaging or LC-MS data with pre-annotated m/z values that include multiple isomer or metabolite names per m/z (stored as semicolon-delimited or multi-record strings), and you want to measure whether a refinement step (e.g., RefineLipids with lipid_info='simple') has meaningfully reduced annotation burden without losing critical structural information.

## When NOT to use

- Input annotations are already in a simplified or non-hierarchical form (e.g., already Lipid Maps class level only).
- Annotation column is sparse, missing, or contains no semicolon-delimited entries (no multi-assignment structure to simplify).
- The refinement tool (RefineLipids or equivalent) is not installed or the lipid_info parameter is not supported in your tool version.

## Inputs

- Seurat object or assay metadata with pre-annotated m/z values
- Annotation column containing semicolon-delimited isomer names or multi-record metabolite assignments (e.g., 'all_IsomerNames')
- RefineLipids parameter set: annotation.column name and lipid_info level (e.g., 'simple')

## Outputs

- Refined annotations dataframe with simplified lipid nomenclature
- Summary table with per-m/z base_count (before) and refined_count (after) columns
- Reduction statistics: per-m/z reduction magnitude, maximum reduction, mean reduction, and distribution

## How to apply

Count the number of unique annotations (isomers, metabolite names, or lipid classes) for each m/z before refinement by splitting delimited strings or tallying multi-record entries. Apply RefineLipids() with annotation.column (e.g., 'all_IsomerNames') and lipid_info='simple' to collapse lipid nomenclature into Lipid Maps categories and classes, or apply an equivalent simplification method. Recount annotations per m/z after refinement, handling NA values for non-lipid metabolites. Calculate per-m/z reduction as (base_count − refined_count), then aggregate to summary statistics (e.g., mean, max, distribution). Document the maximum and median reduction per m/z to validate the expected magnitude of simplification and detect edge cases (e.g., m/z values with zero or negative reduction).

## Related tools

- **RefineLipids** (Simplifies lipid nomenclature into common lipid categories and classes via the lipid_info parameter; applied to assay metadata annotation columns to collapse isomer/metabolite redundancy.) — https://github.com/GenomicsMachineLearning/SpaMTP
- **SpaMTP** (R package providing RefineLipids and related annotation functions; loads Seurat objects and manages assay metadata.) — https://github.com/GenomicsMachineLearning/SpaMTP
- **dplyr** (Used for grouping, counting, and summarizing annotation counts per m/z before and after refinement.)
- **tidyr** (Used for parsing and splitting delimited annotation strings into separate records for counting.)
- **ggplot2** (Used for visualization of reduction distributions (e.g., histogram or boxplot of per-m/z reduction magnitudes).)

## Examples

```
refined_lipid_annotations <- RefineLipids(spotted@assays$[redacted-email], annotation.column='all_IsomerNames', lipid_info='simple'); summary_table <- data.frame(base_count = base_counts, refined_count = refined_counts, reduction = base_counts - refined_counts)
```

## Evaluation signals

- Base counts are consistently greater than or equal to refined counts for all m/z values (no negative reductions).
- Maximum reduction matches or approaches the reported benchmark (e.g., 161 → 1 in the spotted dataset study).
- Summary table schema is valid: contains m/z, base_count, refined_count, and reduction columns; row count equals unique m/z values.
- Refined annotations contain NA values only for non-lipid metabolites; lipid m/z values retain valid Lipid Maps class assignments.
- Reduction magnitude distribution (mean, median, quartiles) is reported and aligns with expected simplification scope for the dataset.

## Limitations

- The observed maximum reduction (e.g., 161 → 1) is specific to the spotted dataset's annotation depth; other datasets may exhibit smaller or larger reductions depending on m/z density and LCMS fragmentation patterns.
- RefineLipids with lipid_info='simple' collapses to Lipid Maps categories and classes only; structural isomerism within a class is lost, which may be undesirable for structure-activity or biomarker discovery studies.
- Handling of non-lipid metabolites and mixed-metabolite m/z entries requires explicit NA handling; incorrect handling may inflate or underestimate reduction counts.
- The article notes missing sections for 'Pseudo MS/MS-Based Refinement' and 'Refinement with Paired Targeted Metabolic Data', suggesting alternative refinement pipelines are in development and may produce different reduction profiles.

## Evidence

- [other] The available document text does not contain explicit quantitative results stating the annotation reduction from 161 to 1 when running RefineLipids with lipid_info=simple on the spotted dataset.: "The available document text does not contain explicit quantitative results stating the annotation reduction from 161 to 1 when running RefineLipids with lipid_info=simple on the spotted dataset."
- [other] Count the number of annotations per m/z before refinement by splitting the semicolon-delimited isomer name strings. Call RefineLipids() on the assay metadata with annotation.column='all_IsomerNames' and lipid_info='simple' to simplify lipid nomenclature into Lipid Maps categories and classes. Count the number of annotations per m/z after refinement, handling NA values for non-lipid metabolites. Calculate the reduction in annotation count per m/z and identify the maximum reduction value.: "Count the number of annotations per m/z before refinement by splitting the semicolon-delimited isomer name strings. Call RefineLipids() on the assay metadata with annotation.column='all_IsomerNames'"
- [methods] RefineLipids can be used to simplify the lipid nomenclature into common lipid categories and classes: "RefineLipids can be used to simplify the lipid nomenclature into common lipid categories and classes"
- [methods] Runs lipid nomenclature simplification on annotations refined_lipid_annotations <- RefineLipids(spotted@assays$[redacted-email]: "Runs lipid nomenclature simplification on annotations refined_lipid_annotations <- RefineLipids(spotted@assays$[redacted-email]"
- [other] Output the refined annotations dataframe and a summary table showing base_count versus refined_count for validation against the reported 161→1 maximum reduction.: "Output the refined annotations dataframe and a summary table showing base_count versus refined_count for validation against the reported 161→1 maximum reduction."