% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sg-vpc-vis.R
\name{sg_vpc_vis}
\alias{sg_vpc_vis}
\title{Visual Predictive Check (VPC) Function}
\usage{
sg_vpc_vis(
  ds_sim,
  data_i,
  output_names,
  time_col = "TIME",
  dv_col = "DV",
  log_y = FALSE,
  piLow = 0.1,
  piUp = 0.9,
  ciLow = 0.025,
  ciUp = 0.975,
  pred.corr = FALSE,
  lab_y = "DV",
  lab_x = "Time, h",
  theor_perc = TRUE,
  theor_percCI = TRUE,
  emp_perc = TRUE,
  dt_obs_fl = FALSE,
  legend_fl = FALSE,
  n_bins = 10,
  method = "kmeans",
  interpolation = TRUE,
  strat_by_dose = NULL
)
}
\arguments{
\item{ds_sim}{A data frame with simulated data containing columns:
\itemize{
\item ID: simulation replicate identifier
\item TIME: time points
\item VAR: output variable name
\item VALUE: simulated values
}}

\item{data_i}{A data frame with observed data containing columns:
\itemize{
\item ID: patient identifier
\item TIME: time points
\item DV: observed dependent variable values
\item DVID: dependent variable identifier
}}

\item{output_names}{A data frame mapping \code{VAR} values (from \code{ds_sim})
to \code{DVID} values (from \code{data_i}). Must contain columns:
\itemize{
\item output: character, \code{VAR} values (e.g., "Cc", "Cp")
\item dvid: numeric, corresponding DVIDs (e.g., 1, 2)
}}

\item{time_col}{String. The column to use as a time column. Currently, can be only \code{TIME}. Default is \code{TIME}.}

\item{dv_col}{Character. Name of DV column in data_i. Default is \code{DV}}

\item{log_y}{Logical. If \code{TRUE}, a logarithmic scale is applied to y-axis. Default is \code{FALSE}.}

\item{piLow}{Numeric. Lower prediction interval bound. Default is 0.10.}

\item{piUp}{Numeric. Upper prediction interval bound Default is 0.90.}

\item{ciLow}{Numeric. Lower confidence interval bound. Default is 0.025}

\item{ciUp}{Numeric. Upper confidence interval bound. Default is 0.975}

\item{pred.corr}{Logical. Apply prediction correction. Default is \code{FALSE}.}

\item{lab_y}{String. Y-axis label. Default is "DV".}

\item{lab_x}{String. X-axis label. Default is "TIME, h".}

\item{theor_perc}{Logical. Show theoretical percentiles. Default is \code{TRUE}.}

\item{theor_percCI}{Logical. Show CI around theoretical percentiles. Default is \code{TRUE}.}

\item{emp_perc}{Logical. Show empirical percentiles. Default is \code{TRUE}}

\item{dt_obs_fl}{Logical. Show observed data points. Default is \code{FALSE}}

\item{legend_fl}{Logical. Show legend. Default is \code{FALSE}.}

\item{n_bins}{Integer. Number of bins to use in the histogram. Default is 10.}

\item{method}{Character. Binning method: "kmeans", "equal", "quantile" (default: "kmeans").}

\item{interpolation}{Logical. Use line interpolation vs rectangles (default: FALSE).}

\item{strat_by_dose}{Character. Variable name for dose stratification (default: NULL).}
}
\value{
List of ggplot objects, one for each output variable
}
\description{
Generates VPC plots to assess model performance by comparing observed data
with prediction intervals derived from simulated data.
}
\details{
For now, the model in the example is NOT the generalized model object (GMO),
as the parameters in generalized fit object are backtransformed, and,
therefore, not transformed in the model. This issue will be fixed in the next
versions of SimuRg package
}
\examples{
\donttest{
library(rxode2)
fpath_i <- system.file("extdata", "simurg_object", "Warfarin_PK.RData", package = "SimuRg")
mod <- rxode2::rxode2({
  ka_pop = 0.1;
  Vd_pop = 10;
  Cl_pop = 0.5;

  omega_ka = 0;
  omega_Vd = 0;
  omega_Cl = 0;

  Cc_b = 0;
  ka_tv = exp(log(ka_pop));
  Vd_tv = exp(log(Vd_pop));
  Cl_tv = exp(log(Cl_pop));

  ka = ka_tv * exp(omega_ka);
  Vd = Vd_tv * exp(omega_Vd);
  Cl = Cl_tv * exp(omega_Cl);

  Cc = Ac / Vd;

  Ad(0) = 0;
  Ac(0) = 0;

  d/dt(Ad) = -ka * Ad;
  d/dt(Ac) = ka * Ad - Cl * Cc;

  Cc_ResErr = Cc * (1 + Cc_b);
})

sim_data <- sg_vpc_sim(fpath_i, model=mod, outputs = "Cc_ResErr")
outp_nms <- data.frame(dvid = 1, output = "Cc")
vpc_plots <- sg_vpc_vis(
  ds_sim = sim_data,
  data_i = warfarin,
  output_names = outp_nms,
  lab_x = "Time (hours)",
  lab_y = "Concentration (ng/mL)",
  n_bins = 8,
  pred.corr = TRUE
)
}
}
