--- name: metaboset-object-manipulation description: 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. license: CC-BY-4.0 metadata: edam_operation: http://edamontology.org/operation_3643 edam_topics: - http://edamontology.org/topic_3172 - http://edamontology.org/topic_0625 tools: - notame - R - missForest - doParallel - Biobase - ExpressionSet techniques: - LC-MS derived_from: - doi: 10.3390/metabo10040135 title: notame - doi: 10.1093/bioinformatics/btr597 title: '' evidence_spans: - This package can be used to analyze preprocessed LC-MS data in non-targeted metabolomics - library(notame) - reads them to R, conducts additional preprocessing and statistical analyses - The implementation we use (from the missForest package) can be parallelized - Load the libraries (doParallel is used for parallel processing) - '```MetaboSet``` is built upon the ```ExpressionSet``` class from the Biobase package by Bioconductor' claims: [] provenance: collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v2 assembled_by: scripts/collect_metabolomics_collection.py sources: - build: coll_notame_cq doi: 10.3390/metabo10040135 title: notame dedup_kept_from: coll_notame_cq schema_version: 0.2.0 attribution: generator: AgenticScienceBuilder original_doi: 10.3390/metabo10040135 all_source_dois: - 10.3390/metabo10040135 - 10.1093/bioinformatics/btr597 zenodo_doi: 10.5281/zenodo.20794027 curators: [] promoter: Louis-Félix Nothias sponsor: CNRS & Université Côte d'Azur --- # 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"