--- title: "MsQuality: Calculation of QC metrics from mass spectrometry data" author: - name: Thomas Naake and Johannes Rainer mail: thomas.naake@embl.de, thomasnaake@googlemail.com, johannes.rainer@eurac.edu affiliation: European Molecular Biology Laboratory, Meyerhofstrasse 1, 69117 Heidelberg/ EURAC Research, Viale Druso 1, 39100 BOlzano package: MsQuality output: BiocStyle::html_document: toc_float: true bibliography: MsQuality-citations.bib vignette: > %\VignetteIndexEntry{QC for metabolomics and proteomics data} %\VignetteEngine{knitr::rmarkdown} %\VignetteKeywords{Mass Spectrometry, MS, Metabolomics, Proteomics, Visualization, QC} %\VignettePackage{MsQuality-vignette} %\VignetteEncoding{UTF-8} --- ```{r style, echo = FALSE, results = 'asis'} BiocStyle::markdown() ``` ```{r env, include=FALSE, echo=FALSE, cache=FALSE} library("knitr") opts_chunk$set(stop_on_error = 1L) suppressPackageStartupMessages(library("MsQuality")) suppressPackageStartupMessages(library("Spectra")) ``` # Introduction {#sec-intro} Data quality assessment is an integral part of preparatory data analysis to ensure sound biological information retrieval. We present here the `MsQuality` package, which provides functionality to calculate quality metrics for mass spectrometry-derived, spectral data at the per-sample level. `MsQuality` relies on the [`mzQC`](https://github.com/HUPO-PSI/mzQC) framework of quality metrics defined by the Human Proteome Organization-Proteomics Standards Intitiative (HUPO-PSI). These metrics quantify the quality of spectral raw files using a controlled vocabulary. The package is especially addressed towards users that acquire mass spectrometry data on a large scale (e.g. data sets from clinical settings consisting of several thousands of samples): while it is easier to control for high-quality data acquisition in small-scale experiments, typically run in one or few batches, clinical data sets are often acquired over longer time frames and are prone to higher technical variation that is often unnoticed. `MsQuality` tries to address this problem by calculating metrics that can be stored along the spectral data sets (raw files or feature-extracted data sets). `MsQuality`, thus, facilitates the tracking of shifts in data quality and quantifies the quality using multiple metrics. It should be thus easier to identify samples that are of low quality (high-number of missing values, termination of chromatographic runs, low instrument sensitivity, etc.). We would like to note here that these metrics only give an indication of data quality, and, before removing indicated low-quality samples from the analysis more advanced analytics, e.g. using the implemented functionality and visualizations in the `MatrixQCvis` package, should be scrutinized. Also, data quality should always be regarded in the context of the sample type and experimental settings, i.e. quality metrics should always be compared with regard to the sample type, experimental setup, instrumentation, etc.. The `MsQuality` package allows to calculate low-level quality metrics that require minimum information on mass spectrometry data: retention time, m/z values, and associated intensities. The list included in the `mzQC` framework is excessive, also including metrics that rely on more high-level information, that might not be readily accessible from .raw or .mzML files, e.g. pump pressure mean, or rely on alignment results, e.g. retention time mean shift, signal-to-noise ratio, precursor errors (ppm). The `MsQuality` package is built upon the `Spectra` and the `MsExperiment` package. Metrics will be calculated based on the information stored in a `Spectra` object and the respective `dataOrigin` entries are used to distinguish between the mass spectral data of multiple samples. The `MsExperiment` serves as a container to store the mass spectral data of multiple samples. `MsQuality` enables the user to calculate quality metrics both on `Spectra` and `MsExperiment` objects. In this vignette, we will (i) create some exemplary `Spectra` and `MsExperiment` objects, (ii) calculate the quality metrics on these data sets, and (iii) visualize some of the metrics. ## Alternative software for data quality assessment Other `R` packages are available in Bioconductor that are able to assess the quality of mass spectrometry data: [`artMS`](https://bioconductor.org/packages/release/bioc/html/artMS.html) uses MaxQuant output and enables to calculate several QC metrics, e.g. correlation matrix for technical replicates, calculation of total sum of intensities in biological replicates, total peptide counts in biological replicates, charge state distribution of PSMs identified in each biological replicates, or MS1 scan counts in each biological replicate. [`MSstatsQC`](https://bioconductor.org/packages/release/bioc/html/MSstatsQC.html) and the visualization tool [`MSstatsQCgui`](https://bioconductor.org/packages/release/bioc/html/MSstatsQCgui.html) require csv files in long format from spectral processing tools such as Skyline and Panorama autoQC or `MSnbase` objects. `MSstatsQC` enables to generate individual, moving range, cumulative sum for mean, and/or cumulative sum for variability control charts for each metric. Metrics can be any kind of user-defined metric stored in the data columns for a given peptide, e.g. retention time and peak area. [`MQmetrics`](https://bioconductor.org/packages/release/bioc/html/MQmetrics.html) provides a pipeline to analyze the quality of proteomics data sets from MaxQuant files and focuses on proteomics-/MaxQuant-specific metrics, e.g. proteins identified, peptides identified, or proteins versus peptide/protein ratio. [`MatrixQCvis`](https://bioconductor.org/packages/release/bioc/html/MatrixQCvis.html) provides an interactive shiny-based interface to assess data quality at various processing steps (normalization, transformation, batch correction, and imputation) of rectangular matrices. The package includes several diagnostic plots and metrics such as barplots of intensity distributions, plots to visualize drifts, MA plots and Hoeffding's D value calculation, and dimension reduction plots and provides specific tools to analyze data sets containing missing values as commonly observed in mass spectrometry. [`proBatch`](https://bioconductor.org/packages/release/bioc/html/proBatch.html) enables to assess batch effects in (prote)omics data sets and corrects these batch effects in subsequent steps. Several tools to visualize data quality are included in the `proBatch` packages, such as barplots of intensity distributions, cluster and heatmap analysis tools, and PCA dimension reduction plots. Additionally, `proBatch` enables to assess diagnostics at the feature level, e.g. peptides or spike-ins. # Installation To install this package, start `R` and enter: ```{r, eval = FALSE} if (!requireNamespace("BiocManager", quietly = TRUE)) install.packages("BiocManager") if (!requireNamespace("remotes", quietly = TRUE)) install.packages("remotes") ## to install from Bioconductor BiocManager::install("MsQuality") ## to install from GitHub BiocManager::install("tnaake/MsQuality") ``` This will install this package and all eventually missing dependencies. # Questions and bugs {-} `MsQuality` is currently under active development. If you discover any bugs, typos or develop ideas of improving `MsQuality` feel free to raise an issue via [GitHub](https://github.com/tnaake/MsQuality) or send a mail to the developer. # Create `Spectra` and `MsExperiment` objects Load the `Spectra` package. ```{r load_Spectra} library("Spectra") library("MsExperiment") library("MsQuality") ``` ## Create `Spectra` and `MsExperiment` objects from mzML files There are several options available to create a `Spectra` object. One way, as outlined in the vignette of the `r BiocStyle::Biocpkg("Spectra")` package is by specifying the location of mass spectrometry raw files in `mzML`, `mzXML` or `CDF` format and using the `MsBackendMzR` backend. Here we load the example files from the `sciex` data set of the `msdata` package and create a `Spectra` object from the two provided `mzML` files. The example is taken from the `Spectra` vignette. ```{r spectra_sciex, eval = FALSE, echo = TRUE} ## this example is taken from the Spectra vignette fls <- dir(system.file("sciex", package = "msdata"), full.names = TRUE) sps_sciex <- Spectra(fls, backend = MsBackendMzR()) ``` The data set consists of a single sample measured in two different injections to the same LC-MS setup. An empty instance of an `MsExperiment` object is created and populated with information on the samples by assigning data on the samples (`sampleData`), information on the `mzML` files (`MsExperimentFiles`) and spectral information (`spectra`). In a last step, using `linkSampleData`, the relationships between the samples and the spectral information are defined. ```{r msexp_sciex, eval = FALSE, echo = TRUE} ## this example is taken from the Spectra vignette lmse <- MsExperiment() sd <- DataFrame(sample_id = c("QC1", "QC2"), sample_name = c("QC Pool", "QC Pool"), injection_idx = c(1, 3)) sampleData(lmse) <- sd ## add mzML files to the experiment experimentFiles(lmse) <- MsExperimentFiles(mzML_files = fls) ## add the Spectra object to the experiment spectra(lmse) <- sps_sciex ## use linkSampleData to establish and define relationships between sample ## annotations and MS data lmse <- linkSampleData(lmse, with = "experimentFiles.mzML_file", sampleIndex = c(1, 2), withIndex = c(1, 2)) ``` ## Create `Spectra` and `MsExperiment` objects from (feature-extracted) intensity tables Another common approach is the creation of `Spectra` objects from a `DataFrame`s using the `MsBackendDataFrame` backend. We will use here the data set of @Lee2019, that contains metabolite level information measured by reverse phase liquid chromatography (RPLC) coupled to mass spectrometry and hydrophilic interaction liquid chromatography (HILIC) coupled to mass spectrometry (derived from the file `STables - rev1.xlsx` in the Supplementary Information). In a separate step (see documentation for `Lee2019_meta_vals` and `Lee2019`), we have created a list containing `Spectra` objects for each samples (objects `sps_l_rplc` and `sps_l_hilic`) and `MsExperiment` objects containing the data of all samples (objects `msexp_rplc` and `msexp_hilic`). We will load here these objects: ```{r load_Lee2019, eval = TRUE, echo = TRUE} data("Lee2019", package = "MsQuality") ``` The final data set contains `r length(unique(sps_rplc$dataOrigin))` paired samples (i.e. `r length(unique(sps_rplc$dataOrigin))` samples derived from RPLC and `r length(unique(sps_hilic$dataOrigin))` samples derived from HILIC). We will combine the `sps_rplc` and `sps_hilic` objects in the following and calculate on this combined document the metrics. ```{r combine_sps_rplc_sps_hilic, eval = TRUE, echo = TRUE} sps_comb <- c(sps_rplc, sps_hilic) ``` The most important function to assess the data quality and to calculate the metrics is the `calculateMetrics` function. The function takes a `Spectra` or `MsExperiment` object as input, a character vector of metrics to be calculated, and, optionally a list of parameters passed to the quality metrics functions. # Calculating the quality metrics on `Spectra` and `MsExperiment` objects Currently, the following metrics are included: ```{r} qualityMetrics(msexp_rplc) ``` The following list gives a brief explanation for these metrics. Further information may be found at the [HUPO-PSI mzQC project page](https://github.com/HUPO-PSI/mzQC) or in the respective help file for the quality metric (accessible by e.g. entering `?rtDuration` to the R console). Currently, all quality metrics can be calculated for both `Spectra` and `MsExperiment` objects. - *rtDuration*, **RT duration** (QC:4000053), "The retention time duration of the MS run in seconds, similar to the highest scan time minus the lowest scan time." [PSI:QC]; - *rtOverTicQuantiles*, **RT over TIC quantile** (QC:4000054), "The interval when the respective quantile of the TIC accumulates divided by retention time duration. The number of quantiles observed is given by the size of the tuple." [PSI:QC]; - *rtOverMsQuarters*, **MS1 quantiles RT fraction** (QC:4000055), "The interval used for acquisition of the first, second, third, and fourth quarter of all MS1 events divided by RT-Duration." [PSI:QC]; - *rtOverMsQuarters*, **MS1/MS2 quantiles RT fraction** (QC:4000055), "The interval used for acquisition of the first, second, third, and fourth quarter of all MS2 events divided by RT-Duration." [PSI:QC]; - *ticQuartileToQuartileLogRatio*, **MS1 TIC-change quartile ratios** (MS:4000057), "The log ratios of successive TIC-change quartiles. The TIC changes are the list of MS1 total ion current (TIC) value changes from one to the next scan, produced when each MS1 TIC is subtracted from the preceding MS1 TIC. The metric's value triplet represents the log ratio of the TIC-change Q2 to Q1, Q3 to Q2, TIC-change-max to Q3" [PSI:MS], `mode = "TIC_change"`; - *ticQuartileToQuartileLogRatio*, **MS1 TIC quartile ratios** (MS:4000058), The log ratios of successive TIC quartiles. The metric's value triplet represents the log ratios of TIC-Q2 to TIC-Q1, TIC-Q3 to TIC-Q2, TIC-max to TIC-Q3." [PSI:MS], `mode = "TIC"; - *numberSpectra*, **Number of MS1 spectra** (QC:4000059), "The number of MS1 events in the run." [PSI:QC]; - *numberSpectra*, **Number of MS2 spectra** (QC:4000060), "The number of MS2 events in the run." [PSI:QC]; - *medianPrecursorMz*, **Precursor median m/z for IDs** (QC:4000065), "Median m/z value for all identified peptides (unique ions) after FDR." [PSI:QC]; - *rtIqr*, **Interquartile RT period for peptide identifications** (QC:4000072), "The interquartile retention time period, in seconds, for all peptide identifications over the complete run." [PSI:QC]; - *rtIqrRate*, **Peptide identification rate of the interquartile RT period** (QC:4000073), "The identification rate of peptides for the interquartile retention time period, in peptides per second." [PSI:QC]; - *areaUnderTic*, **Area under TIC** (QC:4000077), "The area under the total ion chromatogram." [PSI:QC]; - *areaUnderTicRtQuantiles*, **Area under TIC RT quantiles** (QC:4000078), "The area under the total ion chromatogram of the retention time quantiles. Number of quantiles are given by the n-tuple." [PSI:QC]; - *extentIdentifiedPrecursorIntensity*, **Extent of identified precursor intensity** (QC:4000125), "Ratio of 95th over 5th percentile of precursor intensity for identified peptides" [PSI:QC]; - *medianTicRtIqr*, **Median of TIC values in the RT range in which the middle half of peptides are identified** (QC:4000130), "Median of TIC values in the RT range in which half of peptides are identified (RT values of Q1 to Q3 of identifications)" [PSI:QC]; - *medianTicOfRtRange*, **Median of TIC values in the shortest RT range in which half of the peptides are identified** (QC:4000132), "Median of TIC values in the shortest RT range in which half of the peptides are identified" [PSI:QC] - *mzAcquisitionRange*, **m/z acquisition range** (QC:4000138), "Upper and lower limit of m/z values at which spectra are recorded." [PSI:QC]; - *rtAcquisitionRange*, **Retention time acquisition range** (QC:4000139), "Upper and lower limit of time at which spectra are recorded." [PSI:QC]; - *precursorIntensityRange*, **Precursor intensity range** (QC:4000144), "Minimum and maximum precursor intensity recorded." [PSI:QC]; - *precursorIntensityQuartiles*, **Precursor intensity distribution Q1, Q2, Q3** (QC:4000167), "From the distribution of precursor intensities, the quartiles Q1, Q2, Q3" [PSI:QC]; - *precursorIntensityQuartiles*, **Identified precursor intensity distribution Q1, Q2, Q3** (QC:4000228), "From the distribution of identified precursor intensities, the quartiles Q1, Q2, Q3" [PSI:QC]; - *precursorIntensityQuartiles*, **Unidentified precursor intensity distribution Q1, Q2, Q3** (QC:4000233), "From the distribution of unidentified precursor intensities, the quartiles Q1, Q2, Q3" [PSI:QC]; - *precursorIntensityMean*, **Precursor intensity distribution mean** (QC:4000168), "From the distribution of precursor intensities, the mean." [PSI:QC]; - *precursorIntensityMean*, **Identified precursor intensity distribution mean** (QC:4000229), "From the distribution of identified precursor intensities, the mean" [PSI:QC]; - *precursorIntensityMean*, **Unidentified precursor intensity distribution mean** (QC:4000234), "From the distribution of unidentified precursor intensities, the mean" [PSI:QC]; - *precursorIntensitySd*, **Precursor intensity distribution sigma** (QC:4000169), "From the distribution of precursor intensities, the sigma value." [PSI:QC]; - *precursorIntensitySd*, **Identified precursor intensity distribution sigma** (QC:4000230), "From the distribution of identified precursor intensities, the sigma value" [PSI:QC]; - *precursorIntensitySD*, **Unidentified precursor intensity distribution sigma** (QC:400235), "From the distribution of unidentified precursor intensities, the sigma value" [PSI:QC]; - *msSignal10xChange*, **MS1 signal jump (10x) count** (QC:4000172), "The count of MS1 signal jump (spectra sum) by a factor of ten or more (10x) between two subsequent scans" [PSI:QC]; - *msSignal10xChange*, **MS1 signal fall (10x) count** (QC:4000173), "The count of MS1 signal decline (spectra sum) by a factor of ten or more (10x) between two subsequent scans" [PSI:QC]; - *RatioCharge1over2*, **Charged peptides ratio 1+ over 2+** (QC:4000174), "Ratio of 1+ peptide count over 2+ peptide count in identified spectra" [PSI:QC]; - *RatioCharge1over2*, **Charged spectra ratio 1+ over 2+** (QC:4000179), "Ratio of 1+ spectra count over 2+ spectra count in all MS2" [PSI:QC]; - *RatioCharge3over2*, **Charged peptides ratio 3+ over 2+** (QC:4000175), "Ratio of 3+ peptide count over 2+ peptide count in identified spectra" [PSI:QC]; - *RatioCharge3over2*, **Charged spectra ratio 3+ over 2+** (QC:4000180), "Ratio of 3+ peptide count over 2+ peptide count in all MS2" [PSI:QC]; - *RatioCharge4over2*, **Charged peptides ratio 4+ over 2+** (QC:4000176), "Ratio of 4+ peptide count over 2+ peptide count in identified spectra" [PSI:QC]; - *RatioCharge4over2*, **Charged spectra ratio 4+ over 2+** (QC:4000181), "Ratio of 4+ peptide count over 2+ peptide count in all MS2" [PSI:QC]; - *meanCharge*, **Mean charge in identified spectra** (QC:4000177), "Mean charge in identified spectra" [PSI:QC]; - *meanCharge*, **Mean precursor charge in all MS2** (QC:4000182), "Mean precursor charge in all MS2" [PSI:QC]; - *medianCharge*, **Median charge in identified spectra** (QC:4000178), "Median charge in identified spectra" [PSI:QC]; - *medianCharge*, **Median precursor charge in all MS2** (QC:4000183), "Median precursor charge in all MS2" [PSI:QC]. The most important function to assess the data quality and to calculate the metrics is the `calculateMetrics` function. The function takes a `Spectra` or `MsExperiment` object as input, a character vector of metrics to be calculated, and, optionally a list of parameters passed to the quality metrics functions. When passing a `Spectra`/`MsExperiment` object to the function, a `data.frame` returned by `calculateMetrics` with the metrics specified by the argument `metrics`. By default, `qualityMetrics(object)` is taken to specify the calculation of quality metrics. `calculateMetrics` also accepts a list of parameters passed to the individual quality metrics functions. For each quality metrics functions, the relevant parameters are selected based on the accepted arguments. Additional arguments can be given to the quality metrics functions. For example, the function `ticQuartileToQuartileLogRatio` function has the arguments `relativeTo`, `mode`, and `msLevel`. `relativeTo` specifies to which quantile the log TIC quantile is relatively related to (either to the 1st quantile or the respective previous one). `mode` (either `"TIC_change"` or `"TIC"`) specifies if the quantiles are taken from the changes between TICs of scan events or the TICs directly. One `Spectra`/`MsExperiment` object may also contain more than one `msLevel`, e.g. if it also contains information on MS$^2$ or MS$^3$ features. If the user adds the arguments `relativeTo = "Q1", mode = "TIC", msLevel = c(1L, 2L))`, `ticQuartileToQuartileLogRatio` is run with the parameter combinations `relativeTo = "Q1", mode = "TIC", msLevel = c(1L, 2L)`. The results based on these parameter combinations are returned and the used parameters are returned as attributes to the returned vector. Here, we would like to calculate the metrics of **all** included quality metrics functions (`qualityMetrics(object)`) and additionally pass the parameter `relativeTo = "Q1"` and `relativeTo = "previous"`. For computational reasons, we will restrict the calculation of the metrics to the first sample and to RPLC samples. ```{r calculateMetrics} ## subset the Spectra objects sps_comb_subset <- sps_comb[grep("Sample.1_", sps_comb$dataOrigin), ] ## for RPLC and HILIC metrics_sps_Q1 <- calculateMetrics(object = sps_comb_subset, metrics = qualityMetrics(sps_comb_subset), relativeTo = "Q1", msLevel = 1L) metrics_sps_Q1 metrics_sps_previous <- calculateMetrics(object = sps_comb_subset, metrics = qualityMetrics(sps_comb_subset), relativeTo = "previous", msLevel = 1L) metrics_sps_previous ``` Alternatively, an `MsExperiment` object might be passed to `calculateMetrics`. The function will iterate over the samples (referring to rows in `sampleData(msexp))`) and calculate the quality metrics on the corresponding `Spectra`s. There are in total `r length(msexp_hilic)` samples respectively in the objects `msexp_rplc` and `msexp_hilic`. To improve the visualization and interpretability, we will only calculate the metrics from the first 20 of these samples. ```{r metrics_rplc_hilic_lee2019} ## subset the MsExperiment objects msexp_rplc_subset <- msexp_rplc[1:20] msexp_hilic_subset <- msexp_hilic[1:20] ## define metrics metrics_sps <- c("rtDuration", "rtOverTicQuantiles", "rtOverMsQuarters", "ticQuartileToQuartileLogRatio", "numberSpectra", "medianPrecursorMz", "rtIqr", "rtIqrRate", "areaUnderTic") ## for RPLC-derived MsExperiment metrics_rplc_msexp <- calculateMetrics(object = msexp_rplc_subset, metrics = qualityMetrics(msexp_rplc_subset), relativeTo = "Q1", msLevel = 1L) ## for HILIC-derived MsExperiment metrics_hilic_msexp <- calculateMetrics(object = msexp_hilic_subset, metrics = qualityMetrics(msexp_hilic_subset), relativeTo = "Q1", msLevel = 1L) ``` When passing an `MsExperiment` object to `calculateMetrics` a `data.frame` object is returned with the samples (derived from the rownames of `sampleData(msexp)`) in the rows and the metrics in columns. We will show here the objects `metrics_rplc_msexp` and `metrics_hilic_msexp` ```{r paged_table_metrics, eval = TRUE, echo = FALSE} print("metrics_rplc_msexp") rmarkdown::paged_table(as.data.frame(metrics_rplc_msexp)) print("metrics_hilic_msexp") rmarkdown::paged_table(as.data.frame(metrics_hilic_msexp)) ``` # Visualizing the results The quality metrics can be most easily compared when graphically visualized. The `MsQuality` package offers the possibility to graphically display the metrics using the `plotMetric` and `shinyMsQuality` functions. The `plotMetric` function will create one plot based on a single metric. `shinyMsQuality`, on the other hand, opens a shiny application that allows to browse through all the metrics stored in the object. As a way of example, we will plot here the number of features. A high number of missing features might indicate low data quality, however, also different sample types might exhibit contrasting number of detected features. As a general rule, only samples of the same type should be compared to adjust for sample type-specific effects. ```{r} metrics_msexp <- rbind(metrics_rplc_msexp, metrics_hilic_msexp) plotMetric(qc = metrics_msexp, metric = "numberSpectra") ``` Similarly, we are able to display the area under the TIC for the retention time quantiles. This plot gives information on the perceived signal (TIC) for the differnt retention time quantiles and could indicate drifts or interruptions of sensitivity during the run. ```{r} plotMetric(qc = metrics_msexp, metric = "ticQuartileToQuartileLogRatio") ``` Alternatively, to browse through all metrics that were calculated in an interactive way, we can use the `shinyMsQuality` function. ```{r eval = FALSE} shinyMsQuality(qc = metrics_msexp) ``` # Appendix {-} ## Session information {-} All software and respective versions to build this vignette are listed here: ```{r session,eval=TRUE, echo=FALSE} sessionInfo() ``` ## References