# Metaboprep Object Manipulation

> Use when you have imported raw (un)targeted metabolite data (from Metabolon, Nightingale, Olink, or SomaLogic platforms, or custom tab-delimited tables) and need to apply a uniform, reproducible QC and normalization pipeline.

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

---


# metaboprep-object-manipulation

## Summary

Construct, inspect, and transform Metaboprep objects—data structures that bundle metabolite abundance matrices, sample metadata, and feature metadata—through piped operations (batch normalization, quality control) and export them as tab-delimited or HTML outputs. This is the core workflow for standardizing (un)targeted metabolomic datasets before downstream analysis.

## When to use

You have imported raw (un)targeted metabolite data (from Metabolon, Nightingale, Olink, or SomaLogic platforms, or custom tab-delimited tables) and need to apply a uniform, reproducible QC and normalization pipeline. Use this skill when you want to exclude samples or features by user-defined thresholds (sample/feature missingness, outlier distance, peak area), generate a QC report documenting exclusions, and save processed data in standardized tab-delimited format for export to other tools.

## When NOT to use

- Input data are already a processed feature table without raw sample/feature metadata or platform information—the pipeline requires structured annotation tables.
- You need real-time streaming QC or have >1 million features; the current implementation may have computational limits.
- Data have been pre-QC'd in an external tool and you only need to reformat to tab-delimited for export—use simpler export wrappers instead.

## Inputs

- Abundance matrix (rows = features/metabolites; columns = samples; values = peak area, intensity, or normalized abundance)
- Sample metadata table (rows = samples; columns = sample identifiers and covariates)
- Feature metadata table (rows = features; columns = feature identifiers, metabolite names, platform, pathway, KEGG/HMDB annotations)
- Platform/run mode annotation (column name indicating platform or ion polarity)

## Outputs

- Metaboprep object with 'input' and 'qc' data layers
- Sample exclusion summary (counts and reasons: extreme/user-defined missingness, total peak area outliers, PCA outliers)
- Feature exclusion summary (counts and reasons: extreme/user-defined missingness)
- Tab-delimited export files (processed data matrix, sample metadata, feature metadata with exclusion flags)
- HTML QC report (project_name_metaboprep_qc_report.html) with tables, summary statistics, and diagnostic plots
- Feature tree dendrogram (hierarchical clustering based on Pearson correlation, stored as dendrogram object)

## How to apply

First, construct a Metaboprep object by calling Metaboprep(data=, samples=, features=) with an abundance matrix, sample annotation table, and feature annotation table. Then apply batch_normalise() if data were collected across multiple platforms or runs, specifying the platform column and mode mapping (e.g., 'pos'/'neg' for ion modes). Next, pipe the object into quality_control() with user-defined thresholds: sample_missingness (proportion of missing values per sample), feature_missingness (proportion per feature), total_peak_area_sd (number of standard deviations from mean for total ion abundance), outlier_udist (Mahalanobis distance cutoff for PCA-based outliers), winsorize_quantile, pc_outlier_sd, and tree_cut_height. The function returns an object with an additional 'qc' data layer and exclusion flags annotated on samples and features. Finally, export the object using export(format='metaboprep') to write tab-delimited outputs (data, sample metadata, feature metadata), and optionally call generate_report(format='html', template='qc_report') to produce an interactive HTML summary showing sample/feature counts, exclusion reasons, and diagnostic plots.

## Related tools

- **metaboprep** (Primary package providing Metaboprep class, batch_normalise(), quality_control(), export(), generate_report(), and summary methods) — https://github.com/MRCIEU/metaboprep
- **rmarkdown** (Templating engine for rendering QC HTML reports from embedded R code)
- **knitr** (Document processor for Rmarkdown vignettes and QC report generation)
- **ggplot2** (Visualization of summary statistics and diagnostic plots within QC reports)
- **dendextend** (Feature tree dendrogram manipulation and annotation)
- **kableExtra** (Styled table rendering in HTML reports (kable_styling))

## Examples

```
library(metaboprep); mydata <- Metaboprep(data = mydata$data, samples = mydata$samples, features = mydata$features); mydata <- mydata |> batch_normalise(run_mode_col = "platform", run_mode_colmap = c(pos="pos", neg="neg")) |> quality_control(source_layer = "input", sample_missingness = 0.2, feature_missingness = 0.2, total_peak_area_sd = 5, outlier_udist = 5); export(mydata, directory = output_dir, format = "metaboprep"); generate_report(mydata, project_name = "my_project", output_directory = output_dir, format = "html", template = "qc_report")
```

## Evaluation signals

- Verify the returned Metaboprep object has exactly 2 data layers ('input' and 'qc') and that the 'qc' layer has fewer samples/features than 'input' (by design, exclusions are cumulative).
- Check that sample and feature metadata tables have new 'excluded' and 'reason_excluded' columns, with reasons matching the quality_control() parameters applied (e.g., 'user_defined_sample_missingness', 'user_defined_sample_totalpeakarea').
- Confirm that the HTML report file is generated at the specified output directory with the naming scheme project_name_metaboprep_qc_report.html and displays summary counts matching the summary(object) output.
- Verify that tab-delimited exports exist (.txt/.tsv files) with the same number of rows/columns as the object's 'qc' layer data frame, and that headers match feature/sample identifiers.
- Ensure feature tree dendrogram can be extracted via attr(mydata@feature_summary, 'qc_tree') and plotted without errors, confirming hierarchical clustering was computed.

## Limitations

- PCA outlier detection may warn or fail if fewer informative PCs exist than requested (max_num_pcs parameter), especially in small or low-variance datasets.
- The pipeline assumes batch effects align with platform/run_mode columns; if confounding structure exists outside these categories, batch_normalise() may not fully address it.
- No automated method is provided to select optimal thresholds (sample_missingness, feature_missingness, outlier_udist); users must set these manually or validate on a pilot dataset.
- Tree dendrogram is computed only if tree_cut_height is specified; if omitted, feature clustering information is not stored.

## Evidence

- [readme] Workflow overview and multi-platform support: "Read in and processes (un)targeted metabolite data, saving datasets in tab-delimited format for use elsewhere"
- [readme] Output types and report generation: "Provide useful summary data in the form of tab-delimited text file and a html report"
- [readme] QC function parameters and thresholds: "mydata |> quality_control( source_layer = "input", sample_missingness = 0.2, feature_missingness = 0.2, total_peak_area_sd = 5, outlier_udist = 5, outlier_treatment = "leave_be", winsorize_quantile ="
- [methods] Report generation workflow: "Call generate_report() with project name, output directory, format='html', and template='qc_report' to render the QC report"
- [methods] Export workflow: "Call export() with format='metaboprep' to write processed data, sample metadata, and feature metadata as tab-delimited text files"
- [readme] Exclusion summary inspection: "Exclusion Codes Summary: Sample Exclusions: Exclusion | Count. user_defined_sample_missingness | 2"
- [readme] Feature tree dendrogram storage: "tree <- attr(mydata@feature_summary, "qc_tree")"