MetaboSet Object Manipulation
License: restricted — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution.
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"
1---2name: metaboset-object-manipulation-23description: 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.4license: CC-BY-4.05---67# MetaboSet Object Manipulation89> **License: restricted** — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution. <!-- asb-license-banner -->10## Summary1112Create, 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.1314## When to use1516When 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).1718## When NOT to use1920- Input is already in Bioconductor ExpressionSet format; use construct_metabosets directly on the three data parts instead of read_from_excel.21- 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.22- Missing obligatory columns (Injection_order, mass/mz, retention time) in the input file; read_from_excel will fail or produce incomplete MetaboSet objects.2324## Inputs2526- Excel (.xlsx) peak table file with three data compartments: sample phenotype data, feature annotation data, and abundance expression matrix27- Row and column corner coordinates identifying where the Ion Mode label is located in the spreadsheet28- Column specification mapping (group_col, time_col, subject_col) to designate special sample metadata fields2930## Outputs3132- One or more MetaboSet objects (list) — one per LC-MS mode or split_by value33- 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)3435## How to apply3637First, 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.3839## Related tools4041- **notame** (Core package providing read_from_excel and construct_metabosets functions for MetaboSet creation and manipulation) — https://github.com/hanhineva-lab/notame42- **Biobase** (Provides ExpressionSet class upon which MetaboSet is built, enabling unified storage of exprs, fData, and pData)43- **ExpressionSet** (Bioconductor data structure for storing high-dimensional abundance data with associated feature and sample metadata)44- **R** (Language and runtime environment for executing read_from_excel, construct_metabosets, and subsequent MetaboSet manipulations)4546## Examples4748```49library(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')50```5152## Evaluation signals5354- Returned list contains one or more MetaboSet objects with non-empty exprs, fData, and pData slots.55- Feature_ID column is present in fData and exactly matches row names of the exprs matrix.56- All obligatory columns (Injection_order, mass/Average_mz, retention time) are populated with non-NA values across all samples and features.57- QC field in pData correctly distinguishes QC samples (value='QC') from biological samples (value='Sample').58- 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.5960## Limitations6162- 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.63- 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.64- 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.65- The package API is described as experimental; breaking changes are possible between versions.6667## Evidence6869- [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"70- [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"71- [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."72- [other] ExpressionSet inheritance and multi-compartment design: "```MetaboSet``` is built upon the ```ExpressionSet``` class from the Biobase package by Bioconductor"73- [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"
HolobiomicsLab 