# MS2 chromatograms based alignment of targeted mass-spectrometry runs

Shubham Gupta and Hannes Röst

#### 2021-10-26

#### Package

DIAlignR 2.2.0

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 `xics` 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 “xics” 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")
    params <- paramsDIAlignR()
    params[["context"]] <- "experiment-wide"
    # For specific runs provide their names.
    alignTargetedRuns(dataPath = dataPath, outFile = "test.csv", runs = runs, oswMerged = TRUE, params = params)
    # For all the analytes in all runs, keep them as NULL.
    alignTargetedRuns(dataPath = dataPath, outFile = "test.csv", runs = NULL, oswMerged = TRUE, params = params)

## 0.4 Investigating alignment of 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 “xics” 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 = 4618L, runs = runs, dataPath = dataPath, objType   = "light", params = params)
    #> [1] "hroest_K120809_Strep0%PlasmaBiolRepl2_R04_SW_filt"
    #> [2] "hroest_K120809_Strep10%PlasmaBiolRepl2_R04_SW_filt"
    #> [1] "Finding reference run using SCORE_PEPTIDE table"
    # First element contains names of runs, spectra files, chromatogram files and feature files.
    AlignObjLight[[1]][, c("runName", "spectraFile")]
    #>                                                 runName
    #> run1  hroest_K120809_Strep0%PlasmaBiolRepl2_R04_SW_filt
    #> run2 hroest_K120809_Strep10%PlasmaBiolRepl2_R04_SW_filt
    #>                                                              spectraFile
    #> run1  data/raw/hroest_K120809_Strep0%PlasmaBiolRepl2_R04_SW_filt.mzML.gz
    #> run2 data/raw/hroest_K120809_Strep10%PlasmaBiolRepl2_R04_SW_filt.mzML.gz
    obj <- AlignObjLight[[2]][["4618"]][[1]][["AlignObj"]]
    slotNames(obj)
    #> [1] "indexA_aligned" "indexB_aligned" "score"
    names(as.list(obj))
    #> [1] "indexA_aligned" "indexB_aligned" "score"
    AlignObjMedium <- getAlignObjs(analytes = 4618L, runs = runs, dataPath = dataPath, objType  = "medium", params = params)
    #> [1] "hroest_K120809_Strep0%PlasmaBiolRepl2_R04_SW_filt"
    #> [2] "hroest_K120809_Strep10%PlasmaBiolRepl2_R04_SW_filt"
    #> [1] "Finding reference run using SCORE_PEPTIDE table"
    obj <- AlignObjMedium[[2]][["4618"]][[1]][["AlignObj"]]
    slotNames(obj)
    #> [1] "s"              "path"           "indexA_aligned" "indexB_aligned"
    #> [5] "score"

Alignment object has slots * indexA_aligned aligned indices of reference chromatogram. * indexB_aligned aligned indices of experiment chromatogram * score cumulative score of the alignment till an index. * s similarity score matrix. * path path of the alignment through similarity score matrix.

## 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 = 4618L, runs = runs, dataPath = dataPath, params = params)
    #> [1] "hroest_K120809_Strep0%PlasmaBiolRepl2_R04_SW_filt"
    #> [2] "hroest_K120809_Strep10%PlasmaBiolRepl2_R04_SW_filt"
    #> [1] "Finding reference run using SCORE_PEPTIDE table"
    plotAlignedAnalytes(AlignObj, annotatePeak = TRUE)
    #> Warning: Removed 30 row(s) containing missing values (geom_path).

## 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 = 4618L, runs = runs, params = params, dataPath = dataPath, objType = "medium")
    #> [1] "hroest_K120809_Strep0%PlasmaBiolRepl2_R04_SW_filt"
    #> [2] "hroest_K120809_Strep10%PlasmaBiolRepl2_R04_SW_filt"
    #> [1] "Finding reference run using SCORE_PEPTIDE table"
    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 version 4.1.1 (2021-08-10)
    #> Platform: x86_64-w64-mingw32/x64 (64-bit)
    #> Running under: Windows Server x64 (build 17763)
    #>
    #> 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-45  DIAlignR_2.2.0   BiocStyle_2.22.0
    #>
    #> loaded via a namespace (and not attached):
    #>  [1] Rcpp_1.0.7          ape_5.5             tidyr_1.1.4
    #>  [4] png_0.1-7           zoo_1.8-9           assertthat_0.2.1
    #>  [7] digest_0.6.28       utf8_1.2.2          R6_2.5.1
    #> [10] signal_0.7-7        RSQLite_2.2.8       evaluate_0.14
    #> [13] pracma_2.3.3        highr_0.9           ggplot2_3.3.5
    #> [16] pillar_1.6.4        rlang_0.4.12        data.table_1.14.2
    #> [19] jquerylib_0.1.4     blob_1.2.2          phangorn_2.7.1
    #> [22] magick_2.7.3        Matrix_1.3-4        reticulate_1.22
    #> [25] rmarkdown_2.11      labeling_0.4.2      stringr_1.4.0
    #> [28] igraph_1.2.7        bit_4.0.4           munsell_0.5.0
    #> [31] compiler_4.1.1      xfun_0.27           pkgconfig_2.0.3
    #> [34] RMSNumpress_1.0.1   htmltools_0.5.2     tidyselect_1.1.1
    #> [37] gridExtra_2.3       tibble_3.1.5        bookdown_0.24
    #> [40] quadprog_1.5-8      codetools_0.2-18    fansi_0.5.0
    #> [43] crayon_1.4.1        dplyr_1.0.7         MASS_7.3-54
    #> [46] grid_4.1.1          nlme_3.1-153        jsonlite_1.7.2
    #> [49] gtable_0.3.0        lifecycle_1.0.1     DBI_1.1.1
    #> [52] magrittr_2.0.1      scales_1.1.1        stringi_1.7.5
    #> [55] cachem_1.0.6        farver_2.1.0        latticeExtra_0.6-29
    #> [58] bslib_0.3.1         ellipsis_0.3.2      generics_0.1.1
    #> [61] vctrs_0.3.8         fastmatch_1.1-3     RColorBrewer_1.1-2
    #> [64] tools_4.1.1         bit64_4.0.5         glue_1.4.2
    #> [67] purrr_0.3.4         jpeg_0.1-9          parallel_4.1.1
    #> [70] fastmap_1.1.0       yaml_2.2.1          colorspace_2.0-2
    #> [73] BiocManager_1.30.16 memoise_2.0.0       knitr_1.36
    #> [76] sass_0.4.0