% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/utils.R
\name{sg_dummy}
\alias{sg_dummy}
\title{The function to store common parameters description}
\usage{
sg_dummy(
  ...,
  abreaks = scales::pretty_breaks(7),
  addcov = TRUE,
  addOFV = TRUE,
  addline = TRUE,
  aggr = NULL,
  alpha_i = 0.5,
  atol = 1e-08,
  cap,
  cat_cov_l,
  ci_band_alpha = 0.2,
  ci_band_col = "firebrick",
  ci_limits = c(0.8, 1.25),
  ci_quantiles = c("P025", "P975"),
  cont_cov_l,
  cov_cols,
  cov,
  covint = "locf",
  covsens_res,
  ciLow = 0.025,
  ciUp = 0.975,
  col_i,
  col_lab,
  covs,
  data,
  dens,
  ds_covs,
  ds_i,
  ds_parest = NULL,
  dt_obs_fl = FALSE,
  DVID = 1,
  dv_col = "DV",
  emp_perc = TRUE,
  errorbar_width = 0.2,
  est_covmat,
  et,
  eta_seq = NULL,
  excl_col = NULL,
  exclude_vars = NULL,
  f_scales = "fixed",
  facet_i,
  fill_i = NULL,
  filt = "T",
  fit = FALSE,
  fpath_i,
  free_stat = "free",
  group_i = "VAR",
  headers,
  ncores = 1,
  id_col = NULL,
  indiv = TRUE,
  inits = NULL,
  keep = NULL,
  lab_x,
  lab_y,
  legend_fl = FALSE,
  levels_discrete = 10,
  log_x = FALSE,
  log_y = FALSE,
  log_axes = FALSE,
  lty_i = NULL,
  max_x = NULL,
  max_y = NULL,
  method = "lsoda",
  min_x = NULL,
  min_y = NULL,
  model,
  n_bins = 30,
  n_quantiles = 3,
  n_sim,
  no_leg = FALSE,
  npop = 1,
  nsub = 1,
  occ,
  opt_name = "Monolix",
  omega,
  outputs = NULL,
  output = NULL,
  path_to_fitter = NULL,
  path_to_save_output = NULL,
  par_bounds,
  par_seq = NULL,
  par_type = "Ind",
  params = NULL,
  piLow = 0.1,
  piUp = 0.9,
  plot_type = "DIST",
  point_size = 2.5,
  pred.corr = FALSE,
  project_name,
  quantiles = c(0.1, 0.9),
  re,
  ref_line_col = "grey25",
  rtol = 1e-06,
  run_id = 1,
  ruv,
  sc_factor = 1,
  scale = NULL,
  seed = 123,
  sigma = NULL,
  shp_i = NULL,
  smooth = TRUE,
  stat_comp = NULL,
  stimes = NULL,
  task_opt = NULL,
  tdist = TRUE,
  time_col = "TIME",
  theor_perc = TRUE,
  theor_percCI = TRUE,
  theta = NULL,
  thetamat = NULL,
  tsld = FALSE,
  val_col = "VALUE",
  wrap_i = NULL,
  wrap_ncol = NULL,
  wrap_nrow = NULL
)
}
\arguments{
\item{...}{Other arguments that will be passed to rxSolve function.}

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

\item{addcov}{Logical. If \code{TRUE}, columns with covariate values will be added
to the resulting dataset. Default is \code{TRUE}.}

\item{addOFV}{Logical. If \code{TRUE}, information about OFV and AIC of the model
will be added. Default is \code{TRUE}.}

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

\item{aggr}{A string that specifies the aggregation type. Set to \code{NULL} for
no aggregation, \code{ID} for aggregation by time, population and ID, \code{NPOP} for
aggregation by population and time, \code{TIME} for aggregation by time.
Default is \code{NULL}.}

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

\item{atol}{A numeric absolute tolerance used by the ODE solver to determine
if a good solution has been achieved. This is also used in the solved linear
model to check if prior doses do no add anything to the solution.
Default is 1e-8.}

\item{cap}{A string that specifies the plot caption.}

\item{cat_cov_l}{A named list. Each element defines one categorical covariate
and must itself be a list with components:
\describe{
\item{\code{NAME}}{Character. Column name of the covariate
(e.g. \code{"SEX"}).}
\item{\code{NICENAME}}{Character or \code{NULL}. Display label.}
\item{\code{REF}}{Character or \code{NULL}. Reference category value.
If \code{NULL}, the first factor level (alphabetically) is used.}
\item{\code{par_vec}}{Character vector. Model parameter(s) affected by
this covariate (e.g. \code{c("ka")}).}
}}

\item{ci_band_alpha}{Numeric in \eqn{[0,1]}: transparency of the shaded band.
Default \code{0.2}.}

\item{ci_band_col}{Color for the band fill and dotted limit lines.
Default \code{"firebrick"}.}

\item{ci_limits}{Numeric vector of length 2: lower and upper bounds of the
shaded acceptance band and of the dotted horizontal guides.  Default
\code{c(0.8, 1.25)} is a common bioequivalence-style window on the ratio
scale.}

\item{ci_quantiles}{Character vector of length 2: names of the lower and
upper uncertainty columns in the sensitivity table, in that order.
Defaults \code{c("P025", "P975")} to match the default percentiles in
\code{sg_covsens_sim}.  Use other names (e.g. \code{c("P05", "P95")}) if
you changed \code{quantiles} in the simulation and the columns exist.}

\item{cont_cov_l}{A named list. Each element defines one continuous covariate
and must itself be a list with components:
\describe{
\item{\code{NAME}}{Character. Column name of the (transformed)
covariate in the dataset (e.g. \code{"LG_AGE"}).}
\item{\code{UTNAME}}{Character or \code{NULL}. Column name of the
untransformed (back-transformed) covariate
(e.g. \code{"AGE"}).  If \code{NULL} or \code{NA}, defaults to
\code{NAME}.}
\item{\code{REF}}{Character or numeric. Reference value for the
covariate.  Use \code{"median"} to derive from data, or a numeric
value.}
\item{\code{NICENAME}}{Character or \code{NULL}. Display label for
plots and tables (e.g. \code{"Age, years"}).}
\item{\code{par_vec}}{Character vector. Model parameter(s) affected by
this covariate (e.g. \code{c("CL")}).}
}}

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

\item{cov}{Covariates passed to \code{sg_sim()}. Default is \code{NULL}.}

\item{covint}{String. Specifies the interpolation method for time-varying
covariates. When solving ODEs it often samples times outside the sampling
time specified in event table. When this happens, the time varying
covariates are interpolated. Currently this can be:
\itemize{
\item \code{"linear"} interpolation, which interpolates the covariate by solving the
line between the observed covariates and extrapolating the new covariate value
\item \code{"locf"} last observation carried forward
\item \code{"NOCB"} next observation carried backward.
This is the same method that NONMEM uses
\item \code{"midpoint"} last observation carried forward to midpoint;
next observation carried backward to midpoint
}

Default is \code{"locf"}}

\item{covsens_res}{Named list as returned by \code{sg_covsens_sim()}.  Must
contain the element selected by \code{type} (\code{PARSENS} and/or
\code{EXPSENS} data.frames with columns \code{LAB}, \code{VAR},
\code{mean}, \code{Type}, and the interval columns named by
\code{ci_quantiles}).}

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

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

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

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

\item{covs}{A list of covariate structures. Each element should be a list containing covariate relationship definitions with the following structure:
\itemize{
\item \code{PAR} - string, name of the parameter to which covariate effect is applied
\item \code{COVNAME} - string, name of the covariate column in the dataset
\item \code{FUNC} - string, functional form of the covariate effect
\item \code{TRANS} - string, transformation applied to covariate
\item \code{REF} - numeric, reference value for categorical covariates
\item \code{INIT} - numeric, initial value for the covariate effect parameter
\item \code{EST} - logical, whether to estimate the covariate effect
Can be \code{NULL}, if no covariates are used. Default is \code{NULL}
}}

\item{data}{String. Path to the dataset used to fit a model. Should be a CSV file containing the pharmacokinetic/pharmacodynamic data with appropriate column structure matching the headers specification}

\item{dens}{Logical. If \code{TRUE}, plot histogram/density of residuals instead of scatter}

\item{ds_covs}{Data.frame. The dataframe with covariates}

\item{ds_i}{Data.frame. The data frame with source data.}

\item{ds_parest}{Data.frame. Parameter estimates table with columns
\code{parameter} and \code{value}.
Required when \code{fpath_i} is \code{NULL}; must be provided together
with \code{ds_covs}.  Default is \code{NULL}.}

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

\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{dv_col}{Character. Name of DV column in data_i. Default is \code{DV}}

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

\item{errorbar_width}{Numeric. Width argument for \code{geom_errorbar}.  Default
\code{0.2}.}

\item{est_covmat}{Data.frame. Parameter estimation covariance matrix.  The
first column (\code{X1}) must list parameter names; remaining columns
(named identically) form the symmetric variance–covariance matrix.}

\item{et}{An event table passed to \code{sg_sim()}.}

\item{eta_seq}{Vector of strings. Character vector of parameter names to be plotted. If \code{NULL}, all parameters be included. Default is \code{NULL}}

\item{excl_col}{Character vector. Contains column names to exclude from synthesis. Default: \code{NULL}}

\item{exclude_vars}{Character vector. Contains \code{VAR} levels to omit (e.g.
\code{"Cc_Cmin"}).  \code{NULL} keeps all rows.}

\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{facet_i}{String. Column name for facet}

\item{fill_i}{String. Column name for fill aesthetic. Default is \code{NULL}}

\item{filt}{String. Provide a filter to apply. Default is \code{"T"}}

\item{fit}{Logical. If \code{TRUE}, the model fitting will be executed immediately
using the specified fitter. If \code{FALSE}, only the fit configuration file will
be generated without running the fit. Set to \code{FALSE} for file preparation only,
or \code{TRUE} to run the complete fitting process. Default is \code{FALSE}.}

\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{free_stat}{String. Facet scaling option. One of \code{"free"}, \code{"free_x"},
\code{"free_y"}, or \code{"fixed"}. Default is \code{'free'}.}

\item{group_i}{String. Primary grouping variable for lines. Default is \code{'VAR'}.}

\item{headers}{List. A list specifying the data frame column headers.
Each element should be a list containing column information with the following structure:
\itemize{
\item \code{name} - string, column name in the dataset
\item \code{use} - string, column usage type. Valid values include:
\itemize{
\item "identifier" for subject ID columns
\item "time" for time columns
\item "observation" for dependent variable columns
\item "observationtype" for observation type identifier
\item "administration" for administration route
\item "amount" for dose amount
\item "eventidentifier" for event ID
\item "missingdependentvariable" for missing DV flag
\item "covariate" for covariate columns
}
\item \code{type} - string or NULL, data type specification. For observations use
"continuous", "count/categorical" or "event", depending on the nature of
observations. For covariates use "continuous" or "categorical". Can be NULL for non-covariate columns.
}}

\item{ncores}{Integer. Number of cores used for calculations. Default is 1.}

\item{id_col}{Character string. Specify the name of the identifier column
to exclude from synthesis. Default: \code{NULL}.}

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

\item{inits}{A named vector specifying initial conditions for model variables; Default is \code{NULL}.}

\item{keep}{Vector of strings. Columns of event table to keep in the output data frame. Default is \code{NULL}.}

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

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

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

\item{levels_discrete}{Integer. Maximum unique values to consider a variable discrete. Default is 10.}

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

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

\item{log_axes}{Logical. If \code{TRUE}, a logarithmic scale is applied to all axes. Default is \code{FALSE}.}

\item{lty_i}{String. Column name for linetype aesthetic. Default is \code{NULL}.}

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

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

\item{method}{Character string. \code{"PRCC"} or \code{"eFAST"}.}

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

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

\item{model}{A model object passed to \code{sg_sim()}.}

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

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

\item{n_sim}{Integer. Number of samples (LHS size for PRCC, base frequency size for eFAST).}

\item{no_leg}{Logical. If \code{TRUE}, the legend is not shown. Default is \code{FALSE}}

\item{npop}{Integer. Number of population replicates. Default is 1.}

\item{nsub}{Integer. Number of subjects sampled per population (omega/sigma matrices per ID). Default is 1.}

\item{occ}{A list specifying interoccasion variability properties, containing:
\itemize{
\item \code{init} - matrix, initial values for the interoccasion variance-covariance matrix.
Same structure as \code{re$init} but for occasion-to-occasion variability. Use 0 for no interoccasion variability
\item \code{est} - matrix, logical matrix specifying which interoccasion variance-covariance
elements to estimate. Use \code{TRUE} to estimate, \code{FALSE} to fix, \code{NA} for
elements not applicable. Typically all elements are NA when no interoccasion variability is modeled.
}}

\item{opt_name}{String. Specify the optimizer/fitter to use for model fitting.
Currently supported options:
\itemize{
\item \code{"Monolix"} - uses Monolix Suite for population pharmacokinetic modeling (generates .mlxtran files)
\item \code{"Simurg"} - uses SimuRg internal fitter (generates .R files with JSON control structure)
Default is \code{"Monolix"}.
}}

\item{omega}{A named matrix or vector.}

\item{outputs}{Vector of strings. Names of the model variables to output.
If \code{NULL}, all variables returned. Default is \code{NULL}.}

\item{output}{A character vector of outputs to keep. Passed to \code{sg_sim()}.}

\item{path_to_fitter}{String. The path to the program fitter executable.
For Monolix, this should point to the monolix.bat file.
If \code{NULL}, "C:/ProgramData/Lixoft/MonolixSuite2023R1/bin/monolix.bat" will be used as default. Default is \code{NULL}.}

\item{path_to_save_output}{String. Path to save fit output files.
Should be a valid directory path where the fit results and project files
will be saved. If \code{NULL}, current working directory will be used. Default is \code{NULL}.}

\item{par_bounds}{A tibble or data frame with columns \code{PAR}, \code{LB}, \code{UB}.}

\item{par_seq}{Vector of strings. Character vector of parameter names to be plotted. If \code{NULL}, all parameters be included. Default is \code{NULL}}

\item{par_type}{String. A character string specifying the type of parameters used for
theoretical distribution overlay (only relevant when \code{plot_type = 'DIST'}
and \code{tdist = TRUE}). If 'Ind' - Individual (default), distributions are shown on the
natural parameter scale assuming log-normal variability. If 'RE' - Random Effect, distributions are shown on the ETA scale,
assuming a normal distribution with mean zero and covariance defined
by \verb{$OMEGAMAT}, without transformation.}

\item{params}{Character vector of parameter names to vary.}

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

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

\item{plot_type}{Character. Type of plot to produce:
\itemize{
\item \code{"DIST"} (default) - histogram of individual parameters,
\item \code{"QQ"} - QQ-plot of individual parameters.
}}

\item{point_size}{Point size for \code{geom_point}.  Default \code{2.5}.}

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

\item{project_name}{String. The name of the Monolix project without file extension.
This will be used as the base name for output files and directories.}

\item{quantiles}{A numeric vector of length 2. Lower and upper quantiles of
the continuous covariate distribution to test.
Default is \code{c(0.1, 0.9)}.}

\item{re}{List. A list specifying options for random effects used in model fit, containing:
\itemize{
\item \code{init} - matrix, initial values for the variance-covariance matrix of random
effects. Rows and columns should correspond to parameters defined in theta.
Diagonal elements represent variances, off-diagonal elements represent covariances. Use 0 for no variability
\item \code{est} - matrix, logical matrix of same dimensions as \code{init} specifying
which variance-covariance elements to estimate. Use \code{TRUE} to estimate,
\code{FALSE} to fix, \code{NA} to not use this random effect.
}}

\item{ref_line_col}{Color for the dashed horizontal line at \code{y = 1}
(no change from reference).  Default \code{"grey25"}.}

\item{rtol}{Numeric. A numeric relative tolerance used by the ODE solver to determine
if a good solution has been achieved. This is also used in the solved linear
model to check if prior doses do not add anything to the solution. Default is 1e-6.}

\item{run_id}{Integer. Tested model ID. Default is 1.}

\item{ruv}{A list specifying options for residual error used in model fit, containing:
\itemize{
\item \code{YNAME} - string, output name. Typically \code{"y1"}, \code{"y2"},...
\item \code{DVID} - numeric, observation type identifier corresponding to DVID column values
\item \code{TRANS} - string, residual error distribution. Can be: \code{"normal"}, \code{"logNormal"}, \code{"logitNormal"}
\item \code{PRED} - string, prediction variable name from the model
\item \code{ERR} - string, error model type. Options include:
\itemize{
\item "constant" for additive error
\item "proportional" for proportional error
\item "combined1" for combined additive and proportional error
}
\item \code{INIT} - numeric vector, initial values for error parameters (length depends on error model)
\item \code{EST} - logical vector, whether to estimate each error parameter (same length as INIT)
\item \code{BLQM} - below limit of quantification method (can be NULL)
For several observation types list of lists should be provided:
one residual error (ruv) object for each observations.
}}

\item{sc_factor}{Numeric. Scaling factor for DV/PRED/IPRED values. Default is 1 (no scaling).}

\item{scale}{A numeric named vector. Scaling for ODE parameters of the system.
The names must correspond to the parameter identifiers in the ODE specification.
Each of the ODE variables will be divided by the scaling factor. Default is \code{NULL}.}

\item{seed}{Integer. Random seed for synthetic data generation reproducibility. Default is \code{123}.}

\item{sigma}{A named matrix representing a sigma covariance matrix or its
Cholesky decomposition; Default is \code{NULL}.}

\item{shp_i}{String. Column name for shape aesthetic. Default is \code{NULL}.}

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

\item{stat_comp}{A character vector of summary statistics to compute.
Supported internally: \verb{"mean","median","min","max","sd","cmax","SS"}.}

\item{stimes}{A numeric vector of simulation times.}

\item{task_opt}{String. Additional task options to be passed to the fitting software.
For Monolix, this can include specific task configurations or optimization settings.
When \code{NULL}, default tasks (populationParameters, individualParameters, fim, logLikelihood)
will be used.  Default is \code{NULL}.}

\item{tdist}{Logical. If \code{TRUE}, overlay theoretical parameter distributions
based on population mean and OMEGA matrix. Default is \code{TRUE}.}

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

\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{theta}{A named numeric vector of baseline parameters. Default is \code{NULL}.
Parameters listed in \code{params} are replaced by sampled values.}

\item{thetamat}{A named variance-covariance matrix (for parameters brought to normal distribution).
Default is \code{NULL}.}

\item{tsld}{Logical. If \code{TRUE}, uses time since last dose instead of time from first dose. Default is \code{FALSE}.}

\item{val_col}{String. Name of value column. Default is \code{VALUE}.}

\item{wrap_i}{String. Faceting formula for \code{facet_wrap}. Default is \code{NULL}.}

\item{wrap_ncol}{Integer. Number of columns for \code{facet_wrap}. Default is \code{NULL}.}

\item{wrap_nrow}{Integer. Number of rows for \code{facet_wrap}. Default is \code{NULL}.}
}
\description{
The function to store common parameters description
}
