---
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()`.

<a id="fig-plot-spectrum"></a>

```{r fig-plot-spectrum, eval=TRUE}
#| fig.cap: |
#|   <strong>Figure 2.</strong> 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
#|   <code>smit</code>/<code>smws</code> and <code>delta</code> were chosen well
#|   and that the deconvolution was successful.
<<chunk-plot-spectrum>>
```

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

<a id="fig-align"></a>

```{r fig-align, eval=TRUE}
#| fig.cap: |
#|   <strong>Figure 3.</strong> 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])
```

<!-- Footnotes -->
