% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/utils_nmr_qc.R
\name{noise_sd}
\alias{noise_sd}
\title{Estimate Noise Standard Deviation in 1D NMR Spectra}
\usage{
noise_sd(
  X,
  ppm = NULL,
  where = c(14.6, 14.7),
  method = c("mad", "sd", "p95"),
  baseline_correct = FALSE,
  lambda = 10000,
  min_points = 50L,
  ns = NULL,
  normalise_scans = FALSE
)
}
\arguments{
\item{X}{Numeric matrix (spectra in rows), numeric vector (single spectrum), or a named list
as returned by \code{\link{read1d}}/\code{read1d_proc} containing \code{X}, \code{ppm}, and \code{meta}.}

\item{ppm}{Numeric vector of chemical shift values (ppm) corresponding to columns of \code{X}.
If \code{NULL}, \code{ppm} is inferred in the following order:
\enumerate{
\item \code{X$ppm} if \code{X} is a list input,
\item \code{attr(X, "m8_axis")$ppm} (if present),
\item numeric \code{colnames(X)} (if present).
}}

\item{where}{Numeric vector of length 2. ppm range used for noise estimation.
Should be free of metabolite signals (default \code{c(14.6, 14.7)}).}

\item{method}{Character. Noise estimator: \code{"mad"} (default), \code{"sd"}, or \code{"p95"} (legacy amplitude).}

\item{baseline_correct}{Logical. If \code{TRUE}, subtract a smooth baseline in the noise window
using asymmetric least squares (\code{\link[ptw]{asysm}}). Default \code{FALSE}.}

\item{lambda}{Numeric. Smoothing parameter for \code{\link[ptw]{asysm}} when \code{baseline_correct = TRUE}.}

\item{min_points}{Integer. Minimum number of points required in the noise window.
May be a single value (recycled across spectra) or a numeric vector of
length \code{nrow(X)}. If \code{X} is a list input as returned by
\code{\link{read1d}}/\code{read1d_proc} and \code{ns} is \code{NULL},
the function attempts to extract the number of scans from
\code{X$meta$a_NS} when available.}

\item{ns}{Number of scans / transients (required if normalise_scans=TRUE)}

\item{normalise_scans}{Logical. If \code{TRUE}, noise estimates are
multiplied by \eqn{\sqrt{NS}} to account for the theoretical scaling
of noise with the number of scans (\eqn{\sigma \propto 1/\sqrt{NS}}).
This is useful when comparing noise levels across spectra acquired
with different numbers of scans. Default is \code{FALSE}.}
}
\value{
Numeric vector of noise estimates (length \code{nrow(X)}).
}
\description{
Estimates the noise standard deviation (\eqn{\sigma}) for each spectrum from a signal-free ppm region.
The default estimator is robust (MAD-based) and suitable for signal-to-noise calculations.
}
\details{
In NMR spectroscopy, noise scales predictably with the number of scans (\eqn{NS}).
For otherwise identical acquisition settings:

\itemize{
\item Signal increases approximately proportional to \eqn{NS}.
\item Noise increases approximately proportional to \eqn{\sqrt{NS}}.
\item Consequently, signal-to-noise ratio (SNR) increases proportional to \eqn{\sqrt{NS}}.
}

Equivalently, the noise standard deviation scales as:

\deqn{\sigma(NS) \propto \frac{1}{\sqrt{NS}},}

assuming a fixed underlying signal scale and comparable acquisition conditions.

To compare noise levels across datasets acquired with different numbers of scans,
a scan-normalised noise estimate may be used:

\deqn{\sigma_{\mathrm{norm}} = \sigma \cdot \sqrt{NS}.}

Under stable receiver gain and processing conditions, this normalised noise
should be approximately constant across runs.
}
\examples{
data(hiit_raw)
X <- hiit_raw$X
ppm <- hiit_raw$ppm
sigma <- noise_sd(X, ppm, where = c(10,11))
plot(hiit_raw$meta$a_NS, sigma,
  xlab = "Number of scans (NS)",
  ylab = expression(sigma~"(noise estimate)"),
   pch = 16)
 lines(lowess(hiit_raw$meta$a_NS, sigma), col = "red", lwd = 2)
}
