Get Started
In metabodecon: Deconvolution and Alignment of 1d NMR Spectra

knitr::opts_chunk$set(
    fig.dim = c(5, 5), # Size of stored figures in inches
    fig.show = "hold", # Render images as inline elements
    out.height = "auto", # (1)
    eval = FALSE,
    echo = FALSE,
    results = FALSE,
    message = FALSE
    # (1) Either out.width or out.heigt must be set of rmarkdown will not put
    # a div.figure around the individual img elements
)

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.

Deconvolute spectra

To find the path to the Sim dataset, you can use the metabodecon_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:

sim_dir <- metabodecon::metabodecon_file("bruker/sim")
sim <- metabodecon::read_spectra(sim_dir)
deconvoluted_spectra <- metabodecon::deconvolute(
    sim,                 # The object containing spectra
    sfr = c(3.35, 3.55), # Borders of signal free region (SFR) in ppm
    smopts = c(2, 5),    # Smoothing parameters
    verbose = FALSE,     # Disable verbose output
    ask = TRUE           # Enable interactive prompting
)

After calling deconvolute(), the function will ask you to answer the following questions to determine the optimal deconvolution parameters interactively:

Use same parameters for all spectra? (y/n)
Number of spectrum for adjusting parameters? (1: sim_01, 2: sim_02, ...)
Signal free region correctly selected? (y/n)
Water artefact fully inside red vertical lines? (y/n)

You can answer questions one and two with y and 1, as the dataset is homogeneous, i.e., all spectra were measured in the same lab with the same acquisition and processing parameters. However, for heterogeneous datasets, it's advisable to optimize parameters for each batch of spectra individually.

Questions three and four are accompanied by two plots, shown in Figure 1, which help you to verify the accuracy of the selected signal-free region (SFR) and water signal half-width (WSHW) [^wshw]. In this case, the provided parameters are already fine, so you can answer both questions with y. If adjustments are needed, you can respond with n and input the correct values.

#| fig.cap: |
#|    <strong>Figure 1.</strong> The first spectrum  of  the  Sim  dataset.  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).  The  signal  free  regions  are  shown  as  green
#|    rectangles in the left plot. The water signal  region,  usually  shown  as
#|    blue rectangle, is shown in the right plot. Because the water signal  half
#|    width is set to zero in this case, the rectangle collapses to  a  vertical
#|    line.
metabodecon::evalwith(
    answers = list(sameParams = "y", adjNo="1", sfrOk = "y", wsOk = "y"),
    pars = list(mar = c(4, 4, 2, 2)),
    expr = {
        <<chunk-deconvolute>>
    }
)

When using the function in scripts, where interactive user input is not desired, you can disable the interactive prompting by setting parameter ask to FALSE. In this case, the provided parameters will be used for the deconvolution of all spectra automatically. [^askFALSE]

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.

# Visualize the first spectrum.
metabodecon::plot_spectrum(deconvoluted_spectra[[1]])

# Visualize the second spectrum, this time without the legend.
metabodecon::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) {
    metabodecon::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. Things to look out for are:

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 smopts in the call to generate_lorentz_curves().
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 generate_lorentz_curves().

#| 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>smopts</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():

# Plot spectra before alignment. Only show spectra 1-8 for clarity.
metabodecon::plot_spectra(deconvoluted_spectra[1:8], lgd = FALSE)

# Align spectra and plot again.
aligned_spectra <- try(metabodecon::align(deconvoluted_spectra)) # (1)
metabodecon::plot_spectra(aligned_spectra[1:8])

# (1) The call to align() is wrapped in try() because the function may fail
# if speaq's Bioconductor dependencies (MassSpecWavelet, impute) are missing
# and the code runs in a non-interactive R session (e.g., during vignette
# creation). In interactive sessions, try() is not needed, as the user will
# be prompted to install missing dependencies automatically.

The resulting plots are shown in Figure 3. 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.

#| 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.
metabodecon::plot_spectra(deconvoluted_spectra[1:8], lgd = FALSE)

# Align spectra and plot again.
aligned_spectra <- try(
    metabodecon::align(deconvoluted_spectra, install_deps = FALSE)
    # We must wrap the call to align() in try() because the function
    # may fail if speaq's Bioconductor dependencies (MassSpecWavelet,
    # impute) are missing during vignette creation
)
if (!inherits(aligned_spectra, "try-error")) {
    metabodecon::plot_spectra(aligned_spectra[1:8])
}

[^wshw]: Since the used dataset was simulated based on actual measurements in the range of approx. 3.6 to 3.3 ppm, it doesn't contain a water signal. Therefore, the water signal half width was set to zero.

[^askFALSE]: In this case it may be useful to set ask = TRUE for the first run to determine the optimal parameters interactively and then set ask = FALSE for subsequent runs.