# MS2 chromatograms based alignment of targeted mass-spectrometry runs

Shubham Gupta and Hannes Röst

#### 2020-10-27

#### Package

DIAlignR 1.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 `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.
    alignTargetedRuns(dataPath = dataPath, outFile = "test.csv", runs = runs, oswMerged = TRUE)
    # For all the analytes in all runs, keep them as NULL.
    alignTargetedRuns(dataPath = dataPath, outFile = "test.csv", runs = NULL, oswMerged = TRUE)

## 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 “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 = 4618L, runs = runs, dataPath = dataPath, objType   = "light")
    #> [1] "hroest_K120809_Strep0%PlasmaBiolRepl2_R04_SW_filt"
    #> [2] "hroest_K120809_Strep10%PlasmaBiolRepl2_R04_SW_filt"
    #> [1] "Finding reference run using m-score."
    # 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")
    #> [1] "hroest_K120809_Strep0%PlasmaBiolRepl2_R04_SW_filt"
    #> [2] "hroest_K120809_Strep10%PlasmaBiolRepl2_R04_SW_filt"
    #> [1] "Finding reference run using m-score."
    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)
    #> [1] "hroest_K120809_Strep0%PlasmaBiolRepl2_R04_SW_filt"
    #> [2] "hroest_K120809_Strep10%PlasmaBiolRepl2_R04_SW_filt"
    #> [1] "Finding reference run using m-score."
    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,
                                   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 m-score."
    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.0.3 (2020-10-10)
    #> 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-41  DIAlignR_1.2.0   BiocStyle_2.18.0
    #>
    #> loaded via a namespace (and not attached):
    #>  [1] zoo_1.8-8           tidyselect_1.1.0    xfun_0.18
    #>  [4] purrr_0.3.4         colorspace_1.4-1    vctrs_0.3.4
    #>  [7] generics_0.0.2      htmltools_0.5.0     yaml_2.2.1
    #> [10] blob_1.2.1          rlang_0.4.8         pillar_1.4.6
    #> [13] glue_1.4.2          DBI_1.1.0           mzR_2.24.0
    #> [16] BiocGenerics_0.36.0 bit64_4.0.5         RColorBrewer_1.1-2
    #> [19] jpeg_0.1-8.1        lifecycle_0.2.0     stringr_1.4.0
    #> [22] ProtGenerics_1.22.0 munsell_0.5.0       gtable_0.3.0
    #> [25] codetools_0.2-16    evaluate_0.14       memoise_1.1.0
    #> [28] labeling_0.4.2      latticeExtra_0.6-29 Biobase_2.50.0
    #> [31] knitr_1.30          parallel_4.0.3      Rcpp_1.0.5
    #> [34] scales_1.1.1        BiocManager_1.30.10 magick_2.5.0
    #> [37] farver_2.0.3        bit_4.0.4           gridExtra_2.3
    #> [40] png_0.1-7           ggplot2_3.3.2       digest_0.6.27
    #> [43] stringi_1.5.3       bookdown_0.21       dplyr_1.0.2
    #> [46] ncdf4_1.17          grid_4.0.3          tools_4.0.3
    #> [49] magrittr_1.5        tibble_3.0.4        RSQLite_2.2.1
    #> [52] crayon_1.3.4        tidyr_1.1.2         pkgconfig_2.0.3
    #> [55] ellipsis_0.3.1      MASS_7.3-53         rmarkdown_2.5
    #> [58] R6_2.4.1            signal_0.7-6        compiler_4.0.3