% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/char_pretreatment.R
\name{char_pretreatment}
\alias{char_pretreatment}
\title{Interpolate and pretreat a charcoal time series}
\usage{
char_pretreatment(
  char_data,
  site,
  pretreatment,
  results = NULL,
  plot_data = 1L
)
}
\arguments{
\item{char_data}{Numeric matrix (n x 6+): cmTop, cmBot, ageTop, ageBot,
charVol, charCount. Rows sorted youngest-first (ascending ageTop).}

\item{site}{Character string; site name used in diagnostic messages.}

\item{pretreatment}{Named list with elements:
\describe{
  \item{zoneDiv}{Numeric vector of zone boundaries (cal. yr BP),
    strictly ascending, at least 2 values.}
  \item{yrInterp}{Resampling interval (yr).  0 = use median raw
    resolution (auto).}
  \item{transform}{Integer: 0 = none; 1 = log10(x+1); 2 = ln(x+1).}
}}

\item{results}{Named list; only \code{allFigures} is referenced.
Pass \code{NULL} to suppress any plot-related behaviour (no plots are
produced in the R implementation in Phase 1).}

\item{plot_data}{0/1 integer flag.  Ignored in R (no diagnostic plots);
included for API symmetry with the MATLAB function signature.}
}
\value{
Named list with three elements:
  \describe{
    \item{charcoal}{List of raw and resampled series:
      \code{cm, count, vol, con, ybp, acc} (raw);
      \code{cmI, countI, volI, conI, accI, ybpI} (resampled).}
    \item{pretreatment}{Input list returned with \code{yrInterp} updated
      when it was 0 (auto), and \code{zoneDiv[end]} corrected if it
      exceeded the bottom age of the last raw sample.}
    \item{gap_in}{Integer matrix (nGaps x 2) of gap row-index pairs, or
      \code{matrix(NA_integer_, 0, 2)} when no gaps exist.}
  }
}
\description{
Resamples the raw charcoal data to equal time steps using a
proportion-weighted scheme, fills missing-value gaps by linear
interpolation, computes charcoal accumulation rates (CHAR), and optionally
applies a log transformation.
}
\details{
Mirrors \code{CharPretreatment.m} from the MATLAB v2.0 codebase.  The
vectorised proportion matrix (four broadcast cases) produces results
numerically identical to the MATLAB implementation within floating-point
tolerance (~1e-14).


  ## Proportion matrix
  For each resampled interval \eqn{i} and each raw sample \eqn{j},
  \code{prop_matrix[i,j]} is the fraction of the raw sample's age span
  that falls within the resampled interval.  Four mutually exclusive
  overlap geometries (Cases A-D) are evaluated via matrix broadcasting
  across the full \eqn{[N_{rs} \times N_{raw}]} grid -- no loops required.

  | Case | Geometry                                      | Overlap            |
  |------|-----------------------------------------------|--------------------|
  | A    | Raw straddles the **bottom** edge             | rsAgeBot - ageTop  |
  | B    | Raw straddles the **top** edge                | ageBot - rsAgeTop  |
  | C    | Raw lies **entirely within** resampled interval | ageBot - ageTop  |
  | D    | Resampled lies **entirely within** raw sample | yrInterp           |

  ## zoneDiv auto-correction
  If \code{zoneDiv[end]} exceeds the bottom age of the last raw sample,
  the terminal resampled intervals would have no overlapping raw data and
  \code{accI} would be \code{NA}.  These \code{NA}s propagate into
  \code{charBkg} and can hang the GMM in Phase 2.  The value is silently
  corrected to \code{lastAgeBotInData} and the user is notified
  (v2.0 behaviour, preserved here).
}
\seealso{
[char_parameters()], [char_validate_params()], [CharAnalysis()]
}
