@@ -13,7 +12,7 @@
## HaDeX: Analysis and Visualisation of Hydrogen/Deuterium Exchange Mass Spectrometry Data
-Hydrogen/Deuterium eXchange Mass Spectrometry (HDX-MS) is a staple technology in structural proteomics. HaDeX provides a analytic workflow for HDX-MS data available as a standalone GUI (https://sourceforge.net/projects/HaDeX/), web server (http://mslab-ibb.pl/shiny/HaDeX/) and the **R** package available on CRAN (https://cran.r-project.org/web/packages/HaDeX/index.html).
+Hydrogen/Deuterium eXchange Mass Spectrometry (HDX-MS) is a staple technology in structural proteomics. HaDeX provides a analytic workflow for HDX-MS data available as a standalone GUI (https://sourceforge.net/projects/HaDeX/), web server (https://hadex.mslab-ibb.pl/) and the **R** package available on CRAN (https://cran.r-project.org/web/packages/HaDeX/index.html).
### Local instance of HaDeX GUI
@@ -24,7 +23,7 @@ To run HaDeX GUI locally on Windows, install it using the following binary file:
You can install the latest development version of the package:
```R
-source("https://install-github.me/hadexversum/HaDeX")
+devtools::install_github("hadexversum/HaDeX")
```
or the latest version available on CRAN:
@@ -45,8 +44,8 @@ The HaDeX documentation is available [online](https://HaDeXversum.github.io/HaDe
### Citation
-Puchala W, Burdukiewicz M, Kistowski M, Dabrowska KA, Badaczewska-Dawid AE, Cysewski D and Dadlez M (2019). HaDeX: Analysis and Visualisation of Hydrogen/Deuterium Exchange Mass Spectrometry Data. R package version 1.2.
+Puchala W, Burdukiewicz M, Kistowski M, Dabrowska KA, Badaczewska-Dawid AE, Cysewski D and Dadlez M (2020). HaDeX: Analysis and Visualisation of Hydrogen/Deuterium Exchange Mass Spectrometry Data. Bioinformatics, 10.1093/bioinformatics/btaa587.
### Funding
-This work is supported by Foundation of Polish Science (TEAM TECH CORE FACILITY/2016-2/2 *Mass Spectrometry of Biopharmaceuticals - improved methodologies for qualitative, quantitative and structural characterization of drugs, proteinaceous drug targets and diagnostic molecules)*.
+This work is supported by Foundation of Polish Science (TEAM TECH CORE FACILITY/2016-2/2 *Mass Spectrometry of Biopharmaceuticals - improved methodologies for qualitative, quantitative and structural characterization of drugs, proteinaceous drug targets and diagnostic molecules)* and Narodowe Centrum Nauki (Preludium Bis 1 2019/35/O/NZ2/03745 *Wysokorozdzielcza analiza danych z eksperymentów wymiany proton-deuter monitorowanych spektrometrią mas)*.
diff --git a/appveyor.yml b/appveyor.yml
deleted file mode 100644
index 3a75e16a..00000000
--- a/appveyor.yml
+++ /dev/null
@@ -1,52 +0,0 @@
-# DO NOT CHANGE the "init" and "install" sections below
-
-# Download script file from GitHub
-init:
- ps: |
- $ErrorActionPreference = "Stop"
- Invoke-WebRequest http://raw.github.com/krlmlr/r-appveyor/master/scripts/appveyor-tool.ps1 -OutFile "..\appveyor-tool.ps1"
- Import-Module '..\appveyor-tool.ps1'
-
-install:
- ps: Bootstrap
-
-cache:
- - C:\RLibrary
-
-environment:
- NOT_CRAN: true
- # env vars that may need to be set, at least temporarily, from time to time
- # see https://github.com/krlmlr/r-appveyor#readme for details
- # USE_RTOOLS: true
- # R_REMOTES_STANDALONE: true
-
-# Adapt as necessary starting from here
-
-build_script:
- - travis-tool.sh install_deps
-
-test_script:
- - travis-tool.sh run_tests
-
-on_failure:
- - 7z a failure.zip *.Rcheck\*
- - appveyor PushArtifact failure.zip
-
-artifacts:
- - path: '*.Rcheck\**\*.log'
- name: Logs
-
- - path: '*.Rcheck\**\*.out'
- name: Logs
-
- - path: '*.Rcheck\**\*.fail'
- name: Logs
-
- - path: '*.Rcheck\**\*.Rout'
- name: Logs
-
- - path: '\*_*.tar.gz'
- name: Bits
-
- - path: '\*_*.zip'
- name: Bits
diff --git a/docs/404.html b/docs/404.html
index 5d15c6e5..54c8081a 100644
--- a/docs/404.html
+++ b/docs/404.html
@@ -17,23 +17,27 @@
-
+
-
+
-
+
+
+
+
+
-
-
+
+
-
+
-
-
+
+
@@ -60,7 +64,7 @@
-
Supplement to: “HaDeX: Analysis and Visualisation of Hydrogen/Deuterium Exchange Mass Spectrometry Data”
+
Weronika Puchała, Michał Burdukiewicz, Michał Kistowski, Katarzyna A. Dąbrowska, Aleksandra E. Badaczewska-Dawid, Dominik Cysewski, Michał Dadlez
+
+
20.06.2019
+
+
+
HaDeX.Rmd
+
+
+
+
+
+
+
+About HaDeX
+
HaDeX is a novel tool for processing, analysis, and visualization of HDX-MS experiments. HaDeX covers the final parts of the analytic process, including a comparison of experiments, quality control and generation of publication-quality figures. To make the HaDeX R package available to the less R-fluent users, we enhanced it with a comprehensive Graphical User Interface available as a HaDeX GUI. The reproducibility of the whole procedure is ensured with advanced reporting functions.
This document covers the main functionalities of both the R package and the GUI.
+
+
+Comparison of the existing HDX-MS software
+
To show the novelty of HaDeX, we compare its functionalities with other relatively new software for analysis of HDX-MS data: MEMHDX (Hourdel et al. 2016) and Deuteros (Lau et al. 2019).
+
+
We have not considered HDX Workbench (Pascal et al. 2012) as it deals with the preliminary steps of the analysis. This comparison also does not cover a versatile structural visualisation tool for HDX-MS results, HDX-Viewer (Bouyssié et al. 2019) as its scope is different from the tools mentioned above.
+
Web server: a software is available as a web server.
+
Programmatic access: analytic functionalities are documented and available from a command line.
+
Desktop software: a software can be installed locally.
+
Multi-state analysis: a software supports comparisons of more than two states.
+
ISO-based uncertainty: analytic functions produce ISO-compatible uncertainty intervals.
+
Coverage and peptide overlap: overview of experimental sequence coverage is available in a user-friendly way.
+
Quality control: additional information about course of the experiment.
+
N- and C-terminal length corrections: manual correction of sequence length.
+
Global visualization of deuterium uptake: deuterium uptake for different states is shown together for comparison.
+
Woods plot: deuteration difference between chosen states shown in the format of Woods plot.
+
Zooming of the Woods plot: Woods plot can be zoomed in.
+
Customizable label names and colors: Labels and colors on the plot can be changed by the user.
+
Peptide kinetics chart: Kinetics plot (deuteration change in time) are available for each peptide.
+
3D structure visualization: structure of the protein is visualized in 3D.
+
Downloadable charts: charts are downloadable, preferably in a vector format (.eps, .svg or .pdf).
+
Deuterium uptake download: data shown on Woods plot is downloadable (e.q. as CSV file).
+
Downloadable results of intermediate computations: results of intermediate computations (e.q. pure deuteration data) are downloadable.
+
Report generation: generates a report (e.q. in Html format) with results of the analysis with parametrization.
HDX Data Summary: summary of the experimental data (Masson et al. 2019).
+
+
+
+
+HaDeX functionalities
+
+
+Data import
+
The HaDeX web server works only on data in the DynamX datafile format (Waters Corp.). The data from other sources may be also adjusted to the format accepted by HaDeX provided it has following columns:
+
+
Although data can be imported into R using other tools, we strongly advise to rely on the read_hdx() function:
Currently, read_hdx() supports .csv, .tsv and .xls files fulfilling the data structure described above. Files with data from multiple proteins are supported. The user need to indicate which protein is of interest for calculations.
+
+
+
+Computation of deuteration levels
+
The computation of the level of deuteration involves several pre-processing steps, all of which are described in this section. These steps are performed automatically in the GUI or by the prepare_dataset() function in the console.
+
+
+Measured data into overall peptide mass
+
The results of HDX-MS measurements as given in the DynamX data files are represented as the measured mass of peptides plus proton mass to charge ratio (\(Center\)). For later use, this value has to be transformed into an overall mass of a peptide measured after specific time point from a protein in a specific state, as shown in equation 1:
+
\[pepMass = z \times (Center-protonMass)\tag{1}\] where:
+
+
\(pepMass\) - expected mass of the peptide after incubation (Da),
+
\(protonMass\) - the mass of the proton (Da),
+
\(z\) - charge of the peptide,
+
\(Center\) - experimentally measured peptide mass plus proton mass to charge ratio \(\left(\frac{m}{z}\right)\).
+
+
HDX-MS experiments are often repeated (by the rule of thumb at least three times). Thus, we aggregate the results of replicates as a weighted mean mass into a single result per peptide using equation 2:
\(aggMass\) - weighted mean mass of the peptide (Da),
+
\(k\) - replicate index,
+
\(Inten\) - intensity,
+
\(N\) - number of replicates.
+
+
This data manipulation results from an original data structure. Each repetition of the measurement gives the data for given peptide in a given time per possible value of \(z\) as shown in the example below. We need to use the value of \(pepMass\) as shown in equation 1 but still keep the information about original measurement - that’s why we use the weighted mass.
The uncertainty of a measurement is variability associated with the precision of measuring instrumentation. We present here a novel derivation of uncertainty formulas for HDX-MS data according to the ISO guidelines (Joint Committee for Guides in Metrology 2008). Input files always encompass results of more than one measurement. We assume uncorrelatedness of replicates as they come from different samples. Therefore, we average measurements of replicates for each time point and for all protein states. Thus, we compute peptide mass uncertainty \(u\) as uncertainty for aggregate estimate using the formula for standard deviation of the mean:
After obtaining the mass of the peptide, we can compute the deuteration level depending on the chosen maximum deuteration level. The maximum deuteration can also be computed in two different ways: either as theoretical (where the maximum deuteration depends on the theoretical deuteration levels) and experimental (where the maximum deuteration is assumed to be equal to the deuteration measured at the last time point).
+
+
+
+Experimental deuteration level
+
The experimental deuteration level is computed as the deuteration level of the peptide from a protein in a specific state and after incubation time \(t\) compared to the deuteration level measured at the start of the incubation (\(t_0\)). It yields a value for the chosen state and chosen time \(t\).
+
\[D = D_{t} - D_{t_0}\tag{4}\]
+
where:
+
+
\(D\) - deuteration level (Da),
+
\(D_{t_0}\) - experimentally measured deuteration at the beginning of the incubation (0 or close to 0),
+
+
The equation 4 produces only absolute deuteration levels. The computations of relative deuteration levels follows a similar logic and is normalized by the difference of deuteration between the start (\(t_0\)) and the end of the experiment (\(t_out\)) as shown in the equation 4a:
All functions in the HaDeX package contain the logical parameter \(relative\) to determine if they should return absolute or relative deuteration levels.
+
+
+Uncertainty calculations
+
We describe the methodology of the uncertainty calculations for relative deuteration levels. The uncertainty for absolute deuteration levels is computed similarly, but without scaling.
+
To calculate uncertainty related to functions of more than one variables (e. g., equation 4) the Law of propagation of uncertainty is defined by equation 5:
\(u(D_{k})\) - an uncertainty associated with \(D_{k}\) as standard deviation of the mean value,
+
+
Then, expanding the equation 6:
+
\[u_{c}(D) = \sqrt{ \left[
+\frac{1}{D_{t_{out}}-D_{t_0}} u(D_{t}) \right]^2 +
+\left[ \frac{D_{t} - D_{t_{out}}}{(D_{t_{out}}-D_{t_0})^2} u(D_{t_0}) \right]^2 +
+\left[ \frac{D_{t_0} - D_{t}}{(D_{t_{out}}-D_{t_0})^2} u (D_{t_{out}}) \right]^2}\tag{7}\] As expected, the uncertainty associated with \(D_{t}\) has the biggest impact on \(u_{c}(D)\).
+
+
+
+
+Theoretical deuteration level
+
As opposed to the experimental deuteration levels, theoretical deuteration level only partially depends on the experimental data. Here, the maximum deuteration level is based on a hypothetical peptide where all hydrogens were replaced by deuterons, as it is shown in equation 8:
For the absolute values, \(u(D)\) is identical with \(u(D_{t})\), based on equations 8a and 9.
+
+
+
+
+
+Difference of deuteration levels between two states
+
The differences of deuteration levels between two states are associated with a different level of protection of hydrogens. Therefore, we are especially interested in the differential analysis of the deuteration levels. Thus, the deuteration level in one state \((D_{2})\) is subtracted from deuteration level in the other state \((D_{1})\):
+
\[diff = D_{1} - D_{2}\tag{11}\]
+
and the uncertainty is a function of two variables (based on equation 11 and 5):
Comparison plots show the deuteration level of all peptides in selected states in a given time. The x-axis represents positions of amino acids in the sequence. The y-axis shows the deuteration level, expressed either as a relative or absolute deuteration. The chart below shows peptide deuteration after 25 minutes of the incubation along with the confidence intervals.
+
– theoretical:
+
+
relative values:
+
+
+comparison_plot(calc_dat =calc_dat,
+ theoretical =TRUE,
+ relative =TRUE,
+ state_first ="Nucb2 Factor 1",
+ state_second ="Nucb2 Factor 2")+
+ labs(title ="Theoretical fraction exchanged in state comparison in 25 min time")
+
+
+
absolute values:
+
+
+comparison_plot(calc_dat =calc_dat,
+ theoretical =TRUE,
+ relative =FALSE,
+ state_first ="Nucb2 Factor 1",
+ state_second ="Nucb2 Factor 2")+
+ labs(title ="Theoretical fraction exchanged in state comparison in 25 min time")
+
+
– experimental:
+
+
relative values:
+
+
+comparison_plot(calc_dat =calc_dat,
+ theoretical =FALSE,
+ relative =TRUE,
+ state_first ="Nucb2 Factor 1",
+ state_second ="Nucb2 Factor 2")+
+ labs(title ="Fraction exchanged in state comparison in 25 min time")
+
+
+
absolute values:
+
+
+comparison_plot(calc_dat =calc_dat,
+ theoretical =FALSE,
+ relative =FALSE,
+ state_first ="Nucb2 Factor 1",
+ state_second ="Nucb2 Factor 2")+
+ labs(title ="Fraction exchanged in state comparison in 25 min time")
+
+
+
+
+
+Woods plot
+
Woods plots show the difference between the deuteration of all peptides in two different states in a specific time point as described by equation 11. Similarly to the comparison plot, HaDeX provides both experimental and theoretical deuteration levels using either relative or absolute values:
+
– theoretical:
+
+
relative values:
+
+
+woods_plot(calc_dat =calc_dat,
+ theoretical =TRUE,
+ relative =TRUE)+
+ labs(title ="Theoretical fraction exchanged between states in 25 min time")
+
+
+
absolute values:
+
+
+woods_plot(calc_dat =calc_dat,
+ theoretical =TRUE,
+ relative =FALSE)+
+ labs(title ="Theoretical fraction exchanged between states in 25 min time")
+
+
– experimental:
+
+
relative values:
+
+
+woods_plot(calc_dat =calc_dat,
+ theoretical =FALSE,
+ relative =TRUE)+
+ labs(title ="Theoretical fraction exchanged between states in 25 min time")
+
+
+
absolute values:
+
+
+woods_plot(calc_dat =calc_dat,
+ theoretical =FALSE,
+ relative =FALSE)+
+ labs(title ="Theoretical fraction exchanged between states in 25 min time")
+
+
+
+Confidence limit in Woods plot
+
The function calculate_confidence_limit_values() calculates confidence limit values as it is described elsewhere (Houde, Berkowitz, and Engen 2011).
By the term kinetics we understand deuteration change in time. To calculate deuteration values per peptide for different time points is used function calculate_kinetics(). This function uses the calculate_state_deuteration() function.
+
+(kin_YYDEYL_gg_Nucb2_CaCl2<-calculate_kinetics(dat =dat,
+ protein ="db_Nucb2",
+ sequence ="YYDEYL",
+ state ="gg_Nucb2_CaCl2",
+ start =45,
+ end =50,
+ time_in =0.001,
+ time_out =1440))
HaDeX provides additional tools for assessment of experiments.
+
+
+Peptide coverage
+
The sequence of the protein(s) is reconstructed from the peptides from the input file. Thus, amino acids not covered by peptides are marked as X according to the IUPAC convention. The sequence is reconstructed using the reconstruct_sequence() function.
The user can choose which state (or states) should be included in these plots. If this parameter is not provided, the first possible state is chosen. If a given peptide is available in more than one state, it is shown only once.
+
+
+
+Quality control
+
The function quality_control() plots the change in the uncertainty of deuteration levels as a function of incubation time. The uncertainty is averaged over all peptides available at a given time point in a selected state. This chart has a double function: firstly, it allows checking if the measurement uncertainty is decreasing over time (which is the expected behavior) and the second one helps to plan the appropriate incubation length for the tested protein (whether we obtain the desired data reliability values).
+
In HDX-MS experiments, the average uncertainty of measurements decreases over time as the sample is more and more deuterated (even accounting for the back-propagation). Therefore, if the level of uncertainty is stable, the exchange is still ongoing and it would be advisable to prolong the reaction.
+
Moreover, the user can detect a time point after which the decrease of the deuteration uncertainty becomes too marginal to prolong the measurements. This function is most useful in case of multiple measurements of the same or very similar proteins because it helps to optimize the duration of the incubation. The result of this function can be easily visualized.
+ggplot(result)+
+ geom_line(aes(x =out_time, y =avg_err_state_first, color ="Average error (first state)"))+
+ geom_line(aes(x =out_time, y =avg_err_state_second, color ="Average error (second state)"))+
+ scale_x_log10()+
+ labs(x ="log(time) [min]", y ="Average uncertainty", title ="Uncertainty change")+
+ theme_bw(base_size =11)+
+ theme(legend.position ="bottom",
+ legend.title =element_blank())
+
+
The chart below shows how we interpret the three most common results of quality control.
+
+
+
+
+
+
+HaDeX Graphical User Interface
+
The HaDeX Shiny app is launched by the HaDeX_gui() function or available at MS Lab website: http://mslab-ibb.pl/shiny/HaDeX/. In the Input Data tab the user can adjust parameters to be propagated for the whole analysis.
+
+
+
+Examples
+
+
+Example 1: CD160-HVEM
+
The interaction between HVEM and the CD160 receptor was measured with HDX-MS.
+
Firstly, we read the input data, exactly as provided by the DynamX 3.0 (Waters Corp.)
Then, we reconstruct the protein sequence from the peptides measured during the experiment. We observe the region from amino acid 107 till amino acid 124 is not covered by any peptide.
The theoretical plot allows finding regions, which exchange quickly (N-terminus, regions between 30-70 amino acid) and regions, which exchange slowly (peptides 15-24, 95-110 amino acid). We can also see the differences in the exchange between two states, indicating regions which changed upon binding with other protein.
On the experimental plot, there are visible regions, which exchange quickly (N terminal part, regions between 30-70 amino acid) and regions, which exchange slowly (peptides 15-24, 30-35, 95-110 amino acid).
The plot below shows peptides for which levels of deuteration were significantly lower upon binding with other protein (red) and peptides for which levels of exchange were significantly higher upon binding with other protein (blue). The plot also shows peptides in which no significant changes in deuteration between states are visible (grey). The biggest changes on the theoretical plot can be observed in 3 peptides (15-24, 30-35, 75-90).
+# example quality control visualisation - relative values
+library(ggplot2)
+ggplot(result[result["out_time"]>=1,])+
+ geom_line(aes(x =out_time, y =avg_err_state_first, color ="Average error (first state)"))+
+ geom_line(aes(x =out_time, y =avg_err_state_second, color ="Average error (second state)"))+
+ scale_x_log10()+
+ labs(x ="log(time) [min]", y ="Average uncertainty", title ="Uncertainty change")+
+ theme(legend.position ="bottom",
+ legend.title =element_blank())
+
+
+
+
+
+References
+
+
+
Bouyssié, David, Jean Lesne, Marie Locard-Paulet, Renaud Albigot, Odile Burlet-Schiltz, and Julien Marcoux. 2019. “HDX-Viewer: Interactive 3D Visualization of Hydrogen-Deuterium Exchange Data.” Bioinformatics (Oxford, England), July. https://doi.org/10.1093/bioinformatics/btz550.
+
+
+
Houde, Damian, Steven A. Berkowitz, and John R. Engen. 2011. “The Utility of Hydrogen/Deuterium Exchange Mass Spectrometry in Biopharmaceutical Comparability Studies.” Journal of Pharmaceutical Sciences 100 (6): 2071–86. https://doi.org/10.1002/jps.22432.
+
+
+
Hourdel, Véronique, Stevenn Volant, Darragh P. O’Brien, Alexandre Chenal, Julia Chamot-Rooke, Marie-Agnès Dillies, and Sébastien Brier. 2016. “MEMHDX: An Interactive Tool to Expedite the Statistical Validation and Visualization of Large HDX-MS Datasets.” Bioinformatics 32 (22): 3413–9. https://doi.org/10.1093/bioinformatics/btw420.
+
+
+
Joint Committee for Guides in Metrology. 2008. “JCGM 100: Evaluation of Measurement Data - Guide to the Expression of Uncertainty in Measurement.” JCGM.
+
+
+
Lau, Andy M. C., Zainab Ahdash, Chloe Martens, and Argyris Politis. 2019. “Deuteros: Software for Rapid Analysis and Visualization of Data from Differential Hydrogen Deuterium Exchange-Mass Spectrometry.” Bioinformatics (Oxford, England), January. https://doi.org/10.1093/bioinformatics/btz022.
+
+
+
Masson, Glenn R., John E. Burke, Natalie G. Ahn, Ganesh S. Anand, Christoph Borchers, Sébastien Brier, George M. Bou-Assaf, et al. 2019. “Recommendations for Performing, Interpreting and Reporting Hydrogen Deuterium Exchange Mass Spectrometry (HDX-MS) Experiments.” Nature Methods 16 (7): 595–602. https://doi.org/10.1038/s41592-019-0459-y.
+
+
+
Pascal, Bruce D., Scooter Willis, Janelle L. Lauer, Rachelle R. Landgraf, Graham M. West, David Marciano, Scott Novick, Devrishi Goswami, Michael J. Chalmers, and Patrick R. Griffin. 2012. “HDX Workbench: Software for the Analysis of H/D Exchange MS Data.” Journal of the American Society for Mass Spectrometry 23 (9): 1512–21. https://doi.org/10.1007/s13361-012-0419-6.
Currently, HaDeX is limited to the cluster file from DynamX 3.0 or 2.0. Below we explain how the data file is processed.
+
+
+Processing data from DynamX
+
Let’s investigate how the data processing of the cluster file from DynamX is conducted on the example file from the package.
+
+
+Differences between files
+
What is the difference between cluster files from DynamX 3.0 and 2.0? The datafiles from DynamX 2.0 don’t include Modification and Fragment columns. The variations of the experiment were limited, while the DynamX 2.0 was the latest version.
## Protein Start End Sequence Modification Fragment MaxUptake MHP
+## 1: db_CD160 1 15 INITSSASQEGTRLN NA NA 14 1590.808
+## 2: db_CD160 1 15 INITSSASQEGTRLN NA NA 14 1590.808
+## 3: db_CD160 1 15 INITSSASQEGTRLN NA NA 14 1590.808
+## 4: db_CD160 1 15 INITSSASQEGTRLN NA NA 14 1590.808
+## 5: db_CD160 1 15 INITSSASQEGTRLN NA NA 14 1590.808
+## 6: db_CD160 1 15 INITSSASQEGTRLN NA NA 14 1590.808
+## 7: db_CD160 1 15 INITSSASQEGTRLN NA NA 14 1590.808
+## 8: db_CD160 1 15 INITSSASQEGTRLN NA NA 14 1590.808
+## 9: db_CD160 1 15 INITSSASQEGTRLN NA NA 14 1590.808
+## 10: db_CD160 1 15 INITSSASQEGTRLN NA NA 14 1590.808
+## State Exposure File z RT Inten Center
+## 1: CD160 0.000 KD_160527_CD160_sekw_05 1 3.232479 6592 1591.2584
+## 2: CD160 0.000 KD_160527_CD160_sekw_05 2 3.238079 394066 796.3552
+## 3: CD160 0.000 KD_160527_CD160_sekw_05 3 3.238759 173526 531.2633
+## 4: CD160 0.001 KD_160527_CD160_IN_01 2 3.258598 232221 796.3634
+## 5: CD160 0.001 KD_160527_CD160_IN_01 3 3.256844 110675 531.2849
+## 6: CD160 0.167 KD_160530_CD160_10s_01 2 3.262774 99894 800.3610
+## 7: CD160 0.167 KD_160530_CD160_10s_02 2 3.264558 117541 800.3852
+## 8: CD160 0.167 KD_160530_CD160_10s_03 2 3.263795 90562 800.3682
+## 9: CD160 0.167 KD_160530_CD160_10s_04 2 3.273656 66131 800.4242
+## 10: CD160 1.000 KD_160530_CD160_1min_01 2 3.262300 109301 800.7878
+
As you can see, the data file has a very specific structure and is not informative yet. In the file, we have m/z values for each z value (charge) for each time point for each state of each peptide, repeated as many times as measurement was repeated (each measurement should be repeated at least three times).
+
+
Our aim is to have one result with an uncertainty of the measurement per each peptide in each biological state in each measured time point - data in this format allows further calculations, e.q. calculating deuterium uptake values.
+
For a better understanding of the process of aggregating the data, see the Data aggregation article.
+
Within each replicate of the measurement (we recognize each replicate by the File value), the m/z values are provided for each possible z value. The m/z values are in the Center column, as it is a geometrical centroid calculated from the isotopic envelope. Firstly, we have to calculate the mass value, measured experimentally:
+
\[expMass = z \times (Center-protonMass)\tag{1}\]
+
To aggregate data from different z values, we have to calculate the mean mass weighted by intensity. Additional information about this step and how the weighted mean impacts the results can be found in Mass calculation article.
+\(aggMass\) - mass of the peptide [Da], average from replicates,
+
+\(Inten_k\) - intensity of the measurement,
+
+\(pepMass\) - mass of the peptide, calculated using Equation 1.
+
+
As we use the aggregated result from the replicates, we need to calculate an uncertainty associated with the measurement. We use the mean value as the final result, so we need to calculate error as a standard deviation of the mean, according to the Equation 3:
+\(\overline{x}\) - mean value from all of the replicates,
+
+\(n\) - number of replicates.
+
+
Now we have the format we want for further calculations.
+
+
+
+Calculation of the deuterium uptake
+
HaDeX package provides the calculated values in different forms. All of them are provided with associated uncertainty of the measurement. All of the uncertainties are derived from the formula - the Law of propagation of uncertainty:
Deuterium uptake is the increase of the mass of the peptide in time \(t\). The minimal exchange control \(m_{t_0}\) is mass measured directly after adding the buffer (before the start of the exchange), and \(m_t\) is the mass measured in chosen time point \(t\). The value is in Daltons [Da].
+
\[D = m_{t} - m_{t_0}\] The uncertainty associated with deuterium uptake [Da] (based on equation 3):
+
\[u_c(D) = \sqrt{u(m_t)^2 + u(m_{t_0})^2}\]
+
+
+
+Fractional deuterium uptake
+
Fractional deuterium uptake is the ratio of the increase of the mass in time \(t\) to the maximal exchange control. The maximal exchange control \(m_{t_{100}}\) is measured after a long time (chosen by the experimenter, usually 1440 min = 24 h). It is assumed that after this long time, the exchange is finished. The minimal exchange control \(m_{t_0}\) is mass measured directly after adding the buffer (before the start of the exchange), and \(m_t\) is the mass measured in chosen time point \(t\). This value is a percentage value [%].
Theoretical deuterium uptake is the increase of mass in time \(t\) compared with the theoretical value of the peptide mass without any exchange (\(MHP\) - a mass of the singly charged monoisotopic molecular ion), and \(m_t\) is the mass measured in chosen time point \(t\). This value is in daltons [Da]:
+
\[D_{theo} = m_{t} - MHP\]
+
The uncertainty associated with theoretical deuterium uptake [Da] (the \(MHP\) value is a constant without measurement uncertainty - based on the equation 3):
+
\[u(D_{theo}) = u(m_t)\]
+
+
+
+Theoretical fractional deuterium uptake
+
Theoretical fractional deuterium uptake is the ratio of the increase of mass in time \(t\) compared with a theoretical value of the mass of the peptide without any exchange to the possible theoretical increase of the mass, based on the maximal potential uptake of the peptide (based on the peptide sequence). This value is a percentage value [%].
Differential value is the way to see how the deuterium uptake differs between two biological states. It allows seeing if the possible difference is statistically important (more information below). This value is calculated as the difference between the previously described (in a chosen form) deuterium uptake of the first and second states.
+
\[diff = D_{1} - D_{2}\] The uncertainty associated with the difference of deuterium uptake (based on the equation 3):
+
\[u_{c}(diff) = \sqrt{u(D_{1})^2 + u(D_{2})^2}\]
+
The convenient way to present results calculated as described is the comparison plot and differential plot (Woods’ plot).
+
+
+
+
+Additional information
+
If the file contains modified peptides - the value from column Modification is added to the value from column State and is treated as a new biological state. The further aspects of the analysis are the same as for non-modified peptides.
+Comparison of results with weighted mean and without
+
As it is described in Data processing article, the data within each replicate of the experiment is aggregated using weighted mean. Below we present the effect it has on the results.
+
The whole workflow is described in the mentioned article. Here the focus is on the first aspect of the processing.
+
For the analysis, we use the example file from HaDeX.
As described, the first step is to transform the Center value (geometric centroid of the isotopic envelope for given peptide in a given state in given time point) and then to aggregate the values measured for different charge values. This is all done within each replicate.
+
The aggregation in our workflow is a weighted mean, with Inten (intensity) values as weights, as shown below.
Supplement to: “HaDeX: Analysis and Visualisation of Hydrogen/Deuterium Exchange Mass Spectrometry Data”
+
Supplement to: “HaDeX: Analysis and Visualisation of Hydrogen/Deuterium Exchange Mass Spectrometry Data”
Weronika Puchała, Michał Burdukiewicz, Michał Kistowski, Katarzyna A. Dąbrowska, Aleksandra E. Badaczewska-Dawid, Dominik Cysewski, Michał Dadlez
20.06.2019
@@ -92,6 +103,10 @@
20.06.2019
+
## Warning: replacing previous import 'vctrs::data_frame' by 'tibble::data_frame'
+## when loading 'dplyr'
+
## Warning: pakiet 'ggplot2' został zbudowany w wersji R 4.0.3
+
## Warning: pakiet 'DT' został zbudowany w wersji R 4.0.3
About HaDeX
@@ -102,8 +117,8 @@
Comparison of the existing HDX-MS software
To show the novelty of HaDeX, we compare its functionalities with other relatively new software for analysis of HDX-MS data: MEMHDX (Hourdel et al. 2016) and Deuteros (Lau et al. 2019).
-
-
We have not considered HDX Workbench (Pascal et al. 2012) as it deals with the preliminary steps of the analysis. This comparison also does not cover a versatile structural visualisation tool for HDX-MS results, HDX-Viewer (Bouyssié et al. 2019) as its scope is different from the tools mentioned above.
+
+
We have not considered HDX Workbench (Pascal et al. 2012) as it deals with the preliminary steps of the analysis. This comparison also does not cover a versatile structural visualisation tool for HDX-MS results, HDX-Viewer (Bouyssié et al. 2019) as its scope is different from the tools mentioned above.
Web server: a software is available as a web server.
Programmatic access: analytic functionalities are documented and available from a command line.
Desktop software: a software can be installed locally.
@@ -133,10 +148,11 @@
Data import
The HaDeX web server works only on data in the DynamX datafile format (Waters Corp.). The data from other sources may be also adjusted to the format accepted by HaDeX provided it has following columns:
-
-
Although data can be imported into R using other tools, we strongly advise to rely on the read_hdx() function:
Currently, read_hdx() supports .csv, .tsv and .xls files fulfilling the data structure described above. Files with data from multiple proteins are supported. The user need to indicate which protein is of interest for calculations.
@@ -215,7 +231,7 @@
Theoretical deuteration level
-
As opposed to the experimental deuteration levels, theoretical deuteration level only partially depends on the experimental data. Here, the maximum deuteration level is based on a hypothetical peptide where all hydrogens were replaced by deuters, as it is shown in equation 8:
+
As opposed to the experimental deuteration levels, theoretical deuteration level only partially depends on the experimental data. Here, the maximum deuteration level is based on a hypothetical peptide where all hydrogens were replaced by deuterons, as it is shown in equation 8:
+woods_plot(calc_dat =calc_dat,
+ theoretical =FALSE,
+ relative =FALSE)+
+ labs(title ="Theoretical fraction exchanged between states in 25 min time")
Confidence limit in Woods plot
The function calculate_confidence_limit_values() calculates confidence limit values as it is described elsewhere (Houde, Berkowitz, and Engen 2011).
By the term kinetics we understand deuteration change in time. To calculate deuteration values per peptide for different time points is used function calculate_kinetics(). This function uses the calculate_state_deuteration() function.
The sequence of the protein(s) is reconstructed from the peptides from the input file. Thus, amino acids not covered by peptides are marked as X according to the IUPAC convention. The sequence is reconstructed using the reconstruct_sequence() function.
The user can choose which state (or states) should be included in these plots. If this parameter is not provided, the first possible state is chosen. If a given peptide is available in more than one state, it is shown only once.
@@ -484,19 +520,21 @@
In HDX-MS experiments, the average uncertainty of measurements decreases over time as the sample is more and more deuterated (even accounting for the back-propagation). Therefore, if the level of uncertainty is stable, the exchange is still ongoing and it would be advisable to prolong the reaction.
Moreover, the user can detect a time point after which the decrease of the deuteration uncertainty becomes too marginal to prolong the measurements. This function is most useful in case of multiple measurements of the same or very similar proteins because it helps to optimize the duration of the incubation. The result of this function can be easily visualized.
Then, we reconstruct the protein sequence from the peptides measured during the experiment. We observe the region from amino acid 107 till amino acid 124 is not covered by any peptide.
The theoretical plot allows finding regions, which exchange quickly (N-terminus, regions between 30-70 amino acid) and regions, which exchange slowly (peptides 15-24, 95-110 amino acid). We can also see the differences in the exchange between two states, indicating regions which changed upon binding with other protein.
On the experimental plot, there are visible regions, which exchange quickly (N terminal part, regions between 30-70 amino acid) and regions, which exchange slowly (peptides 15-24, 30-35, 95-110 amino acid).
The plot below shows peptides for which levels of deuteration were significantly lower upon binding with other protein (red) and peptides for which levels of exchange were significantly higher upon binding with other protein (blue). The plot also shows peptides in which no significant changes in deuteration between states are visible (grey). The biggest changes on the theoretical plot can be observed in 3 peptides (15-24, 30-35, 75-90).
The aggregation of the data is complex. This article describes the process step by step for a better understanding of the data transformation.
+
+
+Aggregation of the data - visualization
+
Let’s see how the data is transformed. We will use the example file “KD_180110_CD160_HVEM.csv” from the HaDeX package and focus on just one peptide - “LCKDRSGDCSPETSLKQLRLKRDPGIDGVGEISSQL” in the state “CD160”. The measurement was made for timepoint 1 min.
+
Below is shown the original and unaggregated data for chosen peptide.
+
## Protein Start End Sequence Modification
+## 1: db_CD160 34 69 LCKDRSGDCSPETSLKQLRLKRDPGIDGVGEISSQL NA
+## 2: db_CD160 34 69 LCKDRSGDCSPETSLKQLRLKRDPGIDGVGEISSQL NA
+## 3: db_CD160 34 69 LCKDRSGDCSPETSLKQLRLKRDPGIDGVGEISSQL NA
+## 4: db_CD160 34 69 LCKDRSGDCSPETSLKQLRLKRDPGIDGVGEISSQL NA
+## 5: db_CD160 34 69 LCKDRSGDCSPETSLKQLRLKRDPGIDGVGEISSQL NA
+## 6: db_CD160 34 69 LCKDRSGDCSPETSLKQLRLKRDPGIDGVGEISSQL NA
+## 7: db_CD160 34 69 LCKDRSGDCSPETSLKQLRLKRDPGIDGVGEISSQL NA
+## 8: db_CD160 34 69 LCKDRSGDCSPETSLKQLRLKRDPGIDGVGEISSQL NA
+## 9: db_CD160 34 69 LCKDRSGDCSPETSLKQLRLKRDPGIDGVGEISSQL NA
+## 10: db_CD160 34 69 LCKDRSGDCSPETSLKQLRLKRDPGIDGVGEISSQL NA
+## 11: db_CD160 34 69 LCKDRSGDCSPETSLKQLRLKRDPGIDGVGEISSQL NA
+## 12: db_CD160 34 69 LCKDRSGDCSPETSLKQLRLKRDPGIDGVGEISSQL NA
+## 13: db_CD160 34 69 LCKDRSGDCSPETSLKQLRLKRDPGIDGVGEISSQL NA
+## 14: db_CD160 34 69 LCKDRSGDCSPETSLKQLRLKRDPGIDGVGEISSQL NA
+## 15: db_CD160 34 69 LCKDRSGDCSPETSLKQLRLKRDPGIDGVGEISSQL NA
+## 16: db_CD160 34 69 LCKDRSGDCSPETSLKQLRLKRDPGIDGVGEISSQL NA
+## 17: db_CD160 34 69 LCKDRSGDCSPETSLKQLRLKRDPGIDGVGEISSQL NA
+## 18: db_CD160 34 69 LCKDRSGDCSPETSLKQLRLKRDPGIDGVGEISSQL NA
+## 19: db_CD160 34 69 LCKDRSGDCSPETSLKQLRLKRDPGIDGVGEISSQL NA
+## 20: db_CD160 34 69 LCKDRSGDCSPETSLKQLRLKRDPGIDGVGEISSQL NA
+## Fragment MaxUptake MHP State Exposure File z
+## 1: NA 33 3900.991 CD160 1 KD_160530_CD160_1min_01 3
+## 2: NA 33 3900.991 CD160 1 KD_160530_CD160_1min_01 4
+## 3: NA 33 3900.991 CD160 1 KD_160530_CD160_1min_01 5
+## 4: NA 33 3900.991 CD160 1 KD_160530_CD160_1min_01 6
+## 5: NA 33 3900.991 CD160 1 KD_160530_CD160_1min_01 7
+## 6: NA 33 3900.991 CD160 1 KD_160530_CD160_1min_02 3
+## 7: NA 33 3900.991 CD160 1 KD_160530_CD160_1min_02 4
+## 8: NA 33 3900.991 CD160 1 KD_160530_CD160_1min_02 5
+## 9: NA 33 3900.991 CD160 1 KD_160530_CD160_1min_02 6
+## 10: NA 33 3900.991 CD160 1 KD_160530_CD160_1min_02 7
+## 11: NA 33 3900.991 CD160 1 KD_160530_CD160_1min_03 3
+## 12: NA 33 3900.991 CD160 1 KD_160530_CD160_1min_03 4
+## 13: NA 33 3900.991 CD160 1 KD_160530_CD160_1min_03 5
+## 14: NA 33 3900.991 CD160 1 KD_160530_CD160_1min_03 6
+## 15: NA 33 3900.991 CD160 1 KD_160530_CD160_1min_03 7
+## 16: NA 33 3900.991 CD160 1 KD_160530_CD160_1min_04 3
+## 17: NA 33 3900.991 CD160 1 KD_160530_CD160_1min_04 4
+## 18: NA 33 3900.991 CD160 1 KD_160530_CD160_1min_04 5
+## 19: NA 33 3900.991 CD160 1 KD_160530_CD160_1min_04 6
+## 20: NA 33 3900.991 CD160 1 KD_160530_CD160_1min_04 7
+## RT Inten Center
+## 1: 4.524763 325032 1307.8329
+## 2: 4.524404 753259 981.0960
+## 3: 4.523707 1340447 785.0905
+## 4: 4.524032 2076956 654.3858
+## 5: 4.525778 759271 561.0548
+## 6: 4.522330 239810 1307.7777
+## 7: 4.521255 583325 981.0817
+## 8: 4.521919 1011160 785.0811
+## 9: 4.521726 1584254 654.4194
+## 10: 4.522196 600218 561.0268
+## 11: 4.523605 176788 1307.8942
+## 12: 4.524804 402630 981.1597
+## 13: 4.521938 746309 785.0906
+## 14: 4.522238 1117344 654.4344
+## 15: 4.524647 397718 561.0833
+## 16: 4.531138 189258 1307.8739
+## 17: 4.530608 441817 981.1656
+## 18: 4.528928 796722 785.1220
+## 19: 4.530066 1186263 654.4411
+## 20: 4.531333 451071 561.0588
+
As we can see from the File column, there are four replicates of the experiment. Each measurement of a replicate provide values for different possible charge values for each peptide. The result of a measurement is in column Center - this is a geometrical centroid of an isotopic envelope - the product of the measurement from a mass spectrometer.
+
Let’s take a look for values for each replicate.
+
+
The centroid values for different charge values are not useful. We have to transform it to the mass values, according to an equation:
+
\[ aggMass = z*(Center - protonMass)\] The results are shown below.
+
+
This results are just for one repetition. We have four of them:
+
+
Values from each replicate are aggregated into one value, using weighted mean (with intencity value as weight):
+
+
The results from replicates are aggregated into the final result (mean), and the uncertainty (standard deviation of the mean) is calculated.
+
+
Now we have the mass value for chosen peptide in the chosen state, measured in the chosen time point. This calculation is done for every other peptide, and these values of mass and uncertainty are used in the calculation of deuterium uptake, as described in the Data processing article.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/articles/transformation_files/figure-html/unnamed-chunk-3-1.png b/docs/articles/transformation_files/figure-html/unnamed-chunk-3-1.png
new file mode 100644
index 00000000..e10b1f51
Binary files /dev/null and b/docs/articles/transformation_files/figure-html/unnamed-chunk-3-1.png differ
diff --git a/docs/articles/transformation_files/figure-html/unnamed-chunk-4-1.png b/docs/articles/transformation_files/figure-html/unnamed-chunk-4-1.png
new file mode 100644
index 00000000..2da1046f
Binary files /dev/null and b/docs/articles/transformation_files/figure-html/unnamed-chunk-4-1.png differ
diff --git a/docs/articles/transformation_files/figure-html/unnamed-chunk-5-1.png b/docs/articles/transformation_files/figure-html/unnamed-chunk-5-1.png
new file mode 100644
index 00000000..e9bb02d7
Binary files /dev/null and b/docs/articles/transformation_files/figure-html/unnamed-chunk-5-1.png differ
diff --git a/docs/articles/transformation_files/figure-html/unnamed-chunk-6-1.png b/docs/articles/transformation_files/figure-html/unnamed-chunk-6-1.png
new file mode 100644
index 00000000..fefe4261
Binary files /dev/null and b/docs/articles/transformation_files/figure-html/unnamed-chunk-6-1.png differ
diff --git a/docs/articles/transformation_files/figure-html/unnamed-chunk-7-1.png b/docs/articles/transformation_files/figure-html/unnamed-chunk-7-1.png
new file mode 100644
index 00000000..6847d8c7
Binary files /dev/null and b/docs/articles/transformation_files/figure-html/unnamed-chunk-7-1.png differ
diff --git a/docs/authors.html b/docs/authors.html
index daa6acb2..277eda33 100644
--- a/docs/authors.html
+++ b/docs/authors.html
@@ -15,21 +15,29 @@
+
-
+
-
-
+
+
+
+
+
+
+
-
+
+
-
+
-
-
+
+
+
@@ -37,10 +45,12 @@
+
+
@@ -51,9 +61,10 @@
+
-
+
Puchala W, Burdukiewicz M, Kistowski M, Dabrowska KA, Badaczewska-Dawid AE, Cysewski D and Dadlez M (2019). HaDeX: Analysis and Visualisation of Hydrogen/Deuterium Exchange Mass Spectrometry Data. R package version 1.0.
+
Puchala W, Burdukiewicz M, Kistowski M, Dabrowska KA, Badaczewska-Dawid AE, Cysewski D and Dadlez M (2020). HaDeX: Analysis and Visualisation of Hydrogen/Deuterium Exchange Mass Spectrometry Data. Bioinformatics, 10.1093/bioinformatics/btaa587.
logical value to determine if values are relative or absolute.
-
+
Value
calc_dat extended by column specifying if given peptide is relevant in given confidence limit.
The value of the confidence limit is added as an attribute - as well as parameters used to calculate (theoretical/relative)
assert_start_end
+This function asserts values of parameters. Start (of the sequence) should be
+bigger than 0 and smaller than end of the sequence. The end of the sequence
+should be bigger than start.
Calculate the mass of the singly charged monoisotopic (or not)
+molecular ion of for given peptide.
+
+
+
calculate_MHP(Sequence, mono =FALSE)
+
+
Arguments
+
+
+
+
Sequence
+
sequence of the peptide (string) or vector of sequences. Each letter
+of the sequence of the peptide represents different amino acid (three letter
+representation not allowed)
+
+
+
mono
+
logical value to determine if the mass should be monoisotopic or not.
+FALSE by default
+
+
+
+
Value
+
+
vector of numeric MHP values of provided Sequences
+
Details
+
+
This function calculates the mass of the singly charged monoisotopic (or not)
+molecular ion for given peptide. It is the sum of the residue masses plus the masses
+of the terminationg group (H and OH). The source of the masses can be found here:
+http://www.matrixscience.com/help/aa_help.html.
logical value to determine if values are relative or absolute.
-
+
Value
range of confidence limit interval
-
Details
...
-
References
Houde, D., Berkowitz, S.A., and Engen, J.R. (2011).
The Utility of Hydrogen/Deuterium Exchange Mass Spectrometry in
Biopharmaceutical Comparability Studies. J Pharm Sci 100, 2071–2086.
percentage of deuterium the protein was exposed to, value in range [0, 1]
-
+
Value
data frame with deuteration calculated for all the data points
@@ -178,7 +203,6 @@
Value
is available in column `time_chosen`. The rest of
the returned structure is equivalent to structure returned by
calculate_state_deuteration.
-
Details
The function calculates deuteration data for all available data points
@@ -188,112 +212,107 @@
Details
to during the exchange in theoretical calculations is provided.
To visualize obtained data we recommend using plot_kinetics function.
The first version doesn't support filled Modification and Fragment columns.
-
The function calculate_state_deuteration calculates deuteration for peptides in given protein in given state based
@@ -171,67 +193,60 @@
Details
supplied (mean values and uncertainty). Manual correction of percentage of deuterium the protein was exposed to during the exchange
in theoretical calculations is provided.
Methods of calculation and uncertainty are profoundly discussed in the vignette.
# load example data
-dat<-read_hdx(system.file(package="HaDeX", "HaDeX/data/KD_180110_CD160_HVEM.csv"))
+dat<-read_hdx(system.file(package ="HaDeX", "HaDeX/data/KD_180110_CD160_HVEM.csv"))# calculate deuteration for state "CD160"
-calculate_state_deuteration(dat, protein="db_CD160", state="CD160",
- time_in=0, time_chosen=5.000, time_out=1440.000)
#> # A tibble: 41 x 14
-#> Protein Sequence Start End State frac_exch_state err_frac_exch_s…
+calculate_state_deuteration(dat, protein ="db_CD160", state ="CD160",
+ time_in =0, time_chosen =5.000, time_out =1440.000)
+
Generate the data frame with differential data from two
+provided states - experimental/fractional calculations with the
+uncertainty, based on supplied parameters.
vector of two states to calculate difference between them,
+the order is important (state first - state second)
+
+
+
protein
+
...
+
+
+
time_0
+
...
+
+
+
time_t
+
...
+
+
+
time_100
+
...
+
+
+
deut_part
+
...
+
+
+
+
Value
+
+
...
+
Details
+
+
The names of the parameters and variables will be changed
+later after the glossary project.
+
See also
+
+
...
+
+
Examples
+
# load example data
+dat<-read_hdx(system.file(package ="HaDeX", "HaDeX/data/KD_180110_CD160_HVEM.csv"))
+
+# calculate differential values between states "CD160" and "CD160_HVEM" for protein "db_CD160"
+generate_differential_data_set(dat =dat, states =c("CD160", "CD160_HVEM"), protein ="db_CD160",
+ time_0 =0.001, time_t =5.000, time_100 =1440.000)
+
This is a wrapper for calculate_kinetics, but for
+the peptide list instead of one peptide. The names of the parameters and
+variables will be changed later after the glossary project.
The format in the table is suggested in Masson, G.R., Burke, J.E.,
+Ahn, N.G., Anand, G.S., Borchers, C., Brier, S., Bou-Assaf, G.M., Engen, J.R.,
+Englander, S.W., Faber, J., et al. (2019). Recommendations for performing,
+interpreting and reporting hydrogen deuterium exchange mass spectrometry
+(HDX-MS) experiments. Nat Methods 16, 595–602
The function plot_coverage plots sequence coverage based on experimental data for chosen protein in chosen state.
Only non-duplicated peptides are shown on the plot, next to each other.
The aim of this plot is to see the dependence between positions of the peptides on the protein sequence. Their position in y-axis
does not contain any information.
This function visualises the output of the
@@ -158,101 +173,97 @@
Details
If you want to plot data for more then one peptide in one state, join
calculated data by using bind_rows from dplyr package and
pass the result as kin_dat.
# load example data
-dat<-read_hdx(system.file(package="HaDeX", "HaDeX/data/KD_180110_CD160_HVEM.csv"))
+dat<-read_hdx(system.file(package ="HaDeX", "HaDeX/data/KD_180110_CD160_HVEM.csv"))# calculate data for the sequence INITSSASQEGTRLN in the CD160 state
-(kin1<-calculate_kinetics(dat,
- protein="db_CD160",
- sequence="INITSSASQEGTRLN",
- state="CD160",
- start=1,
- end=15,
- time_in=0.001,
- time_out=1440))
#> # A tibble: 5 x 15
+(kin1<-calculate_kinetics(dat,
+ protein ="db_CD160",
+ sequence ="INITSSASQEGTRLN",
+ state ="CD160",
+ start =1,
+ end =15,
+ time_in =0.001,
+ time_out =1440))
+
# calculate data for the sequence INITSSASQEGTRLN in the CD160_HVEM state
-(kin2<-calculate_kinetics(dat,
- protein="db_CD160",
- sequence="INITSSASQEGTRLN",
- state="CD160_HVEM",
- start=1,
- end=15,
- time_in=0.001,
- time_out=1440))
#> # A tibble: 5 x 15
+(kin2<-calculate_kinetics(dat,
+ protein ="db_CD160",
+ sequence ="INITSSASQEGTRLN",
+ state ="CD160_HVEM",
+ start =1,
+ end =15,
+ time_in =0.001,
+ time_out =1440))
+
The function plot_position_frequency plots a histogram of the coverage frequency based on experimental data.
The aim of this plot is to see how many times each position of the sequence was covered (by different peptides).
# load example data
-dat<-read_hdx(system.file(package="HaDeX",
- "HaDeX/data/KD_180110_CD160_HVEM.csv"))
-
+dat<-read_hdx(system.file(package ="HaDeX",
+ "HaDeX/data/KD_180110_CD160_HVEM.csv"))
+
# function call with default parameters
-plot_position_frequency(dat)
+plot_position_frequency(dat)
+
# function call with explicit parameters
-plot_position_frequency(dat, chosen_state="CD160_HVEM")
# load example data
-dat<-read_hdx(system.file(package="HaDeX", "HaDeX/data/KD_180110_CD160_HVEM.csv"))
+dat<-read_hdx(system.file(package ="HaDeX", "HaDeX/data/KD_180110_CD160_HVEM.csv"))# prepare dataset for states `CD160` and `CD160_HVEM` in given time parameters
-prepare_dataset(dat,
- in_state_first="CD160_0.001",
- chosen_state_first="CD160_1",
- out_state_first="CD160_1440",
- in_state_second="CD160_HVEM_0.001",
- chosen_state_second="CD160_HVEM_1",
- out_state_second="CD160_HVEM_1440")
data.frame with mean uncertainty per different `out_time` value
-
Details
The function calculates mean uncertainty of all peptides and its uncertainty (standard error) based on given `in_time` and `chosen_time`
@@ -162,22 +177,21 @@
Details
experimental calculations depends on `out_time` variable. The results are either in form of relative or absolute values depending on the `relative`
parameter supplied by the user.
This data can be useful for general overview of the experiment and analyse of the chosen time parameters.
-
First version accepts files produced by DynamX 3.0 and 2.0 in `cluster data` format.
The function checks if all necessary columns are provided in correct format. The file must
include at least two repetitions of the measurement for the uncertainty to be calculated.
reconstruct_sequence(dat, protein =dat[["Protein"]][1])
+
Arguments
@@ -138,56 +154,48 @@
Arg
the protein of which the structure is to be reconstructed
-
+
Value
reconstructed sequence - character object.
-
Details
The function reconstructs protein sequence from supplied experimental data. If a position is not covered, x is shown.
First version doesn't support manual sequence length correction.
time point (in minutes) for fully deuterated sample. Numeric value, bigger than other
+time points in the file. Obligatory
+
+
+
old_protein_name
+
protein name to be changed. String or string vector (if the file contains
+data from multiple proteins). Not obligatory
+
+
+
new_protein_name
+
new names for old_protein_name. String or string vector (if the file contains
+data from multiple proteins). Not obligatory
+
+
+
old_state_name
+
state names to be changed. String or string vector (if the file contains
+data from multiple states). Not obligatory
+
+
+
new_state_name
+
new names for old_state_name. String or string vector (if the file contains
+data from multiple states). Not obligatory
+
+
+
confidence
+
vector of accepted confidence values (internal flag from HDeXaminer). By default only
+accepted values are `Medium` and `High`, with `Low` excluded. The user can control that by specifying
+this parameter
+
+
+
+
Value
+
+
dat - a data.frame with validated and updated content.
+
Details
+
+
Data from HDeXaminer is condensed and automated data retrieving may be corrected by the user.
+The original file has a mark "FD" for fully deuterated data instead of numerical value for time point
+(provided in minutes) that is not consistent for workflow and not enough for precise data description.
+Moreover, the data about both protein and state is included in one column and for detailed information
+function update_hdexaminer_file allows to change them.
This is the first version - multi-state calculations are not supported.
-
References
Woods, V.L., and Hamuro, Y. (2001). High resolution,
high-throughput amide deuterium exchange-mass spectrometry (DXMS)
determination of protein binding site structure and dynamics: utility
in pharmaceutical design. J. Cell. Biochem. Suppl. Suppl 37, 89–98.
## Warning: pakiet 'ggplot2' został zbudowany w wersji R 4.0.3
+
## Warning: pakiet 'DT' został zbudowany w wersji R 4.0.3
+
+
1 About HaDeX
+
HaDeX is a novel tool for processing, analysis, and visualization of HDX-MS experiments. HaDeX covers the final parts of the analytic process, including a comparison of experiments, quality control and generation of publication-quality figures. To make the HaDeX R package available to the less R-fluent users, we enhanced it with a comprehensive Graphical User Interface available as a HaDeX GUI. The reproducibility of the whole procedure is ensured with advanced reporting functions.
This document covers the main functionalities of both the R package and the GUI.
+
+
1.1 Comparison of the existing HDX-MS software
+
To show the novelty of HaDeX, we compare its functionalities with other relatively new software for analysis of HDX-MS data: MEMHDX (Hourdel et al. 2016) and Deuteros (Lau et al. 2019).
+
+
+
We have not considered HDX Workbench (Pascal et al. 2012) as it deals with the preliminary steps of the analysis. This comparison also does not cover a versatile structural visualisation tool for HDX-MS results, HDX-Viewer (Bouyssié et al. 2019) as its scope is different from the tools mentioned above.
+
Web server: a software is available as a web server.
+
Programmatic access: analytic functionalities are documented and available from a command line.
+
Desktop software: a software can be installed locally.
+
Multi-state analysis: a software supports comparisons of more than two states.
+
ISO-based uncertainty: analytic functions produce ISO-compatible uncertainty intervals.
+
Coverage and peptide overlap: overview of experimental sequence coverage is available in a user-friendly way.
+
Quality control: additional information about course of the experiment.
+
N- and C-terminal length corrections: manual correction of sequence length.
+
Global visualization of deuterium uptake: deuterium uptake for different states is shown together for comparison.
+
Woods plot: deuteration difference between chosen states shown in the format of Woods plot.
+
Zooming of the Woods plot: Woods plot can be zoomed in.
+
Customizable label names and colors: Labels and colors on the plot can be changed by the user.
+
Peptide kinetics chart: Kinetics plot (deuteration change in time) are available for each peptide.
+
3D structure visualization: structure of the protein is visualized in 3D.
+
Downloadable charts: charts are downloadable, preferably in a vector format (.eps, .svg or .pdf).
+
Deuterium uptake download: data shown on Woods plot is downloadable (e.q. as CSV file).
+
Downloadable results of intermediate computations: results of intermediate computations (e.q. pure deuteration data) are downloadable.
+
Report generation: generates a report (e.q. in Html format) with results of the analysis with parametrization.
HDX Data Summary: summary of the experimental data (Masson et al. 2019).
+
+
+
+
2 HaDeX functionalities
+
+
2.1 Data import
+
The HaDeX web server works only on data in the DynamX datafile format (Waters Corp.). The data from other sources may be also adjusted to the format accepted by HaDeX provided it has following columns:
+
+
+
Although data can be imported into R using other tools, we strongly advise to rely on the read_hdx() function:
+
dat <-read_hdx(system.file(package ="HaDeX",
+"HaDeX/data/KD_190304_Nucb2_EDTA_CaCl2_test02_clusterdata.csv"))
+
Currently, read_hdx() supports .csv, .tsv and .xls files fulfilling the data structure described above. Files with data from multiple proteins are supported. The user need to indicate which protein is of interest for calculations.
+
+
+
2.2 Computation of deuteration levels
+
The computation of the level of deuteration involves several pre-processing steps, all of which are described in this section. These steps are performed automatically in the GUI or by the prepare_dataset() function in the console.
+
+
2.2.1 Measured data into overall peptide mass
+
The results of HDX-MS measurements as given in the DynamX data files are represented as the measured mass of peptides plus proton mass to charge ratio (\(Center\)). For later use, this value has to be transformed into an overall mass of a peptide measured after specific time point from a protein in a specific state, as shown in equation 1:
+
\[pepMass = z \times (Center-protonMass)\tag{1}\] where:
+
+
\(pepMass\) - expected mass of the peptide after incubation (Da),
+
\(protonMass\) - the mass of the proton (Da),
+
\(z\) - charge of the peptide,
+
\(Center\) - experimentally measured peptide mass plus proton mass to charge ratio \(\left(\frac{m}{z}\right)\).
+
+
HDX-MS experiments are often repeated (by the rule of thumb at least three times). Thus, we aggregate the results of replicates as a weighted mean mass into a single result per peptide using equation 2:
\(aggMass\) - weighted mean mass of the peptide (Da),
+
\(k\) - replicate index,
+
\(Inten\) - intensity,
+
\(N\) - number of replicates.
+
+
This data manipulation results from an original data structure. Each repetition of the measurement gives the data for given peptide in a given time per possible value of \(z\) as shown in the example below. We need to use the value of \(pepMass\) as shown in equation 1 but still keep the information about original measurement - that’s why we use the weighted mass.
The uncertainty of a measurement is variability associated with the precision of measuring instrumentation. We present here a novel derivation of uncertainty formulas for HDX-MS data according to the ISO guidelines (Joint Committee for Guides in Metrology 2008). Input files always encompass results of more than one measurement. We assume uncorrelatedness of replicates as they come from different samples. Therefore, we average measurements of replicates for each time point and for all protein states. Thus, we compute peptide mass uncertainty \(u\) as uncertainty for aggregate estimate using the formula for standard deviation of the mean:
After obtaining the mass of the peptide, we can compute the deuteration level depending on the chosen maximum deuteration level. The maximum deuteration can also be computed in two different ways: either as theoretical (where the maximum deuteration depends on the theoretical deuteration levels) and experimental (where the maximum deuteration is assumed to be equal to the deuteration measured at the last time point).
+
+
+
2.2.2 Experimental deuteration level
+
The experimental deuteration level is computed as the deuteration level of the peptide from a protein in a specific state and after incubation time \(t\) compared to the deuteration level measured at the start of the incubation (\(t_0\)). It yields a value for the chosen state and chosen time \(t\).
+
\[D = D_{t} - D_{t_0}\tag{4}\]
+
where:
+
+
\(D\) - deuteration level (Da),
+
\(D_{t_0}\) - experimentally measured deuteration at the beginning of the incubation (0 or close to 0),
+
+
The equation 4 produces only absolute deuteration levels. The computations of relative deuteration levels follows a similar logic and is normalized by the difference of deuteration between the start (\(t_0\)) and the end of the experiment (\(t_out\)) as shown in the equation 4a:
All functions in the HaDeX package contain the logical parameter \(relative\) to determine if they should return absolute or relative deuteration levels.
+
+
2.2.2.1 Uncertainty calculations
+
We describe the methodology of the uncertainty calculations for relative deuteration levels. The uncertainty for absolute deuteration levels is computed similarly, but without scaling.
+
To calculate uncertainty related to functions of more than one variables (e. g., equation 4) the Law of propagation of uncertainty is defined by equation 5:
\(u(D_{k})\) - an uncertainty associated with \(D_{k}\) as standard deviation of the mean value,
+
+
Then, expanding the equation 6:
+
\[u_{c}(D) = \sqrt{ \left[
+\frac{1}{D_{t_{out}}-D_{t_0}} u(D_{t}) \right]^2 +
+\left[ \frac{D_{t} - D_{t_{out}}}{(D_{t_{out}}-D_{t_0})^2} u(D_{t_0}) \right]^2 +
+\left[ \frac{D_{t_0} - D_{t}}{(D_{t_{out}}-D_{t_0})^2} u (D_{t_{out}}) \right]^2}\tag{7}\] As expected, the uncertainty associated with \(D_{t}\) has the biggest impact on \(u_{c}(D)\).
+
+
+
+
2.2.3 Theoretical deuteration level
+
As opposed to the experimental deuteration levels, theoretical deuteration level only partially depends on the experimental data. Here, the maximum deuteration level is based on a hypothetical peptide where all hydrogens were replaced by deuterons, as it is shown in equation 8:
For the absolute values, \(u(D)\) is identical with \(u(D_{t})\), based on equations 8a and 9.
+
+
+
+
+
2.3 Difference of deuteration levels between two states
+
The differences of deuteration levels between two states are associated with a different level of protection of hydrogens. Therefore, we are especially interested in the differential analysis of the deuteration levels. Thus, the deuteration level in one state \((D_{2})\) is subtracted from deuteration level in the other state \((D_{1})\):
+
\[diff = D_{1} - D_{2}\tag{11}\]
+
and the uncertainty is a function of two variables (based on equation 11 and 5):
Comparison plots show the deuteration level of all peptides in selected states in a given time. The x-axis represents positions of amino acids in the sequence. The y-axis shows the deuteration level, expressed either as a relative or absolute deuteration. The chart below shows peptide deuteration after 25 minutes of the incubation along with the confidence intervals.
6{r warning=FALSE} # comparison_plot(calc_dat = calc_dat, # theoretical = FALSE, # relative = TRUE, # state_first = "Nucb2 Factor 1", # state_second = "Nucb2 Factor 2") + # labs(title = "Fraction exchanged in state comparison in 25 min time") #
+
+
absolute values:
+
+
+
+
7{r warning=FALSE} # comparison_plot(calc_dat = calc_dat, # theoretical = FALSE, # relative = FALSE, # state_first = "Nucb2 Factor 1", # state_second = "Nucb2 Factor 2") + # labs(title = "Fraction exchanged in state comparison in 25 min time") #
+
+
7.1 Woods plot
+
Woods plots show the difference between the deuteration of all peptides in two different states in a specific time point as described by equation 11. Similarly to the comparison plot, HaDeX provides both experimental and theoretical deuteration levels using either relative or absolute values:
+
– theoretical:
+
+
relative values:
+
+
+
+
+
8{r warning=FALSE} # woods_plot(calc_dat = calc_dat, # theoretical = TRUE, # relative = TRUE) + # labs(title = "Theoretical fraction exchanged between states in 25 min time") #
+
+
absolute values:
+
+
+
+
9{r warning=FALSE} # woods_plot(calc_dat = calc_dat, # theoretical = TRUE, # relative = FALSE) + # labs(title = "Theoretical fraction exchanged between states in 25 min time") #
+
– experimental:
+
+
relative values:
+
+
+
+
10{r warning=FALSE } # woods_plot(calc_dat = calc_dat, # theoretical = FALSE, # relative = TRUE) + # labs(title = "Theoretical fraction exchanged between states in 25 min time") #
+
+
absolute values:
+
+
+
+
11{r warning=FALSE } # woods_plot(calc_dat = calc_dat, # theoretical = FALSE, # relative = FALSE) + # labs(title = "Theoretical fraction exchanged between states in 25 min time") #
+
+
11.0.1 Confidence limit in Woods plot
+
The function calculate_confidence_limit_values() calculates confidence limit values as it is described elsewhere (Houde, Berkowitz, and Engen 2011).
By the term kinetics we understand deuteration change in time. To calculate deuteration values per peptide for different time points is used function calculate_kinetics(). This function uses the calculate_state_deuteration() function.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Calculated data can be shown next to each other on the plot for comparison. To visualize kinetic data we recommend plot_kinetics() function:
+
– theoretical:
+
+
relative values:
+
+
+
+
+
+
+
+
absolute values:
+
+
+
+
+
+
+
– experimental:
+
+
relative values:
+
+
+
+
+
+
+
+
absolute values:
+
+
+
+
+
+
+
+
+
13.2 Additional tools
+
HaDeX provides additional tools for assessment of experiments.
+
+
13.2.1 Peptide coverage
+
The sequence of the protein(s) is reconstructed from the peptides from the input file. Thus, amino acids not covered by peptides are marked as X according to the IUPAC convention. The sequence is reconstructed using the reconstruct_sequence() function.
The user can choose which state (or states) should be included in these plots. If this parameter is not provided, the first possible state is chosen. If a given peptide is available in more than one state, it is shown only once.
+
+
+
13.2.2 Quality control
+
The function quality_control() plots the change in the uncertainty of deuteration levels as a function of incubation time. The uncertainty is averaged over all peptides available at a given time point in a selected state. This chart has a double function: firstly, it allows checking if the measurement uncertainty is decreasing over time (which is the expected behavior) and the second one helps to plan the appropriate incubation length for the tested protein (whether we obtain the desired data reliability values).
+
In HDX-MS experiments, the average uncertainty of measurements decreases over time as the sample is more and more deuterated (even accounting for the back-propagation). Therefore, if the level of uncertainty is stable, the exchange is still ongoing and it would be advisable to prolong the reaction.
+
Moreover, the user can detect a time point after which the decrease of the deuteration uncertainty becomes too marginal to prolong the measurements. This function is most useful in case of multiple measurements of the same or very similar proteins because it helps to optimize the duration of the incubation. The result of this function can be easily visualized.
The chart below shows how we interpret the three most common results of quality control.
+
+
+
16 HaDeX Graphical User Interface
+
The HaDeX Shiny app is launched by the HaDeX_gui() function or available at MS Lab website: http://mslab-ibb.pl/shiny/HaDeX/. In the Input Data tab the user can adjust parameters to be propagated for the whole analysis.
+
+
+
17 Examples
+
+
17.1 Example 1: CD160-HVEM
+
The interaction between HVEM and the CD160 receptor was measured with HDX-MS.
+
Firstly, we read the input data, exactly as provided by the DynamX 3.0 (Waters Corp.)
Then, we reconstruct the protein sequence from the peptides measured during the experiment. We observe the region from amino acid 107 till amino acid 124 is not covered by any peptide.
The theoretical plot allows finding regions, which exchange quickly (N-terminus, regions between 30-70 amino acid) and regions, which exchange slowly (peptides 15-24, 95-110 amino acid). We can also see the differences in the exchange between two states, indicating regions which changed upon binding with other protein.
On the experimental plot, there are visible regions, which exchange quickly (N terminal part, regions between 30-70 amino acid) and regions, which exchange slowly (peptides 15-24, 30-35, 95-110 amino acid).
The plot below shows peptides for which levels of deuteration were significantly lower upon binding with other protein (red) and peptides for which levels of exchange were significantly higher upon binding with other protein (blue). The plot also shows peptides in which no significant changes in deuteration between states are visible (grey). The biggest changes on the theoretical plot can be observed in 3 peptides (15-24, 30-35, 75-90).
Bouyssié, David, Jean Lesne, Marie Locard-Paulet, Renaud Albigot, Odile Burlet-Schiltz, and Julien Marcoux. 2019. “HDX-Viewer: Interactive 3D Visualization of Hydrogen-Deuterium Exchange Data.” Bioinformatics (Oxford, England), July. https://doi.org/10.1093/bioinformatics/btz550.
+
+
+
Houde, Damian, Steven A. Berkowitz, and John R. Engen. 2011. “The Utility of Hydrogen/Deuterium Exchange Mass Spectrometry in Biopharmaceutical Comparability Studies.” Journal of Pharmaceutical Sciences 100 (6): 2071–86. https://doi.org/10.1002/jps.22432.
+
+
+
Hourdel, Véronique, Stevenn Volant, Darragh P. O’Brien, Alexandre Chenal, Julia Chamot-Rooke, Marie-Agnès Dillies, and Sébastien Brier. 2016. “MEMHDX: An Interactive Tool to Expedite the Statistical Validation and Visualization of Large HDX-MS Datasets.” Bioinformatics 32 (22): 3413–9. https://doi.org/10.1093/bioinformatics/btw420.
+
+
+
Joint Committee for Guides in Metrology. 2008. “JCGM 100: Evaluation of Measurement Data - Guide to the Expression of Uncertainty in Measurement.” JCGM.
+
+
+
Lau, Andy M. C., Zainab Ahdash, Chloe Martens, and Argyris Politis. 2019. “Deuteros: Software for Rapid Analysis and Visualization of Data from Differential Hydrogen Deuterium Exchange-Mass Spectrometry.” Bioinformatics (Oxford, England), January. https://doi.org/10.1093/bioinformatics/btz022.
+
+
+
Masson, Glenn R., John E. Burke, Natalie G. Ahn, Ganesh S. Anand, Christoph Borchers, Sébastien Brier, George M. Bou-Assaf, et al. 2019. “Recommendations for Performing, Interpreting and Reporting Hydrogen Deuterium Exchange Mass Spectrometry (HDX-MS) Experiments.” Nature Methods 16 (7): 595–602. https://doi.org/10.1038/s41592-019-0459-y.
+
+
+
Pascal, Bruce D., Scooter Willis, Janelle L. Lauer, Rachelle R. Landgraf, Graham M. West, David Marciano, Scott Novick, Devrishi Goswami, Michael J. Chalmers, and Patrick R. Griffin. 2012. “HDX Workbench: Software for the Analysis of H/D Exchange MS Data.” Journal of the American Society for Mass Spectrometry 23 (9): 1512–21. https://doi.org/10.1007/s13361-012-0419-6.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/vignettes/datafiles.Rmd b/vignettes/datafiles.Rmd
new file mode 100644
index 00000000..f8834d9e
--- /dev/null
+++ b/vignettes/datafiles.Rmd
@@ -0,0 +1,136 @@
+---
+title: "Data processing"
+output: html_document
+vignette: >
+ %\VignetteIndexEntry{Data processing}
+ %\VignetteEngine{knitr::rmarkdown}
+ %\VignetteEncoding{UTF-8}
+---
+
+```{r setup, include=FALSE}
+knitr::opts_chunk$set(echo = TRUE)
+```
+
+
+
+Currently, HaDeX is limited to the `cluster` file from DynamX 3.0 or 2.0. Below we explain how the data file is processed.
+
+## Processing data from DynamX
+
+Let's investigate how the data processing of the `cluster` file from DynamX is conducted on the example file from the package.
+
+### Differences between files
+
+What is the difference between `cluster` files from DynamX 3.0 and 2.0?
+The datafiles from DynamX 2.0 don't include `Modification` and `Fragment` columns. The variations of the experiment were limited, while the DynamX 2.0 was the latest version.
+
+### Initial processing of the data
+
+Let's start with a glimpse of the datafile.
+
+```{r warning=FALSE}
+library(HaDeX)
+dat <- read_hdx(system.file(package = "HaDeX", "HaDeX/data/KD_180110_CD160_HVEM.csv"))
+head(dat, 10)
+```
+
+As you can see, the data file has a very specific structure and is not informative yet. In the file, we have `m/z` values for each `z` value (charge) for each time point for each state of each peptide, repeated as many times as measurement was repeated (each measurement should be repeated at least three times).
+
+
+
+Our aim is to have one result with an uncertainty of the measurement per each peptide in each biological state in each measured time point - data in this format allows further calculations, e.q. calculating deuterium uptake values.
+
+For a better understanding of the process of aggregating the data, see the `Data aggregation` article.
+
+Within each replicate of the measurement (we recognize each replicate by the `File` value), the `m/z` values are provided for each possible `z` value. The `m/z` values are in the `Center` column, as it is a geometrical centroid calculated from the isotopic envelope. Firstly, we have to calculate the mass value, measured experimentally:
+
+$$expMass = z \times (Center-protonMass)\tag{1}$$
+
+
+To aggregate data from different `z` values, we have to calculate the mean mass weighted by intensity. Additional information about this step and how the weighted mean impacts the results can be found in `Mass calculation` article.
+
+$$aggMass = \frac{1}{N}\sum_{k = 1}^{N}Inten_k{\cdot}pepMass_k\tag{2}$$.
+
+Where:
+
+* $aggMass$ - mass of the peptide [Da], average from replicates,
+* $Inten_k$ - intensity of the measurement,
+* $pepMass$ - mass of the peptide, calculated using Equation 1.
+
+As we use the aggregated result from the replicates, we need to calculate an uncertainty associated with the measurement. We use the mean value as the final result, so we need to calculate error as a standard deviation of the mean, according to the Equation 3:
+
+$$u(\vec{x}) = \sqrt{\frac{ \sum_{i=1}^n \left( x_{i} - \overline{x} \right)^2}{n(n-1)}}\tag{3}$$.
+
+Where:
+
+* $x_{i}$ - measured value from a replicate,
+* $\overline{x}$ - mean value from all of the replicates,
+* $n$ - number of replicates.
+
+Now we have the format we want for further calculations.
+
+### Calculation of the deuterium uptake
+
+HaDeX package provides the calculated values in different forms. All of them are provided with associated uncertainty of the measurement. All of the uncertainties are derived from the formula - the Law of propagation of uncertainty:
+
+$$u_{c}(y) = \sqrt{\sum_{k} \left[ \frac{\partial y}{\partial x_{k}} u(x_{k}) \right]^2}$$
+
+#### Deuterium uptake
+
+Deuterium uptake is the increase of the mass of the peptide in time $t$. The minimal exchange control $m_{t_0}$ is mass measured directly after adding the buffer (before the start of the exchange), and $m_t$ is the mass measured in chosen time point $t$. The value is in Daltons [Da].
+
+$$D = m_{t} - m_{t_0}$$
+The uncertainty associated with deuterium uptake [Da] (based on equation 3):
+
+$$u_c(D) = \sqrt{u(m_t)^2 + u(m_{t_0})^2}$$
+
+#### Fractional deuterium uptake
+
+Fractional deuterium uptake is the ratio of the increase of the mass in time $t$ to the maximal exchange control. The maximal exchange control $m_{t_{100}}$ is measured after a long time (chosen by the experimenter, usually 1440 min = 24 h). It is assumed that after this long time, the exchange is finished. The minimal exchange control $m_{t_0}$ is mass measured directly after adding the buffer (before the start of the exchange), and $m_t$ is the mass measured in chosen time point $t$. This value is a percentage value [%].
+
+$$D_{frac} = \frac{m_{t} - m_{t_0}}{m_{t_{100}} - m_{t_0}}$$
+
+The uncertainty associated with fractional deuterium uptake [%] (based on equation 3):
+
+$$u_{c}(D_{frac}) = \sqrt{ \left[
+\frac{1}{m_{t_{100}}-m_{t_0}} u(m_{t}) \right]^2 +
+\left[ \frac{m_{t} - m_{t_{100}}}{(m_{t_{100}}-m_{t_0})^2} u(m_{t_0}) \right]^2 +
+\left[ \frac{m_{t_0} - m_{t}}{(m_{t_{100}}-m_{t_0})^2} u (m_{t_{100}}) \right]^2}$$
+
+#### Theoretical deuterium uptake
+
+Theoretical deuterium uptake is the increase of mass in time $t$ compared with the theoretical value of the peptide mass without any exchange ($MHP$ - a mass of the singly charged monoisotopic molecular ion), and $m_t$ is the mass measured in chosen time point $t$. This value is in daltons [Da]:
+
+$$D_{theo} = m_{t} - MHP$$
+
+The uncertainty associated with theoretical deuterium uptake [Da] (the $MHP$ value is a constant without measurement uncertainty - based on the equation 3):
+
+$$u(D_{theo}) = u(m_t)$$
+
+#### Theoretical fractional deuterium uptake
+
+Theoretical fractional deuterium uptake is the ratio of the increase of mass in time $t$ compared with a theoretical value of the mass of the peptide without any exchange to the possible theoretical increase of the mass, based on the maximal potential uptake of the peptide (based on the peptide sequence). This value is a percentage value [%].
+
+$$D_{theo, frac} = \frac{m_{t}-MHP}{MaxUptake \times protonMass}$$
+
+The uncertainty associated with theoretical fractional deuterium uptake [%] (based on the equation 3):
+
+$$u(D_{theo, frac}) = \left|\frac{1}{MaxUptake \times protonMass} u(D_{t}) \right|$$
+
+#### Differential values
+
+Differential value is the way to see how the deuterium uptake differs between two biological states. It allows seeing if the possible difference is statistically important (more information below). This value is calculated as the difference between the previously described (in a chosen form) deuterium uptake of the first and second states.
+
+$$diff = D_{1} - D_{2}$$
+The uncertainty associated with the difference of deuterium uptake (based on the equation 3):
+
+$$u_{c}(diff) = \sqrt{u(D_{1})^2 + u(D_{2})^2}$$
+
+The convenient way to present results calculated as described is the comparison plot and differential plot (Woods' plot).
+
+### Additional information
+
+If the file contains modified peptides - the value from column `Modification` is added to the value from column `State` and is treated as a new biological state. The further aspects of the analysis are the same as for non-modified peptides.
+
+
+
\ No newline at end of file
diff --git a/vignettes/mass_comparison.Rmd b/vignettes/mass_comparison.Rmd
new file mode 100644
index 00000000..125dff48
--- /dev/null
+++ b/vignettes/mass_comparison.Rmd
@@ -0,0 +1,147 @@
+---
+title: "Mass calculation"
+output: html_document
+vignette: >
+ %\VignetteIndexEntry{Mass calculation}
+ %\VignetteEngine{knitr::rmarkdown}
+ %\VignetteEncoding{UTF-8}
+---
+
+## Comparison of results with weighted mean and without
+
+As it is described in `Data processing` article, the data within each replicate of the experiment is aggregated using weighted mean. Below we present the effect it has on the results.
+
+The whole workflow is described in the mentioned article. Here the focus is on the first aspect of the processing.
+
+```{r setup, include=FALSE}
+knitr::opts_chunk$set(echo = TRUE)
+knitr::opts_chunk$set(dev = "png", dev.args = list(type = "cairo-png"))
+
+options(digits=3)
+
+library(tidyr)
+library(dplyr)
+
+calculate_mass <- function(dat){
+
+ proton_mass <- 1.00727647
+
+ dat %>%
+ mutate(exp_mass = Center*z - z*proton_mass) %>%
+ select(-Center, -z, -Modification, -Fragment) %>%
+ group_by(Sequence, Start, End, MHP, MaxUptake, State, Exposure, Protein, File) %>%
+ summarize(avg_exp_mass = weighted.mean(exp_mass, Inten, na.rm = TRUE)) %>%
+ ungroup(.) %>%
+ group_by(Sequence, Start, End, MHP, MaxUptake, State, Exposure, Protein) %>%
+ summarize(mass = mean(avg_exp_mass, na.rm = TRUE),
+ err_mass = coalesce(sd(avg_exp_mass, na.rm = TRUE)/sqrt(sum(!is.na(avg_exp_mass))), 0),
+ num = (sum(!is.na(avg_exp_mass)))) %>%
+ ungroup(.) %>%
+ arrange(Start, End, Start, Exposure) %>%
+ as.data.frame()
+
+}
+
+calculate_mass_no_inten <- function(dat){
+
+ proton_mass <- 1.00727647
+
+ dat %>%
+ mutate(exp_mass = Center*z - z*proton_mass) %>%
+ select(-Center, -z, -Modification, -Fragment) %>%
+ group_by(Sequence, Start, End, MHP, MaxUptake, State, Exposure, Protein, File) %>%
+ summarize(avg_exp_mass = mean(exp_mass, na.rm = TRUE)) %>%
+ ungroup(.) %>%
+ group_by(Sequence, Start, End, MHP, MaxUptake, State, Exposure, Protein) %>%
+ summarize(mass = mean(avg_exp_mass, na.rm = TRUE),
+ err_mass = coalesce(sd(avg_exp_mass, na.rm = TRUE)/sqrt(sum(!is.na(avg_exp_mass))), 0)) %>%
+ ungroup(.) %>%
+ arrange(Start, End, Start, Exposure) %>%
+ as.data.frame()
+
+}
+
+```
+
+For the analysis, we use the example file from HaDeX.
+
+```{r}
+library(HaDeX)
+dat <- read_hdx(system.file(package = "HaDeX", "HaDeX/data/KD_180110_CD160_HVEM.csv"))
+```
+
+As described, the first step is to transform the Center value (geometric centroid of the isotopic envelope for given peptide in a given state in given time point) and then to aggregate the values measured for different charge values. This is all done within each replicate.
+
+The aggregation in our workflow is a weighted mean, with Inten (intensity) values as weights, as shown below.
+
+```{r eval=FALSE}
+avg_exp_mass = weighted.mean(exp_mass, Inten, na.rm = TRUE)
+```
+
+Later, the results from replicates are aggregated using the mean, and their uncertainty is calculated as the standard deviation of the mean.
+
+How the weighted mean change the result in comparison with the simple mean? Let's see.
+
+```{r include=FALSE}
+dat_no_weight <- calculate_mass_no_inten(dat) %>%
+ arrange(Start, End, State, Exposure) %>%
+ mutate(source = "no_weight") %>%
+ select(Sequence, Start, End, State, Exposure, mass, err_mass, source)
+
+dat_weight <- calculate_mass(dat) %>%
+ arrange(Start, End, State, Exposure) %>%
+ mutate(source = "weight") %>%
+ select(Sequence, Start, End, State, Exposure, mass, err_mass, source)
+
+tmp <- bind_rows(dat_no_weight, dat_weight) %>%
+ gather(type, value, -Sequence, -Start, -End, -source, -State, -Exposure) %>%
+ spread(source, value) %>%
+ mutate(diff = (weight-no_weight))
+```
+
+Below are calculated values of mass in two approaches and the difference between them for the example peptide.
+
+```{r echo=FALSE}
+tmp %>%
+ filter(type == "mass") %>%
+ select(-type) %>%
+ filter(Sequence == "ARSQKSGIRLQGHF")
+```
+
+Below are calculated values of the uncertainty of mass in two approaches and the difference between them for the example peptide.
+
+```{r echo=FALSE}
+tmp %>%
+ filter(type == "err_mass") %>%
+ select(-type) %>%
+ filter(Sequence == "ARSQKSGIRLQGHF")
+```
+
+And for the whole set of peptides, the average mass difference is:
+
+```{r echo=FALSE}
+mean(tmp[ tmp[["type"]] == "mass" , "diff"])
+```
+and uncertainty difference is:
+
+```{r echo=FALSE}
+mean(tmp[ tmp[["type"]] == "err_mass" , "diff"])
+```
+Below are the histograms of these differences.
+
+```{r message=FALSE, warning=FALSE, echo=FALSE}
+library(gridExtra)
+library(ggplot2)
+
+p1 <- ggplot(filter(tmp, type == "mass"), aes(diff)) +
+ geom_histogram() +
+ labs(title = "Differences between mass",
+ x = "Difference")
+
+p2 <- ggplot(filter(tmp, type == "err_mass"), aes(diff)) +
+ geom_histogram() +
+ labs(title = "Differences between uncertainties of mass",
+ x = "Difference")
+
+grid.arrange(p1, p2, ncol=2)
+```
diff --git a/vignettes/transformation.Rmd b/vignettes/transformation.Rmd
new file mode 100644
index 00000000..2d19c778
--- /dev/null
+++ b/vignettes/transformation.Rmd
@@ -0,0 +1,121 @@
+---
+title: "Data aggregation"
+output: html_document
+vignette: >
+ %\VignetteIndexEntry{Data aggregation}
+ %\VignetteEngine{knitr::rmarkdown}
+ %\VignetteEncoding{UTF-8}
+---
+
+```{r setup, include=FALSE}
+knitr::opts_chunk$set(echo = FALSE)
+knitr::opts_chunk$set(dev = "png", dev.args = list(type = "cairo-png"))
+```
+
+The aggregation of the data is complex. This article describes the process step by step for a better understanding of the data transformation.
+
+## Aggregation of the data - visualization
+
+```{r, echo=FALSE, message=FALSE, warning=FALSE}
+library(HaDeX)
+library(dplyr)
+library(ggplot2)
+
+tmp_seq <- "LCKDRSGDCSPETSLKQLRLKRDPGIDGVGEISSQL"
+tmp_state <- "CD160"
+tmp_time <- "1 min"
+proton_mass <- 1.00727647
+
+dat <- read_hdx(system.file(package = "HaDeX", "HaDeX/data/KD_180110_CD160_HVEM.csv")) %>%
+ filter(Exposure == 1, State == "CD160", Sequence == "LCKDRSGDCSPETSLKQLRLKRDPGIDGVGEISSQL")
+```
+
+Let's see how the data is transformed. We will use the example file "KD_180110_CD160_HVEM.csv" from the HaDeX package and focus on just one peptide - "LCKDRSGDCSPETSLKQLRLKRDPGIDGVGEISSQL" in the state "CD160". The measurement was made for time point 1 min.
+
+Below is shown the original and not aggregated data for chosen peptide.
+
+```{r}
+dat
+```
+
+As we can see from the `File` column, there are four replicates of the experiment. Each measurement of a replicate provide values for different possible charge values for each peptide. The result of a measurement is in column `Center` - this is a geometrical centroid of an isotopic envelope - the product of the measurement from a mass spectrometer.
+
+Let's take a look for values for each replicate.
+
+```{r echo=FALSE}
+dat %>%
+ filter(File == "KD_160530_CD160_1min_01") %>%
+ggplot() +
+ geom_segment(aes(x = Start, xend = End, y = Center, yend = Center, colour = z)) +
+ coord_cartesian( xlim = c(30, 75)) +
+ labs(title = paste0("Measurements for sequence in ", tmp_state, " state"),
+ x = "Position in the sequence")
+```
+
+The centroid values for different charge values are not useful. We have to transform it to the mass values, according to an equation:
+
+$$ aggMass = z*(Center - protonMass)$$
+The results are shown below.
+
+```{r echo=FALSE}
+dat %>%
+ filter(File == "KD_160530_CD160_1min_01") %>%
+mutate(exp_mass = z*(Center - proton_mass)) %>%
+ ggplot() +
+ geom_segment(aes(x = Start, xend = End, y = exp_mass, yend = exp_mass, colour = z)) +
+ coord_cartesian( xlim = c(30, 75)) +
+ labs(title = "", # paste0("Measurements for sequence in ", tmp_state, " state"),
+ x = "Position in the sequence",
+ y = "Measured mass [Da]")
+```
+
+This results are just for one repetition. We have four of them:
+
+```{r echo=FALSE}
+dat %>%
+mutate(exp_mass = z*(Center - proton_mass)) %>%
+ ggplot() +
+ geom_segment(aes(x = Start, xend = End, y = exp_mass, yend = exp_mass, colour = z, linetype = File)) +
+ coord_cartesian( xlim = c(30, 75)) +
+ labs(title = "", # paste0("Measurements for sequence in ", tmp_state, " state"),
+ x = "Position in the sequence",
+ y = "Measured mass [Da]")
+```
+
+Values from each replicate are aggregated into one value, using weighted mean (with intensity value as weight):
+
+```{r echo=FALSE, warning=FALSE, message=FALSE}
+dat %>%
+ mutate(exp_mass = z*(Center - proton_mass)) %>%
+ group_by(Sequence, Start, End, File) %>%
+ summarize(avg_exp_mass = weighted.mean(exp_mass, Inten, na.rm = TRUE)) %>%
+ ungroup(.) %>%
+ ggplot() +
+ geom_segment(aes(x = Start, xend = End, y = avg_exp_mass, yend = avg_exp_mass, linetype = File)) +
+ coord_cartesian( xlim = c(30, 75), ylim = c(3920.3, 3920.6)) +
+ labs(title = "", # paste0("Measurements for sequence in ", tmp_state, " state"),
+ x = "Position in the sequence",
+ y = "Measured mass [Da]")
+```
+
+The results from replicates are aggregated into the final result (mean), and the uncertainty (standard deviation of the mean) is calculated.
+
+```{r echo=FALSE, warning=FALSE, message=FALSE}
+dat %>%
+ mutate(exp_mass = z*(Center - proton_mass)) %>%
+ group_by(Sequence, Start, End, File) %>%
+ summarize(avg_exp_mass = weighted.mean(exp_mass, Inten, na.rm = TRUE)) %>%
+ ungroup(.) %>%
+ group_by(Sequence, Start, End) %>%
+ summarize(aggMass = mean(avg_exp_mass),
+ err_aggMass = sd(avg_exp_mass)) %>%
+ ggplot() +
+ geom_segment(aes(x = Start, xend = End, y = aggMass, yend = aggMass)) +
+ geom_errorbar(aes(x = 51.5, ymin = aggMass - err_aggMass, ymax = aggMass + err_aggMass)) +
+ coord_cartesian( xlim = c(30, 75), ylim = c(3920.3, 3920.6)) +
+ labs(title = paste0("Measurements for sequence in ", tmp_state, " state"),
+ x = "Position in the sequence",
+ y = "Measured mass [Da]")
+```
+
+Now we have the mass value for chosen peptide in the chosen state, measured in the chosen time point. This calculation is done for every other peptide, and these values of mass and uncertainty are used in the calculation of deuterium uptake, as described in the `Data processing` article.
