# Metabcombiner Object Construction

> Use when you have two peak-picked, conventionally aligned untargeted LC-MS metabolomics datasets (metabData objects) acquired under different conditions and need to identify overlapping <m/z, retention time> features across them.

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

---


# metabcombiner-object-construction

## Summary

Construct a metabCombiner object by grouping feature pairs from two LC-MS metabolomics datasets by m/z tolerance and creating an aligned combined table with structured columns for downstream processing. This is the foundational step that establishes the feature pair alignment scaffold before scoring and reduction.

## When to use

You have two peak-picked, conventionally aligned untargeted LC-MS metabolomics datasets (metabData objects) acquired under different conditions and need to identify overlapping <m/z, retention time> features across them. Use this skill when you are ready to construct the initial feature pair grouping and combined alignment table after data formatting and filtering are complete.

## When NOT to use

- Input datasets are already merged or aligned—use this skill only when you have two separate peak-picked metabData objects that need initial grouping.
- Feature pair alignments have already been manually validated or filtered—this skill generates candidate alignments before scoring/reduction steps.
- Data have not yet been formatted and filtered (retention time range, missingness, duplicates)—complete data QC before object construction.

## Inputs

- metabData object (X dataset, typically higher-resolution or reference LC-MS run)
- metabData object (Y dataset, typically lower-resolution or secondary LC-MS run)
- binGap parameter (numeric, m/z tolerance in Da for grouping features)

## Outputs

- metabCombiner object containing the combined feature pair alignment table
- combined table with 15+ initial columns (idx, mzx, rtx, idy, mzy, rty, rtProj, score, rankx, ranky) plus sample and extra columns

## How to apply

Load two metabData objects (e.g., p30 as the X dataset and p20 as the Y dataset) into R. Call the metabCombiner() constructor function, specifying the X and Y datasets and setting the binGap parameter to define the m/z grouping tolerance (e.g., binGap=0.0075 Da). The function groups features from both datasets by m/z within the binGap window and generates candidate feature pairs. Extract the combined table using the combinedTable accessor to verify structure: the first 15 columns should contain idx, mzx, rtx from X; idy, mzy, rty from Y; and placeholder columns (rtProj, score, rankx, ranky) for downstream computations, followed by sample measurement columns and extra metadata columns.

## Related tools

- **metabCombiner** (R package providing the metabCombiner() constructor, combinedTable accessor, and metabData object handling for LC-MS feature alignment) — github.com/hhabra/metabCombiner
- **R** (Programming environment for executing metabCombiner object construction and table manipulation)
- **mgcv** (Provides generalized additive model (gam) functions used internally by metabCombiner for retention time mapping)

## Examples

```
library(metabCombiner); data(p30, p20); comb <- metabCombiner(x = p30, y = p20, binGap = 0.0075); head(combinedTable(comb)[, 1:15])
```

## Evaluation signals

- metabCombiner object is successfully created without errors; inspect class(object) == 'metabCombiner'
- Combined table has exactly 15 named initial columns in the expected order: idx, mzx, rtx, idy, mzy, rty, rtProj, score, rankx, ranky, followed by sample columns and extra columns
- Feature pairs are grouped within the specified binGap m/z tolerance; verify by examining mzx and mzy differences for all rows (should all be ≤ binGap)
- No spurious or duplicate feature pair entries; check that each unique combination of (idx, idy) appears exactly once in the combined table
- Placeholder scoring columns (rtProj, score, rankx, ranky) are initialized as NA or 0; these will be populated by downstream scoring steps

## Limitations

- The m/z tolerance (binGap) is global and uniform across all m/z ranges; users must choose a single binGap value appropriate for their instrument mass accuracy rather than adaptive per-region tolerance.
- Initial grouping is based on m/z alone; feature pairs sharing similar m/z but originating from different chemical compounds are not distinguished until downstream scoring incorporates retention time and similarity metrics.
- No changelog or version history available in the repository, limiting reproducibility tracking of changes to the metabCombiner constructor behavior across releases.

## Evidence

- [other] object structure and column composition: "The combined table contains 15 initial columns consisting of input from the x dataset (idx, mzx, rtx, ...), input from the y dataset (idy, mzy, rty, ...), and placeholder columns (rtProj, score,"
- [other] constructor call and parameters: "Construct a metabCombiner object using the metabCombiner() function with p30 as the X dataset, p20 as the Y dataset, and binGap parameter set to 0.0075."
- [readme] m/z grouping and feature alignment principle: "metabCombiner takes peak-picked and conventionally aligned untargeted LC-MS datasets and determines the overlapping <mass-to-charge (m/z), retention time (rt)> features, concatenating their"
- [intro] workflow context within broader pipeline: "Feature m/z Grouping and Pairwise Alignment Detection"