Excel file parsing for metabolomics

excel-file-parsing-for-metabolomics

License: restricted — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution. <!-- asb-license-banner -->

Summary

Parse LC-MS peak tables from Excel spreadsheets (e.g., MS-DIAL output) into R and construct MetaboSet objects with properly annotated Feature_ID identifiers, sample metadata, and feature annotations. This is the foundational step in the notame workflow that converts raw peak-picking output into a structured, queryable data object for downstream preprocessing and analysis.

When to use

You have a preprocessed LC-MS peak table exported from peak-picking software (e.g., MS-DIAL) in Excel format with three logical compartments: sample annotation (rows), feature annotation (columns), and abundance matrix (numeric values). You need to ingest this data into R as a MetaboSet object to apply notame's preprocessing functions (drift correction, missing value imputation, batch correction, QC flagging).

When NOT to use

• Input data is not in Excel format or does not follow MS-DIAL layout conventions (three compartments: sample annotation, feature annotation, abundance matrix).
• Excel file lacks obligatory columns: Injection_order (numeric, unique) in samples; Mass or Average_mz and one of {Retention time, RetentionTime, Average_rt(min), rt} in features.
• Data has already been read into R as a separate matrix, data frame, and annotation pair; use construct_metabosets() directly instead.

Inputs

• Excel spreadsheet (.xlsx) with MS-DIAL peak table output or equivalent format
• Sheet number (integer) and corner coordinates (row, column) specifying the location of the Ion Mode label
• Column names for split_by (e.g., 'LC_column', 'Ion_mode') or a single name string if unimodal

Outputs

• MetaboSet object (or list of MetaboSet objects, one per ionization mode)
• ExpressionSet with exprs slot containing feature abundance matrix (features × samples)
• Feature data (fData) with Feature_ID, mass, retention time, and all parsed feature annotations
• Phenotype data (pData) with Sample_ID, Injection_order, QC status, and all parsed sample metadata

How to apply

Load the notame package and call read_from_excel() with the Excel file path, sheet number, and corner coordinates (row and column where the 'Ion Mode' label is located) to automatically parse the three data compartments. Specify split_by columns (typically LC column and ionization mode) so the function generates a Split field that will be incorporated into Feature_ID; alternatively supply a single name argument if the file contains only one mode. Verify that obligatory columns are present in the sample information (Injection_order as numeric and unique), feature data (Mass or Average_mz, and one of: Retention time, RetentionTime, Average_rt(min), or rt), and that the abundance matrix is numeric. Allow automatic generation of Sample_ID (via id_prefix, default 'ID') and QC field (value 'QC' for QC samples, 'Sample' for biological samples) if not present. Call construct_metabosets() with the three returned data parts and specify group_col and optionally time_col and subject_col to assign special column semantics. The function will automatically create Feature_ID by combining Split, mass, and retention time, set as row names of the expression matrix.

Related tools

• notame (Provides read_from_excel() and construct_metabosets() functions to parse Excel peak tables and assemble MetaboSet objects; core package bundling preprocessing methods for LC-MS metabolomics) — https://github.com/hanhineva-lab/notame
• Biobase (Supplies ExpressionSet class upon which MetaboSet is built; provides the eSet infrastructure (exprs, fData, pData slots))
• ExpressionSet (Data structure class (from Biobase) that stores expression-level data, feature annotations, and phenotype data in a unified object)
• R (Runtime environment for executing read_from_excel(), construct_metabosets(), and downstream notame workflows)

Examples

library(notame); peaks <- read_from_excel('sample_data_whole.xlsx', sheet = 1, corner = c(row = 10, col = 1), split_by = c('LC_column', 'Ion_mode')); metabosets <- construct_metabosets(peaks$exprs, peaks$pheno_data, peaks$feature_data, group_col = 'Group')

Evaluation signals

• The returned MetaboSet object (or list thereof) contains non-empty exprs, fData, and pData slots with matching dimensions: nrow(exprs) == nrow(fData), ncol(exprs) == nrow(pData).
• Feature_ID column is present in fData and matches row names of exprs, with all Feature_IDs unique and formatted as '{Split}{mass}{retention_time}'.
• Obligatory columns are fully populated with no missing values: Injection_order is numeric and unique across all samples; Mass/Average_mz and retention time columns are numeric and non-negative in fData; Sample_ID, QC, and group_col assignments are non-empty in pData.
• If split_by was specified, the Split field is correctly generated by concatenating the specified columns (e.g., 'HILIC_pos' from LC_column='HILIC' and Ion_mode='pos'), and each MetaboSet corresponds to one unique Split value.
• Row and column indices are contiguous integers starting from 1, with no gaps or reordering relative to the source Excel worksheet.

Limitations

• The function assumes a fixed Excel layout: sample metadata in rows, feature metadata in columns, and a single contiguous abundance matrix block. Worksheets with merged cells, multiple tables, or non-standard layouts will fail to parse correctly.
• Retention time columns must be present and unambiguous; if multiple retention time columns exist (e.g., both 'rt' and 'Average_rt(min)'), the function may select unpredictably or error.
• Feature_ID is constructed deterministically from Split, mass, and retention time; if mass or retention time values are duplicated, Feature_IDs will not be unique, violating the assumption that Feature_ID is a primary key.
• The notame package API is described as experimental with possible breaking changes; scripts written for one version may not be compatible with later releases.
• The function does not validate ion mode values or tolerate missing Ion_mode labels; if corner coordinates are incorrect, the parser will misalign data compartments.

Evidence

• [other] To construct a MetaboSet object, you need to have the data read in R. This can be achieved with read_from_excel function: "To construct a MetaboSet object, you need to have the data read in R. This can be achieved with read_from_excel function"
• [other] Call read_from_excel with the Excel file path, sheet number, and corner coordinates (row and column where Ion Mode label is located) to parse the three data compartments: "Call read_from_excel with the Excel file path, sheet number, and corner coordinates (row and column where Ion Mode label is located) to parse the three data compartments (pheno data, feature data,"
• [other] Obligatory columns must include Injection_order (numeric, unique) in sample information; Mass or Average_mz in feature data; and Retention time / RetentionTime / Average_rt(min) / rt in feature data: "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 is created by combining Split, mass, and retention time and is set as row names of exprs: "Confirm Feature_ID is created by combining Split, mass, and retention time and is set as row names of exprs"
• [readme] The first step is to take raw data files created by the LC-MS instrument and create a peak table using a peak picking software (we use MS-DIAL): "The first step is to take raw data files created by the LC-MS instrument and create a peak table using a peak picking software (we use MS-DIAL)"
• [readme] Reading data from Excel spreadsheets created with MS-DIAL: "Reading data from Excel spreadsheets created with MS-DIAL"
• [other] MetaboSet is built upon the ExpressionSet class from the Biobase package by Bioconductor: "MetaboSet is built upon the ExpressionSet class from the Biobase package by Bioconductor"