---
title: "Get Started"
output:
rmarkdown::html_vignette: default
pdf_document:
latex_engine: xelatex
header-includes:
- \usepackage{fontspec}
- \usepackage{etoolbox}
- \usepackage{fvextra}
- \usepackage{needspace}
- \definecolor{shadecolor}{RGB}{232,232,232}
- \fvset{breaklines=true,breakanywhere=true}
- \BeforeBeginEnvironment{Shaded}{\Needspace{10\baselineskip}}
- \BeforeBeginEnvironment{Shaded}{\vspace{0.5em}}
- \DefineVerbatimEnvironment{Highlighting}{Verbatim}{breaklines=true,breakanywhere=true,commandchars=\\\{\}}
- \RecustomVerbatimEnvironment{verbatim}{Verbatim}{breaklines=true,breakanywhere=true}
css: styles.css
vignette: >
%\VignetteIndexEntry{Get Started}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r set-defaults, echo=FALSE, results=FALSE, message=FALSE}
knitr::opts_chunk$set(
fig.dim = c(5, 5), # Size of stored figures in inches
fig.show = "hold", # Render images as inline elements
out.width = "50%", # [^1]
eval = FALSE,
echo = FALSE,
results = FALSE,
message = FALSE
# [^1]: Either out.width or out.height must be set or rmarkdown will
# not put a div.figure around the individual img elements. Furthermore,
# we must not use out.width = "auto" or out.height = "auto", as LaTeX
# cannot handle that.
)
```
This article shows how Metabodecon can be used for deconvoluting and aligning
one-dimensional NMR spectra using the pre-installed [Sim] dataset as an example.
The Sim dataset includes 16 simulated spectra, each with 2048 data points
ranging from ≈ 3.6 to 3.3 ppm. These simulated spectra closely mimic the
resolution and signal strength of real NMR experiments on blood plasma from 16
individuals. The Sim dataset is used instead of the Blood dataset because it is
smaller, faster to process, and comes pre-installed with the package. For more
information on the Sim and Blood datasets, see [Datasets].
[Sim]: https://spang-lab.github.io/metabodeconplus/articles/Datasets.html#sim
[Datasets]: https://spang-lab.github.io/metabodeconplus/articles/Datasets.html
For an overview of the S3 classes used to represent spectra throughout the
package (`spectrum`, `decon2`, `align`, and their collections), see
[`?metabodeconplus-classes`][metabodeconplus-classes].
[metabodeconplus-classes]: https://spang-lab.github.io/metabodeconplus/reference/metabodeconplus-classes.html
# Read spectra
Spectra are read from disk with `read_spectrum()` (single spectrum) or
`read_spectra()` (a whole directory of spectra). Both support the Bruker and
JCAMP-DX formats.
## File structure
`read_spectra()` expects one of the two directory layouts shown below. For
Bruker data, point `data_path` at the folder that *contains* the individual
sample folders; each sample folder holds an experiment number (`expno`, e.g.
`10`) and, under `pdata/`, a processing number (`procno`, e.g. `10`). For
JCAMP-DX data, point `data_path` at the folder containing the `.dx` files.
```txt
C:/bruker/urine # data_path (user input)
├── urine_1/ # sample name (user input)
│ └── 10/ # expno (called spectroscopy_value here)
│ ├── acqus # acquisition parameters (constant)
│ └── pdata/
│ └── 10/ # procno (called processing_value here)
│ ├── 1r # real part of the processed spectrum (constant)
│ └── procs # processing parameters (constant)
├── urine_2/...
└── ...
C:/jcampdx/urine # data_path (user input)
├── urine_1.dx # one .dx file per sample (user input)
├── urine_2.dx
└── ...
```
# Deconvolute spectra
To find the path to the Sim dataset, you can use the `metabodeconplus_file()`
function, which returns the path to any file or directory within the package
directory. To deconvolute the spectra within the Sim dataset you can read
them into R using `read_spectra()` and then call `deconvolute()` as follows:
```{r chunk-deconvolute, echo=TRUE, eval=TRUE}
sim_dir <- metabodeconplus::metabodeconplus_file("bruker/sim")
sim <- metabodeconplus::read_spectra(sim_dir)
deconvoluted_spectra <- metabodeconplus::deconvolute(
sim, # The object containing spectra
sfr = c(3.35, 3.55), # Borders of signal free region (SFR) in ppm
smit = 2, smws = 5, # Smoothing parameters
verbose = FALSE # Disable verbose output
)
```
The provided parameters are used directly for the deconvolution of all
spectra. To verify that the signal-free region was set correctly and to assess
the quality of the deconvolution, use `plot_spectrum()` after the call (see
below).
# Visualize deconvoluted spectra
After completing the deconvolution, it is advisable to visualize the extracted
signals using `plot_spectrum()` to assess the quality of the deconvolution.
```{r chunk-plot-spectrum, echo=TRUE}
# Visualize the first spectrum.
metabodeconplus::plot_spectrum(deconvoluted_spectra[[1]])
# Visualize the second spectrum, this time without the legend.
metabodeconplus::plot_spectrum(deconvoluted_spectra[[1]], lgd = FALSE)
# Visualize all spectra and save them to a pdf file
pdfpath <- tempfile(fileext = ".pdf")
pdf(pdfpath)
for (x in deconvoluted_spectra) {
metabodeconplus::plot_spectrum(x, main = x$filename)
}
dev.off()
cat("Plots saved to", pdfpath, "\n")
```
Out of the 16 generated plots, the first two are shown as examples in [Figure
2](#fig-plot-spectrum). Things to look out for are:
1. That the smoothing does not remove any real signals. If the smoothing is too
strong, i.e., the smoothed signal intensity (SI) is very different from the
raw SI, you should adjust the smoothing parameters `smit` and `smws` in the
call to `deconvolute()`.
2. That the superposition of the lorentz curves is a good approximation of the
smoothed SI. If major peaks are missed by the algorithm, you should reduce
the threshold `delta` in the call to `deconvolute()`.
```{r fig-plot-spectrum, eval=TRUE}
#| fig.cap: |
#| Figure 2. Deconvolution results for the first two spectra
#| of the Sim dataset. The raw SI (black), smoothed SI (blue), and
#| superposition of Lorentz curves (red) are closely aligned, indicating that
#| smit/smws and delta were chosen well
#| and that the deconvolution was successful.
<>
```
# Align deconvoluted spectra
The last step in the Metabodecon Workflow is to align the deconvoluted spectra.
This is necessary because the chemical shifts of the peaks in the spectra may
vary slightly due to differences in the measurement conditions.
To perform the alignment, you can use `align()`. To visualize the data before
and after the alignment, you can use `plot_spectra()`:
```{r chunk-align, echo=TRUE}
# Plot spectra before alignment. Only show spectra 1-8 for clarity.
metabodeconplus::plot_spectra(deconvoluted_spectra[1:8], lgd = FALSE)
# Align spectra and plot again.
aligned_spectra <- metabodeconplus::align(deconvoluted_spectra)
metabodeconplus::plot_spectra(aligned_spectra[1:8])
```
The resulting plots are shown in [Figure 3](#fig-align). Before the alignment,
the spectra exhibit generally similar shapes but do not perfectly overlap. After
the alignment, the spectra are much more consistent with each other, indicating
that the alignment was successful. Notably, spectrum two has been shifted
significantly to the left.
```{r fig-align, eval=TRUE}
#| fig.cap: |
#| Figure 3. Overlay of the first eight deconvoluted spectra
#| from the Sim dataset before alignment (left) and after alignment (right).
#| The x-Axis gives the chemical shift of each datapoint in parts per million
#| (ppm). The y-Axis gives the signal intensity of each datapoint in arbitrary
#| units (au). All specta are pretty similar to each other except for Spectrum
#| 2, which got shifted approx. 0.01 ppm to the right.
# Plot spectra before alignment. Only show spectra 1-8 for clarity.
metabodeconplus::plot_spectra(deconvoluted_spectra[1:8], lgd = FALSE)
# Align spectra and plot again.
aligned_spectra <- metabodeconplus::align(deconvoluted_spectra)
metabodeconplus::plot_spectra(aligned_spectra[1:8])
```