% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/preproc_correct_lw.R
\name{correct_lw}
\alias{correct_lw}
\title{Linewidth correction by scaling spectra to a reference linewidth}
\usage{
correct_lw(
  x,
  lw_ref = 0.8,
  beta = 0.6,
  shift = c(-0.1, 0.1),
  ppm = NULL,
  sf = NULL,
  estimate_beta = TRUE,
  beta_min_n = 6,
  only_if_improves = TRUE,
  notes = NULL
)
}
\arguments{
\item{x}{A numeric matrix (samples x variables) or a named list containing
\code{X}, \code{ppm}, and optionally \code{meta}.}

\item{lw_ref}{Numeric reference linewidth (FWHM) to which spectra are
normalized. If \code{NULL}, the median linewidth across samples is used.}

\item{beta}{Numeric exponent governing the linewidth-to-height relationship.
Ignored if \code{estimate_beta = TRUE} and sufficient samples are available.}

\item{shift}{Numeric vector of length 2 specifying the ppm region used for
linewidth estimation and peak height measurement (e.g. \code{c(-0.1, 0.1)}
for TSP).}

\item{ppm}{Optional numeric ppm axis. If \code{NULL}, inferred from
\code{attr(X, "m8_axis")$ppm} or numeric \code{colnames(X)}.}

\item{sf}{Optional spectrometer frequency (MHz). If \code{NULL}, obtained from
\code{meta$a_SFO1} in list input or \code{attr(X, "m8_meta")$a_SFO1}.}

\item{estimate_beta}{Logical; if \code{TRUE}, estimate \code{beta} from a
log-log regression of reference peak height versus FWHM.}

\item{beta_min_n}{Minimum number of valid samples required to estimate
\code{beta}.}

\item{only_if_improves}{Logical; if \code{TRUE}, apply correction only if the
CV of the reference peak height decreases after correction.}

\item{notes}{Optional character string appended to the preprocessing log.}
}
\value{
An object of the same type as input:
\itemize{
\item If input is a matrix, returns a corrected matrix with attributes
preserved and updated.
\item If input is a list, returns the same list with corrected \code{$X}.
}
}
\description{
Applies a multiplicative correction to each spectrum to compensate for
linewidth-induced peak height variation, using a reference peak region
(e.g. TSP). The correction assumes an empirical power-law relationship
between peak height and linewidth:
}
\details{
\deqn{I \propto \mathrm{FWHM}^{-\beta}}

Spectra are scaled such that all samples are adjusted to a common reference
linewidth \code{lw_ref}:

\deqn{X_{\mathrm{adj}} = X \cdot \left(\frac{\mathrm{FWHM}}{lw_{\mathrm{ref}}}\right)^{\beta}}

where FWHM is estimated per spectrum within the specified \code{shift}
region (typically containing an internal reference signal).

If \code{estimate_beta = TRUE}, the exponent \code{beta} is estimated from a
log-log regression between peak height (max within \code{shift}) and FWHM
across samples. Otherwise, the user-supplied \code{beta} is used.

The correction is only applied if it reduces the coefficient of variation (CV)
of the reference peak height across samples when \code{only_if_improves = TRUE}.

Input may be either:
\itemize{
\item a numeric matrix \code{X} (samples x variables), with ppm axis supplied
via \code{attr(X, "m8_axis")$ppm} or numeric \code{colnames(X)}, or
\item a named list with elements \code{X}, \code{ppm}, and optionally \code{meta}.
}

Attributes \code{"m8_prep"}, \code{"m8_axis"}, and \code{"m8_meta"} are
preserved and the applied correction is appended to the preprocessing log
via \code{.m8_stamp()}.

This correction removes systematic peak height variation due to spectral
broadening (e.g. shimming differences) under the assumption that the internal
reference signal has constant concentration across samples. The exponent
\code{beta} reflects the empirical sensitivity of peak height to linewidth
in the current acquisition and processing regime.

This adjustment improves comparability of signal intensities across spectra
by reducing linewidth-induced amplitude bias, thereby enhancing the
detectability of small effects in downstream multivariate analyses
(e.g. PLS-type models).
}
\examples{
data(covid_raw)
# matrix input with ppm in m8_axis
Xcor <- correct_lw(covid_raw, shift = c(-0.1, 0.1))

}
\seealso{
\code{\link{lw}}

Other preprocessing: 
\code{\link{align_segment}()},
\code{\link{align_spectra}()},
\code{\link{binning}()},
\code{\link{calibrate}()},
\code{\link{correct_baseline}()},
\code{\link{pqn}()},
\code{\link{print_preprocessing}()}
}
\concept{preprocessing}
