Metabodeconplus—An R Package for Automated Deconvolution and Alignment of 1D NMR Metabolomics Data

Abstract

Background: In one-dimensional NMR spectra of complex biofluids such as urine and plasma, extensive signal overlap obscures individual metabolite signals. Resolving this overlap by deconvolution is only the first step: turning a set of spectra into a table for subsequent statistical analysis also requires the alignment of signals across samples and their integration into a single feature matrix. Methods: Here, metabodeconplus is presented, an R package that unifies this entire path into a single reproducible end-to-end workflow. From raw one-dimensional spectra, it deconvolutes overlapping signals, aligns resulting signals across samples, and integrates them into a data matrix for built-in sample classification or downstream statistical analysis. Automated parameter optimization removes manual tuning, and a Rust computational backend with parallelization leads to fast runtimes. Results: On the simulated Sim3 spectra, a combined score of correctly identified signals and reconstruction accuracy (maximum 1) rose from 0.712 for the predecessor package to 0.801 for metabodeconplus. For the urinary AKI dataset, metabodeconplus reached a classification accuracy of 73.7 ± 2.20% and an $\mathrm{AUC}=0.827\pm 0.025$, which is comparable to the binning baseline. An advantage is the potential unambiguous metabolite assignment of the deconvoluted signals. Conclusions: The package is freely available as open source on GitHub and on CRAN.

1. Introduction

1.1. Background

Nuclear magnetic resonance (NMR) spectroscopy is a widely used analytical technique in metabolomics [1,2,3]. By exploiting the magnetic properties of atomic nuclei, NMR provides structural and quantitative information about the metabolite composition of biomedical specimens such as urine and plasma, as well as cells and tissues. Alongside mass spectrometry, this makes it a key tool in metabolomics, where researchers seek to characterize the metabolite profile of biological systems.

1.2. Challenges in 1D NMR Spectra Analysis

The goal of a metabolomics experiment is to identify and quantify the metabolites present in a sample. To this end, certain physical properties are recorded, allowing inferences about the contained metabolites. In NMR spectroscopy, the measured properties are the resonance frequencies of atomic nuclei like ¹H in a magnetic field, which are influenced by their electronic environment, and the intensities of these resonances. Following Fourier transformation of the raw time-domain data, the obtained NMR spectrum can be used to infer the presence and concentrations of specific metabolites [4]. However, despite its advantages, NMR spectroscopy faces challenges that complicate the direct extraction of metabolite concentrations from raw spectra. Two major issues that hinder accurate identification and quantification of metabolites are signal overlap and signal shifts.

1.2.1. Signal Overlap

Ideally, the resonance frequencies in an NMR spectrum would appear as sharp signals, allowing straightforward identification and quantification. However, in reality, these signals possess distinct linewidths and, therefore, may overlap with one another, rendering it difficult to distinguish individual signals. Several factors contribute to signal broadening, including $T_2$ relaxation effects [5], magnetic field inhomogeneities [6], chemical exchange processes [7], sample viscosity and molecular interactions, which both contribute to relaxation [8], and the measurement process itself.

The process of reconstructing the individual metabolite contributions from a complex spectrum of overlapping signals is known as deconvolution. This is one of the key challenges that metabodeconplus seeks to address.

1.2.2. Signal Shifts

Another major challenge in NMR-based metabolomics is that the resonance frequencies of the same metabolite might slightly vary across samples. Several factors can cause these signal shifts, including variations in temperature [4], differences in sample pH [8], and variations in ionic strength and solvent composition [8]. With respect to variations in pH, pronounced signal shifts are, for example, commonly observed for side-chain resonances in metabolites like histidine, where the pKa of the side-chain is close to physiological levels (approximately 6.0 for histidine).

These inconsistencies complicate direct comparisons between samples and hinder both identification and quantification of metabolites. To address this issue, signal alignment techniques are used to shift signals across spectra to concordant positions, allowing for more accurate quantitative comparisons.

1.3. Existing Solutions

Available open-source solutions include the R packages BATMAN [9], rDolphin [10], speaq 2.0 [11], ASICS [12], SigMa [13], and MetaboDecon1D [14] (the predecessor of this package); the Python program decon1d [15]; the MATLAB applications icoshift [16] and COW [17]; and the web applications BAYESIL [18], DEEP Picker1D [19], and NMRProcFlow [20]. Proprietary software suites available for NMR spectral analysis include NMR Workbook Suite by ACD/Labs, AMIX by Bruker, Chenomx NMR Suite by Chenomx Inc., and Mnova NMR by Mestrelab Research. Furthermore, Bruker TopSpin 4.2 includes the program mldecon [21].

A summary of the main features of each tool is provided in

Table 1. Summary of tasks performed by various published approaches. ^a Indicated are only approaches that perform a dedicated signal deconvolution of overlapping signals. ^b Tools that allow an absolute quantification of metabolites. ^c Approaches performing a dedicated signal alignment, allowing for non-linear signal corrections, across a set of measured spectra. ^d Additional tools to perform a statistical analysis of obtained data. ^e Commercial approaches.

Name	Deconvolution a	Quantification b	Alignment c	Statistics d
ACD/NMR e	✓	✓	–	✓
AMIX e	✓	✓	–	✓
ASICS	✓	✓	–	✓
BATMAN	✓	✓	–	–
BAYESIL	✓	✓	–	–
Chenomx e	✓	✓	–	–
COW	–	–	✓	–
decon1d	✓	–	–	–
DEEP Picker1D	✓	–	–	–
icoshift	–	–	✓	–
metabodeconplus	✓	✓	✓	✓
MetaboDecon1D	✓	–	–	–
mldecon	✓	–	–	✓
Mnova NMR e	✓	✓	–	✓
NMRProcFlow	–	–	✓	✓
rDolphin	✓	✓	–	–
SigMa	✓	✓	✓	–
speaq 2.0	✓	–	✓	✓

; detailed descriptions of individual solutions are given in Appendix A.

1.4. The Role of Metabodeconplus

The aim of metabodeconplus is to deconvolute 1D NMR spectra of complex biofluids such as plasma, urine, or CSF containing numerous overlapping signals to determine accurate integrals of the underlying signals regardless of whether the corresponding metabolites are known. Therefore, no library of known reference compounds is required. As a result, unidentified signals can also be used for a variety of tasks such as sample classification. Previously, MetaboDecon1D [14] has been developed, an R package for the deconvolution and integration of overlapping 1D NMR signals. For each spectrum, the output is a list of deconvoluted signals characterized by their spectral positions together with accurate integral values. However, to make full use of this data, additional signal alignment is required for subsequent statistical analyses. metabodeconplus is not a new version of MetaboDecon1D but a new and substantially broader package: whereas MetaboDecon1D performed deconvolution of a single spectrum, metabodeconplus provides a complete, automated pipeline that takes a set of raw 1D NMR spectra all the way to an aligned, classification-ready table of signal integrals. As deconvoluted signals, in contrast to bins, correspond to single compounds, this also facilitates subsequent potential identification and accurate quantification of compounds by other methods. Note that tools for the latter two tasks are not part of metabodeconplus. For signal alignment, the CluPA algorithm [22] of the speaq 2.0 package [11] was included. To this end, CluPA was adapted to the output format of the deconvolution step of metabodeconplus. The CluPA algorithm was chosen because it offers reliable alignment between target and reference spectra and has been implemented in R, which facilitated its addition to the metabodeconplus R package. Furthermore, the alignment approach has been extended by the new snap_to_ref function to remove the residual positional uncertainty that remains after CluPA.

In addition, the underlying deconvolution algorithm was optimized for speed and accuracy.

The contribution of metabodeconplus is thus a single, automated end-to-end workflow for 1D NMR fingerprinting: from raw spectra, it produces a two-dimensional table of aligned signal integrals that feeds directly into built-in sample classification. It achieves this by integrating three previously separate steps (deconvolution, signal alignment via the adapted CluPA algorithm, and classification) into one package and by automating the parameter search of these steps. A substantially faster deconvolution backend allows the application to large datasets containing several hundred spectra. For a user, this means the entire path from raw spectra to a classification-ready feature matrix is handled by one package, replacing the ad-hoc combination of separate deconvolution and alignment tools that this analysis previously required.

2. Materials and Methods

2.1. Package Availability

The R package is available on GitHub at https://github.com/spang-lab/metabodeconplus and on CRAN at https://cran.r-project.org/package=metabodeconplus. Both were accessed on 11 August 2026. All results reported here were produced with metabodeconplus versions 0.20.0 to 0.22.2 under R 4.5.3, using the R packages ranger 0.18.0 and speaq 2.7.0, and the Rust backend mdrb 0.0.5, built with Rust 1.94.0.

2.2. Study Cohorts

Four datasets were used throughout this study. The Urine dataset is distributed with the package, and the Sim3, Blood and AKI datasets can be obtained via download_example_datasets() or downloaded manually from GitHub.

The Sim3 dataset consists of 100 simulated spectra, each containing 2048 data points covering a chemical shift range of 3.59 to 3.28 ppm (datapoint spacing $0.00015$ ppm). The spectra are evenly split into two groups, A and B (50 each). Each spectrum contains the same 25 underlying Lorentzian signals: a fixed set of reference signal positions, signal intensities, and half-widths is reused across all spectra, with per-spectrum variability introduced by (i) a scalar global ppm shift drawn from $\mathcal{N}(0,{0.00120}^2)$ ppm (SD $=8$ datapoints), (ii) a per-signal ppm jitter drawn from $\mathcal{N}(0,{0.00060}^2)$ ppm (SD $=4$ datapoints), (iii) per-signal amplitude scaling drawn from $\mathcal{U}[0.4,1.6]$, (iv) per-signal half-width scaling drawn from $\mathcal{U}[0.9,1.1]$, and (v) additive Gaussian noise. In group A, the amplitudes of 3 of the 25 signals (the discriminating signals) are additionally scaled by fixed factors of $1.35$, $1.35$, and $1/1.35$ (≈0.74); group B is left unmodified. The first spectrum is generated without any positional shift and serves as a clean unshifted reference. The shared reference parameters were derived from an initial deconvolution of the Blood dataset with manually optimized settings so that the simulated spectra closely resemble real blood plasma spectra while providing exact ground truth for signal parameters, group labels, and noise levels.

The Blood dataset consists of 16 human blood plasma spectra measured with a 1D ¹H Carr–Purcell–Meiboom–Gill (CPMG) pulse sequence.

The Urine dataset consists of 2 human urine spectra measured with a 1D ¹H NOESY pulse sequence. Specimens from both the Blood and Urine data sets were obtained from the German Chronic Kidney Disease (GCKD) study collected at the baseline time point [23,24]. The GCKD study was carried out in accordance with the Declaration of Helsinki, registered in the German Register of Clinical Trials (DRKS 00003971), and approved by the ethics committees of the participating institutions.

The AKI dataset consists of 106 urinary 1D ¹H NMR spectra acquired with a 1D ¹H NOESY pulse sequence in the context of a study on acute kidney injury (AKI) following cardiac surgery with cardiopulmonary bypass (CPB) use [25]. Urinary specimens were collected 24 h after surgery. These spectra had been previously collected with written informed consent of the patients upon ethical approval from the University Clinic Erlangen, Erlangen, Germany. The study was approved by an institutional review board at the Faculty of Medicine at the Friedrich-Alexander University (FAU) Erlangen-Nuremberg under the identifier #4010 [26].

All experimental measurements for these datasets were performed on a 600 MHz Bruker Avance III spectrometer (Bruker BioSpin GmbH, Rheinstetten, Germany) employing a helium cooled cryogenic probe and a cooled sample changer. The measurements were performed using optimized pulse sequences for the suppression of water signals.

An overview of all datasets is given in

Table 2. Summary of sample types, number of samples, and measurement techniques used. The Blood dataset seeds the reference signal parameters of the simulated Sim3 dataset (Section 3.1); the Urine dataset is used to select the default npmax for the AKI benchmark (Section 3.4).

Name	Sample Type	Number of Samples	Exp. Technique
Sim3	Simulated	100	1D Sim
Blood	Human Blood Plasma	16	1D CPMG
Urine	Human Urine	2	1D NOESY
AKI	Human Urine	106	1D NOESY

.

2.3. The Deconvolution Method

The input for metabodeconplus is a set of Fourier-transformed, phase- and baseline-corrected, and properly referenced 1D ¹H NMR spectra. The deconvolution algorithm used in metabodeconplus was first described in Koh et al. (2009) [27] and implemented as part of MetaboDecon1D v0.2.2 [14]. The implementation in metabodeconplus was completely restructured into a modular framework with four distinct stages: (i) smoothing, (ii) peak detection, (iii) peak filtering, and (iv) Lorentzian function fitting. Throughout, signal refers to a resonance or other contribution that raises the measured intensity at a given position, and each detected signal is approximated by one Lorentzian curve, whose maximum is called its peak. A concise overview of the major functional differences between MetaboDecon1D v0.2.2 and metabodeconplus is provided in

Table A1. Concise comparison of major functional differences between MetaboDecon1D and metabodeconplus.

Aspect	MetaboDecon1D	Metabodeconplus
Scope	Deconvolution	Deconvolution, Alignment, Modeling
Implemented in	R	R and Rust
Lorentzian fitting	Uses original formulation	Uses algebraically simplified equations
Smoothing	Smoothed intensities propagate into fitting	Smoothing is used for peak detection only; Lorentzian fitting uses the raw intensities
Artifact handling	Negative intensities rectified; water region set to zero	Negative intensities retained; user-defined ignore regions replace hard zeroing of artifact regions
Parameter optimization	Manual parameter selection	Manual selection or grid search via npmax
Alignment	Not available	CluPA followed by snap_to_ref
Predictive modeling	Not available	End-to-end classifier pipeline via fit_mdm() with a Random Forest learner; nested-CV performance estimation via benchmark()
Performance and reuse	Legacy implementation	Faster peak detection and smoothing, parallel execution, and optimized Lorentzian superposition

. The overall algorithm is visualized for a small, simulated spectrum in Figure 1.

2.3.1. Smoothing

Smoothing is required to suppress spurious detections caused by noise. Following Koh et al. (2009) [27], a moving average filter is applied to the spectral intensities before peak detection. A moving average filter is a low-pass filter that replaces each intensity value with the equally weighted average of the values within a surrounding window of user-defined size m. Denoting the spectral intensities as $Y_{\left(0\right)}=Y$, the chemical shift at data point i as ${\omega }_i$, the half window $h=\lceil {\displaystyle \frac{m}{2}}\rceil$, and the number of points N, one pass of the filter is given by

$$Y_{\left(k\right)}\left({\omega }_i\right)={\displaystyle \frac{1}{m}}{\displaystyle \sum _{j=1}^m}{Y}_{(k-1)}\left({\omega }_{i-h+j}\right),i\in [h,N-h].$$

(1)

It is applied iteratively n times, yielding the smoothed spectral intensities $Y_{\left(n\right)}=Z$.

2.3.2. Peak Detection

Peak detection operates on the smoothed spectral intensities using the curvature-based method introduced by Koh et al. (2009) [27]. Peaks are identified based on local minima in the second derivative of the smoothed spectrum. Each peak is represented by a left, center, and right point $k_i\in \{1,\dots ,N\}$, with $i=1,2,3$, respectively. Each peak is assigned the score introduced by Koh et al. (2009) [27]:

$$\mathrm{score}=\min \left({\displaystyle \sum _{i=k_1}^{k_2}}|Z^{″}\left({\omega }_i\right)|,{\displaystyle \sum _{i=k_2}^{k_3}}\left|Z^{″}\left({\omega }_i\right)\right|\right),$$

(2)

i.e., the smaller of the two cumulative absolute second-derivative sums over the peak’s left and right halves. Sharper, more prominent peaks therefore receive higher scores.

2.3.3. Peak Filtering

Peaks in the signal-free region are used to estimate the noise distribution. Only peaks with a score exceeding $\mu +\delta ·\sigma$ are retained, where $\mu$ and $\sigma$ are the mean and standard deviation of the noise scores and $\delta$ is a user-tunable multiplier (default 6.4) that controls peak-detection sensitivity. Peaks inside user-specified ignore regions, such as the water-artifact region, are also removed.

2.3.4. Lorentzian Function Fitting

Each detected peak is characterized by a triplet of observed points $({\omega }_i,y_i)$, $i=1,2,3$, which uniquely determines the center ${\omega }_0$, half-width $\lambda$, and amplitude A of a Lorentzian function passing exactly through those three points. These are the initial parameter estimates. When the resulting Lorentzian curves are superimposed, the sum tends to exceed the observed spectrum due to spill-over from neighboring peaks. Following Koh et al. [27], each peak’s height is, therefore, iteratively reduced by a rule of proportion until the superposition matches the raw spectrum. Compared to the original MetaboDecon1D implementation, metabodeconplus uses a more efficient strategy for computing the Lorentzian parameters during both initial estimation and iterative refinement; mathematical details are provided in Appendix C.

2.3.5. Rust Implementation

In addition to the native R implementation, metabodeconplus provides an optional Rust backend that implements the same deconvolution algorithm with further refinements for numerical stability and computational efficiency. The backend is accessible through the standard R interface via the use_rust parameter of deconvolute() and yields results that are numerically very close, though not identical, to the R implementation. The substantially reduced runtimes allow for a systematic grid search of optimal deconvolution parameters (Section 2.5.1) even for large datasets consisting of several hundred spectra.

2.3.6. Scoring of Deconvolution Quality

To score the deconvolution quality of simulated data or controlled measurements of known compounds, a new measure called PRARPX was devised. It scores both the number of correctly identified Lorentzians and the approximation of the measured spectra. The Extended Peak Ratio compares the correctly identified Lorentzians c to the true Lorentzians t plus the incorrectly identified Lorentzians i,

$$\mathrm{PRX}={\displaystyle \frac{c}{t+i}},$$

(3)

and the Area Ratio is the total absolute residual R over the total absolute observed signal S,

$$\mathrm{AR}={\displaystyle \frac{R}{S}}.$$

(4)

PRARPX is the product of the two,

$$\mathrm{PRARPX}=\mathrm{PRX}·\max (0,1-\mathrm{AR}).$$

(5)

Both factors fall within $[0,1]$. The score approaches 1 the more unique true Lorentzians are assigned a fitted Lorentzian and the smaller the residual becomes. Therefore, PRARPX approaches 1 for an ideal deconvolution. Because PRARPX requires ground-truth Lorentzian parameters, it is not applicable to biological specimens containing unknown compound numbers. Appendix D motivates it in detail and contrasts it with using PR or AR alone.

2.4. The Alignment Method

Proper signal alignment is crucial to correct for chemical-shift variations across samples and to ensure that subsequent statistical analyses compare the same signals from the same metabolites. Following deconvolution, the obtained peak lists are passed through two consecutive steps: a coarse CluPA (cluster-based peak alignment) shift, followed by a refinement step snap_to_ref(). Both operate on the discrete peak grid: CluPA shifts whole spectrum segments by the same integer-datapoint offset, so all peaks within one segment move together. One peak may end up well-aligned while another in the same segment is still slightly off. The refinement step removes this residual mismatch by snapping each remaining peak individually onto the nearest peak column of the reference spectrum. The two steps are exposed individually as clupa() and snap_to_ref() and are chained by the wrapper align(). The combined procedure is visualized for a set of simulated spectra in Figure 2.

2.4.1. CluPA

The first stage is based on the hierarchical cluster-based peak alignment (CluPA) approach from the speaq package [11,22]. CluPA aligns a target spectrum to a reference spectrum in two phases. First, it shifts the spectrum globally. Then, it iteratively splits the spectrum into smaller local segments that are individually aligned. The segment boundaries are defined by hierarchical clustering applied to the combined peak list of the reference and target spectrum: peaks are grouped into a tree based on their distances, and at each iteration, all segments are bisected according to the dendrogram. For each segment, the optimal integer datapoint shift is determined by fast Fourier transform cross-correlation, bounded by the user-supplied tolerance maxShift. Iterations stop when a segment contains only peaks from the same spectrum or fewer than three peaks. CluPA changes peak centers but does not change the number of peaks per spectrum.

2.4.2. snap_to_ref

CluPA shifts whole spectrum segments, not individual peaks, so peaks within the same segment all move equally in terms of direction and distance. Following CluPA, the alignment of spectra is substantially improved, but individual peaks are still not guaranteed to exhibit the exact same chemical shift across spectra, and a refinement step is needed to enforce a common peak grid. The snap_to_ref() step does this by collapsing (snapping) each spectrum’s peak list onto the peak grid of the reference spectrum chosen by CluPA. For each peak, the nearest reference peak within maxCombine columns is its target. Peaks farther than maxCombine from every reference peak are dropped. If multiple peaks are snapped to the same reference, their integrals are summed when the feature matrix is built. Rare signals not present in the reference spectrum may be lost or attributed to the wrong reference. The interpretation of maxCombine is, therefore, the residual positional uncertainty that remains after CluPA. Figure 2 visualizes the cumulative effect of the two steps: the top row overlays the six reconstructed spectra after each step, the middle row renders them as intensity heatmaps, and the bottom row reduces each spectrum to its sparse peak-position marks.

Both clupa() and snap_to_ref() align/snap each spectrum towards a fixed reference spectrum. This makes application to new samples trivial: each new sample is aligned and snapped to the same reference.

2.5. Parameter Optimization

2.5.1. Unsupervised Parameter Optimization

Metabodeconplus’s deconvolution exposes four tunable parameters: nfit, smit, smws and delta. nfit sets the number of iterative Lorentzian-refinement passes, smit the number of moving-average smoothing passes, smws the smoothing window size (in datapoints), and delta the noise-threshold multiplier from Section 2.3.3. Without class labels, these can be optimized for each spectrum individually in an automated fashion by minimizing the Area Ratio (AR) between observed intensities Y and reconstructed intensities $\widehat{Y}$:

$$\mathrm{AR}={\displaystyle \frac{{\sum }_i|Y\left({\omega }_i\right)-\widehat{Y}\left({\omega }_i\right)|}{{\sum }_i\left|Y\left({\omega }_i\right)\right|}},i\in \{1,\dots ,N\}.$$

(6)

For evenly sampled spectra, this is the mean absolute residual divided by the mean absolute signal, and smaller values indicate a better fit.

Minimizing the AR alone is not always optimal as the AR keeps decreasing as more Lorentzians are fitted, so the optimum may drift towards over-fit reconstructions with many spurious peaks. Therefore, the maximum number of expected signals npmax was added as a user-defined parameter. The automated parameter optimization of the deconvolution step then sweeps a 60-cell parameter grid $\mathtt{smit}\in \{1,2,3\}$, $\mathtt{smws}\in \{3,5,7,9\}$, $\mathtt{delta}\in \{1.6,3.2,4.8,6.4,8.0\}$, $\mathtt{nfit}=10$ and picks the smallest-AR cell whose peak count does not exceed npmax. As a consequence, the user has to set only npmax manually. A suitable npmax can be set from domain knowledge (e.g., expected maximum signal numbers in blood or urine spectra) or chosen by maximizing downstream classification performance in cases where class labels are available (Section 2.5.2).

The 60-cell grid above was chosen by deconvoluting representative blood and urine spectra over a broader candidate grid, visually inspecting the resulting Lorentzian reconstructions, and trimming the grid to the values that consistently produced plausible fits. The delta step of $1.6$ was picked so that the previous hand-tuned default $\mathtt{delta}=6.4$ falls on a grid point. Users who want finer control can supply their own parameter grid.

When neither domain knowledge nor class labels are available, passing $\mathtt{npmax}=-1$ derives the value from the data as the elbow of the curve relating AR to the number of fitted signals, located with the Kneedle heuristic [28] (Appendix G).

2.5.2. Supervised Parameter Optimization

When class labels are available, npmax, maxShift and maxCombine can be optimized jointly by maximizing classification performance on the resulting feature matrix. Because the same metabolites may not be detectable in all spectra, zeros in the feature matrix encode “missing signal” rather than “zero area”. Linear models confound these zeros with small observed values and become unstable. Therefore, a non-linear random forest classifier from the ranger package [29] was used. It can partition based on the presence of a signal as well as based on its magnitude. Random forests also performed well in a systematic comparison of classification algorithms on metabolic ¹H NMR fingerprints [30]. A further advantage of random forests is the out-of-bag (OOB) error [31], a generalization-error estimate obtained during training itself. The OOB error does not require an extra held-out split or inner cross-validation loop. The two alignment parameters, maxShift (CluPA tolerance) and maxCombine (snap-to-ref window width), are governed by different sources of positional error, and their empirical optima do not necessarily coincide, so tuning them jointly is in general not redundant. All three parameters can therefore in principle be swept as a three-dimensional grid via the supervised search in fit_mdm().

In practice, tuning all three at once is usually not recommended, as the runtime grows multiplicatively with the size of each axis, and the deconvolution and CluPA stages dominate that cost. Instead, the following two-step procedure is recommended:

1.

Pick npmax from domain knowledge (e.g., urine spectra typically contain more metabolites than blood), by visual inspection of a representative deconvolution (Section 2.5.1), or by setting $\mathtt{npmax}=-1$ to leave it to the elbow heuristic [28] of Appendix G.

2.

Rely on CluPA’s internal optimum by setting $\mathtt{maxShift}=-1$. This triggers an adaptive sweep that doubles maxShift through $\{1,2,4,8,\dots \}$, runs CluPA at each step, computes the average pairwise Pearson correlation of the aligned Lorentzian superpositions, and stops one step before that correlation first decreases.

The supervised search is then reduced to a one-dimensional sweep over maxCombine, which is by far the cheapest of the three stages to rerun.

fit_mdm() relies on caching and multiprocessing to keep its runtime reasonable. Three optimizations are combined:

1.

Each npmax value has an associated set of per-spectrum deconvolution parameters that give the lowest reconstruction error. Finding them requires an internal grid search per spectrum, which is run once at function entry and attached to each spectrum. Whenever npmax changes, the optimal parameters can be looked up instead of repeatedly recomputed.

2.

The grid is traversed with npmax varying slowest, then maxShift, then maxCombine. If npmax is unchanged between two rows, the deconvolution of the previous row is reused instead of recomputed; if npmax and maxShift are both unchanged, the CluPA alignment is reused as well.

3.

Deconvolution, alignment, and fitting use several workers each. Parallelization is done with respect to spectra and not with respect to grid rows to keep memory low. Parallelization over grid rows would force every worker to hold a copy of all spectra, whereas for parallelization over spectra, each worker only holds the spectra it is currently processing.

3. Results

3.1. Deconvolution Quality on Sim3: Metabodeconplus vs. MetaboDecon1D and Grid Search

Deconvolution quality was scored with PRARPX as defined in the materials and methods section. To this end, a simulated dataset Sim3 (see Table 2 for details) was used. Note that this simulated dataset also contained noise to approximate a realistic experimental data set. Each of the 100 Sim3 spectra was deconvoluted with MetaboDecon1D (default parameters), metabodeconplus (default parameters), and metabodeconplus with unsupervised grid-search parameter selection at $\mathtt{npmax}\in \{10,15,20,25,30,35,40\}$. The signal-free region was auto-derived per spectrum so that all methods saw equivalent inputs. Note that PRARPX is computed from ground-truth Lorentzian parameters, whereas the general grid search parameter optimization has to operate on the Area Ratio alone.

Table 3. PRARPX summary on the Sim3 dataset across all spectra: mean, standard deviation, minimum, and maximum for each configuration. Bold marks the best achievable (mean, SD) pair (highest mean, ties broken by smallest SD); the metabodeconplus optimal row is excluded from this comparison.

Configuration	Mean	SD	Min	Max
MetaboDecon1D (default)	0.712	0.041	0.610	0.814
metabodeconplus (default)	0.791	0.037	0.691	0.872
metabodeconplus (npmax = 10)	0.734	0.045	0.593	0.833
metabodeconplus (npmax = 15)	0.734	0.045	0.593	0.833
metabodeconplus (npmax = 20)	0.751	0.030	0.661	0.833
metabodeconplus (npmax = 25)	0.801	0.041	0.693	0.876
metabodeconplus (npmax = 30)	0.796	0.044	0.654	0.876
metabodeconplus (npmax = 35)	0.796	0.044	0.654	0.876
metabodeconplus (npmax = 40)	0.796	0.044	0.654	0.876
metabodeconplus (optimal)	0.812	0.032	0.745	0.876

summarizes PRARPX (mean, SD, min, max) across all spectra for each configuration, and Figure 3 plots the per-spectrum trace. The default metabodeconplus configuration already improved on MetaboDecon1D, and the grid-search cutoff at moderate npmax closed part of the remaining gap to the metabodeconplus optimal bound. The gap is smallest at $\mathtt{npmax}=25$; smaller and larger budgets are both worse, and each settles onto a plateau (Table 3).

Even with the metabodeconplus optimal parameters, an ideal value of $\mathrm{PRARPX}=1$ is not reached for two reasons. First, the superposition of the estimated noiseless Lorentzian signals cannot fully reproduce the noisy observation. Figure A2A illustrates this. Second, small signals completely shadowed by larger neighbors produce no detectable curvature minimum and are therefore not recovered, so $\mathrm{PRX}<1$ for ordinary spectra (Figure A2B).

3.2. Alignment Quality on Sim3: CluPA and snap_to_ref

Every Sim3 spectrum contains the same 25 simulated signals named A–Y at known positions, and the first spectrum was simulated without any per-spectrum jitter or global shift, so it serves as the unshifted reference. This allows alignment quality to be quantified directly. For each extracted peak, it was recorded which of these 25 simulated signals it corresponded to: a peak whose fitted center lay within ±2 data points of a simulated position inherited that signal’s name; a peak farther away from any simulated position was labeled Z (a spurious detection). Labels are assigned to the raw deconvolution output, before any alignment. Therefore, each peak carries the identity of the simulated source it came from through the rest of the pipeline.

Deconvolution with default parameters returns 18–22 peaks per Sim3 spectrum over the $0.15$ ppm interval holding its 25 simulated signals. On 100 windows of that width drawn at random from the analyzed regions of the urinary AKI spectra, it returns 0–47 (median 23), so the average simulated signal density is typical of real experimental spectra, although this also shows that real experimental spectra contain especially challenging regions with a very high signal density.

CluPA moves whole spectrum segments by a common integer offset, so peaks may not be matched exactly. snap_to_ref() then moves each peak to the nearest peak column of the unshifted reference spectrum, dropping peaks with no such column within maxCombine datapoints. A signal counts as recovered when the reference spectrum carries a fitted peak within two datapoints of its simulated position, and only recovered signals have a reference column, so how many columns exist is a property of the deconvolution and is stated per panel. A (spectrum, signal) pair counts as correct when its reference column receives that signal’s peak and no other. The fraction of correct pairs over the 100 spectra and the reference columns of the panel is the snap purity reported in Figure 4.

Results show that the snap purity is highest where CluPA has already brought peaks within a small maxCombine window of their reference columns. Widening the window past that point costs essentially nothing only when the deconvolution recovers every reference signal and fits no spurious Lorentzians so that no peak is available to be mis-snapped: at $\mathtt{npmax}=25$, purity is flat at $94\%$ out to $\mathtt{maxCombine}=64$ ($0.0$ points, Figure 4a). If either condition fails, i.e., signals are missed ($\mathtt{npmax}=15$, Figure 4b) or spurious Lorentzians are fitted, due to a modified noise threshold ($\mathtt{delta}=1.6$, Figure 4c), peaks are swept onto wrong reference neighbors and a clear valley appears, costing $2.0$ and $11.5$ points by $\mathtt{maxCombine}=64$; it is deepest in (c), where on average, $30.5$ peaks are fitted per spectrum against 25 simulated ones, so correspondingly more peaks can be swept into an occupied column.

3.3. Supervised Parameter Optimization on Sim3

In the following, it was investigated whether the supervised classification-based search described in Section 2.5.2, where class labels are known, is feasible. To this end, a 5000-tree ranger probability forest was run over a small grid. The grid spans all three parameters ($\mathtt{npmax}\in \{10,15,20,25,30,35,40\}$, $\mathtt{maxShift}\in \{2,4,8,16,32\}$, $\mathtt{maxCombine}\in \{1,5,10\}$). This Sim3 sweep is the only instance where all three parameters were tuned at once. The small spectrum count and coarse grid keep the runtime under a few minutes. This made it possible to analyze whether the supervised optimum of parameters obtained here is consistent with the unsupervised one. The grid search selected $\mathtt{npmax}=20$, $\mathtt{maxShift}=16$, $\mathtt{maxCombine}=5$ as the best combination (OOB accuracy $70\%$, OOB AUC $68.8\%$). Applied to the held-out 50 test spectra, this configuration achieved a test accuracy of $68\%$ and AUC of $80.0\%$. Of the top-10 features ranked by ranger permutation importance, 3 fall within 3 datapoints of a discriminative signal.

The supervised optimum $\mathtt{npmax}=20$ is close to, but not identical with, the unsupervised optimum $\mathtt{npmax}=25$ of Section 3.1. The supervised search optimizes classification accuracy, the unsupervised one reconstruction fidelity, so the two criteria need not select the same value. In contexts where signal recovery rather than classification accuracy is the criterion of interest, $\mathtt{npmax}$ is more naturally set to a prior upper bound on the expected signal count than tuned by the supervised search.

Data show that automated parameter optimization selects a working configuration, reaching an out-of-bag accuracy of 70%. As can be seen from Figure 5a, classification performance depends strongly on the parameter settings: only 1 of the 105 combinations attains that value. Figure 5b shows that the true discriminatory features are among the most informative features picked by the classification algorithm [29,31]. The fact that other features are also considered by the classification algorithm is due to the fact that the three discriminatory features of group A were up- and downscaled only very moderately. Furthermore, a per-signal amplitude scaling and the addition of Gaussian noise were performed on the Sim3 data set as described in the Study cohorts section. As can be seen from Figure 5c, the three discriminatory signals are of only moderate intensity and show partial overlap with other signals. Therefore, the Sim3 dataset provides a challenging realistic example.

3.4. End-to-End Prediction Performance on the AKI Dataset

The end-to-end predictive performance was evaluated on the AKI dataset (34 AKI versus 72 control urinary spectra, creatinine-normalized) by comparing three models. The first was an equidistant-binning baseline that mirrors the fixed-bin feature representation originally used by Zacharias et al. [25], who introduced the AKI dataset. To this end, a 700-bin feature matrix consisting of 300 bins covering $6.5$–$9.5$ ppm and 400 bins covering $0.5$–$4.5$ ppm (at a fixed bin width of $0.01$ ppm) was used. Zacharias et al. [25] employed a support-vector machine (SVM) for classification. For the current contribution, the SVM was replaced with a ranger-based random forest [29,31,32] run in probability mode (one class probability per sample). This matched the classifier used by the metabodeconplus pipeline and ensured a fair comparison.

The second was the full metabodeconplus pipeline: deconvolute → CluPA → snap_to_ref → ranger, with $\mathtt{npmax}=-1$. The third was speaq 2.0 [11], the only tool of Table 1 that extracts features without a metabolite reference library and runs unattended from R, so that it can be driven from the same cross-validation harness. Its wavelet based peak detection, peak grouping and feature-matrix construction were run on the same $0.5$–$4.5$ and $6.5$–$9.5$ ppm windows at package defaults, except for the baseline threshold, which was lowered from 1000 to 100 because it is an absolute intensity cut-off and the creatinine-normalized AKI spectra are about three orders of magnitude smaller than the data speaq’s default is calibrated for. This yielded 426 cross-sample peak groups, classified with the same ranger setup on the same folds.

For metabodeconplus, npmax was left to the elbow heuristic of Appendix G by setting it to $-1$, which resolves to an npmax of 1117 on the full AKI dataset and to 1105–1130 across the 30 training folds. The test further relies on CluPA’s internal optimum for $\mathtt{maxShift}$, again by setting it to $-1$ (see Section 2.5.2), so that only $\mathtt{maxCombine}$ is swept on the training fold of each cross-validation split via the inner grid-search in fit_mdm(). At the maxCombine selected on the full AKI dataset for optimal classification performance ($\mathtt{maxCombine}=2$), snapping discards $63.8$% of the $111,494$ Lorentzians fitted on all spectra of the dataset and merges $0.1$%; across $\mathtt{maxCombine}$ from 1 to 32, the discard rate runs from $74.0$% to $2.2$% while accuracy and AUC stay flat (Figure A5).

Predictive performance was estimated by stratified 10-fold cross-validation repeated over three random seeds (30 folds in total per model). Each fold’s training portion was independently re-fit before scoring on the held-out fold, and standard errors are taken across folds. The binning baseline reached 75.4 ± 2.33% accuracy and AUC = 0.810 ± 0.027; metabodeconplus reached 73.7 ± 2.20% and AUC = 0.827 ± 0.025, thus matching the binning baseline with no significant loss or gain in accuracy or AUC, while operating on a higher-resolution feature matrix whose columns correspond to individually localized signals rather than fixed-width bins. Paired over the 30 shared folds, none of the three representations differs significantly from another in terms of accuracy or AUC (smallest Holm-adjusted $p=0.69$ [33],

Table A3. Fold-wise paired comparison of the three feature representations over the 30 shared folds. $\Delta$ is the mean difference, with a paired t-test and Holm correction across the family.

Comparison	Metric	$\mathbf{\Delta }$	95% CI	t-Test	Wilcoxon
metabodeconplus vs. binning	Accuracy (pp)	$-1.7$	$[-6.2,+2.9]$	1.00	0.96
metabodeconplus vs. speaq 2.0	Accuracy (pp)	$-2.9$	$[-6.5,+0.8]$	0.69	0.80
speaq 2.0 vs. binning	Accuracy (pp)	$+1.2$	$[-1.5,+3.9]$	1.00	0.96
metabodeconplus vs. binning	AUC	$+0.017$	$[-0.020,+0.053]$	1.00	0.96
metabodeconplus vs. speaq 2.0	AUC	$+0.013$	$[-0.019,+0.044]$	1.00	0.96
speaq 2.0 vs. binning	AUC	$+0.004$	$[-0.018,+0.026]$	1.00	0.96

).

On the same folds, speaq 2.0 reached 76.6 ± 2.01% and AUC = 0.814 ± 0.024. The figures obtained by speaq 2.0 are not directly comparable with those of the other two approaches, which already differ in what a feature measures: a bin sum, a wavelet peak height, and a fitted line-shape integral. The peak grouping is a cohort-level clustering with no per-fold equivalent, so the speaq feature columns were defined once on the whole cohort, whereas the binning and metabodeconplus features are re-derived inside every training fold; this favors speaq. For the same reason, a fitted speaq model cannot be applied to a new sample without re-clustering the cohort and re-training.

To compare the features selected by the binning and metabodeconplus models, both were refitted on the full AKI dataset and their ranger permutation importances extracted. The top 20 features of each were overlaid on the alignment reference spectrum: Figure 6 shows the $1.5$–$1.0$ ppm section, Appendix E the full range.

On its higher-resolution, per-signal feature matrix, metabodeconplus performed on par with the binning model. One main advantage of using a deconvolution approach is that each selected feature is localized at a single deconvoluted signal of the reference spectrum rather than spanning a fixed-width bin. This, in principle, allows for an unambiguous metabolite assignment of selected features. Note that this feature assignment step is not part of the metabodeconplus package. For assignment of deconvoluted signals, a comparison with database spectra of pure compounds measured under similar conditions is required. Once feature assignment has been done by external approaches, predictive signatures may be transferred to other methods from, for example, clinical chemistry. In addition, this allows for a biological interpretation of obtained signatures. In this context, it should be noted that predictive signatures only provide correlations between metabolites and groups of specimens; they do not provide causal relationships.

Whereas, as can be seen from Figure 6, for the binning model, a bin may contain contributions from multiple signals and metabolites, which substantially hinders assignment of predictive signatures to corresponding metabolites.

3.5. Runtime Performance and Parallel Scaling

The per-spectrum, single-core runtime of the original MetaboDecon1D implementation (Figure 7A); the R implementation of the new metabodeconplus package (Figure 7B); and the Rust backend of metabodeconplus as activated from within the R environment (Figure 7C) were compared. To this end, spectra with a different number of data points ($2^{11}$ to $2^{17}$) and signal counts ($2^4$ to $2^{12}$) were simulated. Typical 1D ¹H spectra of biofluids such as urine and plasma consist of $2^{16}$ to $2^{17}$ data points with approximately 1000 signals. For the original MetaboDecon1D implementation, this resulted in an average runtime of around 40 s at $2^{17}$ data points (Figure 7A). In the R implementation of the new metabodeconplus package, the runtime is substantially reduced to well below one second per spectrum in this regime (Figure 7B). The Rust backend (Figure 7C) provides a further speed-up that becomes most pronounced for densely packed spectra: at $2^{17}$ data points and 4096 signals, the deconvolution takes around $3.7$ s in pure R but only around $2.4$ s with Rust, while at the more typical $\approx 1000$ signals, the two backends are essentially indistinguishable on a single spectrum. Panels A–C of Figure 7 are single-core single-spectrum measurements; parallelization across spectra is shown separately in Figure 7D, showing the deconvolution times of all 106 AKI spectra with respect to the degree of parallelization (1 to 10 parallel workers) for both the R and Rust backend. Runtime scales close to the ideal $1/k$ reference throughout the measured range, with the Rust backend completing the full 106-spectrum batch in under 6 s on 10 workers and the R implementation in under 8 s. These short runtimes make it tractable to determine the optimal deconvolution parameters for each dataset individually by systematic grid search.

Because deconvolution is performed independently for each spectrum, with no shared state or inter-spectrum dependencies, total runtime scales linearly with the number of spectra, subject to the near-ideal $1/k$ speed-up of Figure 7D. A tenfold-replicated AKI cohort of 1060 spectra completed in 52 s with the Rust backend at $\mathtt{nworkers}=10$, against the 60 s predicted by linear scaling from the 106-spectrum measurement ($6.0$ s), i.e., marginally faster than linear.

These figures cover deconvolution, the only stage that is independent per spectrum. Memory consumption is likewise linear in the size of the spectra. The per-peak bookkeeping cannot introduce a separate scaling term, since the number of detectable peaks is bounded by one third of the number of data points and is far lower in practice, while the storage per peak is a small constant. The total footprint therefore grows linearly with the number of spectra held in memory. Peak resident memory should be read as an upper bound rather than as the requirement of the algorithm, as R’s garbage collector does not deterministically return freed memory to the operating system. Measured on the replicated cohort for a single worker, where the peak is attributable to one process, the 1060 spectra occupy $2.1$ GiB and the peak resident memory reaches $8.0$ GiB, i.e., $3.8$ times the size of the loaded spectra; repeated runs on identical input agreed to within 12%.

Because of R’s garbage collector, this is an upper bound rather than the requirement of the algorithm, and allows a workstation with 32 GiB of RAM to be used without swapping.

As a concrete example, the following costs were measured on the 106 AKI spectra with the pure-R backend, given as a single-core cost with the observed wall-clock time at $\mathtt{nworkers}=56$ in parentheses. The 60-cell deconvolution grid that fit_mdm() evaluates once at entry costs 40 min (57 s), and alignment, the adaptive $\mathtt{maxShift}=-1$ sweep plus the CluPA pass that follows it, costs 14 min (60 s). A complete fit_mdm() call with $\mathtt{npmax}=-1$, $\mathtt{maxShift}=-1$ and 5 maxCombine values costs 56 min ($2.2$ min). The single-core figures are CPU times of the parallel runs and therefore include parallelization overhead.

4. Discussion

With metabodeconplus, a single end-to-end workflow for the analysis of 1D NMR fingerprinting data of complex biofluids is provided, requiring no prior knowledge of the individual molecules present. The workflow integrates three steps that previously required separate tools: deconvolution of overlapping signals into individual Lorentzian lines, alignment of the deconvoluted signals, and sample classification, tied together by an automated parameter search. Results showed that, with the new implementation of the deconvolution algorithm, a substantial improvement in runtime could be obtained. With this, the deconvolution of large datasets containing several hundred spectra becomes feasible. This is especially true when the Rust implementation of the deconvolution part is used. This substantial improvement in runtime permits a systematic search of optimal deconvolution and alignment parameters. To analyze the performance of metabodeconplus in terms of signal detection and deconvolution, a carefully designed challenging simulated data set was used, where the ground truth is known. It was shown that metabodeconplus facilitates a reliable signal detection and deconvolution of overlapping signals in complex data. The residual gap to $\mathrm{PRARPX}=1$ on the simulated data is dominated by small signals shadowed by larger neighbors (suppressing PRX); the additive-noise floor alone (raising AR above zero) caps PRARPX only at $0.999$, as detailed in Section 3.1 and illustrated in Figure A2. Deconvolution quality depends on appropriate parameter selection. To this end, a grid search procedure was devised to search the parameter space by optimizing the Area Ratio. However, especially for complex experimental spectra, it is not guaranteed that this will always lead to an optimal selection. One critical parameter is the expected maximal number of signals npmax that ensures that there are not a large number of spurious Lorentzians that are fitted. For experimental data such as urine and plasma spectra, the maximum number of expected signals can be set from prior knowledge, or left to the elbow heuristic of Appendix G by passing $\mathtt{npmax}=-1$. To make full use of the deconvoluted data in subsequent statistical analysis proper signal alignment is required to correct for small variations in signal positions across spectra. For alignment, the well-established CluPA algorithm is employed. It was extended by the snap_to_ref function to ensure that corresponding peaks are put to the exact same position. As was shown, this in general provides good alignment. However, alignment quality depends on the two parameters maxShift and maxCombine. These, together with npmax, may be manually set by the user after careful spectra inspection. In addition, an automated supervised grid search via fit_mdm() was devised that in principle allows all three parameters to be tuned jointly. For this, two well-separable classes with known class labels are required. In practice, it is recommended, as mentioned above, to fix npmax from domain knowledge or visual inspection or automatically based on the so-called elbow heuristic, leaving maxShift to the adaptive CluPA-internal sweep, and to tune only maxCombine on the labeled data; this avoids the multiplicative runtime of the full three-dimensional grid without sacrificing classification performance. The higher spectral resolution and interpretability of the signal-based feature matrix were achieved without loss of predictive performance. The classification performance of metabodeconplus matched the equidistant-binning baseline. This, in principle, allows each discriminatory feature to be assigned to an individual metabolite. This is often not possible with a coarse bin, which potentially contains contributions from several signals. The cross-sample peak groups of speaq 2.0 [11] classified as well as either of them (Section 3.4), but a peak group, like a bin, is a position on the chemical-shift axis without a fitted line shape, and it is defined on the cohort analyzed, so a speaq model does not transfer to a new sample without re-clustering.

Limitations: Direct file-format support is restricted to Bruker and JCAMP-DX; other vendor formats are not parsed natively. Users can, however, provide spectra as a chemical-shift vector and a corresponding signal-intensity vector, so any format that can be loaded into the R session is usable. Native readers for further vendor formats remain as future work. No routines are provided to group deconvoluted signals into multiplet structures, and no automatic signal-to-metabolite assignment (e.g., matching against reference spectra) is included. Finally, PRARPX has a hard upper bound below 1 on noisy spectra: additive measurement noise keeps $\mathrm{AR}>0$, and signals completely overlapped by larger neighbors produce no detectable curvature minimum and are therefore not recovered (Figure A2). The set of experimental data sets used for testing the metabodeconplus package is limited. However, the urinary AKI dataset used represents a challenging test case. In comparison to serum, plasma, and tissue extracts, urine spectra generally contain more signals, leading to increased signal overlap, which makes them a real challenge for deconvolution. Furthermore, signal shifts across spectra are usually larger in urine than in serum, plasma, or tissue extracts, making urine a challenging matrix for signal alignment. Therefore, it is safe to expect that metabodeconplus will also perform well for other sample matrices. However, a broader validation employing additional urine and plasma cohorts would clearly strengthen this claim. All spectra used here were measured at a ¹H resonance frequency of 600 MHz. For spectra measured at substantially lower resonance frequencies, increased signal overlap is expected, which in some cases might lead to complete shadowing and therefore incomplete deconvolution of some smaller signals.

5. Conclusions

In summary, metabodeconplus makes 1D NMR fingerprinting a single automated workflow (from deconvolution through alignment to classification) with automated parameter optimization and a fast, parallelized backend that makes this end-to-end pipeline practical at the scale of modern metabolomics cohorts. For example, metabodeconplus could be applied to questions like the integrated use of microbiome and urinary metabolome data to predict secondary infection in critically ill patients, as described in [34].