Create data for VPC

Simulates trial data for producing VPCs

vpc_IQRnlmeProject(
  project = NULL,
  dataVPC = NULL,
  Ntrials,
  gpf = NULL,
  dosingInfo = NULL,
  regressors = NULL,
  model = NULL,
  modelsSample = NULL,
  FLAGpreparePC = FALSE,
  simtimeOption = c("obs", "simTFD", "simTAD"),
  simtimeN = 200,
  simtimes = NULL,
  simtimeMax = NULL,
  FLAGindivSimtimeMax = FALSE,
  FLAGaddResidualNoise = TRUE,
  FLAGsampleUncertainty = TRUE,
  FLAGlogOutput = FALSE,
  factorMult = NULL,
  ncores = 1,
  seed = NULL,
  FLAGkeepParameters = FALSE,
  opt_initstep = 0,
  opt_abstol = 1e-06,
  opt_reltol = 1e-06,
  opt_maxstep = 0,
  opt_minstep = 0,
  par_lower = NULL,
  par_upper = NULL,
  FLAGfixDoseOverlap = TRUE,
  FLAGstopFailedSim = FALSE
)

Arguments

project

Path to IQRnlmeProject to be used to generate the VPC. The stuctural model of this project will be used and parameters will be sampled from this project.

dataVPC

Dataset for VPC generation. If undefined, the modeling dataset from modelSampleSimulate will be used. Mandatory if sampling from GPF.

Ntrials

Number of trials to simulate for the VPC

gpf

GPF object or path to GPF as xlsx file.

dosingInfo

Required for information on lagtimes and zero order absorption when no project is provided. A list with one field per input in the model. Fields need to be named according to the input names in the model. Each field is a named vector with the required name "type" and the optional names "Tlag" and "Tk0". "type" can be "BOLUS", "INFUSION", or "ABSORPTION0". Only difference between INFUSION and ABSORPTION0 is that in the first case the infusion RATE is provided in the data and in the second the absorption time is sampled. Lag times can be added to each dosing input by defining "Tlag" as vector element. The value of this element needs to be the parameter named for this lag time. If type="ABSORPTION0" then also "Tk0" needs to be present as element in the vector. The value is a parameter name that also needs to appear in the model. For examples see dosing_IQRest

regressors

Required for information on regressors if no project is given. Input is a vector with the names of the regressors taken from the dataset.

model

Required structural model (IQRmodel) if no project is given

modelsSample

If sequential model building has been done (e.g. PKPD) model parameters might need to be sampled from additional IQRnlmeProjects. modelSample can be a vector with paths to these additional IQRnlmeProjects. It is not allowed that in these projects and modelSampleSimulate estimated parameter names overlap

FLAGpreparePC

Flag whether to prepare prediction correction by corresponding additional simulations

simtimeOption

Select for which times, outputs are simulated: 'obs': respective indivdual observation time, 'simTFD': Equidistant or user-profided times after first dose, or 'simTAD': equidistant or user-provided times after last dose (these will be repeated for each dose)

simtimeN

Define number of simulation time steps to add between smallest and largest event time in the dataset. Equidistant sampling will be used.

simtimes

Vector of simulation times. If not NULL, this vector of simulation times overrules simtimeN

simtimeMax

Define maximum simulation time for VPC for all subjects.

FLAGindivSimtimeMax

If TRUE then the simulation time of a simulated subject will be limited to the max event time for this subject in the dataset. A subject here basically defines the dosing schedule and the covariates. If set to FALSE then the simulation results will not be truncated.

FLAGaddResidualNoise

logical. If TRUE then residual noise will be added to the simulations

FLAGsampleUncertainty

logical. If set to TRUE then for each new trial new population parameters are drawn from the uncertainty distribution

FLAGlogOutput

Logical. If set to TRUE then the model outputs are assumed to be log transformed data and will be back-transformed. The data in dataVPC are assumed to be in the normal domain - to simplify dose-normalization. If FALSE then data and model outputs are assumed to be in the same domain.

factorMult

named vector allowing to define multiplicative factors to modulate by name selected sampled parameters for simulation

ncores

Number of cores for parallelization.

seed

Set seed for reproducible sampling. If the simulations are parallelized, the seed will be set for the simulation of each population to seed + population number - 1.

FLAGkeepParameters

Logical. If set to TRUE, sampled parameters will be added to returned simulation results. Defaults to FALSE

opt_initstep

Double value for initial step-size to be attempted for simulation

opt_abstol

Double value for absolute tolerance for simulation

opt_reltol

Double value for relative tolerance for simulation

opt_maxstep

Double value for maximal integrator step-size for simulation

opt_minstep

Double value for minimal integrator step-size for simulation

par_lower

Named vector of lower limits for sampled individual parameters. Applies to individual parameters after potential modulation by factorMult argument.

par_upper

Named vector of upper limits for sampled individual parameters. Applies to individual parameters after potential modulation by factorMult argument.

FLAGfixDoseOverlap

Input argument for IQReventTable. If TRUE (default) then ensure non-overlapping dosing intervals if these occur by re-defining the dosing events. If FALSE in case of overlapping dose intervals, error is issued. Please inspect correct behavior. If correction does not work, par_upper could be an alternative to avoid overlapping dosing events.

FLAGstopFailedSim

Logical. If TRUE execution will be stopped if simulation fails for any of the repeated trials. Defaults to FALSE. Execution will stop anyways if all simulations fail.

Value

List with data frames sim and obs. If not prediction correction preparation is required, sim contains individual predictions and obs the observation data, including dosing records. Otherwise sim and obs contains typical predictions in addition.

Details

Model from IQR nlme project is used to simulate trial population defined either in contained dataset or given dataset as dataVPC. It will also perform additional simulations to performed prediction correction for the VPCs if required. For the observations, a typical prediction will also be performed using the population parameter point estimates. The VPC can subsequently e plotted using plotVPC_IQRdataVPC.

See also

Other IQRnlmeProject: IQRnlmeEst(), IQRnlmeProject(), addCovariateToModelSpec_IQRest(), addPar_modelSpec(), as_IQRnlmeProject(), as_IQRnlmeProjectMulti(), bootstrap_IQRnlmeProject(), compareModels_IQRnlmeProjectMulti(), convertETAINDIVPRED_IQRnlmeProject(), covariateEffect_IQRnlmeProject(), data_IQRest(), dosing_IQRest(), duplicate_IQRnlmeProject(), eigenvalues_IQRnlmeProject(), exportVirtualSubjects_IQRnlmeProject(), getData_IQRnlmeProject(), getETAs_IQRnlmeProject(), getEst_IQRnlmeProject(), getHeader_IQRnlmeProject(), getIndivParameters_IQRnlmeProject(), getIndivPredictions_IQRnlmeProject(), getModel_IQRnlmeProject(), getObsPred_IQRnlmeProject(), getPopParameters_IQRnlmeProject(), getResults_IQRnlmeProject(), getResults_IQRnlmeProjectMulti(), hasrun_IQRnlmeProject(), hasrun_IQRnlmeProjectMulti(), informationContent_IQRnlmeProject(), is_IQRnlmeEst(), is_IQRnlmeProject(), is_IQRnlmeProjectMulti(), is_MONOLIX_IQRnlmeProject(), is_NLMIXR_IQRnlmeProject(), is_NONMEM_IQRnlmeProject(), modelSpec_IQRest(), outlier_IQRnlmeProject(), plot.IQRnlmeProject(), plot.IQRnlmeProjectMulti(), plotBLQVPC_IQRdataVPC(), plotConvergence_IQRnlmeProject(), plotETACOV_IQRnlmeProject(), plotETA_IQRnlmeProject(), plotGOF_IQRnlmeProject(), plotINDIVSIM_IQRnlmeProject(), plotINDIV_IQRnlmeProject(), plotMEANSIM_IQRnlmeProject(), plotVPC_IQRdataVPC(), pred_IQRnlmeProject(), print.IQRnlmeEst(), print.IQRnlmeProject(), print.IQRnlmeProjectMulti(), print_modelSpec(), run_IQRnlmeProject(), run_IQRnlmeProjectMulti(), sample_IQRnlmeProject(), scm_IQRnlmeProject(), summary.IQRnlmeProject(), summary.IQRnlmeProjectMulti(), summaryComments_IQRnlmeProjectMulti(), summaryCorrelations_IQRnlmeProjectMulti(), summaryCovariates_IQRnlmeProjectMulti(), summaryParameters_IQRnlmeProjectMulti()

Other VPC: extractBins_VPCplot(), filterMutateDataVPC(), plotBLQVPC_IQRdataVPC(), plotVPC_IQRdataVPC(), plotVPC_IQRtteProject()

Examples

if (FALSE) { # \dontrun{
# Example 1: Basic usage
projectPath <- system.file("examples/NLMEProjects/Webinar/03-Models/00_FinalPKmodel/", package = "IQRtools")
vpcData <- vpc_IQRnlmeProject(project = projectPath, Ntrials = 5, FLAGsampleUncertainty = FALSE) # In real applications, Ntrials should be appropriately sized.
plotVPC_IQRdataVPC(vpcData)
} # }