# Metaboset Object Manipulation

> Use when when you have read LC-MS peak table data from Excel (or equivalent) into R and need to organize it into a structured object that tracks feature abundances, sample information (injection order, QC status), and feature metadata (mass, retention time, Feature_ID) simultaneously.

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

---


# MetaboSet Object Manipulation

## Summary

Create, inspect, and modify MetaboSet objects—the primary Biobase-derived data structure in the notame workflow—to organize LC-MS abundances, sample metadata, and feature annotations in a unified, interoperable format.

## When to use

When you have read LC-MS peak table data from Excel (or equivalent) into R and need to organize it into a structured object that tracks feature abundances, sample information (injection order, QC status), and feature metadata (mass, retention time, Feature_ID) simultaneously. Use this when the input is raw expression matrix columns, phenotype data rows, and feature annotation rows that must be bound into a single object for downstream notame preprocessing steps (drift correction, flagging, imputation).

## When NOT to use

- Input is already in Bioconductor ExpressionSet format; use construct_metabosets directly on the three data parts instead of read_from_excel.
- Peak table data is in native mzML, netCDF, or vendor raw formats; first run peak-picking software (e.g., MS-DIAL) to produce a processed peak table spreadsheet.
- Missing obligatory columns (Injection_order, mass/mz, retention time) in the input file; read_from_excel will fail or produce incomplete MetaboSet objects.

## Inputs

- Excel (.xlsx) peak table file with three data compartments: sample phenotype data, feature annotation data, and abundance expression matrix
- Row and column corner coordinates identifying where the Ion Mode label is located in the spreadsheet
- Column specification mapping (group_col, time_col, subject_col) to designate special sample metadata fields

## Outputs

- One or more MetaboSet objects (list) — one per LC-MS mode or split_by value
- Each MetaboSet contains: exprs (abundance matrix with Feature_ID as row names), fData (feature annotations including Feature_ID, mass, retention time, Flag column), and pData (sample metadata including Sample_ID, Injection_order, QC status, group designation)

## How to apply

First, use read_from_excel to parse an Excel peak table file, specifying the corner coordinates (row and column where the Ion Mode label appears) to demarcate the three data compartments: pheno data, feature data, and expression matrix. Verify that obligatory columns are present: Injection_order (numeric, unique) in sample information; Mass or Average_mz in feature data; and a retention time column (Retention time / RetentionTime / Average_rt(min) / rt) in feature data. The function will automatically generate Sample_ID and QC fields if absent. Then call construct_metabosets with the three returned data parts (exprs, pheno_data, feature_data), specifying group_col and optionally time_col and subject_col to designate special column semantics. This produces one or more MetaboSet objects (one per LC-MS mode or split_by combination), each built on the ExpressionSet class from Biobase, with Feature_ID automatically created by combining Split, mass, and retention time and set as row names of the exprs matrix. Subsequent notame functions (flag_detection, flag_quality, mark_nas, impute_rf) operate on this unified object, reading and updating the Flag column in fData and the exprs abundance matrix.

## Related tools

- **notame** (Core package providing read_from_excel and construct_metabosets functions for MetaboSet creation and manipulation) — https://github.com/hanhineva-lab/notame
- **Biobase** (Provides ExpressionSet class upon which MetaboSet is built, enabling unified storage of exprs, fData, and pData)
- **ExpressionSet** (Bioconductor data structure for storing high-dimensional abundance data with associated feature and sample metadata)
- **R** (Language and runtime environment for executing read_from_excel, construct_metabosets, and subsequent MetaboSet manipulations)

## Examples

```
library(notame); mbs_list <- read_from_excel('sample_data_whole.xlsx', sheet=1, corner=c('A','1'), split_by=c('LC_column', 'Ion_mode')); mbs <- construct_metabosets(mbs_list$exprs, mbs_list$pheno_data, mbs_list$feature_data, group_col='treatment')
```

## Evaluation signals

- Returned list contains one or more MetaboSet objects with non-empty exprs, fData, and pData slots.
- Feature_ID column is present in fData and exactly matches row names of the exprs matrix.
- All obligatory columns (Injection_order, mass/Average_mz, retention time) are populated with non-NA values across all samples and features.
- QC field in pData correctly distinguishes QC samples (value='QC') from biological samples (value='Sample').
- Sample_ID values are unique and correspond to rows in pData; Injection_order is numeric and unique; Feature_ID is a character string combining Split, mass, and retention time.

## Limitations

- The read_from_excel parser is tightly coupled to MS-DIAL output format; Excel files from other peak-picking software may require manual reformatting to match the expected three-compartment layout.
- Feature_ID generation concatenates Split, mass, and retention time; collision (identical IDs for different features) can occur if mass and retention time precision are low or if Split names overlap.
- The MetaboSet structure assumes that a single injection_order column and QC designation exist; complex experimental designs with multiple sample groupings or nested batches may require post-hoc modification of pData.
- The package API is described as experimental; breaking changes are possible between versions.

## Evidence

- [other] MetaboSet structure and purpose: "To construct a ```MetaboSet``` object, you need to have the data read in R. This can be achieved with ```read_from_excel``` function"
- [other] Obligatory columns requirement: "Verify obligatory columns are present: Injection_order (numeric, unique) in sample information; Mass or Average_mz in feature data; and Retention time / RetentionTime / Average_rt(min) / rt in"
- [other] Feature_ID generation and role: "Confirm Feature_ID is created by combining Split, mass, and retention time and is set as row names of exprs."
- [other] ExpressionSet inheritance and multi-compartment design: "```MetaboSet``` is built upon the ```ExpressionSet``` class from the Biobase package by Bioconductor"
- [other] Downstream integration with notame preprocessing: "Subsequent notame functions (flag_detection, flag_quality, mark_nas, impute_rf) operate on this unified object, reading and updating the Flag column in fData"