1 Introduction

Metabolomics Workbench (link) hosts a metabolomics data repository. It contains over 1000 publicly available studies including raw data, processed data and metabolite/compound information.

The repository is searchable using a REST service API. The metabolomicsWorkbenchR package makes the endpoints of this service available in R and provides functionality to search the database and import datasets and metabolite information into commonly used formats such as data frames and SummarizedExperiment objects.

2 Installation

To install this package enter:

if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")

BiocManager::install("metabolomicsWorkbenchR")

For older versions, please refer to the appropriate Bioconductor release.

3 Running a query

The Metabolomics Workbench API has a number of endpoints that can be used to query several different databases. Complete details are provided in the API documentation (link).

metabolomicsWorkbenchR provides a simple interface to all API endpoints via the do_query method. Four inputs are required:

  • context - The context determines the type of data to be accessed from the Metabolomics Workbench, such as metadata or results related to the submitted studies, data from metabolites, genes/proteins and analytical chemistry databases as well as other services related to mass spectrometry and metabolite identification. Valid contexts are “study”, “compound”, “refmet”, “gene”, “protein”, “moverz” and “exactmass”.
  • input_item - Input items direct the search towards a specific part of the database. If the database is a table, then input_item is a column in that table that will be searched for matching values.
  • input_value - The value to search for in the named input_item.
  • output_item - The type of output to be returned. Usually some data in the form of a table, but sometimes a file (e.g. png, mol).

By combining different context, input and output items a variety of information can be returned. In this first example, we query the study context for study titles containing the keyword “Diabetes” and request a summary of each matching study.

# search for all studies with "Diabetes" in the title and return a summary
df = do_query(
    context = 'study',
    input_item = 'study_title',
    input_value = 'Diabetes',
    output_item = 'summary'
)
df[1:3,c(1,4)]
##   study_id                       institute
## 1 ST000057 University of California, Davis
## 2 ST000075 University of California, Davis
## 3 ST000091                     Mayo Clinic

The result is a 14x12 data.frame with study titles, authors, descriptions etc.

In the next example we query the compound context for “regno” identifier 11 and request all available information for the matching compound.

df = do_query(
    context = 'compound',
    input_item = 'regno',
    input_value = '11',
    output_item = 'compound_exact'
)

df[,1:3]
##   regno    formula  exactmass
## 1    11 C47H75N5O8 837.561565

We can also request an image of the molecular structure:

img = do_query(
        context = 'compound',
        input_item = 'regno',
        input_value = '11',
        output_item = 'png'
      )

grid.raster(img)

Valid contexts, input items and output items can be listed using the names function:

# valid contexts
names(context) # context, input_item or output_item
## [1] "study"     "compound"  "refmet"    "gene"      "protein"   "moverz"   
## [7] "exactmass"

Valid inputs and outputs for a context can be displayed by accessing the list of context objects. Valid inputs for a particular output can also be displayed by accessing the list of output item objects. Use of metabolmicsWorkbenchR objects is detailed in a later section. In addition, functions context_inputs, context_outputs and input_example are provided for convenience.

# valid inputs for "study" context
context_inputs('study')
## [1] "study_id"      "study_title"   "institute"     "last_name"    
## [5] "analysis_id"   "metabolite_id"

More information about the different contexts can be found in the API documentation (link)

4 Special cases

metabolomicsWorkBenchR includes some output items in addition to those specified by the API documentation. These special cases are described here.

4.1 input_item “ignored”

The input item is used with the “study” context and the “untarg_studies” input_item. The API ignores the input_item and the input_value when using this query and returns a list of studies with untargeted data.

df = do_query(
  context = 'study',
  input_item = 'ignored',
  input_value = 'ignored',
  output_item = 'untarg_studies'
)

df[1:3,1:3]
##   study_id analysis_id                         analysis_display
## 1 ST000009    AN000023 LC/Electro-spray /QTOF positive ion mode
## 2 ST000009    AN000024 LC/Electro-spray /QTOF negative ion mode
## 3 ST000010    AN000025 LC/Electro-spray /QTOF positive ion mode

4.2 output_item “compound_exact”, “protein_exact” and “gene_exact”

These outputs refer to compound, protein and gene context API outputs that can be used with exact matching. This means that only exact matches to the input_value will be returned. For these outputs all available output fields will be returned. These output items are used in place of the ‘all’ item specified in the API documentation.

df = do_query(
  context = 'compound',
  input_item = 'regno',
  input_value = '11',
  output_item = 'compound_exact'
)

df[,1:3]
##   regno    formula  exactmass
## 1    11 C47H75N5O8 837.561565

4.3 output_item “protein_partial” and “gene_partial”

These outputs refer to protein and gene contexts API outputs that can be used with partial matching. This means that all records with a partial match to the input_value will be returned. For these outputs all available output fields will be returned.

df = do_query(
  context = 'gene',
  input_item = 'gene_name',
  input_value = 'acetyl-CoA',
  output_item = 'gene_partial'
)

df[1:3,1:3]
##                      gene_name    mgp_id gene_id
## 1 acetyl-CoA acyltransferase 1 MGP000015      30
## 2 acetyl-CoA carboxylase alpha MGP000016      31
## 3  acetyl-CoA carboxylase beta MGP000017      32

4.4 output_item “SummarizedExperiment” and “DatasetExperiment”

This output refers to the study context and uses multiple queries to return a SummarizedExperiment or DatasetExperiment object for a study_id or analysis_id.

SE = do_query(
    context = 'study',
    input_item = 'study_id',
    input_value = 'ST000001',
    output_item = 'SummarizedExperiment' # or 'DatasetExperiment'
)

SE
## class: SummarizedExperiment 
## dim: 102 24 
## metadata(8): data_source study_id ... description subject_type
## assays(1): ''
## rownames(102): ME000097 ME000096 ... ME000002 ME000001
## rowData names(3): metabolite_name metabolite_id refmet_name
## colnames(24): LabF_115811 LabF_115816 ... LabF_115924 LabF_115929
## colData names(4): local_sample_id study_id Arabidopsis_Genotype
##   Plant_Wounding_Treatment

4.5 output_item “MultiAssayExperiment”

This output refers to the study context and uses multiple queries to return a MultiAssayExperiment object for a study_id.

MAE = do_query(
    context = 'study',
    input_item = 'study_id',
    input_value = 'ST000009',
    output_item = 'MultiAssayExperiment' 
)

MAE
## A MatchedAssayExperiment object of 2 listed
##  experiments with user-defined names and respective classes.
##  Containing an ExperimentList class object of length 2:
##  [1] AN000023: SummarizedExperiment with 248 rows and 114 columns
##  [2] AN000024: SummarizedExperiment with 172 rows and 114 columns
## Functionality:
##  experiments() - obtain the ExperimentList instance
##  colData() - the primary/phenotype DataFrame
##  sampleMap() - the sample coordination DataFrame
##  `$`, `[`, `[[` - extract colData columns, subset, or experiment
##  *Format() - convert into a long or wide DataFrame
##  assays() - convert ExperimentList to a SimpleList of matrices
##  exportClass() - save data to flat files

4.6 output_item “untarg_SummarizedExperiment” and “untarg_DatasetExperiment”

This output refers to the study context and uses multiple queries to return a SummarizedExperiment or DatasetExperiment object of untargeted data for an analysis_id.

SE = do_query(
    context = 'study',
    input_item = 'analysis_id',
    input_value = 'AN000023',
    output_item = 'untarg_SummarizedExperiment' # or 'untarg_DatasetExperiment'
)

SE
## class: SummarizedExperiment 
## dim: 4481 114 
## metadata(2): data_source analysis_id
## assays(1): ''
## rownames(4481): 584.27947_3.47455 1467.60377_3.4788 ... UNKNOWN UP0038
##   UNKNOWN UP0040
## rowData names(1): feature_id
## colnames(114): S00008880 S00008886 ... S00008913 S00008939
## colData names(4): AFTER_MEAL_TIME V2 POST_SURGERY_TIME V4

5 S4 classes

A number of classes have been defined in this package and for completeness they are described below. They are used to implement access to the API endpoints and it is not expected that they will be used as objects by the user. The do_query function uses character strings to access predefined instances of these objects and simplify the query.

5.1 Contexts

Each database is referred to as a ‘context’. These contexts can be searched using input/output pairs to search the database for matches and return the results.

In metabolmicsWorkbenchR a predefined list called context contains mw_context objects. These objects define which inputs and outputs are valid options for a context.

The name of all valid contexts can be displayed:

# list all context names
names(context)
## [1] "study"     "compound"  "refmet"    "gene"      "protein"   "moverz"   
## [7] "exactmass"

Information about a specific context can be obtained using the show method for a an mw_context object:

# list valid inputs/outputs for the "study" context
context$study
## A Metabolomics Workbench "context"
## 
## Name:    "study"
## 
## Valid input_item names:
##  "study_id"
##  "study_title"
##  "institute"
##  "last_name"
##  "analysis_id"
##  "metabolite_id"
## 
## Valid output_item names:
##  "summary"
##  "factors"
##  "analysis"
##  "metabolites"
##  "mwtab"
##  "source"
##  "species"
##  "disease"
##  "number_of_metabolites"
##  "data"
##  "datatable"
##  "untarg_studies"
##  "untarg_factors"
##  "untarg_data"
##  "metabolite_info"
##  "SummarizedExperiment"
##  "untarg_SummarizedExperiment"
##  "DatasetExperiment"
##  "untarg_DatasetExperiment"

5.2 Input / Output Items

Once the context of the search has been decided upon valid inputs and outputs can be chosen. All input and output items have been predefined as lists called input_item and output_item.

The input_item list contains mw_input_item objects that specify valid pattern matching of the input value using regex.

# input item "study_id" info
input_item$study_id
## A Metabolomics Workbench "input_item"
## 
## Name:    "study_id"
## 
## Exact pattern matching:
##  "^ST[0-9]{6}$"
## 
## Partial pattern matching:
##  "^S(T[0-9]{0,6})?$"
## 
## Examples: 
##  "ST000001"
##  "ST"

The output_item list contains mw_output_item objects that specify valid inputs, the expected return fields (if the return is a data.frame) and the type of input matching that is supported.

# output item 'summary' info
output_item$summary
## A Metabolomics Workbench "output_item"
## 
## Name:    "summary"
## 
## Returns:
##  "study_id"
##  "study_title"
##  "study_type"
##  "institute"
##  "department"
##  "last_name"
##  "first_name"
##  "email"
##  "phone"
##  "submit_date"
##  "study_summary"
##  "subject_species"
## 
## Allowed input_item names:
##  "study_id"
##  "study_title"
##  "institute"
##  "last_name"
## 
## Type of matching supported:  "partial"

6 Session Info

## R version 4.2.1 (2022-06-23)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 20.04.5 LTS
## 
## Matrix products: default
## BLAS:   /home/biocbuild/bbs-3.16-bioc/R/lib/libRblas.so
## LAPACK: /home/biocbuild/bbs-3.16-bioc/R/lib/libRlapack.so
## 
## locale:
##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
##  [3] LC_TIME=en_GB              LC_COLLATE=C              
##  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
##  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
##  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
## 
## attached base packages:
## [1] grid      stats     graphics  grDevices utils     datasets  methods  
## [8] base     
## 
## other attached packages:
## [1] metabolomicsWorkbenchR_1.8.0 BiocStyle_2.26.0            
## 
## loaded via a namespace (and not attached):
##  [1] Rcpp_1.0.9                  highr_0.9                  
##  [3] bslib_0.4.0                 compiler_4.2.1             
##  [5] BiocManager_1.30.19         jquerylib_0.1.4            
##  [7] GenomeInfoDb_1.34.0         XVector_0.38.0             
##  [9] MatrixGenerics_1.10.0       bitops_1.0-7               
## [11] tools_4.2.1                 zlibbioc_1.44.0            
## [13] digest_0.6.30               lattice_0.20-45            
## [15] jsonlite_1.8.3              evaluate_0.17              
## [17] png_0.1-7                   rlang_1.0.6                
## [19] Matrix_1.5-1                DelayedArray_0.24.0        
## [21] cli_3.4.1                   magick_2.7.3               
## [23] curl_4.3.3                  yaml_2.3.6                 
## [25] xfun_0.34                   fastmap_1.1.0              
## [27] GenomeInfoDbData_1.2.9      httr_1.4.4                 
## [29] stringr_1.4.1               knitr_1.40                 
## [31] BiocBaseUtils_1.0.0         S4Vectors_0.36.0           
## [33] sass_0.4.2                  IRanges_2.32.0             
## [35] struct_1.10.0               stats4_4.2.1               
## [37] MultiAssayExperiment_1.24.0 data.table_1.14.4          
## [39] Biobase_2.58.0              R6_2.5.1                   
## [41] ontologyIndex_2.10          rmarkdown_2.17             
## [43] bookdown_0.29               magrittr_2.0.3             
## [45] htmltools_0.5.3             matrixStats_0.62.0         
## [47] BiocGenerics_0.44.0         GenomicRanges_1.50.0       
## [49] SummarizedExperiment_1.28.0 stringi_1.7.8              
## [51] RCurl_1.98-1.9              cachem_1.0.6