% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ncaComparison.R
\name{ncaComparisonTable}
\alias{ncaComparisonTable}
\title{Build a side-by-side NCA comparison table (simulated vs. reference)}
\usage{
ncaComparisonTable(
  simulated,
  reference,
  by = NULL,
  params = NULL,
  tolerance_pct = 20,
  units = NULL,
  label_first_column = "NCA parameter"
)
}
\arguments{
\item{simulated}{Model-predicted NCA. One of: a `PKNCAresults` object,
a `data.frame` with columns `PPTESTCD` and `PPORRES` plus any
grouping columns named in `by`, or a wide `data.frame` (one row per
group, one column per PKNCA code).}

\item{reference}{Reference NCA. Same shapes as `simulated`. A wide
`data.frame` is the typical form when transcribing values from a
paper table.}

\item{by}{Optional character vector of grouping column name(s) (e.g.
`"treatment"`, `c("cohort","weight_band")`). When `NULL`, the inputs
are treated as a single ungrouped comparison.}

\item{params}{Optional character vector of PKNCA codes restricting
which parameters appear in the output. Defaults to the intersection
of codes present in both inputs.}

\item{tolerance_pct}{Numeric scalar; rows with
`|% diff| > tolerance_pct` get a trailing `*` and the function
attaches a footnote string via the `"footnote"` attribute on the
result. Pass `Inf` to disable flagging.}

\item{units}{Optional named character vector keyed by PKNCA code,
passed through to [ncaParamLabel()].}

\item{label_first_column}{Header for the parameter column. Defaults to
`"NCA parameter"`.}
}
\value{
A `data.frame` whose first column is the friendly parameter
  label (under `label_first_column`); when `by` is non-NULL, the
  grouping column(s) follow; the final three columns are `Reference`,
  `Simulated`, and `% diff`. Rows are sorted by canonical PKNCA
  parameter order then by group. Carries a `"footnote"` attribute when
  any row exceeds the tolerance.
}
\description{
Combines model-predicted NCA results with a reference set (e.g. paper
values, prior estimates, alternative model runs, observed data) into a
single tidy comparison frame ready for `knitr::kable()` or interactive
review. Each row is one NCA parameter \eqn{\times} optional grouping
level; columns show the reference value, simulated value, and percent
difference. Rows whose discrepancy exceeds `tolerance_pct` are flagged
with a trailing asterisk and the function attaches a footnote string
to the result.
}
\details{
Designed for any nlmixr2 user comparing predicted NCA to a reference
-- not solely a vignette utility. Accepts a `PKNCAresults` object,
the `$result` data.frame, or a tidy long frame with columns `PPTESTCD`
and `PPORRES` for `simulated`; the same shapes plus a wide
`data.frame` (one row per group, one column per PKNCA parameter code)
for `reference`. Multiple rows per group in `simulated` (the typical
per-subject case from [PKNCA::pk.nca()]) are aggregated to the group
level using [stats::median()] before joining; pass a pre-aggregated
frame if a different summary statistic is required.
}
\examples{
simulated <- data.frame(
  treatment = rep(c("50 mg", "100 mg"), each = 3),
  PPTESTCD  = rep(c("cmax", "tmax", "auclast"), 2),
  PPORRES   = c(15.2, 2.0, 96.0, 29.1, 2.1, 191.0)
)
reference <- data.frame(
  treatment = c("50 mg", "100 mg"),
  cmax      = c(14.8, 28.5),
  tmax      = c(2.0,  2.1),
  auclast   = c(95.0, 190.0)
)
tbl <- ncaComparisonTable(
  simulated, reference,
  by = "treatment",
  units = c(cmax = "ug/mL", auclast = "ug*h/mL", tmax = "h")
)
tbl
attr(tbl, "footnote")
}
\author{
Bill Denney
}
