# MS2 chromatograms based alignment of targeted mass-spectrometry runs

Shubham Gupta and Hannes Röst

#### 2022-11-01

#### Package

DIAlignR 2.6.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.sqMass) 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 (Paper):

- 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` commands to be used:

    OpenSwathWorkflow -in Filename.mzML.gz -tr library.pqp -tr_irt
    iRTassays.TraML -out_osw Filename.osw -out_chrom Filename.chrom.mzML
    OpenSwathMzMLFileCacher -in Filename.chrom.mzML -out Filename.chrom.sqMass -lossy_compression false

Output files Filename.osw and Filename.chrom.sqMass are required for next steps.

Note: If you prefer to use chrom.mzML instead of chrom.sqMass, 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. This step is suggested only for small studies (n<30). For large n, look into the large-scale analysis section. 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=ms1ms2
    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.sqMass 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

There are three modes for multirun alignment: star, MST and Progressive. The functions align proteomics or metabolomics DIA runs. They expect two directories “osw” and “xics” at `dataPath`, and output an intensity table where rows specify each analyte and columns specify runs.

    runs <- c("hroest_K120809_Strep0%PlasmaBiolRepl2_R04_SW_filt",
              "hroest_K120809_Strep10%PlasmaBiolRepl2_R04_SW_filt")
    params <- paramsDIAlignR()
    params[["context"]] <- "experiment-wide"

## 0.4 Star alignmnet

    # For specific runs provide their names.
    alignTargetedRuns(dataPath = dataPath, outFile = "test", runs = runs, oswMerged = TRUE, params = params)
    # For all the analytes in all runs, keep them as NULL.
    alignTargetedRuns(dataPath = dataPath, outFile = "test", runs = NULL, oswMerged = TRUE, params = params)

## 0.5 MST alignmnet

For MST alignment, a precomputed guide-tree can be supplied.

    tree <- "run2 run2\nrun1 run0"
    mstAlignRuns(dataPath = dataPath, outFile = "test", mstNet = tree, oswMerged = TRUE, params = params)
    # Compute tree on-the-fly
    mstAlignRuns(dataPath = dataPath, outFile = "test", oswMerged = TRUE, params = params)

## 0.6 Progressive alignmnet

Similar to previous approach, a precomputed guide-tree can be supplied.

    text1 <- "(run1:0.08857142857,(run0:0.06857142857,run2:0.06857142857)masterB:0.02)master1;"
    progAlignRuns(dataPath = dataPath, outFile = "test", newickTree = text1, oswMerged = TRUE, params = params)
    # Compute tree on-the-fly
    progAlignRuns(dataPath = dataPath, outFile = "test", oswMerged = TRUE, params = params)

## 0.7 For large-scale analysis

In a large-scale study, the `pyprophet merge` would create a huge file that can’t be fit in the memory. Hence, scaling-up of pyprophet based on subsampling is recommended. Do not run the last two commands `pyprophet backpropagate` and `pyprophet export`, as these commands copy scores from `model_global.osw` to each run, increasing the size unnecessarily.

Instead, use `oswMerged = FALSE` and `scoreFile=PATH/TO/model_global.osw`.

## 0.8 Requantification

## 0.9 Visualizing multiple chromatograms

## 0.10 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.11 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.12 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.13 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.14 Session Info

    sessionInfo()
    #> R version 4.2.1 (2022-06-23 ucrt)
    #> Platform: x86_64-w64-mingw32/x64 (64-bit)
    #> Running under: Windows Server x64 (build 20348)
    #>
    #> Matrix products: default
    #>
    #> locale:
    #> [1] LC_COLLATE=C
    #> [2] LC_CTYPE=English_United States.utf8
    #> [3] LC_MONETARY=English_United States.utf8
    #> [4] LC_NUMERIC=C
    #> [5] LC_TIME=English_United States.utf8
    #>
    #> attached base packages:
    #> [1] stats     graphics  grDevices utils     datasets  methods   base
    #>
    #> other attached packages:
    #> [1] lattice_0.20-45  DIAlignR_2.6.0   BiocStyle_2.26.0
    #>
    #> loaded via a namespace (and not attached):
    #>  [1] Rcpp_1.0.9          ape_5.6-2           deldir_1.0-6
    #>  [4] tidyr_1.2.1         png_0.1-7           zoo_1.8-11
    #>  [7] assertthat_0.2.1    digest_0.6.30       utf8_1.2.2
    #> [10] R6_2.5.1            signal_0.7-7        RSQLite_2.2.18
    #> [13] evaluate_0.17       pracma_2.4.2        highr_0.9
    #> [16] ggplot2_3.3.6       pillar_1.8.1        rlang_1.0.6
    #> [19] data.table_1.14.4   jquerylib_0.1.4     blob_1.2.3
    #> [22] phangorn_2.10.0     magick_2.7.3        Matrix_1.5-1
    #> [25] reticulate_1.26     rmarkdown_2.17      labeling_0.4.2
    #> [28] stringr_1.4.1       igraph_1.3.5        bit_4.0.4
    #> [31] munsell_0.5.0       compiler_4.2.1      xfun_0.34
    #> [34] pkgconfig_2.0.3     RMSNumpress_1.0.1   htmltools_0.5.3
    #> [37] tidyselect_1.2.0    gridExtra_2.3       tibble_3.1.8
    #> [40] bookdown_0.29       quadprog_1.5-8      codetools_0.2-18
    #> [43] fansi_1.0.3         dplyr_1.0.10        withr_2.5.0
    #> [46] MASS_7.3-58.1       grid_4.2.1          nlme_3.1-160
    #> [49] jsonlite_1.8.3      gtable_0.3.1        lifecycle_1.0.3
    #> [52] DBI_1.1.3           magrittr_2.0.3      scales_1.2.1
    #> [55] cli_3.4.1           stringi_1.7.8       cachem_1.0.6
    #> [58] farver_2.1.1        latticeExtra_0.6-30 bslib_0.4.0
    #> [61] ellipsis_0.3.2      generics_0.1.3      vctrs_0.5.0
    #> [64] fastmatch_1.1-3     RColorBrewer_1.1-3  tools_4.2.1
    #> [67] interp_1.1-3        bit64_4.0.5         glue_1.6.2
    #> [70] purrr_0.3.5         jpeg_0.1-9          parallel_4.2.1
    #> [73] fastmap_1.1.0       yaml_2.3.6          colorspace_2.0-3
    #> [76] BiocManager_1.30.19 memoise_2.0.1       knitr_1.40
    #> [79] sass_0.4.2