# MS2 chromatograms based alignment of targeted mass-spectrometry runs

Shubham Gupta and Hannes Röst

#### 2020-03-12

#### Package

DIAlignR 0.99.12

In this document we are presenting a workflow of retention-time alignment across multiple Targeted-MS (e.g. DIA, SWATH-MS, PRM, SRM) runs using DIAlignR. This tool requires MS2 chromatograms and provides a hybrid approach of global and local alignment to establish correspondence between peaks.

## 0.1 Install DIAlignR

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

    library(DIAlignR)

## 0.2 Prepare input files for alignment

Mass-spectrometry files mostly contains spectra. Targeted proteomics workflow identifyies analytes from their chromatographic elution profile. DIAlignR extends the same concept for retention-time (RT) alignment and, therefore, relies on MS2 chromatograms. DIAlignR expects raw chromatogram file (.chrom.mzML) and FDR-scored features (.osw) file.
Example files are available with this package and can be located with this command:

    dataPath <- system.file("extdata", package = "DIAlignR")

(Optional) To obtain files for alignment, following three steps are needed:

- Step 1 Convert spectra files from vendor-specific format to standard mzMl format using ProteoWizard-MSConvert.
- Step 2 Extract features and raw extracted-ion chromatograms(XICs) for library analytes. A detailed tutorial using OpenSWATH is available for this steps. In short, following `bash` command can be used:

    OpenSwathWorkflow -in Filename.mzML.gz -tr library.pqp -tr_irt
    iRTassays.TraML -out_osw Filename.osw -out_chrom Filename.chrom.mzML

Output files Filename.osw and Filename.chrom.mzML are required to next steps. Some chromatograms are stored in compressed form and currently inaccesible by `mzR`. In such cases `mzR` would throw an error indicating `Invalid cvParam accession "1002746"`. To avoid this issue, uncompress chromatograms using OpenMS.

    FileConverter -in Filename.chrom.mzML -in_type 'mzML' -out Filename.chrom.mzML

- Step 3: Score features and calculate their q-values. A machine-learning based workflow is available with PyProphet. For multiplt-runs experiment-wide FDR is recommended. An example of running pyprophet on OpenSWATH results is given below:

    pyprophet merge --template=library.pqp --out=merged.osw *.osw
    pyprophet score --in=merged.osw --classifier=XGBoost --level=ms2 --xeval_num_iter=3 \
    --ss_initial_fdr=0.05 --ss_iteration_fdr=0.01
    pyprophet peptide --in=merged.osw --context=experiment-wide

Congrats! Now we have raw chromatogram files and associated scored features in merged.osw files. Move all .chrom.mzML files in `mzml` directory and merged.osw file in `osw` directory. The parent folder is given as `dataPath` to DIAlignR functions.

## 0.3 Performing alignment on DIA runs

`alignTargetedRuns` function aligns Proteomics or Metabolomics DIA runs. It expects two directories “osw” and “mzml” at `dataPath`. It outputs an intensity table where rows specify each analyte and columns specify runs. Use parameter `saveFiles = TRUE` to have aligned retetion time and intensities saved in the current directory.

    runs <- c("hroest_K120809_Strep0%PlasmaBiolRepl2_R04_SW_filt",
              "hroest_K120809_Strep10%PlasmaBiolRepl2_R04_SW_filt")
    # For specific runs provide their names.
    intensityTbl <- alignTargetedRuns(dataPath = dataPath, runs = runs, analyteInGroupLabel = TRUE)
    # For specific analytes provide their names.
    intensityTbl <- alignTargetedRuns(dataPath = dataPath, runs = NULL,
                                      analytes = c("QFNNTDIVLLEDFQK_3"), analyteInGroupLabel = FALSE)
    # For all the analytes in all runs, keep them as NULL.
    intensityTbl <- alignTargetedRuns(dataPath = dataPath, runs = NULL, analytes = NULL,
                                      analyteInGroupLabel = TRUE)

## 0.4 Fetching AlignObj for analytes

For getting alignment object which has aligned indices of XICs `getAlignObjs` function can be used. Like previous function, it expects two directories “osw” and “mzml” at `dataPath`. It performs alignment for exactly two runs. In case of `refRun` is not provided, m-score from osw files is used to select reference run.

    runs <- c("hroest_K120809_Strep0%PlasmaBiolRepl2_R04_SW_filt",
              "hroest_K120809_Strep10%PlasmaBiolRepl2_R04_SW_filt")
    AlignObjLight <- getAlignObjs(analytes = "QFNNTDIVLLEDFQK_3", runs = runs, dataPath = dataPath,
                                  objType   = "light")
    slotNames(AlignObjLight[["QFNNTDIVLLEDFQK_3"]][[1]])
    #> [1] "indexA_aligned" "indexB_aligned" "score"
    AlignObjMedium <- getAlignObjs(analytes = "QFNNTDIVLLEDFQK_3", runs = runs, dataPath = dataPath,
                                   objType  = "medium")
    slotNames(AlignObjMedium[["QFNNTDIVLLEDFQK_3"]][[1]])
    #> [1] "s"              "path"           "indexA_aligned" "indexB_aligned"
    #> [5] "score"

## 0.5 Visualizing the aligned chromatograms

We can visualize aligned chromatograms using `plotAlignedAnalytes`. The top figure is experiment unaligned-XICs, middle one is reference XICs, last figure is experiment run aligned to reference.

    runs <- c("hroest_K120809_Strep0%PlasmaBiolRepl2_R04_SW_filt",
     "hroest_K120809_Strep10%PlasmaBiolRepl2_R04_SW_filt")
    AlignObj <- getAlignObjs(analytes = "QFNNTDIVLLEDFQK_3", runs = runs, dataPath = dataPath)
    plotAlignedAnalytes(AlignObj, annotatePeak = TRUE)

## 0.6 Visualizing the alignment path

We can also visualize the alignment path using `plotAlignemntPath` function.

    library(lattice)
    runs <- c("hroest_K120809_Strep0%PlasmaBiolRepl2_R04_SW_filt",
     "hroest_K120809_Strep10%PlasmaBiolRepl2_R04_SW_filt")
    AlignObjOutput <- getAlignObjs(analytes = "QFNNTDIVLLEDFQK_3", runs = runs,
                                   dataPath = dataPath, objType = "medium")
    plotAlignmentPath(AlignObjOutput)

## 0.7 Citation

Gupta S, Ahadi S, Zhou W, Röst H. “DIAlignR Provides Precise Retention Time Alignment Across Distant Runs in DIA and Targeted Proteomics.” Mol Cell Proteomics. 2019 Apr;18(4):806-817. doi: https://doi.org/10.1074/mcp.TIR118.001132

## 0.8 Session Info

    sessionInfo()
    #> R Under development (unstable) (2020-01-27 r77730)
    #> Platform: x86_64-w64-mingw32/x64 (64-bit)
    #> Running under: Windows Server 2012 R2 x64 (build 9600)
    #>
    #> Matrix products: default
    #>
    #> locale:
    #> [1] LC_COLLATE=C
    #> [2] LC_CTYPE=English_United States.1252
    #> [3] LC_MONETARY=English_United States.1252
    #> [4] LC_NUMERIC=C
    #> [5] LC_TIME=English_United States.1252
    #>
    #> attached base packages:
    #> [1] stats     graphics  grDevices utils     datasets  methods   base
    #>
    #> other attached packages:
    #> [1] lattice_0.20-40  DIAlignR_0.99.12 BiocStyle_2.15.6
    #>
    #> loaded via a namespace (and not attached):
    #>  [1] zoo_1.8-7           tidyselect_1.0.0    xfun_0.12
    #>  [4] purrr_0.3.3         colorspace_1.4-1    vctrs_0.2.4
    #>  [7] htmltools_0.4.0     yaml_2.2.1          blob_1.2.1
    #> [10] rlang_0.4.5         pillar_1.4.3        glue_1.3.1
    #> [13] DBI_1.1.0           mzR_2.21.1          RColorBrewer_1.1-2
    #> [16] BiocGenerics_0.33.0 bit64_0.9-7         jpeg_0.1-8.1
    #> [19] lifecycle_0.2.0     stringr_1.4.0       ProtGenerics_1.19.3
    #> [22] munsell_0.5.0       gtable_0.3.0        codetools_0.2-16
    #> [25] evaluate_0.14       memoise_1.1.0       latticeExtra_0.6-29
    #> [28] labeling_0.3        Biobase_2.47.2      knitr_1.28
    #> [31] parallel_4.0.0      Rcpp_1.0.3          scales_1.1.0
    #> [34] BiocManager_1.30.10 magick_2.3          farver_2.0.3
    #> [37] bit_1.1-15.2        gridExtra_2.3       png_0.1-7
    #> [40] ggplot2_3.3.0       digest_0.6.25       stringi_1.4.6
    #> [43] bookdown_0.18       dplyr_0.8.5         ncdf4_1.17
    #> [46] grid_4.0.0          tools_4.0.0         magrittr_1.5
    #> [49] tibble_2.1.3        RSQLite_2.2.0       crayon_1.3.4
    #> [52] tidyr_1.0.2         pkgconfig_2.0.3     MASS_7.3-51.5
    #> [55] ellipsis_0.3.0      assertthat_0.2.1    rmarkdown_2.1
    #> [58] R6_2.4.1            signal_0.7-6        compiler_4.0.0