# Compound Identifier Aggregation

> Use when you have metabolomics results from multiple studies with compound identifiers in heterogeneous formats (names, InChI strings, SMILES, ChEBI/KEGG/HMDB codes) and need to merge datasets for vote-counting or meta-analysis. Apply this skill before computing consensus measures (e.

- Skill: `holobiomicslab/compound-identifier-aggregation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/compound-identifier-aggregation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/compound-identifier-aggregation/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/compound-identifier-aggregation

---


# Compound Identifier Aggregation

## Summary

Harmonize and deduplicate metabolite compound identifiers across multiple studies by converting diverse ID formats (chemical name, InChI, InChIKey, SMILES) to a common standard (PubChem ID) and detecting duplicates. This enables meaningful meta-analysis by ensuring each metabolite is counted only once across study results.

## When to use

You have metabolomics results from multiple studies with compound identifiers in heterogeneous formats (names, InChI strings, SMILES, ChEBI/KEGG/HMDB codes) and need to merge datasets for vote-counting or meta-analysis. Apply this skill before computing consensus measures (e.g., vote-counting or weighted p-value combination) to avoid artificially inflating sample size or misattributing results to distinct metabolites.

## When NOT to use

- Identifiers are already standardized to a single namespace (e.g., all KEGG IDs or all PubChem IDs with no aliases) — check_names will still work but adds unnecessary latency.
- Your compound list is already deduplicated and you are only performing within-study analysis (not cross-study meta-analysis); identifier harmonization is critical only for multi-study consensus.
- Internet access to PubChem is unavailable; webchem queries will fail and check_names cannot complete.

## Inputs

- Harmonized metabolite dataset (CSV, XLS, or TXT) with columns: compound identifier (any format), p-value or trend label, fold-change, study sample size (N), and bibliographic reference
- Pre-loaded amanida data frame from amanida_read() with mode='quan' or mode='qual'

## Outputs

- Deduplicated amanida data frame with PubChem IDs, duplicate flags, and harmonized compound records
- Compound descriptor table (optional, if comp.inf=T) including PubChem ID, molecular formula, molecular weight, SMILES, InChIKey, KEGG, ChEBI, HMDB, and Drugbank identifiers

## How to apply

Use the amanida `check_names` function on your harmonized dataset (loaded via `amanida_read` with columns: identifier, p-value or trend label, fold-change, study size N, and reference). The function queries PubChem via the `webchem` package to convert all identifiers to PubChem IDs, then automatically detects and flags duplicates. Set `comp.inf = T` in subsequent analysis to retrieve and attach molecular descriptors (formula, weight, SMILES, InChIKey, KEGG, ChEBI, HMDB, Drugbank) to each deduplicated record. This transformation ensures downstream vote-counting and meta-analysis operate on a single, standardized compound namespace.

## Related tools

- **amanida** (R package providing check_names() function for PubChem ID conversion and duplicate detection, and amanida_read() for loading harmonized datasets) — https://github.com/mariallr/amanida
- **webchem** (R package queried by amanida's check_names to retrieve and convert compound identifiers to PubChem IDs)
- **PubChem** (Public chemical compound database serving as the standard namespace for identifier conversion and metadata retrieval)

## Examples

```
datafile <- amanida_read(input_file, mode = "quan", coln = c("Compound Name", "P-value", "Fold-change", "N total", "References"), separator=";"); datafile <- check_names(datafile)
```

## Evaluation signals

- All identifiers in the output are in PubChem ID format (numeric); no heterogeneous ID formats remain.
- Duplicate compound records are flagged and consolidated; the number of unique compounds in the output matches the expected deduplicated count.
- When comp.inf=T, each record includes non-null molecular formula, weight, and cross-database identifiers (KEGG, ChEBI, HMDB); missing descriptors indicate PubChem lookup failure for that compound.
- Comparison of pre- and post-harmonization record counts shows expected reduction; no data loss for non-duplicate records.
- Subsequent vote-counting or meta-analysis results are reproducible across runs (same deduplicated set produces same consensus votes or p-values).

## Limitations

- PubChem database coverage is incomplete for rare or novel compounds; identifiers without PubChem matches are dropped or retained as-is, reducing harmonization completeness.
- Identical chemical structures with different stereochemistry or ionization states may map to distinct PubChem IDs, causing artificial splitting rather than merging; manual review of flagged duplicates is recommended.
- webchem queries depend on internet connectivity and PubChem API availability; high-throughput queries may be rate-limited or fail transiently.
- Only identifier formats supported by PubChem and webchem (chemical name, InChI, InChIKey, SMILES) are reliably converted; proprietary or institutional metabolite codes may not harmonize.

## Evidence

- [intro] Identifier conversion and deduplication process: "The IDs in format chemical name, InChI, InChIKey, and SMILES are searched in PubChem to transform all into a common nomenclature, PubChem ID. Then duplicates are searched"
- [intro] check_names function purpose and usage: "Before the meta-analysis the IDs can be checked using public databases information. The IDs in format chemical name, InChI, InChIKey, and SMILES are searched in PubChem to transform all into a common"
- [intro] Compound descriptor retrieval with comp.inf parameter: "If you select the option `comp.inf = T` the package will retrieve the PubChem ID from the ID using `webchem`. Results will return the following information: PubChem ID, Molecular Formula, Molecular"
- [intro] Metadata output from identifier harmonization: "Results will return the following information: PubChem ID, Molecular Formula, Molecular Weight, SMILES, InChIKey, KEGG, ChEBI, HMDB, Drugbank"
- [readme] Integration with downstream meta-analysis workflow: "In this step you will obtain an S4 object with two tables: adapted meta-analysis acces by `amanida_result@stat` [, when] Selecting the option `comp.inf = T` the package need the previous use of"