Package 'metabodecon'

Description

get_started and aaa_Get_Started both return (and optionally open) the URL of the "Get Started" page of the metabodecon documentation. The aaa_Get_Started version exists, because functions are listed alphabetically in the reference manual and we want get_started to be shown at the top of the list (i.e., it needs to start with an 'a').

Usage

aaa_Get_Started(open_browser = interactive())

get_started(open_browser = interactive())

Arguments

Value

A character string containing the URL of the "Get Started" page.

Author(s)

2024-2025 Tobias Schmidt: initial version.

Examples

get_started(open_browser = FALSE)
get_started()

Description

Align signals across a list of deconvoluted spectra using the 'CluPA' algorithm from the 'speaq' package, described in Beirnaert et al. (2018) https://doi.org/10.1371/journal.pcbi.1006018 and Vu et al. (2011) https://doi.org/10.1186/1471-2105-12-405 plus the additional peak combination described in combine_peaks().

Usage

align(
  x,
  maxShift = 50,
  maxCombine = 0,
  verbose = TRUE,
  method = 2,
  install_deps = NULL,
  nworkers = 1,
  ref = NULL,
  full = TRUE
)

Arguments

Value

An object of type align as described in Metabodecon Classes.

Author(s)

2024-2025 Tobias Schmidt: initial version.

Examples

if (interactive()) {
    # Example requires an interactive R session, because in case of missing
    # dependencies the user will be asked for confirmation to install them.
    decons <- deconvolute(sim[1:2], sfr = c(3.55, 3.35))
    aligned <- align(decons)
}

Description

Convert a object to a Metabodecon object.

Usage

as_spectrum(x, sf = c(1000, 1e+06))

as_decon0(x, sf = NULL, spectrum = NULL, optional = TRUE)

as_decon1(
  x,
  sf = c(1000, 1e+06),
  spectrum = NULL,
  sfr = NULL,
  wshw = NULL,
  bwc = 2
)

as_decon2(
  x,
  sf = c(1000, 1e+06),
  spectrum = NULL,
  sfr = NULL,
  wshw = NULL,
  bwc = 2
)

as_spectra(
  x,
  file_format = "bruker",
  expno = 10,
  procno = 10,
  raw = FALSE,
  silent = TRUE,
  force = FALSE
)

as_decons0(x, sfs = list(c(1000, 1e+06)), spectra = list(NULL), nworkers = 1)

as_decons1(
  x,
  sfs = list(c(1000, 1e+06)),
  spectra = list(NULL),
  sfrs = list(NULL),
  wshws = list(NULL),
  bwc = 2,
  nworkers = 1
)

as_decons2(
  x,
  sfs = list(c(1000, 1e+06)),
  spectra = list(NULL),
  sfrs = list(NULL),
  wshws = list(NULL),
  bwc = 2,
  nworkers = 1
)

Arguments

Value

An object of the specified class.

Author(s)

2024-2025 Tobias Schmidt: initial version.

Examples

dirpath <- metabodecon_file("sim_subset")
spectra <- read_spectra(dirpath)
spectrum <- spectra[[1]]
decons1 <- generate_lorentz_curves_sim(spectra)
decon1 <- generate_lorentz_curves_sim(spectrum)
decon2 <- as_decon2(decon1)

Description

Helper function of plot_lorentz_curves_save_as_png(). Should not be called directly by the user.

Calculates the lorentz curves of each investigated spectrum.

This function has been deprecated with metabodecon version v1.4.3 and will be removed with version 2.0.0.

Usage

calculate_lorentz_curves(deconv_result, number_of_files = NA)

Arguments

Value

If deconv_result holds the result of a single deconvolution, a matrix containing the generated Lorentz curves is returned, where each row depicts one Lorentz curve. If deconv_result is a list of deconvoluted spectra, a list of such matrices is returned.

Author(s)

2020-2021 Martina Haeckl: initial version.
2024-2025 Tobias Schmidt: Minor updates to pass CRAN checks

See Also

MetaboDecon1D(), plot_triplets(), plot_lorentz_curves_save_as_png(), plot_spectrum_superposition_save_as_png()

Examples

## -~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-
## Deconvolute the spectra in folder "bruker/sim_subset" into a list of
## Lorentz Curves (specified via the parameters A, lambda and x_0).
## -~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-
decons <- generate_lorentz_curves_sim(sim[1:2])
decon0 <- decons[[1]]

## -~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-
## Calculate the corresponding y values at each ppm value for each Lorentz
## Curve. I.e. you get a matrix of dimension n x m for each deconvolution,
## where n is the number of Lorentz Curves and m is the number of ppm values.
## -~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-
yy <- calculate_lorentz_curves(decons)
y1 <- yy[[1]]
dim(y1)

## -~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-
## Visualize the 5th, 9th and 11th Lorentz curve.
## -~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-
nrs <- c(5, 9, 11)
col <- c("red", "blue", "orange")
desc <- paste("Lorentz curve", nrs)
plot(decon0$x_values_ppm, decon0$y_values, type = "l", lty = 2)
for (i in 1:3) lines(decon0$x_values_ppm, y1[nrs[i], ], col = col[i])
legend("topright", legend = desc, col = col, lty = 1)

Description

check_mdrb() returns a boolean indicating whether a suitable version of the metabodecon Rust backend mdrb is currently installed.

check_mdrb_deps() returns a list with information about the installation status of mdrb system dependencies.

Usage

check_mdrb(stop_on_fail = FALSE)

check_mdrb_deps(verbose = FALSE)

Arguments

Value

check_mdrb() returns TRUE if a suitable version of mdrb is installed, else FALSE.

check_mdrb_deps() returns a data.frame as follows:

            check           passed  comment
    r       R >= 4.2        TRUE    Current: R 4.4.2
    rtools  Rtools exist    TRUE    Tested with: pkgbuild::has_build_tools()
    cargo   cargo >= 1.80   TRUE    Current: cargo 1.84.1 (66221abde 2024-11-19)
    rustc   rustc >= 1.80   TRUE    Current: rustc 1.84.1 (e71f9a9a9 2025-01-27)

Column check is a string describing the performed check.
Column passed is a boolean indicating whether the check passed.
Column comment is a string string describing the check result.

The rownames of the dataframe one-word descriptions of the performed checks.

Author(s)

2024-2025 Tobias Schmidt: initial version.

Examples

check_mdrb()


# Checking dependencies might take more than 5 seconds, as it
# requires the compilation of a small test program as well as
# running `cargo --version` and `rustc --version`, which,
# depending on your system, might involve updating or installing
# Rust toolchain components.
check_mdrb_deps(verbose = TRUE)

Description

Helper function of align(). Should not be called directly by the user.

Even after calling speaq_align(), the alignment of individual signals is not always perfect, as 'speaq' performs a segment-wise alignment i.e. groups of signals are aligned. For further improvements, partly filled neighboring columns are merged. See 'Details' for an illustrative example.

Direct usage of this function has been deprecated with metabodecon version 1.4.3 and will be removed with metabodecon version 2.0.0.

Usage

combine_peaks(
  shifted_mat,
  range = 5,
  lower_bound = 1,
  spectrum_data = NULL,
  data_path = NULL
)

Arguments

Details

Example of what the function does:

|            | 1    | 2    | 3    | 4    | 5    |
|----------- |------|------|------|------|------|
| Spectrum 1 | 0.13 | 0    | 0    | 0.11 | 0    |
| Spectrum 2 | 0    | 0.88 | 0    | 0.12 | 0    |
| Spectrum 3 | 0.07 | 0.56 | 0.30 | 0    | 0    |
| Spectrum 4 | 0.08 | 0    | 0.07 | 0    | 0.07 |
| Spectrum 5 | 0.04 | 0    | 0    | 0.04 | 0    |

becomes

|            | 1    | 2    | 3    | 4    | 5    |
|----------- |------|------|------|------|------|
| Spectrum 1 | 0.13 | 0    | 0    | 0.11 | 0    |
| Spectrum 2 | 0    | 0.88 | 0    | 0.12 | 0    |
| Spectrum 3 | 0.07 | 0.56 | 0    | 0.30 | 0    |
| Spectrum 4 | 0.08 | 0    | 0    | 0.07 | 0.07 |
| Spectrum 5 | 0.04 | 0    | 0    | 0.04 | 0    |

I.e.

1. Column 1 and 2 get NOT merged, because they have a common non-zero entry.

2. Column 3 and 4 get merged, because they are in range of each other and have no common non-zero entries.

3. Column 4 and 5 get NOT merged, because it is more beneficial to merge column 3 and 4, as they have more mergeable entries and after merging column 3 and 4, column 4 and 5 have a common non-zero entry.

Value

A list containing two data frames long and short. The first data frame contains one column for each data point in the original spectrum. The second data frame contains only columns where at least one entry is non-zero.

Author(s)

2021-2024 Wolfram Gronwald: initial version.
2024-2025 Tobias Schmidt: refactored initial version.

Examples

deps <- c("MassSpecWavelet", "impute")
deps_installed <- sapply(deps, requireNamespace, quietly = TRUE)
if (all(deps_installed)) {
    # 'speaq' requires 'MassSpecWavelet' and 'impute' to be installed
    sim_subset <- metabodecon_file("bruker/sim_subset")
    spectrum_data <- generate_lorentz_curves_sim(sim_subset)
    shifted_mat <- speaq_align(spectrum_data = spectrum_data, verbose = FALSE)
    range <- 5
    lower_bound <- 1
    obj <- combine_peaks(shifted_mat, range, lower_bound)
    str(obj)
}

Description

Converts positions/widths from unit A to unit B. If the direction of units A and B is reversed, the width's sign will be reversed as well. To keep widths strictly positive, wrap the result with abs().

Usage

convert_pos(xa, ya, yb)

convert_width(xa, ya, yb)

Arguments

Value

A numeric vector of values converted from unit A to unit B.

Author(s)

2024-2025 Tobias Schmidt: initial version.

Examples

ya <- c(244, 246, 248, 250, 252)
yb <- c(15, 10, 5, 0, -5)
convert_width(c(2, 4, 8), ya, yb)
convert_pos(c(247, 249), ya, yb)

Description

Returns the path to the directory where download_example_datasets() stores metabodecon's example data sets or any file within that directory. By default this directory is a subdirectory of R's temporary session directory. If persistent is set to TRUE, the directory equals the data directory returned by tools::R_user_dir() instead.

Usage

datadir(file = NULL, warn = TRUE, persistent = NULL)

Arguments

Details

The decision to use a temporary data dir as default and a persistent one only optionally was made to conform to CRAN package policies, which state that:

Packages should not write in the user's home filespace (including clipboards), nor anywhere else on the file system apart from the R session's temporary directory [...] Limited exceptions may be allowed in interactive sessions if the package obtains confirmation from the user. For R version 4.0 or later [...] packages may store user-specific data, configuration and cache files in their respective user directories obtained from tools::R_user_dir() [...].

Source: cran.r-project.org/web/packages/policies.

Value

Path to the data directory or a file within it.

Author(s)

2024-2025 Tobias Schmidt: initial version.

See Also

download_example_datasets(), datadir_persistent(), datadir_temp()

Examples

# Get temporary datadir and persistent datadir
datadir(persistent = FALSE, warn = FALSE)
datadir(persistent = TRUE,  warn = FALSE)

# Get persistent datadir if existing else temp datadir. Set `warn = TRUE`
# to raise a warning if none of the directories exist yet.
datadir(warn = FALSE)
if (interactive()) datadir()

# Get PERSISTENT_DATADIR/bruker if existing else TEMP_DATADIR/bruker
datadir(file = "bruker/urine", warn = FALSE)

Description

Returns the path to the persistent data directory where metabodecon's data sets are stored. This directory equals the data directory returned by tools::R_user_dir() plus additional path normalization.

Usage

datadir_persistent()

Value

Path to the persistent data directory.

Author(s)

2024-2025 Tobias Schmidt: initial version.

See Also

datadir(), datadir_temp()

Examples

datadir_persistent()

Description

Returns the path to the temporary data directory where metabodecon's data sets are stored. This directory equals subdirectory 'data' of metabodecons temporary session directory tmpdir() plus additional path normalization.

Usage

datadir_temp()

Value

Returns the path to the temporary data directory.

Author(s)

2024-2025 Tobias Schmidt: initial version.

See Also

tmpdir(), datadir(), datadir_persistent()

Examples

datadir_temp()

Description

Returns the temporary session-scoped cache directory used by deconvolution functions such as deconvolute() and the internal grid_deconvolute_spectrum() helper.

Usage

decon_cachedir()

Value

Path to the shared temporary cache directory for deconvolution.

Author(s)

2026 Tobias Schmidt: initial version.

Examples

decon_cachedir()

Description

Deconvolutes NMR spectra by modeling each detected signal within a spectrum as Lorentz Curve.

Usage

deconvolute(
  x,
  nfit = 3,
  smopts = c(2, 5),
  delta = 6.4,
  sfr = NULL,
  wshw = 0,
  ask = FALSE,
  force = FALSE,
  verbose = TRUE,
  nworkers = 1,
  use_rust = FALSE,
  npmax = 0,
  igrs = list(),
  cadir = decon_cachedir()
)

Arguments

Details

First, an automated curvature based signal selection is performed. Each signal is represented by 3 data points to allow the determination of initial Lorentz curves. These Lorentz curves are then iteratively adjusted to optimally approximate the measured spectrum.

Value

A 'decon2' object as described in Metabodecon Classes.

Author(s)

2024-2025 Tobias Schmidt: initial version.

Examples

## Deconvolute a single spectrum
spectrum <- sim[[1]]
decon <- deconvolute(spectrum)

## Read multiple spectra from disk and deconvolute at once
spectra_dir <- metabodecon_file("sim_subset")
spectra <- read_spectra(spectra_dir)
decons <- deconvolute(spectra, sfr = c(3.55, 3.35))

Description

Helper function of align(). Should not be called directly by the user.

Rewrite of speaq::dohCluster(), compatible with the data format returned by 'generate_lorentz_curves()' and 'gen_feat_mat()'. The function name "dohCluster" comes from "Do Hierarchical Clustering" which is part of the Alignment algorithm proposed by Vu et al. (2011) in https://doi.org/10.1186/1471-2105-12-405.

Direct usage of this function has been deprecated with metabodecon version 1.4.3 and will be removed with metabodecon version 2.0.0.

Usage

dohCluster(X, peakList, refInd = 0, maxShift = 100, verbose = TRUE, method = 2)

Arguments

Value

A list containing two data frames Y and new_peakList. The first one contains the aligned spectra, the second one contains the aligned signals of each spectrum.

Author(s)

2021-2024 Wolfram Gronwald: initial version.
2024-2025 Tobias Schmidt: refactored initial version.

Examples

deps <- c("MassSpecWavelet", "impute")
deps_installed <- sapply(deps, requireNamespace, quietly = TRUE)
if (all(deps_installed)) {
    # 'speaq' requires 'MassSpecWavelet' and 'impute' to be installed
    sim_subset <- metabodecon_file("bruker/sim_subset")
    decons <- generate_lorentz_curves_sim(sim_subset)
    feat <- gen_feat_mat(decons)
    refObj <- speaq::findRef(feat$peakList)
    hclObj <- dohCluster(
        X = feat$data_matrix,
        peakList = feat$peakList,
        refInd = refObj$refInd,
        maxShift = 100,
        verbose = TRUE
    )
    str(hclObj, 1)
}

Description

Downloads example datasets that can be used to test the functionality of the metabodecon package. These datasets are not included in the package by default due to size constraints. The datasets are downloaded as zip file and extracted automatically, unless extraction is disabled by the user.

Usage

download_example_datasets(
  dst_dir = NULL,
  extract = TRUE,
  persistent = NULL,
  overwrite = FALSE,
  silent = FALSE
)

Arguments

Value

The path to the downloaded (and possibly extracted) datasets.

Author(s)

2024-2025 Tobias Schmidt: initial version.

See Also

datadir()

Examples

if (interactive()) {
     zip <- download_example_datasets(extract = FALSE, persistent = FALSE)
     dir <- download_example_datasets(extract = TRUE)
}

Description

Draws a single spectrum. Internally used by plot_spectrum(), which is usually the recommended way to plot spectra. For usage examples see test/testthat/test-draw_spectrum.R.

Usage

draw_spectrum(
  obj,
  foc_rgn = NULL,
  foc_frac = NULL,
  foc_only = TRUE,
  add = FALSE,
  fig_rgn = NULL,
  main = NULL,
  show = TRUE,
  show_d2 = FALSE,
  truepar = NULL,
  mar = c(4.1, 5.1, 1.1, 1.1),
  sf_vert = "auto",
  si_line = list(),
  sm_line = list(),
  sp_line = list(),
  d2_line = list(),
  al_line = list(),
  lc_lines = list(),
  tp_lines = list(),
  al_lines = list(),
  cent_pts = list(),
  bord_pts = list(),
  norm_pts = list(),
  tp_pts = list(),
  fp_pts = list(),
  miss_pts = list(),
  bg_rect = list(),
  foc_rect = list(),
  lc_rects = list(),
  tp_rects = list(),
  bt_axis = list(),
  lt_axis = list(),
  tp_axis = list(),
  rt_axis = list(),
  bt_text = list(),
  lt_text = list(),
  tp_text = list(),
  rt_text = list(),
  tp_verts = list(),
  lc_verts = list(),
  al_verts = list(),
  ze_hline = list(),
  al_arrows = list(),
  lgd = list()
)

Arguments

Details

Parameters bt_axis, lt_axis, tp_axis and rt_axis all support option n and digits, where n = 5 means "Draw 5 tickmarks over the full axis range" and digits = 3 means "round the label shown beside each tickmark to 3 digits". If n or digits is omitted, a suitable value is chosen automatically. Providing a vector of digits causes each digit to be tried until a digit is encountered that results in n unique labels. Example:

Assume we have n = 4 and the corresponding calculated tickmark positions are: 1.02421, 1.02542, 1.02663 and 1.02784. If we provide digits = 1:5, the following representations are tried:

In the above example the process would stop at digit = 3, because at this point we have n = 4 unique labels (1.024, 1.025, 1.027 and 1.028).

Value

NULL. Called for side effect of plotting.

Author(s)

2024-2025 Tobias Schmidt: initial version.

Examples

decon <- deconvolute(sim[[1]], sfr = c(3.55, 3.35))
draw_spectrum(obj = decon)
draw_spectrum(obj = decon, lgd = list(x = "top", bg = NA))
draw_spectrum(obj = decon, foc_rgn = c(3.45, 3.37))
draw_spectrum(obj = decon, add = FALSE, lgd = FALSE,
              fig = c(.2, .8, .2, .4), mar = c( 0,  0,  0,  0))
draw_spectrum(obj = decon, add = TRUE, lgd = FALSE,
              fig = c(0.2, 0.8, 0.6, 0.8), mar = c(0, 0, 0, 0))
draw_spectrum(obj = decon, lc_lines = NULL, lc_rects = NULL, foc_only = FALSE)

Description

Evaluates an expression with a predefined global state, including the:

• working directory (set via setwd())

• global options (set via options())

• graphical parameters (set via par())

In addition to that, evalwith allows to:

• Redirect or capture the output and/or message stream via sink()

• Measure the runtime of the evaluated expression via system.time()

• Creating a temporary test directory (inside tmpdir()) and populating it with input files according to inputs

• Predefine answers for calls to readline() happening during evaluation of expr

• Caching the result of the expression

All changes to the global state are reverted after the expression has been evaluated.

Usage

evalwith(
  expr,
  testdir = NULL,
  answers = NULL,
  output = NULL,
  message = NULL,
  plot = NULL,
  datadir_temp = c("default", "missing", "empty", "filled")[1],
  datadir_persistent = c("default", "missing", "empty", "filled")[1],
  inputs = character(),
  opts = NULL,
  pars = NULL,
  cache = FALSE,
  overwrite = FALSE
)

Arguments

Details

The datadir_temp and datadir_persistent arguments accept values "missing", "filled" and "empty". Setting a value unequal NULL causes the functions datadir_temp() and/or datadir_persistent() to be replaced with mock functions pointing to fake directories. Functions depending on these functions will then use the fake directories instead of the real ones. When set to "missing" the returned mock directory does not exist. When set to "empty" it exists and is guaranteed to be empty. When set to "filled", it is populated with example datasets.

Attention: the mocked functions, i.e. datadir_temp() and datadir_persistent() cannot be used directly inside expr when called via devtools::test(). I'm not sure why, but it seems as if devtools and/or testthat have their own copies of the functions which are used when the expression is evaluated.

Value

A list containing with following elements:

• rv: The return value of the expression.

• runtime: The "elapsed" runtime of the expression in seconds. Measured with system.time().

• output: The captured output.

• message: The captured messages.

• plot: The path to the saved plot.

• testdir: The path to the test directory.

• inputs: The paths to the copied input files.

Author(s)

2024-2025 Tobias Schmidt: initial version.

Examples

x1 <- evalwith(output = "captured", cat("Helloworld\n"))
str(x1)

x2 <- evalwith(datadir_persistent = "missing", message = "captured", datadir())
str(x2)

x3 <- evalwith(testdir = "dummy", inputs = "bruker/urine/urine_1", dir())
str(x3)

x4 <- evalwith(Sys.sleep(0.02))
str(x4)

Description

Helper function of align(). Should not be called directly by the user.

Generates a list of elements required by speaq_align(). See 'Value' for a detailed description of the list elements.

Direct usage of this function has been deprecated with metabodecon version 1.4.3 and will be removed with metabodecon version 2.0.0.

Usage

gen_feat_mat(
  data_path,
  ppm_range = get_ppm_range(data_path),
  si_size_real_spectrum = length(data_path$y_values),
  scale_factor_x = 1000,
  warn = TRUE
)

Arguments

Details

Before version 1.2 of metabodecon, the deconvolution functions generate_lorentz_curves and MetaboDecon1D wrote their output partially as txt files to their input folder. Back then, gen_feat_mat() used those txt files as input to generate the feature matrix. Since version 1.2 these txt files are no longer created by default, to prevent accidental modifications of the input folders. Therefore, the recommended way to pass the required information to gen_feat_mat() is to directly pass the output of generate_lorentz_curves() to gen_feat_mat(). However, to stay backwards compatible, the name of parameter data_path was not changed and passing an actual path to data_path is still possible, but will result in a warning (unless warn is set to FALSE).

Value

A list with the following elements:

data_matrix: A data.frame where each row corresponds to one spectrum and each column to one data point, i.e. for 10 input spectra with 131072 data points each data_matrix would have dimensions 10 x 131072.

peakList: A list of vectors, where each vector contains the indices of the peaks in the corresponding spectrum. The indices increase from left to right, i.e. the smallest index corresponds to the highest ppm value, as the ppm values decrease from left to right.

w: A list of vectors where each vector contains the "position parameter" of the peaks in the corresponding spectrum.

A: A list of vectors where each vector contains the "area parameter" of the peaks in the corresponding spectrum.

lambda: A list of vectors where each vector contains the "width parameter" of the peaks in the corresponding spectrum.

Author(s)

2021-2024 Wolfram Gronwald: initial version.
2024-2025 Tobias Schmidt: refactored initial version.

Examples

sim_subset <- metabodecon_file("sim_subset")
decons <- generate_lorentz_curves_sim(sim_subset)
obj <- gen_feat_mat(decons)
str(obj, 2, give.attr = FALSE)

Description

Deconvolutes NMR spectra by modeling each detected signal within a spectrum as Lorentz Curve.

This function has been deprecated with metabodecon version v1.4.3 and will be removed with version 2.0.0. Please use deconvolute() instead.

Usage

generate_lorentz_curves(
  data_path,
  file_format = "bruker",
  make_rds = FALSE,
  expno = 10,
  procno = 10,
  raw = TRUE,
  nfit = 10,
  smopts = c(2, 5),
  delta = 6.4,
  sfr = c(11.44494, -1.8828),
  wshw = 0.1527692,
  ask = TRUE,
  force = FALSE,
  verbose = TRUE,
  nworkers = 1
)

generate_lorentz_curves_sim(
  data_path,
  file_format = "bruker",
  make_rds = FALSE,
  expno = 10,
  procno = 10,
  raw = TRUE,
  nfit = 10,
  smopts = c(2, 5),
  delta = 6.4,
  sfr = c(3.55, 3.35),
  wshw = 0,
  ask = FALSE,
  force = FALSE,
  verbose = FALSE,
  nworkers = 1
)

Arguments

Details

First, an automated curvature based signal selection is performed. Each signal is represented by 3 data points to allow the determination of initial Lorentz curves. These Lorentz curves are then iteratively adjusted to optimally approximate the measured spectrum.

generate_lorentz_curves_sim() is identical to generate_lorentz_curves() except for the defaults, which are optimized for deconvoluting the 'sim' dataset, shipped with 'metabodecon'. The 'sim' dataset is a simulated dataset, which is much smaller than a real NMR spectra and lacks a water signal. This makes it ideal for use in examples. However, the default values for sfr, wshw, and delta in the "normal" generate_lorentz_curves() function are not optimal for this dataset. To avoid having to define the optimal parameters repeatedly in examples, this function is provided to deconvolute the "Sim" dataset with suitable parameters.

Value

A 'decon1' object if a single spectrum was provided. A 'decons1' object if multiple spectra were provided. See Metabodecon Classes for details.

Author(s)

2024-2025 Tobias Schmidt: initial version.

Examples

## Define the paths to the example datasets we want to deconvolute:
## `sim_dir`: directory containing 16 simulated spectra
## `sim_01`: path to the first spectrum in the `sim` directory
## `sim_01_spec`: the first spectrum in the `sim` directory as a dataframe

sim_dir        <- metabodecon_file("sim_subset")
sim_1_dir      <- file.path(sim_dir, "sim_01")
sim_2_dir      <- file.path(sim_dir, "sim_02")
sim_1_spectrum <- read_spectrum(sim_1_dir)
sim_2_spectrum <- read_spectrum(sim_2_dir)
sim_spectra    <- read_spectra(sim_dir)


## Show that `generate_lorentz_curves()` and `generate_lorentz_curves_sim()`
## produce the same results:

sim_1_decon0 <- generate_lorentz_curves(
    data_path = sim_1_dir, # Path to directory containing spectra
    sfr = c(3.55, 3.35),   # Borders of signal free region (SFR) in ppm
    wshw = 0,              # Half width of water signal (WS) in ppm
    ask = FALSE,           # Don't ask for user input
    verbose = FALSE        # Suppress status messages
)
sim_1_decon1 <- generate_lorentz_curves_sim(sim_1_dir)
stopifnot(all.equal(sim_1_decon0, sim_1_decon1))


## Show that passing a spectrum produces the same results as passing the
## the corresponding directory:

decon_from_spectrum_dir <- generate_lorentz_curves_sim(sim_1_dir)
decon_from_spectrum_obj <- generate_lorentz_curves_sim(sim_1_spectrum)
decons_from_spectra_obj <- generate_lorentz_curves_sim(sim_spectra)
decons_from_spectra_dir <- generate_lorentz_curves_sim(sim_dir)

most.equal <- function(x1, x2) {
    ignore <- which(names(x1) %in% c("number_of_files", "filename"))
    equal <- all.equal(x1[-ignore], x2[-ignore])
    invisible(stopifnot(isTRUE(equal)))
}

all.equal(  decon_from_spectrum_dir, decon_from_spectrum_obj     )
all.equal(  decons_from_spectra_dir, decons_from_spectra_obj     )
most.equal( decon_from_spectrum_dir, decons_from_spectra_obj[[1]])
most.equal( decon_from_spectrum_dir, decons_from_spectra_dir[[1]])

Description

Returns the path to the directory storing the example files shipped with metabodecon.

Deprecated since metabodecon v1.2.0. Please use datadir() instead. See examples below for usage.

Usage

get_data_dir(
  dataset_name = c("", "blood", "test", "urine", "aki"),
  warn = TRUE
)

Arguments

Value

Path to the directory storing the example files.

Author(s)

2024-2025 Tobias Schmidt: initial version.

See Also

download_example_datasets()

Examples

x <- get_data_dir("urine")                     # Deprecated
y <- datadir("example_datasets/bruker/urine")  # Preferred
cat(x, y, sep = "\n")

Description

Returns the names of a metabodecon collection object.

Usage

get_names(x, default = "spectrum_%d")

Arguments

Value

A character vector of names.

Author(s)

2024-2025 Tobias Schmidt: initial version.

Examples

s1 <- list()
s2 <- list(name = "foo")
s3 <- list(name = "foo", meta = list(name = "bar"))

get_names(list(s1, s1)) # c("spectrum_1", "spectrum_2")
get_names(list(s1, myspec = s1)) # c("spectrum_1", "myspec")
get_names(list(s1, myspec = s2)) # c("spectrum_1", "foo")
get_names(list(s1, myspec = s3)) # c("spectrum_1", "bar")

Description

Helper function of align(). Should not be called directly by the user.

Returns the ppm range across all peaks of the provided deconvoluted spectra.

Direct usage of this function has been deprecated with metabodecon version 1.4.3 and will be removed with metabodecon version 2.0.0.

Usage

get_ppm_range(spectrum_data, full_range = FALSE)

Arguments

Value

A vector containing the lowest and highest ppm value over all peaks of the provided deconvoluted spectra.

Author(s)

2021-2024 Wolfram Gronwald: initial version.
2024-2025 Tobias Schmidt: refactored initial version.

Examples

spectrum_data <- generate_lorentz_curves(
    data_path = sim[1:2],
    nfit = 3,
    sfr = c(3.55, 3.35),
    wshw = 0,
    ask = FALSE,
    verbose = FALSE
)
ppm_rng <- get_ppm_range(spectrum_data)
print(ppm_rng)

Description

Extracts a peak-area matrix from aligned spectra. Rows are chemical-shift positions, columns are spectra. When maxCombine = 0 the raw aligned integral vectors are returned. When maxCombine > 0, peaks are combined using one of two methods controlled by combineMethod.

Usage

get_si_mat(x, ref = NULL, drop_zero = FALSE, maxCombine = 0, combineMethod = 2)

Arguments

Details

Method 1 (combineMethod = 1) passes the transposed integral matrix to combine_peaks() with range = maxCombine. Partly-filled neighbouring columns are merged when they share no common non-zero row.

Method 2 (combineMethod = 2) maps every peak to the nearest reference peak and keeps it only if the distance is at most maxCombine datapoints. Areas of peaks that map to the same reference peak are summed.

Example for method 2 with ref peaks at indices 5, 9, 20 and maxCombine = 4:

Step 1 – Build intervals [ref ± maxCombine]:

  ref:     5              9                    20
           |              |                     |
  int:  [1 ····· 9]   [5 ···· 13]        [16 ···· 24]
            overlap!

Step 2 – Shrink overlapping neighbours to midpoint.
         Refs 1 & 2 overlap → mid = floor((5+9)/2) = 7.
         Refs 2 & 3 don't  → keep maxCombine boundary.

  ref:     5         9                         20
           |         |                          |
  int:  [1 ··· 7] [8 ·· 13]   gap        [16 ···· 24]

Step 3 – Assign peaks to nearest ref; keep if ≤ maxCombine:

  | Peak | Nearest | Dist | ≤ 4? | Action |
  |------|---------|------|------|--------|
  |    3 | ref 1   |    2 | yes  | keep   |
  |    6 | ref 1   |    1 | yes  | keep   |
  |    8 | ref 2   |    1 | yes  | keep   |
  |   11 | ref 2   |    2 | yes  | keep   |
  |   15 | ref 3   |    5 | no   | DROP   |
  |   21 | ref 3   |    1 | yes  | keep   |

Step 4 – Sum areas (A × pi) per reference peak:

  ref 1 ← A(3) + A(6)    (peaks at 3, 6)
  ref 2 ← A(8) + A(11)   (peaks at 8, 11)
  ref 3 ← A(21)          (peak 15 dropped)

Value

A numeric matrix with chemical shifts as rownames and spectrum names as colnames.

Author(s)

2024-2025 Tobias Schmidt: initial version.

Examples

if (interactive()) {
    decons <- deconvolute(sim[1:2], sfr = c(3.55, 3.35))
    aligns <- align(decons, maxCombine = 0)
    si_mat_0 <- get_si_mat(aligns)
    si_mat_1 <- get_si_mat(aligns, maxCombine = 20)
    si_mat_2 <- get_si_mat(aligns, maxCombine = 20, combineMethod = 1)
}

Description

Returns the first and last n rows of a matrix or data frame. If the input has fewer than 2*n rows, overlapping rows are returned only once.

Usage

headtail(x, n = 6)

Arguments

Value

A subset of x containing head and tail rows.

Author(s)

2024-2026 Tobias Schmidt: initial version.

Examples

x <- matrix(seq_len(30), nrow = 10)
headtail(x, n = 2)

Description

Installs metabodecon's Rust backend mdrb from R-Universe.

lifecycle::badge("experimental")

Usage

install_mdrb(ask = TRUE, ...)

Arguments

Value

NULL. Called for side effect of installing the Rust backend.

Author(s)

2024-2025 Tobias Schmidt: initial version.

Examples

if (interactive()) try(install_mdrb())

Description

Check if an object is an instance of a specific 'Metabodecon Class'. See Metabodecon Classes for a list of classes.

Usage

is_spectrum(x, check_class = TRUE, check_contents = FALSE)

is_decon0(x)

is_decon1(x)

is_decon2(x)

is_align(x)

is_spectra(
  x,
  check_class = TRUE,
  check_contents = FALSE,
  check_child_classes = FALSE
)

is_decons0(x)

is_decons1(x)

is_decons2(x)

is_aligns(x)

Arguments

Value

TRUE if the object is an instance of the specified class, otherwise FALSE.

Author(s)

2024-2025 Tobias Schmidt: initial version.

Examples

ss <- sim[1:2]
s1 <- sim[[1]]
is_spectra(ss) # TRUE
is_spectrum(s1) # TRUE
is_spectrum(s1, check_contents = TRUE) # TRUE

dd <- deconvolute(ss, sfr = c(3.55, 3.35))
d1 <- dd[[1]]
is_decons0(dd) # FALSE
is_decons1(dd) # FALSE
is_decons2(dd) # TRUE
is_decon0(d1) # FALSE
is_decon1(d1) # FALSE
is_decon2(d1) # TRUE

if (interactive()) {
    # Example requires an interactive R session, because in case of missing
    # dependencies the user will be asked for confirmation to install them.
    aa <- align(dd)
    a1 <- aa[[1]]
    is_align(a1) # TRUE
    is_aligns(aa) # TRUE
}

Description

Creates a spectrum object from the provided signal intensities, frequencies and chemical shifts.

Usage

make_spectrum(
  si,
  cs_max,
  cs_width,
  fq_ref,
  fq_width = NULL,
  force = FALSE,
  silent = FALSE,
  name = NULL,
  path = NULL,
  type = NULL,
  simpar = NULL,
  mfs = NULL
)

Arguments

Value

A spectrum object as described in Metabodecon Classes.

Author(s)

2024-2025 Tobias Schmidt: initial version.

Examples

si <- c(1, 1, 3, 7, 8, 3, 8, 5, 2, 1)
cs_max <- 14.8
cs_width <- 20.0
fq_ref <- 600.25 * 1e6
fq_width <- 12005
spectrum <- make_spectrum(si, cs_max, cs_width, fq_ref, fq_width)
spectrum2 <- make_spectrum(si, cs_max, cs_width, fq_ref, fq_width = 12010, force = FALSE)

Description

WARNING: These functions are experimental and must not be used in production. Their API is very likely to change in non-backwards-compatible ways over the next few weeks.

Utilities for fitting, tuning and benchmarking 'metabodecon models' (mdm).

A mdm is a essentially a glmnet lasso model, fitted on a feature matrix X, obtained by deconvoluting and aligning spectra and snapping their peaks to a shared reference spectrum. Lambda is chosen via cross-validation on X. Deconvolution parameters (npmax or nfit/smit/smws/delta), alignment parameter maxShift, and peak-combining parameters (maxCombine, combineMethod) are tunable hyperparameters.

When npmax > 0, deconvolution runs an internal grid search over smoothing and fitting parameters and keeps at most npmax peaks. The explicit nfit/smit/smws/delta values are ignored in that case. When npmax == 0, the explicit parameters are used directly.

fit_mdm() deconvolutes spectra, aligns detected peaks, combines them via get_si_mat() and fits one lasso model via glmnet::cv.glmnet(). Lambda is selected internally by cross-validation but no performance metrics are reported. Use cv_mdm() to tune preprocessing parameters and benchmark_mdm() for unbiased performance estimates.

cv_mdm() evaluates a grid of preprocessing parameter combinations. For each grid row it builds a feature matrix, runs glmnet::cv.glmnet() with a fixed fold assignment, and records the held-out accuracy and AUC at lambda.min. Returns the model with the best AUC and the full performance grid.

benchmark_mdm() wraps cv_mdm() in an outer cross-validation loop to estimate end-to-end predictive performance. It returns the per-fold models and held-out predictions.

Usage

fit_mdm(
  spectra,
  y,
  sfr = NULL,
  use_rust = TRUE,
  nworkers = 1,
  verbosity = 2,
  seed = 1,
  cadir = decon_cachedir(),
  check = TRUE,
  npmax = 1000,
  nfit = 5,
  smit = 2,
  smws = 5,
  delta = 6.4,
  maxShift = 200,
  maxCombine = 50,
  combineMethod = 2,
  nfolds = 10
)

cv_mdm(
  spectra,
  y,
  sfr = NULL,
  use_rust = TRUE,
  nworkers = 1,
  verbosity = 2,
  seed = 1,
  cadir = decon_cachedir(),
  check = TRUE,
  combineMethod = 2,
  pgrid = get_pgrid("dynamic2"),
  ignore = NULL,
  warm_cache = TRUE,
  nfolds = 10
)

benchmark_mdm(
  spectra,
  y,
  sfr = NULL,
  use_rust = TRUE,
  verbosity = 2,
  seed = 1,
  cadir = decon_cachedir(),
  nwo = 1,
  nwi = half_cores(),
  combineMethod = 2,
  pgrid = get_pgrid(),
  nfo = 5,
  nfl = 10
)

get_pgrid(conf = "dynamic2")

Arguments

Details

Disk caching across processes

cv_mdm() and benchmark_mdm() can share deconvolution results through directory cadir. This on-disk cache lets parallel workers reuse expensive preprocessing results while keeping RAM use manageable. Disk caching can be disabled by setting cadir = NULL, but this will increase runtime drastically (from a few minutes/hours to several days).

RAM caching within processes

fit_mdm() caches the most recent deconvolution and alignment results in RAM when the input spectra carries a "hash" attribute. This avoids redundant preprocessing when cv_mdm() evaluates several settings on the same spectra.

Memory usage by parallel workers

Each outer worker in benchmark_mdm() keeps its own copy of spectra and y, so memory use grows roughly with nwo. Large nwo values can therefore require substantial RAM for large input datasets.

Inner workers (nwi) are used inside each outer worker for deconvolution, alignment and prediction on held-out spectra. They process only the spectra needed for the current task, so their memory impact is much smaller. In RAM-constrained settings, use nwo = 1 and increase nwi instead.

The total amount of processes spawned is nwo * nwi.

Value

fit_mdm() returns an object of class mdm with elements model (a glmnet::cv.glmnet() object), ref (the reference alignment spectrum) and meta (list of preprocessing parameters).

cv_mdm() returns an mdm object with an additional element pgrid containing the performance grid.

benchmark_mdm() returns a list with elements:

• models: List of mdm objects, one per outer fold.

• predictions: Data frame with columns fold, true, link, prob, pred.

Examples

## Not run: 



     # -~-~-~ Inputs -~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-

     aki <- read_aki_data()
     spectra <- aki$spectra
     attr(spectra, "hash") <- rlang::hash(spectra)
     y <- factor(aki$meta$type, levels = c("Control", "AKI"))
     names(y) <- rownames(aki$meta)
     sfr <- c(11, -2)
     cadir <- cachedir("deconvs", persistent = TRUE)



     # -~-~-~-~-~-~-~-~-~ Single -~-~-~-~-~-~-~-~-~

     # Best "simple" model from aki.R (0.797 [0.75 - 0.83])
     mdm <- fit_mdm(
         spectra, y, sfr=NULL,
         nfit=5, smit=3, smws=3, delta=3, npmax=0,
         maxShift=128, maxCombine=256, combineMethod=1,
         nworkers=half_cores(), cadir=cadir
     )

     mdm <- fit_mdm(
         spectra, y, sfr = NULL,
         nfit=5, smit=0, smws=0, delta=0, npmax=1000,
         maxShift=64, maxCombine=16, combineMethod=1,
         nworkers=half_cores(), cadir=cadir
     )



     # -~-~-~-~-~-~-~-~-~ Search -~-~-~-~-~-~-~-~-~

     mdm_grid_stat1 <- cv_mdm(
         spectra, y, pgrid=get_pgrid("static1"),
         nworkers=half_cores(), use_rust=TRUE, cadir=cadir
     )
     saveRDS(mdm_grid_stat1, "tmp/mdm_grid_stat1.rds")


     mdm_grid_stat2 <- cv_mdm(
         spectra, y, pgrid=get_pgrid("static2"),
         nworkers=half_cores(), use_rust=TRUE, cadir=cadir
     )
     saveRDS(mdm_grid_stat2, "tmp/mdm_grid_stat2.rds")
     #
     # Best static2: acc=0.82, auc=0.89
     # smit=2, smws=3, delta=6, nfit=7, npmax=0, maxShift=100, maxCombine=30


     mdm_grid_stat3 <- cv_mdm(
         spectra, y, pgrid=get_pgrid("static3"),
         nworkers=half_cores(), use_rust=TRUE, cadir=cadir
     )
     saveRDS(mdm_grid_stat3, "tmp/mdm_grid_stat3.rds")
     #
     # Best static3: acc=79.34% auc=0.8589
     # smit=2, smws=7, delta=8, nfit=10, npmax=0, maxShift=100, maxCombine=30


     mdm_grid_dyn2 <- cv_mdm(
         spectra, y, pgrid=get_pgrid("dynamic2"),
         nworkers=half_cores(), use_rust=TRUE, cadir=cadir
     )

     # -~-~-~ Full Benchmark -~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-
     bm <- benchmark_mdm(spectra, y, sfr, cadir=cadir)

     # -~-~-~ Interactive Development -~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~
     stub(fit_mdm, spectra=spectra, y=y, sfr=sfr)
     stub(cv_mdm, spectra=spectra, y=y, sfr=sfr)
     stub(benchmark_mdm, spectra=spectra, y=y, sfr=sfr)

## End(Not run)

Description

WARNING: These methods are experimental and must not be used in production. Their API is very likely to change in non-backwards-compatible ways over the next few weeks.

S3 methods for objects of class mdm and summary.mdm.

predict.mdm() predicts probabilities, classes, link scores, or all three from an mdm object. When newdata is a spectra object, the spectra are deconvoluted, aligned and snapped to the reference stored in the model before prediction. When newdata is a numeric matrix, it is used directly as the feature matrix.

print.mdm() prints a compact model summary.

coef.mdm() returns lasso coefficients.

plot.mdm() plots the lasso path.

summary.mdm() builds a compact summary list.

print.summary.mdm() prints formatted output for summary.mdm objects.

Usage

## S3 method for class 'mdm'
predict(
  object,
  newdata,
  type = c("all", "prob", "class", "link"),
  s = "lambda.min",
  nworkers = 1,
  verbosity = 1,
  ...
)

## S3 method for class 'mdm'
print(x, ...)

## S3 method for class 'mdm'
coef(object, ...)

## S3 method for class 'mdm'
plot(x, ...)

## S3 method for class 'mdm'
summary(object, ...)

## S3 method for class 'summary.mdm'
print(x, ...)

Arguments

Value

• predict: numeric vector of probabilities, classes, and/or link scores.

• print: invisibly returns x.

• coef: coefficient object from glmnet.

• plot: invisibly returns NULL.

• summary: object of class summary.mdm.

• print.summary.mdm: invisibly returns x.

Examples

m <- structure(
  list(
    model = NULL,
    ref = NULL,
    meta = list(npmax = 1000, nfit = 3, smit = 2, smws = 5,
                delta = 6.4, maxShift = 100, maxCombine = 50,
                combineMethod = 2)
  ),
  class = "mdm"
)
print(m)
summary(m)

## Not run: 
  m <- cv_mdm(spectra, y, sfr = c(11, -2))
  predict(m, test_spectra, type = "prob")
  coef(m)
  plot(m)

## End(Not run)

Description

Recursively searches for files or directories within the 'metabodecon' package that match the given name.

Usage

metabodecon_file(name = "sim_01")

Arguments

Value

The file or directory path.

Author(s)

2024-2025 Tobias Schmidt: initial version.

Examples

# Unambiguous paths
metabodecon_file("urine_1")
metabodecon_file("urine_1.dx")
metabodecon_file("sim/sim_01")

# Ambiguous paths (i.e. multiple matches)
metabodecon_file("sim")
metabodecon_file("urine")

# Non-existing paths (i.e. a character vector of length zero gets returned)
metabodecon_file("asdfasdf")

Description

Automatic deconvolution of a 1D NMR spectrum into several Lorentz curves and the integration of them. The NMR file needs to be in Bruker format or jcamp-dx format.

This function has been deprecated with metabodecon version v1.2.0 and will be removed with version 2.0.0. Please use deconvolute() instead.

Usage

MetaboDecon1D(
  filepath,
  filename = NA,
  file_format = "bruker",
  number_iterations = 10,
  range_water_signal_ppm = 0.1527692,
  signal_free_region = c(11.44494, -1.8828),
  smoothing_param = c(2, 5),
  delta = 6.4,
  scale_factor = c(1000, 1e+06),
  debug = FALSE,
  store_results = NULL
)

Arguments

Value

A decon0 object as described in Metabodecon Classes.

Author(s)

2020-2021 Martina Haeckl: initial version.
2024-2025 Tobias Schmidt: Minor updates to pass CRAN checks. Parameters debug and store_results added.

References

Haeckl, M.; Tauber, P.; Schweda, F.; Zacharias, H.U.; Altenbuchinger, M.; Oefner, P.J.; Gronwald, W. An R-Package for the Deconvolution and Integration of 1D NMR Data: MetaboDecon1D. Metabolites 2021, 11, 452. https://doi.org/10.3390/metabo11070452

See Also

calculate_lorentz_curves(), plot_triplets(), plot_lorentz_curves_save_as_png(), plot_spectrum_superposition_save_as_png()

Examples

## ATTENTION: using MetaboDecon1D() for deconvolution is deprecated. Please use
## deconvolute() instead.

## The following example shows how a subset of the Sim dataset, consisting
## of two spectrum objects, can be deconvoluted using `MetaboDecon1D()`. The
## whole example code is wrapped into `evalwith()` to simulate user input.
## When using the function interactively, you should type in the answers to
## the questions manually.
expected_answers <- c(
     "10",   # Subfolder of your filepath, i.e. the experiment number?
     "10",   # Subsubsubfolder of filepath, i.e. the processing number?
     "y",    # Use same parameters for all spectra?
     "1",    # File to adjust all parameters.
     "n",    # Signal free region borders correct selected?
     "3.55", # Left border.
     "3.35", # Right border.
     "y",    # Signal free region borders correct selected?
     "n",    # Water artefact fully inside red vertical lines?
     "0",    # Half width range (in ppm) for the water artefact.
     "y",    # Water artefact fully inside red vertical lines?
     "n"     # Save results as text documents?
)
sim <- metabodecon_file("bruker/sim_subset")
evalwith(answers = expected_answers, {
     sim_decon <- MetaboDecon1D(sim)
})

## Deconvolute only the first spectrum of the folder "bruker/sim_subset" into
evalwith(answers = expected_answers[-(3:4)], {
     sim_decon <- MetaboDecon1D(sim, filename = "sim_01")
})

Description

Plots the original spectrum and all generated Lorentz curves and save the result as png under the filepath.

Superseded by plot_spectrum() since metabodecon v1.2.0. Will be replaced with metabodecon v2.

Usage

plot_lorentz_curves_save_as_png(
  deconv_result,
  x_range = c(),
  y_range = c(),
  out_dir = ".",
  ask = TRUE
)

Arguments

Value

NULL, called for side effects.

Author(s)

2020-2021 Martina Haeckl: initial version.
2024-2025 Tobias Schmidt: Minor updates to pass CRAN checks

See Also

MetaboDecon1D(), plot_triplets(), plot_spectrum_superposition_save_as_png()

Examples

sim <- metabodecon_file("bruker/sim_subset")
sim_decon <- generate_lorentz_curves_sim(sim)
png_dir <- tmpdir("sim_decon/pngs", create = TRUE)
plot_lorentz_curves_save_as_png(sim_decon, out_dir = png_dir, ask = FALSE)
dir(png_dir, full.names = TRUE)

Description

Plot a set of deconvoluted spectra.

Usage

plot_spectra(
  obj,
  ...,
  foc_rgn = NULL,
  what = c("si", "sup", "supal"),
  sfy = 1e+06,
  cols = NULL,
  names = NULL,
  xlab = "Chemical Shift [ppm]",
  ylab = paste("Signal Intensity [au] /", sfy),
  mar = c(4.1, 4.1, 1.1, 0.1),
  lgd = list()
)

Arguments

Value

A plot of the deconvoluted spectra.

Author(s)

2024-2025 Tobias Schmidt: initial version.

See Also

plot_spectrum() for a much more sophisticated plotting routine suitable for plotting a single spectrum.

Examples

obj <- deconvolute(sim[1:4], sfr = c(3.55, 3.35))
plot_spectra(obj)

Description

Plot a spectrum and zoom in on a specific region.

Usage

plot_spectrum(
  x,
  ...,
  obj = as_v12_singlet(x),
  foc_frac = get_foc_frac(obj),
  foc_rgn = get_foc_rgn(obj, foc_frac),
  sub1 = TRUE,
  sub2 = FALSE,
  sub3 = width(foc_rgn) < width(obj$cs),
  mar = NULL,
  frame = FALSE,
  con_lines = TRUE
)

Arguments

Details

This function first initializes a new plotting canvas. After that it calls draw_spectrum() multiple times to draw the following sub figures onto the plotting canvas:

1. The signal intensities in the focus region

2. The second derivative in the focus region

3. The signal intensities over all datapoints

The argument lists for the individual calls to draw_spectrum() are determined at runtime and depend on the arguments passed to plot_spectrum() as well as the currently active graphics device. To customize the appearance of the individual sub plots, you can overwrite each value passed to draw_spectrum() by providing a corresponding named element in sub1, sub2 or sub3.

A sketch of the resulting figure is shown below.

 __________________________________________
|        ______________1_____________      |
|       | Sub1: Signal Intensity in  |     |
|       | Focus Region               |     |
|       |             /\             |     |
|       |            /  \            |     |
|       |           /    \  /\       |     |
|     11|          /      \/  \      |7    |
|       |     /\  /            \     |     |
|       |    /  \/              \    |     |
|       |   /                    \   |     |
|       |__/___________0__________\__|     |
|       | Sub2: Second Derivative    |     |
|     11| in Focus Region            |7    |
|       |____________________________|     |
|                      3                   |
|    __________________3_________________  |
|   |  Sub3: Signal Intensity over all   | |
|   |  Datapoints     ________________   | |
| 5 |                | Focus Rectangle|  |1|
|   |     /\         |       /\       |  | |
|   |    /  \        |      /  \/\    |  | |
|   |   /    \   /\  |   /\/      \   |  | |
|   |__/______\_/__\_|__/__________\__|__| |
|______________________5___________________|

Note that the figure created by plot_spectrum() can be part of a multi-figure configuration as created when setting mfrow or mfcol via par(). Example:

_______________________________________
| Plot Spectrum with   | Other Figure  |
| sub3 = TRUE          | Other Figure  |
|      ___________     |  ___________  |
|     | Sub Fig 1 |    | | x      x  | |
|     |___________|    | |      x    | |
|     |_Sub_Fig_2_|    | |      x    | |
|   _________________  | |   x     x | |
|  |    Sub Fig 3    | | |      x    | |
|  |_________________| | |___________| |
|______________________|_______________|
| Some other Figure    | Plot Spectrum |
|                      | sub3 = FALSE  |
|  _________________   |  ___________  |
| |     ___         |  | | Sub Fig 1 | |
| | ___/   \___     |  | |           | |
| |/           \____|  | |___________| |
| |                 |  | | Sub Fig 2 | |
| |_________________|  | |___________| |
|______________________|_______________|

Value

NULL. Called for side effect of plotting as sketched in 'Details'.

Author(s)

2024-2025 Tobias Schmidt: initial version.

Examples

## 1. Prepare a deconvoluted spectrum as input

spec <- read_spectrum(metabodecon_file("sim/sim_01"))
decon <- generate_lorentz_curves_sim(spec)

## 2.1. Plot the full (non-deconvoluted) spectrum
## 2.2. Remove connecting lines, and focus on a specific region specified in ppm
## 2.3. Show second derivative and focus on a specific region specified as fraction
## 2.4. Change color of focus rectangle and margins of sub figure 1
## 2.5. Hide xlab and show second derivative
## 2.6. Change the figure region for sub figure 1

plot_spectrum(spec, sub1 = FALSE)
plot_spectrum(decon, foc_rgn = c(3.49, 3.45), con_lines = FALSE)
plot_spectrum(decon, sub2 = TRUE, foc_frac = c(0.40, 0.30))
plot_spectrum(decon,
    sub1 = list(mar = c(3, 6, 3, 6), lt_axis = list(col = "violet")),
    foc_rect = list(border = "violet", col = transp("violet")),
    con_lines = list(col = "violet")
)
plot_spectrum(decon,
    sub2 = TRUE,
    sub3 = list(bt_text = list(text = "")),
    frame = TRUE,
    con_lines = FALSE
)
plot_spectrum(decon, sub1 = list(fig_rgn_npc = c(0,1,.3,1), mar = c(0,5,0,0)))

Description

Plots the original spectrum and the superposition of all generated Lorentz curves and saves the result as png under the specified filepath.

Superseded by plot_spectrum() since metabodecon v1.2.0. Will be replaced with v2.

Usage

plot_spectrum_superposition_save_as_png(
  deconv_result,
  x_range = c(),
  y_range = c(),
  out_dir = ".",
  ask = TRUE
)

Arguments

Value

NULL, called for side effects.

Author(s)

2020-2021 Martina Haeckl: initial version.

See Also

MetaboDecon1D(), calculate_lorentz_curves(), plot_triplets(), plot_lorentz_curves_save_as_png()

Examples

sim <- metabodecon_file("bruker/sim_subset")
sim_decon <- generate_lorentz_curves_sim(sim)
png_dir <- tmpdir("sim_decon/pngs", create = TRUE)
plot_spectrum_superposition_save_as_png(sim_decon, out_dir = png_dir, ask = FALSE)
dir(png_dir, full.names = TRUE)

Description

Plots the peak triplets for each peak detected by MetaboDecon1D() and stores the plots as png at outdir.

Superseded by plot_spectrum() since metabodecon v1.2.0. Will be replaced with v2.

Usage

plot_triplets(
  deconv_result,
  x_range = c(),
  y_range = c(),
  out_dir = ".",
  ask = TRUE
)

Arguments

Value

No return value, called for side effect of plotting.

Author(s)

2020-2021 Martina Haeckl: initial version.
2024-2025 Tobias Schmidt: Minor updates to pass CRAN checks.

See Also

MetaboDecon1D(), calculate_lorentz_curves(), plot_lorentz_curves_save_as_png(), plot_spectrum_superposition_save_as_png()

Examples

sim <- metabodecon_file("bruker/sim_subset")
sim_decon <- generate_lorentz_curves_sim(sim)
png_dir <- tmpdir("sim_decon/pngs", create = TRUE)
plot_triplets(sim_decon, out_dir = png_dir, ask = FALSE)
dir(png_dir, full.names = TRUE)

Description

S3 Methods for printing metabodecon objects as described in the Metabodecon Classes.

Usage

## S3 method for class 'spectrum'
print(x, name = FALSE, ...)

## S3 method for class 'decon1'
print(x, name = FALSE, ...)

## S3 method for class 'decon2'
print(x, name = FALSE, ...)

## S3 method for class 'align'
print(x, name = FALSE, ...)

## S3 method for class 'spectra'
print(x, ...)

## S3 method for class 'decons1'
print(x, ...)

## S3 method for class 'decons2'
print(x, ...)

## S3 method for class 'aligns'
print(x, ...)

Arguments

Value

NULL, called for side effect of printing to the standard output device.

Author(s)

2024-2025 Tobias Schmidt: initial version.

Examples

print(sim[[1]])
print(sim[[1]], name = TRUE)
print(sim)
decon <- deconvolute(sim[[1]], sfr = c(3.55, 3.35))
print(decon)

Description

read_spectrum() reads a single spectrum from disk and returns it as spectrum object. read_spectra() can be used to read multiple spectra at once and returns a spectra object.

Usage

read_spectra(
  data_path = pkg_file("example_datasets/bruker/urine"),
  file_format = "bruker",
  expno = 10,
  procno = 10,
  raw = FALSE,
  silent = TRUE,
  force = FALSE
)

Arguments

Value

A spectrum object as described in Metabodecon Classes.

Author(s)

2024-2025 Tobias Schmidt: initial version.

Examples

relpath <- "example_datasets/bruker/urine"
urine <- system.file(relpath, package = "metabodecon")
urine_1 <- file.path(urine, "urine_1")
urine_2 <- file.path(urine, "urine_2")
x1 <- read_spectrum(urine_1)
x2 <- read_spectrum(urine_2)
xx <- read_spectra(urine)
str(xx)
str(x1)
stopifnot(all.equal(x1, xx$urine_1))

Description

read_spectrum() reads a single spectrum from disk and returns it as spectrum object. read_spectra() can be used to read multiple spectra at once and returns a spectra object.

Usage

read_spectrum(
  data_path = metabodecon_file("bruker/sim/sim_01"),
  file_format = "bruker",
  expno = 10,
  procno = 10,
  raw = FALSE,
  silent = TRUE,
  force = FALSE
)

Arguments

Value

A spectrum object as described in Metabodecon Classes.

Author(s)

2024-2025 Tobias Schmidt: initial version.

Examples

relpath <- "example_datasets/bruker/urine"
urine <- system.file(relpath, package = "metabodecon")
urine_1 <- file.path(urine, "urine_1")
urine_2 <- file.path(urine, "urine_2")
x1 <- read_spectrum(urine_1)
x2 <- read_spectrum(urine_2)
xx <- read_spectra(urine)
str(xx)
str(x1)
stopifnot(all.equal(x1, xx$urine_1))

Description

The SAP Dataset consists of a single 'Simple-As-Possible' (SAP) spectrum. The purpose of the SAP spectrum is to provide a straightforward example that can be used to test and understand the deconvolution algorithm in detail.

Usage

sap

Format

An object of class spectra of length 1.

Details

The first (and only) spectrum within the SAP dataset contains 128 datapoints ranging from -6.4 to 6.4 ppm with four peaks. A rough sketch of the spectrum is shown below:

-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~
|      SFR      |               w               |     SFR      |
|               |  x           www       p      |              |
|~-~-~-~-~-~-~-~|~-|-|-~-~-~-~-~|~-~-~-~-|-~-~-~-~-~-~-~-~-~-~-~
|               |  | |          |        |      |
6.4             |  | 2.24       0.047    -2.22  -3.2
                |  2.61
                3.2

Description

A simulated dataset generated from the Blood dataset.

Usage

sim

Format

A spectra object consisting of 16 spectrum objects, where each spectrum contains 2048 datapoints ranging from 3.60 to 3.29 ppm. For details about spectrum and spectra objects see Metabodecon Classes.

Description

Simulates a 1D NMR spectrum based on the provided parameters.

Usage

simulate_spectrum(
  name = "sim_00",
  seed = sum(utf8ToInt(name)),
  ndp = 2048,
  npk = 10,
  csres = 0.00015,
  cs = seq(from = 3.6, length.out = ndp, by = -csres),
  pkr = quantile(cs, c(0.25, 0.75)),
  fqref = 600252806.95,
  x0 = sort(runif(npk, pkr[1], pkr[2])),
  A = runif(npk, 2.5, 20) * 1000,
  lambda = runif(npk, 0.9, 1.3)/1000,
  noise = rnorm(length(cs), sd = 1200)
)

Arguments

Value

A spectrum object as described in Metabodecon Classes.

Author(s)

2024-2025 Tobias Schmidt: initial version.

Examples

simA <- simulate_spectrum("simA")
simA_copy <- simulate_spectrum("simA")
simB <- simulate_spectrum("simB")
simC <- simulate_spectrum("simC", npk = 20)
plot_spectrum(simC)
if (!identical(simA, simA_copy)) stop()
if ( identical(simA, simB     )) stop()

Description

Helper function of align(). Should not be called directly by the user.

Performs signal alignment across the individual spectra using the 'speaq' package (Beirnaert C, Meysman P, Vu TN, Hermans N, Apers S, Pieters L, et al. (2018) speaq 2.0: A complete workflow for high-throughput 1D NMRspectra processing and quantification. PLoS Comput Biol 14(3): e1006018. https://www.doi.org/10.1371/journal.pcbi.1006018). The spectra deconvolution process yields the signals of all spectra. Due to slight changes in measurement conditions, e.g. pH variations, signal positions may vary slightly across spectra. As a consequence, prior to further analysis signals belonging to the same compound have to be aligned across spectra. This is the purpose of the 'speaq' package.

Direct usage of this function has been deprecated with metabodecon version 1.4.3 and will be removed with metabodecon version 2.0.0.

Usage

speaq_align(
  feat = gen_feat_mat(spectrum_data),
  maxShift = 50,
  spectrum_data,
  si_size_real_spectrum = length(spectrum_data[[1]]$y_values),
  verbose = TRUE,
  show = FALSE,
  mfrow = c(2, 1)
)

Arguments

Value

A matrix containing the integral values of the spectra after alignment.

There is one row per spectrum and one column per ppm value. The entry at position ⁠i, j⁠ holds the integral value of the signal from spectrum i that has its center at position j after alignment by speaq. If there is no signal with center j in spectrum i, entry ⁠i, j⁠ is set to NA. The column names of the matrix are the ppm values of the original spectra.

Example return matrix:

    ...  3.59  3.55  3.57  3.56  3.55  3.54  3.53
  .----------------------------------------------> PPM
1 | NA   NA    0.20  NA    NA    NA    0.25  NA
2 | NA   NA    0.15  NA    NA    NA    0.13  NA
3 | NA   NA    NA    0.2   NA    NA    0.18  NA
SpNr

Author(s)

2021-2024 Wolfram Gronwald: initial version.
2024-2025 Tobias Schmidt: refactored initial version.

Examples

deps <- c("MassSpecWavelet", "impute")
deps_installed <- sapply(deps, requireNamespace, quietly = TRUE)
if (all(deps_installed)) {
    # 'speaq' requires 'MassSpecWavelet' and 'impute' to be installed
    sim_subset <- metabodecon_file("bruker/sim_subset")
    spectrum_data <- generate_lorentz_curves_sim(sim_subset)
    feat <- gen_feat_mat(spectrum_data)
    maxShift <- 200
    M <- speaq_align(feat, maxShift, spectrum_data, show = TRUE)
    str(M)
}

Description

Returns the path to metabodecon's temporary session directory. This directory equals subdirectory 'metabodecon' of R's temporary session directory base::tempdir() plus additional path normalization.

Usage

tmpdir(subdir = NULL, create = FALSE)

Arguments

Value

Returns the path to the temporary session directory.

Author(s)

2024-2025 Tobias Schmidt: initial version.

See Also

datadir_temp() datadir_persistent()

Examples

tmpdir()
tmpdir("simulate_spectra")

Description

Make a color transparent by adding an alpha channel.

Usage

transp(col = "violet", alpha = 0.08)

Arguments

Value

A character string representing the color with an alpha channel.

Author(s)

2024-2025 Tobias Schmidt: initial version.

Examples

transp("violet", 0.08)
transp("black", 0.5)

Description

Prints the structure of a directory tree up to a specified maximum level of depth. It lists all files and directories under the specified path, displaying them in a tree-like structure.

Usage

tree(
  path,
  max.level = 2,
  max.entries = Inf,
  show.counts = FALSE,
  files.first = FALSE,
  level = 0,
  prefix = ""
)

tree_preview(
  path,
  max.level = 1,
  max.entries = 9,
  show.counts = TRUE,
  files.first = TRUE
)

Arguments

Value

NULL, called for its side effect of printing the directory structure.

Author(s)

2024-2025 Tobias Schmidt: initial version.

Examples

metabodecon_dir <- system.file(package = "metabodecon")
tree(metabodecon_dir, max.level = 1)

Description

Calculates the width of a numeric vector by computing the difference between the maximum and minimum values in the vector.

Usage

width(x)

Arguments

Value

The width of the vector, calculated as the difference between its maximum and minimum values.

Author(s)

2024-2025 Tobias Schmidt: initial version.

Examples

vec <- c(1, 3, 5, 7, 9)
width(vec)