---
title: "XCMS Parameter Optimization with IPO"
author: "Gunnar Libiseller, Thomas Riebenbauer<br>JOANNEUM RESEARCH Forschungsgesellschaft m.b.H., Graz, Austria"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{XCMS Parameter Optimization with IPO}
%\VignetteEngine{knitr::rmarkdown}
\usepackage[utf8]{inputenc}
---
```{r, echo = FALSE, message = FALSE, warning = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
library(faahKO)
```
## Introduction
This document describes how to use the R-package `IPO`
to optimize `xcms` parameters. Code examples on how to
use `IPO` are provided. Additional to `IPO` the R-packages
`xcms` and `rsm` are required. The R-package `msdata` and`mtbls2`
are recommended. The optimization process looks as following:
<br>
<b>IPO optimization process</b>
<p>
<img src="FlowChart.jpg" width="695" height="745">
</p>
## Installation
```{r install_IPO, eval=FALSE}
# try http:// if https:// URLs are not supported
if (!requireNamespace("BiocManager", quietly=TRUE))
install.packages("BiocManager")
BiocManager::install("IPO")
```
<b>Installing main suggested packages</b>
```{r install_IPO_suggestions, eval=FALSE}
# for examples of peak picking parameter optimization:
BiocManager::install("msdata")
# for examples of optimization of retention time correction and grouping
# parameters:
BiocManager::install("faahKO")
```
## Raw data
`xcms` handles the file processing hence all files can be used
that can be processed by `xcms`.
```{r file_choosing}
datapath <- system.file("cdf", package = "faahKO")
datafiles <- list.files(datapath, recursive = TRUE, full.names = TRUE)
```
## Optimize peak picking parameters
To optimize parameters different values (levels) have to
tested for these parameters. To efficiently test many
different levels design of experiment (DoE) is used.
Box-Behnken and central composite designs set three
evenly spaced levels for each parameter. The method
`getDefaultXcmsSetStartingParams` provides default values
for the lower and upper levels defining a range. Since
the levels are evenly spaced the middle level or center
point is calculated automatically. To edit the starting levels
of a parameter set the lower and upper level as desired.
If a parameter should not be optimized, set a single
default value for `xcms` processing, do not set this
parameter to NULL.
The method `getDefaultXcmsSetStartingParams` creates a
list with default values for the optimization of the
peak picking methods `centWave` or `matchedFilter`. To
choose between these two method set the parameter accordingly.
The method `optimizeXcmsSet` has the following parameters:
- files: the raw data which is the basis for optimization.
This does not necessarly need to be the whole dataset,
only quality controls should suffice.
- params: a list consisting of items named according to
`xcms` peak picking methods parameters. A default list
is created by `getDefaultXcmsSetStartingParams()`.
- BPPARAM: a `BiocParallelParam`-object (see `?BiocParallel::BiocParallelParam`)
to controll the use of parallelisation of `xcms`.
Defaults to `bpparam()`.
- nSlaves: the number of experiments of an DoE processed in parallel
- subdir: a directory where the response surface models are
stored. Can also be `NULL` if no rsm's should be saved.
The optimization process starts at the specified levels. After
the calculation of the DoE is finished the result is
evaluated and the levels automatically set accordingly.
Then a new DoE is generated and processed. This continues
until an optimum is found.
The result of peak picking optimization is a list consisting
of all calculated DoEs including the used levels, design,
response, rsm and best setting. Additionally the last list
item is a list (`\$best_settings`) providing the optimized
parameters (`\$parameters`), an xcmsSet object (`\$xset`)
calculated with these parameters and the response this
`xcms`-object gives.
```{r load_IPO, message=FALSE}
library(IPO)
```
```{r optimize_peak_picking, fig.height=7, fig.width=7, warning=FALSE}
peakpickingParameters <- getDefaultXcmsSetStartingParams('matchedFilter')
#setting levels for step to 0.2 and 0.3 (hence 0.25 is the center point)
peakpickingParameters$step <- c(0.2, 0.3)
peakpickingParameters$fwhm <- c(40, 50)
#setting only one value for steps therefore this parameter is not optimized
peakpickingParameters$steps <- 2
time.xcmsSet <- system.time({ # measuring time
resultPeakpicking <-
optimizeXcmsSet(files = datafiles[1:2],
params = peakpickingParameters,
nSlaves = 1,
subdir = NULL,
plot = TRUE)
})
```
```{r optimize_peak_picking_result}
resultPeakpicking$best_settings$result
optimizedXcmsSetObject <- resultPeakpicking$best_settings$xset
```
The response surface models of all optimization steps for the
parameter optimization of peak picking are shown above.
<!-- <br> -->
<!-- <b>Response surface models of DoE 1 of peak picking parameter optimization</b> -->
<!-- <p><img src="rsmDirectory/rsm_1.jpg" width="695" height="521"></p> -->
<!-- <br> -->
<!-- <b>Response surface models of DoE 2 of peak picking parameter optimization</b> -->
<!-- <p><img src="rsmDirectory/rsm_2.jpg" width="695" height="521"></p> -->
Currently the `xcms` peak picking methods `centWave`
and `matchedFilter` are supported. The parameter `peakwidth` of
the peak picking method `centWave` needs two values defining
a minimum and maximum peakwidth. These two values need separate
optimization and are therefore split into `min_peakwidth` and
`max_peakwidth` in `getDefaultXcmsSetStartingParams`. Also for
the `centWave` parameter prefilter two values have to be set.
To optimize these use set `prefilter` to optimize the first value
and `prefilter_value` to optimize the second value respectively.
## Optimize retention time correction and grouping parameters
Optimization of retention time correction and grouping
parameters is done simultaneously. The method
`getDefaultRetGroupStartingParams` provides default
optimization levels for the `xcms` retention time correction
method `obiwarp` and the grouping method `density`.
Modifying these levels should be done the same way done
for the peak picking parameter optimization.
The method `getDefaultRetGroupStartingParams` only supports
one retention time correction method (`obiwarp`) and one grouping
method (`density`) at the moment.
The method `optimizeRetGroup` provides the following parameter:
- xset: an `xcmsSet`-object used as basis for retention time
correction and grouping.
- params: a list consisting of items named according to `xcms`
retention time correction and grouping methods parameters.
A default list is created by `getDefaultRetGroupStartingParams`.
- nSlaves: the number of experiments of an DoE processed in parallel
- subdir: a directory where the response surface models are
stored. Can also be NULL if no rsm's should be saved.
A list is returned similar to the one returned from peak
picking optimization. The last list item consists of the
optimized retention time correction and grouping parameters
(`\$best_settings`).
```{r optimize_retcor_group, fig.height=7, fig.width=7, warning = FALSE}
retcorGroupParameters <- getDefaultRetGroupStartingParams()
retcorGroupParameters$profStep <- 1
retcorGroupParameters$gapExtend <- 2.7
time.RetGroup <- system.time({ # measuring time
resultRetcorGroup <-
optimizeRetGroup(xset = optimizedXcmsSetObject,
params = retcorGroupParameters,
nSlaves = 1,
subdir = NULL,
plot = TRUE)
})
```
The response surface models of all optimization steps for the
retention time correction and grouping parameters are shown above.
<!-- <br> -->
<!-- <b> -->
<!-- Response surface models of DoE 1 of retention time correction and grouping -->
<!-- parameter optimization</b> -->
<!-- <p><img src="rsmDirectory/retgroup_rsm_1.jpg" width="695" height="348"></p> -->
<!-- <br> -->
<!-- <b> -->
<!-- Response surface models of DoE 2 of retention time correction and grouping -->
<!-- parameter optimizationn -->
<!-- </b> -->
<!-- <p><img src="rsmDirectory/retgroup_rsm_2.jpg" width="695" height="348"></p> -->
<!-- <br> -->
<!-- <b> -->
<!-- Response surface models of DoE 3 of retention time correction and grouping -->
<!-- parameter optimization -->
<!-- </b> -->
<!-- <p><img src="rsmDirectory/retgroup_rsm_3.jpg" width="695" height="348"></p> -->
Currently the `xcms` retention time correction method
`obiwarp` and grouping method `density` are supported.
## Display optimized settings
A script which you can use to process your raw data
can be generated by using the function `writeRScript`.
```{r display_settings}
writeRScript(resultPeakpicking$best_settings$parameters,
resultRetcorGroup$best_settings)
```
## Running times and session info
Above calculations proceeded with following running times.
```{r times}
time.xcmsSet # time for optimizing peak picking parameters
time.RetGroup # time for optimizing retention time correction and grouping parameters
sessionInfo()
```