% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sg-gof-res.R
\name{sg_gof_res}
\alias{sg_gof_res}
\title{Create residual diagnostic plots}
\usage{
sg_gof_res(
  fpath_i,
  DVID = 1,
  cov_cols = NULL,
  indiv = TRUE,
  vs_time = TRUE,
  weighted = TRUE,
  addline = TRUE,
  alpha_i = 0.5,
  smooth = TRUE,
  log_x = FALSE,
  abreaks = scales::pretty_breaks(7),
  lab_y = NULL,
  lab_x = NULL,
  col_i = NULL,
  col_lab = NULL,
  facet_i = NULL,
  f_scales = "fixed",
  n_bins = 50,
  min_y = NA,
  max_y = NA,
  min_x = NA,
  max_x = NA,
  legend_fl = FALSE,
  n_quantiles = 3,
  levels_discrete = 10
)
}
\arguments{
\item{fpath_i}{String or sg-fit object. If the string is given, the path to
\code{.Rdata} or \code{.json} file with sg-fit object is expected.}

\item{DVID}{Restrict \code{SDTAB} to one observation type. Numeric values
select the \code{DVID} column (default \code{1}). If \code{SDTAB} has
\code{DVNAME}, a character or factor is matched to \code{DVNAME} first;
otherwise a digit-only string is coerced to numeric \code{DVID}.}

\item{cov_cols}{A character vector specifying the names of the columns with covariates.}

\item{indiv}{Logical. If \code{TRUE}, use individual predictions (\code{"IPRED"});
otherwise use population predictions (\code{"PRED"}). Default is \code{TRUE}.}

\item{vs_time}{Logical. If \code{TRUE}, plot residuals vs TIME; otherwise, plot
residuals vs predictions (IPRED/PRED).}

\item{weighted}{Logical. If \code{TRUE}, use weighted residuals; otherwise, use
RES/IRES}

\item{addline}{Logical. If \code{TRUE}, lines connecting observations of
individual subjects will be added. Default is \code{TRUE}.}

\item{alpha_i}{Numeric. Transparency level (from 0 to 1) for points/lines.
Default is 0.5.}

\item{smooth}{Logical. Add LOESS smooth line. Default is \code{TRUE}.}

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

\item{abreaks}{A function that generates axis breaks. Default is \code{scales::pretty_breaks(7)}.}

\item{lab_y}{String. Y-axis label.}

\item{lab_x}{String. X-axis label.}

\item{col_i}{String. Column name for color}

\item{col_lab}{String. Label for color legend}

\item{facet_i}{String. Column name for facet}

\item{f_scales}{String, one of \code{"fixed"}, \code{"free"}, \code{"free_x"}, \code{"free_y"}. User can specify whether the scales (x and y axes) should be fixed across all panels (\code{"fixed"}), free for each panel (\code{"free"}), or free only in one dimension (\code{"free_x"} or \code{"free_y"}). Default is \code{"fixed"}}

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

\item{min_y}{Numeric. Y-axis minimum limit. Default is \code{NA}.}

\item{max_y}{Numeric. Y-axis maximum limit. Default is \code{NA}.}

\item{min_x}{Numeric. X-axis minimum limit. Default is \code{NA}.}

\item{max_x}{Numeric. X-axis maximum limit. Default is \code{NA}.}

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

\item{n_quantiles}{Integer. Number of quantile groups for continuous variables in \code{col_i}. Default is 3.}

\item{levels_discrete}{Integer. Maximum unique values to consider a variable discrete. Default is 10.}
}
\value{
A \code{ggplot2} object
}
\description{
Generates residual diagnostic plots versus time/predictions.
Supports faceting, covariate coloring, quantile binning for
continuous covariates, and optional smoothing.
}
\examples{
# Basic example with mock data
set.seed(123)  # For reproducibility
n_subjects <- 50
mock_obj <- list(
  SDTAB = do.call(rbind, lapply(1:n_subjects, function(id) {
    n_obs <- 6
    times <- sort(runif(n_obs, min = 0, max = 24))  # random times between 0 and 24h
    data.frame(
      ID    = id,
      TIME  = times,
      DV    = rnorm(n_obs, mean = 10, sd = 2),
      PRED  = rnorm(n_obs, mean = 10, sd = 1.5),
      IPRED = rnorm(n_obs, mean = 10, sd = 1.2),
      IWRES = rnorm(n_obs, mean = 0, sd = 0.8),
      IRES  = rnorm(n_obs, mean = 0, sd = 1.2),
      MDV   = 0
    )
  })),
  COTAB = data.frame(
    ID  = 1:n_subjects,
    AGE = sample(20:80, n_subjects, replace = TRUE)
  ),
  CATAB = data.frame(
    ID   = 1:n_subjects,
    RACE = sample(c("Hispanic", "Asian", "Caucasian"), n_subjects, replace = TRUE)
  )
)

# Basic plot: individual weighted residuals vs TIME (weighted = TRUE, vs_time = TRUE)
p <- sg_gof_res(mock_obj, smooth = FALSE)

# With covariates and faceting (use RACE as facet and AGE as color)
p <- sg_gof_res(
  mock_obj,
  smooth = TRUE,
  cov_cols = c("RACE","AGE"),
  col_i = "RACE",
  facet_i = "AGE",
  indiv = TRUE,
  weighted = TRUE,
  vs_time = FALSE,
  legend_fl = TRUE
)
p

}
