metabolomics-workbench-api-integration
Summary
Retrieve and parse public lipidomics datasets directly from Metabolomics Workbench into a structured LipidomicsExperiment object using the lipidr R package's API integration. This skill enables rapid access to standardized lipidomics data without manual download and reformatting.
When to use
When you need to analyze a publicly archived lipidomics study (identified by study_id like ST001111) and want to bypass manual data download and format conversion. Use this when your input is a Metabolomics Workbench study identifier and your goal is to load the data into R for downstream quality control, differential analysis, or multivariate modeling.
When NOT to use
- Your data is already in a local file format (CSV, Skyline export) — use read.csv() or read_skyline() instead
- You have already downloaded and locally stored the raw Metabolomics Workbench data — load it directly with file I/O functions
- Your study is not publicly archived in Metabolomics Workbench — this skill requires API access to a registered study
Inputs
- Metabolomics Workbench study_id string (e.g., 'ST001111')
- Internet connection to Metabolomics Workbench API
Outputs
- LipidomicsExperiment object containing parsed lipid abundances and sample metadata
- Parsing warnings listing unparsed molecule names and their counts
How to apply
Call lipidr's fetch_mw_study(study_id) function with the target Metabolomics Workbench study identifier to download and automatically parse the dataset into a LipidomicsExperiment object. Examine parsing warnings to identify molecules with unsupported naming patterns (e.g., full chemical names for Ceramides). For unparsed molecules, apply regex-based renaming to convert full names to the supported 'Cer (' convention using pattern substitution (e.g., '^.* (' to '(Cer ('). Verify successful parsing by checking that all molecule names follow supported lipid class naming conventions before proceeding to quality control and analysis steps.
Related tools
- lipidr (R package providing fetch_mw_study() function for API integration and LipidomicsExperiment object creation) — https://github.com/ahmohamed/lipidr
- Metabolomics Workbench API (Remote API service hosting public lipidomics datasets indexed by study_id) — https://www.metabolomicsworkbench.org
- R (Runtime environment for executing lipidr functions and regex-based molecule name standardization)
Examples
d <- fetch_mw_study('ST001111'); d
Evaluation signals
- LipidomicsExperiment object is successfully created with non-zero dimensions (lipids × samples)
- Sample metadata (e.g., SampleType, Cancer Stage, Race) are present in the colData slot
- All molecule names conform to supported lipid naming patterns; parsing warning count is zero or only includes expected non-recoverable entries
- Lipid abundance matrix contains numeric values (typically Areas or peak intensities) with no missing values in the primary measure column
- Row and column names match the expected study layout (lipid names as rows, sample identifiers as columns)
Limitations
- Skill depends on the study being publicly registered in Metabolomics Workbench; private or embargoed studies cannot be accessed via API
- Molecules with non-standard naming conventions (e.g., full chemical nomenclature) will fail to parse unless manually renamed post-fetch
- Large studies may require substantial memory and network bandwidth; no automatic chunking or streaming is documented
- API availability and response time are external to the lipidr package and may vary
Evidence
- [readme] Through integration with Metabolomics Workbench API, lipidr allows users, to quickly explore public lipidomics experiments.: "Through integration with Metabolomics Workbench API, lipidr allows users, to quickly explore public lipidomics experiments."
- [intro] Datasets can be easily downloaded and parsed into LipidomicsExperiment object using lipidr function fetch_mw_study() by supplying a study_id.: "Datasets can be easily downloaded and parsed into LipidomicsExperiment object using lipidr function fetch_mw_study() by supplying a study_id."
- [other] Ceramide molecules written with full chemical names can be recovered by substituting the initial portion with 'Cer' using the RegEx pattern '^.* (' to '(Cer (', enabling successful parsing of all previously unparsed molecules.: "Ceramide molecules written with full chemical names can be recovered by substituting the initial portion with 'Cer' using the RegEx pattern '^.* (' to '(Cer (', enabling successful parsing of all"
- [intro] Note the warning that some molecules were not parsed because their names did not follow the supported patterns.: "Note the warning that some molecules were not parsed because their names did not follow the supported patterns."
- [intro] We can examine these molecules, remove them from the dataset or change their names, if desired.: "We can examine these molecules, remove them from the dataset or change their names, if desired."