% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/char_write_results.R
\name{char_write_results}
\alias{char_write_results}
\title{Write the CharAnalysis results matrix to a CSV file}
\usage{
char_write_results(char_results, site, out_dir, digits = 7L)
}
\arguments{
\item{char_results}{Numeric matrix (\eqn{N \times 33}) returned in
\code{out$char_results} by [CharAnalysis()].}

\item{site}{Character string: site name, used to build the
output filename (\code{<site>_charResults.csv}).}

\item{out_dir}{Directory in which to create the file.  Required;
no default.  Created if it does not exist.  Use \code{tempdir()} for
a transient location, or supply a path of your choosing.}

\item{digits}{Number of significant digits for numeric output.
Default 7, matching MATLAB's \code{fprintf} default precision.
Use \code{NULL} for R's full double precision (15 digits).}
}
\value{
Invisibly returns the full path to the file written.
}
\description{
Writes the \eqn{N \times 33} \code{char_results} matrix (assembled by
[char_post_process()]) to a CSV file whose column headers and numeric
format match the MATLAB CharAnalysis v2.0 \code{*_charResults.csv} output
exactly.
}
\details{
## Column order and headers
  Columns follow the MATLAB \code{charResults} layout:
  \enumerate{
    \item cm Top_i (cm)
    \item age Top_i (yr BP)
    \item char Count_i (#)
    \item char Vol_i (cm3)
    \item char Con_i (# cm-3)
    \item char Acc_i (# cm-2 yr-1)
    \item charBkg (# cm-2 yr-1)
    \item char Peak (# cm-2 yr-1)
    \item thresh 1 (# cm-2 yr-1)
    \item thresh 2 (# cm-2 yr-1)
    \item thresh 3 (# cm-2 yr-1)
    \item thresh FinalPos (# cm-2 yr-1)
    \item thresh FinalNeg (# cm-2 yr-1)
    \item SNI (index)
    \item thresh GOF (p-val)
    \item peaks 1
    \item peaks 2
    \item peaks 3
    \item peaks Final
    \item peaks Insig.
    \item peak Mag (# cm-2 peak-1)
    \item smPeak Frequ (peaks 1ka-1)
    \item smFRIs (yr fire-1)
    \item nFRIs (#)
    \item mFRI (yr fire-1)
    \item mFRI_uCI (yr fire-1)
    \item mFRI_lCI (yr fire-1)
    \item WBLb (yr)
    \item WBLb_uCI (yr)
    \item WBLb_lCI (yr)
    \item WBLc (unitless)
    \item WBLc_uCI (unitless)
    \item WBLc_lCI (unitless)
  }

  ## NA / empty handling
  \code{NA} values are written as empty fields (no quotes), matching
  MATLAB's blank-cell convention.  This applies to:
  \itemize{
    \item \code{smFRIs} rows beyond the smoothed-FRI coverage window;
    \item zone-statistics columns (24-33) for rows beyond the last zone;
    \item any column not computed for a given run configuration.
  }

  ## CI column convention
  MATLAB stores bootstrap CIs as \code{[quantile(2.5\%), quantile(97.5\%)]}
  in the columns labelled \code{uCI} / \code{lCI} respectively (i.e.
  \code{uCI} = lower bound, \code{lCI} = upper bound -- MATLAB's own
  labelling is inverted).  The R output follows the same convention so that
  column indices are identical to the MATLAB reference file.
}
\examples{
\donttest{
  # Run the pipeline on the bundled example and write results to tempdir:
  params_file <- system.file("validation", "CO_charParams.csv",
                             package = "CharAnalysis")
  out <- CharAnalysis(params_file)
  char_write_results(out$char_results, out$site,
                     out_dir = tempdir())
}
}
\seealso{
[char_post_process()], [CharAnalysis()]
}
