Contents

1 Introduction

Neighbor-wise Compound-specific Graphical Time Warping (ncGTW) [1] is an alignment algorithm that can align LC-MS profiles by leveraging expected retention time (RT) drift structures and compound-specific warping functions. This algorithm is improved from graphical time warping (GTW) [2], a popular dynamic time warping (DTW) based alignment method [3]. Specifically, ncGTW uses individualized warping functions for different compounds and assigns constraint edges on warping functions of neighboring samples. That is, ncGTW avoids the popular but not accurate assumption which assumes all the m/z bins in the same sample share the same warping function. This assumption often fails when the dataset contains hundreds of samples or the data acquisition time longer than a week. Moreover, by considering the RT drifts structure, ncGTW can align RT more accurately.

ncGTW is an R package developed as a plug-in of xcms, a popular LC-MS data analysis R package [46]. Due to the same warping function assumption or bad parameter settings, xcms may have some misaligned features, and there is a function in ncGTW to identify such misalignments. After identifying the misaligned features, the user can realign these features with the alignment function in ncGTW to obtain a better alignment result for more accurate analysis, such as peak-regrouping or peak-filling with xcms.

You can install the latest version of ncGTW from GitHub by

devtools::install_github("ChiungTingWu/ncGTW")

or from Bioconductor by

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

BiocManager::install("ncGTW")

2 Quick Start

To check there are misaligned features from xcms or not, one can input two xcms grouping results with different values of RT window parameter (xcms grouping parameter, bw) to the function misalignDetect(). One value of bw should be the expected maximal RT drift, and another should be near to the RT sampling resolution (the inverse of scan frequency). If there are some detected misaligned features, the user can decide to adjust the paramters in xcms or use ncGTW to realign them. Besides the xcms aligment results, the only paramter with no default in misalignDetect() is ppm, which should be set as same as ppm of the peak detection in xcms.

excluGroups <- misalignDetect(xcmsLargeWin, xcmsSmallWin, ppm)

3 Misaligned Feature Detection and Realignment

3.1 RT Structure Incorporation

To demonstrate the workflow of ncGTW, an example dataset is included in the package. The aquisition time of the dataset is more than two weeks, in which the 20 samples are selected from a large dataset for a quick demonstration.

library(xcms)
library(ncGTW)
filepath <- system.file("extdata", package = "ncGTW")
file <- list.files(filepath, pattern = "mzxml", full.names = TRUE)
# The paths of the 20 samples

To incorporate the RT structure, the order of the paths in file should be as same as the sample acquisition order (run order). In the example dataset, the index in each file name is the acquisition order, so we sort the paths according to tempInd. When dealing with other dataset, the user should make sure the order of the paths is as same the order of data acquisition.

tempInd <- matrix(0, length(file), 1)
for (n in seq_along(file)){
    tempCha <- file[n]
    tempLen <- nchar(tempCha)
    tempInd[n] <- as.numeric(substr(tempCha, regexpr("example", tempCha) + 7, 
        tempLen - 6))
}
file <- file[sort.int(tempInd, index.return = TRUE)$ix]
# Sort the paths by data acquisition order to incorporate the RT structure

3.2 XCMS Preprocessing

As a plug-in, the inputs of ncGTW are the alignment results from xcms, so first we need to apply xcms on the dataset. The parameters should be decided by the user when dealing with other datasets.

CPWmin <- 2 
CPWmax <- 25 
ppm <- 15 
xsnthresh <- 3 
LM <- FALSE
integrate <- 2 
RTerror <- 6 
MZerror <- 0.05
prefilter <- c(8, 1000)
# XCMS parameters
ds <- xcmsSet(file, method="centWave", peakwidth=c(CPWmin, CPWmax), ppm=ppm, 
    noise=xsnthresh, integrate=integrate, prefilter=prefilter)
gds <- group(ds, mzwid=MZerror, bw=RTerror)
agds <- retcor(gds, missing=5)
# XCMS peak detection and RT alignment

To detect the misaligned features, ncGTW needs two XCMS grouping results with different values of bw. The larger one should be expected maximal RT drift, and the smaller one should be the RT sampling resolution (the inverse of scan frequency).

bwLarge <- RTerror
bwSmall <- 0.3
# Two different values of bw parameter
xcmsLargeWin <- group(agds, mzwid=MZerror, bw=bwLarge)
xcmsSmallWin <- group(agds, mzwid=MZerror, bw=bwSmall, minfrac=0)
# Two resolution of XCMS grouping results

3.3 ncGTW Workflow

After XCMS preprocessing, ncGTW can be applied on the results. There are two major steps in ncGTW, misaligned feature detection and misaligned feature realignment.

3.3.1 Misaligned Feature Detection

To detect the misaligned features, misalignDetect() needs two different XCMS grouping results as inputs. This function tells which features in xcmsLargeWin could be broken into several small features in xcmsSmallWin, and the detected features should be misaligned features. ppm is one criteria to decide the small features in xcmsLargeWin are from the same compounds or not, and should be set as same as the one in XCMS peak detection.

excluGroups <- misalignDetect(xcmsLargeWin, xcmsSmallWin, ppm)
# Detect misaligned features
show(excluGroups)
#>      index    mzmed    mzmin    mzmax    rtmed    rtmin    rtmax npeaks extdata
#> [1,]     1 630.5534 630.5527 630.5546 349.4897 347.2043 355.5610     14      14
#> [2,]     9 931.5268 931.5251 931.5275 336.6458 335.6331 339.6014     17      17

There are two peak groups (features) are detected as shown in excluGroups. Before realigning them, the raw profile of each detected feature of each sample needs to load from the files. loadProfile() loads the needed information with file paths (file) and the detected features (excluGroups) as inputs.

ncGTWinputs <- loadProfile(file, excluGroups)
# Load raw profiles from the files

The user can also check the detected features are really misaligned or not by viewing the extracted ion chromatogram. plotGroup() draws the extracted ion chromatogram. ncGTWinputs is the loaded information from loadProfile(), xcmsLargeWin@rt$corrected is the alignment by XCMS, and ind is just a parameter for indexing the chromatograms. The user are free to set ind.

for (n in seq_along(ncGTWinputs))
    plotGroup(ncGTWinputs[[n]], slot(xcmsLargeWin, 'rt')$corrected, ind=n)