Interfacing with other tools

Zhiqiang Pang, Jeff Xia

2024-03-07

1. Introduction

MetaboAnalyst and MetaboAnalystR accept generic data format for multiple data processing modules, including statistical analysis, biomarker analysis, does-response analysis, functional enrichment. Many commonly used raw spectra tools could only generate the data pre-processing in their own formats, which cannot be directly used for MetaboAnalyst data processing. However, formatting these results may be labour-intensive or require programming skills.

To be interoperable with other widely used platforms, MetaboAnalystR accepts LC-MS1 feature detection results from MS-DIAL, MZmine, Asari and XCMS. The results can be automatically formatted into the generic format of MetaboAnalystR for processing. Additionally, MetaboAnalystR accepts the pre-processed LC-MS2 results in MSP files generated by MS-DIAL and MZmine. Users could input the MSP files directly for MS2 database searching and export the results for downstream analysis. Moreover, MetaboAnalystR also offers functionalities to convert compound identification results from MS-FINDER and SIRIUS for functional analysis.

2. Interoperate LC-MS1 with other tools

2.1 Formatting results of LC-MS1 from MS-DIAL

MS-DIAL could export height information or area information. MetaboAnalystR could recognize both, user could provide either. In the following example, we are using peak height table.

# Download files first

download.file("https://raw.githubusercontent.com/Zhiqiang-PANG/MetaboRaw/master/examples/Height_0_20231111553.txt", 
              destfile = "Height_0_20231111553.txt", 
              mode = "auto")

download.file("https://raw.githubusercontent.com/Zhiqiang-PANG/MetaboRaw/master/examples/Height_0_20231111553_meta.txt", 
              destfile = "Height_0_20231111553_meta.txt", 
              mode = "auto")
# This example data set is a results table - Height_0_20231111553.txt
# You need to include a meta-data table to tell us the grouping information
# An example is provided here - Height_0_20231111553_meta.txt

# The first parameter file_path should be a valid file of the result.
# User need to specify the type in the 2nd argument, type. This argument can be msdial, mzmine, asari and xcms
# Please note, if your original data does not contain meta information, you need to manually add them in the generated "metaboanalyst_input.csv" file
# The formatted file is 'sample in columns'.

library(MetaboAnalystR)

PerformMS1ResultsFormatting(file_path = "./Height_0_20231111553.txt", 
                            type = "msdial", 
                            meta_data = "./Height_0_20231111553_meta.txt")
## Data formatting is done!
## [1] "The formatted data has been saved here: /raw/Downloads/MetaboAnalystR_4.0.0/MetaboAnalystR/vignettes/metaboanalyst_input.csv"

2.2 Formatting results of LC-MS1 from MZmine

MZmine could export either well-formatted data table which is compatiable to MetaboAnalyst and MetaboAnalystR directly, or a comprehensive table containing complete peak and feature information. Here, MetaboAnalystR could automatically recognize the comprehensive table and format into a standard table.

# Download files first
download.file("https://raw.githubusercontent.com/Zhiqiang-PANG/MetaboRaw/master/examples/c18neg_ms1.csv", 
              destfile = "c18neg_ms1.csv", 
              mode = "auto")

download.file("https://raw.githubusercontent.com/Zhiqiang-PANG/MetaboRaw/master/examples/c18neg_meta_ms1.txt", 
              destfile = "c18neg_meta_ms1.txt", 
              mode = "auto")
# This example data set is a results table - c18neg_ms1.csv
# You need to include a meta-data table to tell us the grouping information
# An example is provided here - c18neg_meta_ms1.txt
library(MetaboAnalystR)

PerformMS1ResultsFormatting(file_path = "./c18neg_ms1.csv", 
                            type = "mzmine", 
                            meta_data = "./c18neg_meta_ms1.txt")
## Data formatting is done!
## [1] "The formatted data has been saved here: /raw/Downloads/MetaboAnalystR_4.0.0/MetaboAnalystR/vignettes/metaboanalyst_input.csv"

2.3 Formatting results of LC-MS1 from Asari

Asari could automatically generate a feature table, you are recommended to use the one named as ‘preferred_Feature_table.tsv’. Here, MetaboAnalystR could automatically recognize the table and format into a standard table which is compatible.

# Download files first

download.file("https://raw.githubusercontent.com/Zhiqiang-PANG/MetaboRaw/master/examples/preferred_Feature_table.tsv", 
              destfile = "preferred_Feature_table.tsv", 
              mode = "auto")

download.file("https://raw.githubusercontent.com/Zhiqiang-PANG/MetaboRaw/master/examples/preferred_Feature_table_meta.txt", 
              destfile = "preferred_Feature_table_meta.txt", 
              mode = "auto")
# This example data set is a results table - preferred_Feature_table.tsv
# You need to include a meta-data table to tell us the grouping information
# An example is provided here - preferred_Feature_table_meta.txt
library(MetaboAnalystR)

PerformMS1ResultsFormatting(file_path = "./preferred_Feature_table.tsv", 
                            type = "mzmine", 
                            meta_data = "./preferred_Feature_table_meta.txt")
## Data formatting is done!
## [1] "The formatted data has been saved here: /raw/Downloads/MetaboAnalystR_4.0.0/MetaboAnalystR/vignettes/metaboanalyst_input.csv"

2.4 Formatting results of LC-MS1 from XCMS online

XCMS online could automatically generate a feature table, you can download the complete analysis result package (usually named as “result.zip”). Then, MetaboAnalystR could automatically recognize the table and format into a standard table which is compatible.

# Download files first

download.file("https://raw.githubusercontent.com/Zhiqiang-PANG/MetaboRaw/master/examples/XCMS.annotated.Report_1404649.tsv", 
              destfile = "XCMS.annotated.Report_1404649.tsv", 
              mode = "auto")

download.file("https://raw.githubusercontent.com/Zhiqiang-PANG/MetaboRaw/master/examples/XCMS.annotated.Report_1404649_meta.txt", 
              destfile = "XCMS.annotated.Report_1404649_meta.txt", 
              mode = "auto")
# This example data set is a results table - XCMS.annotated.Report_1404649.tsv
# You need to include a meta-data table to tell us the grouping information
# An example is provided here - XCMS.annotated.Report_1404649_meta.txt
library(MetaboAnalystR)

PerformMS1ResultsFormatting(file_path = "./XCMS.annotated.Report_1404649.tsv", 
                            type = "mzmine", 
                            meta_data = "./XCMS.annotated.Report_1404649_meta.txt")
## Data formatting is done!
## [1] "The formatted data has been saved here: /raw/Downloads/MetaboAnalystR_4.0.0/MetaboAnalystR/vignettes/metaboanalyst_input.csv"

3. Interoperate LC-MS2 with other tools

3.1 Formatting results of LC-MS2 from MS-FINDER

MS-FINDER could search the database automatically and export compound identification information. MetaboAnalystR could recognize the structure table, user could provide that table. This formatting function is mainly used to help users to format MS2 result list for functional analysis. Therefore, users are expected to provide two essential files.

  1. MS1 peak list, containing m/z, retention time (rt), pvalue, etc.
  2. MS2 results table from either MS-FINDER, usually named as “Structure result XXXXX.txt”;

See the following example for more information.

# Download files first

download.file("https://raw.githubusercontent.com/Zhiqiang-PANG/MetaboRaw/master/examples/Structure_result_2072.txt", 
              destfile = "Structure_result_2072.txt", 
              mode = "auto")

download.file("https://raw.githubusercontent.com/Zhiqiang-PANG/MetaboRaw/master/examples/peaks_ms1_msdial.txt", 
              destfile = "peaks_ms1_msdial.txt", 
              mode = "auto")
# This example data set is a results table - Structure_result_2072.txt
# You need to include a MS1 peak list to tell us the MS1 information
# An example is provided here - peaks_ms1_msdial.txt

#' This function is used to format the results from other tools into the generic format of MetaboAnalystR for functional analysis
#' Currently,we are supporting the compatibility for four commonly used open-source tools: MS-FINDER, and SIRIUS
#' The first parameter file_path should be a valid file of the result.
#' User need to specify the type in the 2nd argument, type. This argument can be msfinder, or sirius
#' The 3rd argument is the MS1 peak list
#' 

library(MetaboAnalystR)

PerformMS2ResultsFormatting(file_path = "./Structure_result_2072.txt", 
                            type = "msfinder", 
                            MS1_features_list = "./peaks_ms1_msdial.txt")
## Loading required package: progress
## Data formatting is done!
## [1] "The formatted MS2 data has been saved here: /raw/Downloads/MetaboAnalystR_4.0.0/MetaboAnalystR/vignettes/metaboanalyst_msms_input.txt"

3.2 Formatting results of LC-MS2 from SIRIUS

SIRIUS could search the database automatically and export compound identification information. MetaboAnalystR could recognize the compound identification table, user could provide that table. This formatting function is mainly used to help users to format MS2 result list for functional analysis. Therefore, users are expected to provide two essential files.

  1. MS1 peak list, containing m/z, retention time (rt), pvalue, etc.
  2. MS2 results table from either SIRIUS, usually named as “compound_identifications.tsv”;

See the following example for more information.

# Download files first

download.file("https://raw.githubusercontent.com/Zhiqiang-PANG/MetaboRaw/master/examples/compound_identifications_sirius.tsv", 
              destfile = "compound_identifications_sirius.tsv", 
              mode = "auto")

download.file("https://raw.githubusercontent.com/Zhiqiang-PANG/MetaboRaw/master/examples/peaks_ms1_mzmine.txt", 
              destfile = "peaks_ms1_mzmine.txt", 
              mode = "auto")
# This example data set is a results table - compound_identifications_sirius.tsv
# You need to include a MS1 peak list to tell us the MS1 information
# An example is provided here - peaks_ms1_mzmine.txt


library(MetaboAnalystR)

PerformMS2ResultsFormatting(file_path = "./compound_identifications_sirius.tsv", 
                            type = "sirius", 
                            MS1_features_list = "./peaks_ms1_mzmine.txt")
## Data formatting is done!
## [1] "The formatted MS2 data has been saved here: /raw/Downloads/MetaboAnalystR_4.0.0/MetaboAnalystR/vignettes/metaboanalyst_msms_input.txt"