-
Notifications
You must be signed in to change notification settings - Fork 20
/
IPO.Rmd
256 lines (202 loc) · 9.29 KB
/
IPO.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
---
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()
```