% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/io_read1d_raw.R
\name{read1d_raw}
\alias{read1d_raw}
\title{Read raw FIDs and process to spectra}
\usage{
read1d_raw(
  path,
  exp_type = list(exp = "PROF_PLASMA_CPMG128_3mm", pulprog = "noesygppr1d"),
  apodisation = list(fun = "exponential", lb = 0.2),
  zerofill = 1L,
  mode = c("absorption", "dispersion", "magnitude"),
  verbose = 1,
  recursive = TRUE,
  n_max = 1000,
  filter = TRUE,
  to_global = FALSE
)
}
\arguments{
\item{path}{Character. Path to the root directory containing Bruker experiment folders.}

\item{exp_type}{Named list. Acquisition-parameter filter to select experiments
(e.g., \code{list(PULPROG = "noesygppr1d")}).}

\item{apodisation}{Named list. Apodisation function and parameters. \code{fun}
must be one of \code{"exponential"}, \code{"cosine"}, \code{"sine"}, \code{"sem"}.}

\item{zerofill}{Integer. Zero-filling exponent (\code{1} doubles points, \code{2} quadruples, …).}

\item{mode}{Character. Spectrum type to return: \code{"absorption"}, \code{"dispersion"}, or \code{"magnitude"}.}

\item{verbose}{Integer. Verbosity level: \code{0} = silent, \code{1} = summary (default),
\code{2} = detailed, \code{3} = debug.}

\item{recursive}{Logical. Recursively search subdirectories for FIDs.}

\item{n_max}{Integer. Maximum number of experiments to process.}

\item{filter}{Logical. Remove experiments with incomplete file structures.}

\item{to_global}{Logical. If TRUE, objects are also assigned to the global
environment; otherwise, only an invisible list is returned.}
}
\value{
A named list with three elements:
\describe{
\item{X}{A numeric matrix of spectra (rows = samples, columns = ppm values).}
\item{ppm}{A numeric vector of chemical-shift axis (ppm).}
\item{meta}{A data frame of acquisition metadata, row-aligned with \code{X}.}
}

If \code{to_global = TRUE}, these objects are also assigned to the global environment.
In that case, any existing objects with the same names will be overwritten.
}
\description{
Reads Bruker 1D NMR FIDs, corrects the digital filter (group delay),
applies apodisation (windowing), optional zero-filling, FFT, phasing and
ppm calibration.

Returns either absorption-, dispersion-, or magnitude-mode
spectra.

If \code{to_global = TRUE}, objects are assigned to the global environment.
}
\details{
FIDs are read from Bruker acquisition folders and processed by the following pipeline:
\enumerate{
\item Digital-filter (group-delay) correction: the initial \emph{n} complex points
are invalid due to the causal DSP decimation filter and are discarded; \emph{n}
equals \code{GRPDLY} when present, or is looked up from Bruker tables indexed by
\code{DECIM} and \code{DSPFVS} on older systems.
\item Apodisation (windowing).
\item Zero-filling (optional).
\item FFT to the frequency domain.
\item Phase correction.
\item PPM calibration (e.g., to TSP).
}
A common ppm scale is then interpolated across spectra.

\strong{Digital filter note:} On newer systems \code{GRPDLY} is written in \code{acqus}/\code{acqu2s}
and should be used directly. For older data sets (\code{GRPDLY < 0} or missing), the group delay
is derived from \code{DECIM} and \code{DSPFVS} via an internal look-up table.

\strong{Apodisation functions}:
\itemize{
\item \code{"uniform"}
\item \code{"cosine"},
\item \code{"sine"},
\item \code{"exponential"} (parameter: \code{lb})
\item \code{"sem"} (sine * exponential, parameter: \code{lb})
\item \code{"gauss"} (parameter: \code{lb}, \code{'gb'}, and \code{'para'})
\item \code{"expGaus_resyG"} (parameter: \code{lb}, \code{'gb'}, and \code{'aq_t'})
}
}
\examples{
path <- system.file("extdata", package = "metabom8")
read1d_raw(
  path,
  exp_type    = list(PULPROG = "noesygppr1d"),
  apodisation = list(fun = "exponential", lb = 0.2),
  zerofill    = 1,
  n_max       = 3
)

}
\seealso{
\code{\link{read1d_proc}} for importing TopSpin-processed spectra
}
