In Roestlab/DIAlign: Dynamic Programming Based Alignment of MS2 Chromatograms

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

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.

Install DIAlignR

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

library(DIAlignR)

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:

```{bash, eval=FALSE} 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.

```{bash, eval=FALSE}
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:

```{bash, eval=FALSE} 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.

## 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.

```r
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)

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)
# First element contains names of runs, spectra files, chromatogram files and feature files.
AlignObjLight[[1]][, c("runName", "spectraFile")]
obj <- AlignObjLight[[2]][["4618"]][[1]][["AlignObj"]]
slotNames(obj)
names(as.list(obj))
AlignObjMedium <- getAlignObjs(analytes = 4618L, runs = runs, dataPath = dataPath, objType  = "medium", params = params)
obj <- AlignObjMedium[[2]][["4618"]][[1]][["AlignObj"]]
slotNames(obj)

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.

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)
plotAlignedAnalytes(AlignObj, annotatePeak = TRUE)

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")
plotAlignmentPath(AlignObjOutput)

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