% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/char_peak_id.R
\name{char_peak_id}
\alias{char_peak_id}
\title{Identify charcoal peaks and apply minimum-count screening}
\usage{
char_peak_id(charcoal, pretreatment, peak_analysis, char_thresh)
}
\arguments{
\item{charcoal}{Named list containing:
\describe{
  \item{peak}{C_peak series (\code{accI - accIS} or \code{accI / accIS}),
    length \eqn{N}.}
  \item{ybpI}{Age at each interpolated sample (cal yr BP), length \eqn{N}.}
  \item{accI}{Interpolated charcoal accumulation rate, length \eqn{N}.}
  \item{countI}{Interpolated charcoal count, length \eqn{N}.}
  \item{volI}{Interpolated sediment volume (cm^3), length \eqn{N}.}
}}

\item{pretreatment}{Named list with element \code{yrInterp} (interpolation
resolution, years).}

\item{peak_analysis}{Named list with elements \code{threshType} (1 = global,
2 = local), \code{threshValues} (numeric vector, length \eqn{T}), and
\code{minCountP} (alpha for minimum-count screen).}

\item{char_thresh}{Named list returned by [char_thresh_global()] or
[char_thresh_local()], containing \code{possible} (251-bin grid) and
\code{pos} (\eqn{[N \times T]} threshold matrix).}
}
\value{
A named list with two components:
  \describe{
    \item{charcoal}{Input \code{charcoal} list augmented with:
      \itemize{
        \item \code{charPeaks}      -- \eqn{[N \times T]} numeric: 1 at peak
          samples, 0 elsewhere.
        \item \code{charPeaksThresh} -- \eqn{[N \times T]} numeric: threshold
          value at each identified peak, 0 elsewhere.
        \item \code{peaksTotal}     -- numeric vector length \eqn{T}: total
          peaks per threshold column.
        \item \code{threshFRI}      -- numeric matrix (\eqn{\leq N \times T}):
          fire-return intervals derived from peak ages per threshold column.
      }
    }
    \item{char_thresh}{Input \code{char_thresh} list augmented with
      \code{minCountP} -- \eqn{[N \times T]} matrix of Shuie-Bain p-values
      (NaN where not computed).}
  }
}
\description{
Mirrors \code{CharPeakID.m} from the MATLAB v2.0 codebase.  For each
threshold column, samples where C_peak exceeds the threshold are flagged,
consecutive exceedances are collapsed to a single event (keeping the
\strong{last} sample of each run, i.e. the oldest, matching the MATLAB
v1.1 / v2.0 convention), and each event is screened against a
minimum-count criterion using the Shuie-Bain (1982) extension of the
Detre-White (1970) test for unequal sediment volumes.
}
\details{
## Threshold value matrix
  For **global** thresholds (\code{threshType == 1}), \code{char_thresh$pos}
  is a constant-row \eqn{[N \times T]} matrix reused directly.  For
  **local** thresholds (\code{threshType == 2}), \code{char_thresh$pos} is
  already \eqn{[N \times T]} (per-sample values).

  ## Consecutive-peak removal
  After flagging all exceedances, a diff-based pass retains only the
  \emph{last} sample of each consecutive run -- the oldest sample within a
  group of contiguous above-threshold values.  This matches the MATLAB v1.1
  algorithm (which the v2.0 comment documents correctly despite the v1.1
  comment being misleading).

  ## Minimum-count test
  For each identified peak \eqn{i} in column \eqn{j}, a time window of
  \eqn{\pm 150} yr is constructed around the peak, then narrowed to the
  adjacent peaks when they fall within the window.  The test statistic is
  \deqn{
    d = \frac{|c_{\min} - (c_{\min}+c_{\max})\,v_{\min}/(v_{\min}+v_{\max})| - 0.5}
             {\sqrt{(c_{\min}+c_{\max})\,v_{\min}\,v_{\max}/(v_{\min}+v_{\max})^2}}
  }
  and the p-value is \eqn{1 - \Phi(d)} (standard normal CDF; equivalent to
  MATLAB's \code{1 - tcdf(d, 1e10)} because \eqn{t_{1\times10^{10}} \to z}).
  Peaks with \eqn{p > \alpha_{\text{peak}}} are removed.
}
\seealso{
[char_thresh_local()], [char_thresh_global()], [CharAnalysis()]
}
