-
Notifications
You must be signed in to change notification settings - Fork 1
/
README.Rmd
129 lines (81 loc) · 7.13 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# eemUtils
<!-- badges: start -->
<!-- badges: end -->
The **eemUtils** package is a collection of useful functions that act as an expansion of the existing existing R fluorescence analysis framework provided by the [eemR](https://cran.r-project.org/web/packages/eemR/index.html), [staRdom](https://github.com/MatthiasPucher/staRdom) and [EEM](https://CRAN.R-project.org/package=EEM) packages. Many of the functions within this package are alterations or wrappers for existing functions from eemR, staRdom or EEM - thus, if you use the functions from this package, please allocate proper credit to those packages and their authors.
This package is a work in progress, and is subject to change. Always back up your data!
If you have any questions or comments, I can be reached at m.r.p.harris@keele.ac.uk.
## Example functions
Below are some examples of functions within this package.
#### ggeem2
An updated EEM plotter, directly adapted from `staRdom::ggeem()`. It retains much of the same functionality, with tweaked graphical elements. Designed for use in my thesis and future pubs. It has integrated options for binning, and the default colour scheme takes after MATLAB's 'jet' scheme. Below are two examples, using some Black Tea OM SRM.
```{r, echo = TRUE, eval = TRUE, collapse = FALSE, warning = FALSE, message = FALSE}
pacman::p_load(eemUtils,staRdom,eemR,ggplot2,cowplot,pracma,magrittr,magick,tidyverse)
ILSMBT_36_eem_average <- (function(...)get(data(...,envir = new.env())))("ILSMBT_36_eem_average")
intp_eem <- eemUtils::interpolate_eem(ILSMBT_36_eem_average, n_pp = 2, verbose = FALSE)
p1 <- eemUtils::ggeem2(ILSMBT_36_eem_average, contour = TRUE, legend = FALSE, title_text = "Black tea 36-EEM avg") + theme(aspect.ratio = 1/1)
p2 <- eemUtils::ggeem2(intp_eem, bin_vals = "colpal", contour = FALSE, legend = FALSE, title_text = "Black tea 36-EEM avg interp + bin") + theme(aspect.ratio = 1/1)
cowplot::plot_grid(p1,p2,
ncol = 2, nrow = 1)
```
#### plot_eem_3D
A simple conversion of `staRdom::eempf_comps3D()`, but for use with sample EEM data, rather than outputs from a PARAFAC model. Extremely useful when checking individual samples for the presence of scatter lines or artefacts, or for quickly identifying the point of maximum fluorescence within part of an EEM. Option for the darker, MATLAB 'jet'-esque colourscheme, or for a more vibrant rainbow as is used in staRdom.
<p align="center">
<img src="man/figures/3D_eem_example_PHSC.png" height="800px" />
</p>
To view a 3D, interactive render of the black tea from the two plots above, download the BlackTea_plot_eem_3D_widget html file in the 'extras' folder and open it with a suitable program (e.g. Chrome).
#### Generate_CORCONDIA
`Generate_CORCONDIA()` is a simple function wrapper for staRdom's existing core consistency diagnostic function `staRdom::eempf_corcondia()`. It produces a more legible output.
<p align="center">
<img src="man/figures/generate_CORCONDIA_example.PNG" height="400px" />
</p>
#### extrpf_loadings
Use `extrpf_loadings()` to get the modeled per-sample fluorescence intensity loadings for each component within a set of PARAFAC models. This is a simple way to get quick series data from any number of PARAFAC models generated by `staRdom::eem_parafac()`.
#### get_pfload_percent
Outputs from `extrpf_loadings()` can be immediately passed to `get_pfload_percent()`, which will calculate the percentage contribution of each modeled component to a given sample's total fluorescence intensity.
#### extract_ramanpeak_areas
This function incorporates two methods in order to find the area under the Raman peak of water, for EEM data Raman normalisation purposes. The first method utilises a port of the MATLAB package drEEM's RamanIntegrationRange function, which uses adjustable gradient detection to identify the start and end of the Raman peak. The method is presented and discussed at length in Murphy, 2011. The second method is a straightforward, fixed-range integration used by the Aqualog fluorometer, which assumes the Raman peak extends from 380nm to 410nm at 350nm excitation.
Some sample Raman curve spectra are included in the package as below.
```{r, echo = TRUE, eval = TRUE, collapse = TRUE}
library(pacman)
pacman::p_load(eemUtils,ggplot2,cowplot,pracma,magrittr,magick)
data(SampleRamanCurves)
head(SampleRamanCurves)
```
`extract_ramanpeak_areas()` can then be used to get the areas under the raman peaks, and exported as image and/or .gif files for visualisation. The below .gif shows a use of the drEEM RamanIntegrationRange method, using gradient detection.
```{r, echo = TRUE, eval = TRUE, collapse = TRUE}
eemUtils::extract_ramanpeak_areas(RAMdat = SampleRamanCurves, range_upper = 500, method = "RIR", output_dir = NULL, gif = FALSE)
```
This function can also optionally produce images or a .gif of the detected peak bounds and areas.
<p align="center">
<img src="man/figures/Peaks_RIR.gif" height="500px" />
</p>
## Installation
To get access to the functions in **eemUtils**, simply use the **devtools** package to install the package from github.
```r
devtools::install_github("MRPHarris/eemUtils")
```
## Update Notes
23/09/21 | An updated ggplot2-compatible EEM plotter, `ggeem2()`, has been added. This function updates the plotting provided by staRdom's ggeem() function, tweaking the graphical parameters and adding an option for intensity value binning via `eem_bin()`. The check_eem() function has been removed, as it is no longer useful.
01/10/21 | `ggeem2()` now has multi-plot support, and inherits staRdom::ggeem()'s class handling.
17/01/22 | Various bug fixes. Gradually removing `extrpf_spectra_or_eems()`, as that workflow and associated functions have already been superseded by other functions in this package.
18/01/22 | Removed `extrpf_spectra_or_eems()`. Functionality provided by the functions `extrpf_peak_spectra()` and `extrpf_eems()`, which are easier to use and have more efficient syntax.
## References
Massicotte, P. (2019). eemR: Tools for Pre-Processing Emission-Excitation-Matrix (EEM) Fluorescence Data. R
package version 1.0.1. https://CRAN.R-project.org/package=eemR
Murphy, K. R. (2011). A Note on Determining the Extent of the Water Raman Peak in Fluorescence Spectroscopy. Applied Spectroscopy, 65(2), 233–236. https://doi.org/10.1366/10-06136
Murphy, K. R., Stedmon, C. A., Graeber, D., & Bro, R. (2013). Fluorescence spectroscopy and multi-way techniques. PARAFAC. _Analytical Methods_, *5*, 6557–6566. doi: [10.1039/C3AY41160E](https://doi.org/10.1039/C3AY41160E)
Pucher, M., Wünsch, U., Weigelhofer, G., Murphy, K., Hein, T., & Graeber, D. (2019). staRdom: Versatile Software for Analyzing Spectroscopic Data of Dissolved Organic Matter in R. _Water_, *11*, 2366. doi: [10.3390/w11112366](https://doi.org/10.3390/w11112366)
Trivittayasil, V. (2016). EEM: Read and Preprocess Fluorescence Excitation-Emission Matrix (EEM) Data. R package
version 1.1.1. https://CRAN.R-project.org/package=EEM