Simulate an IQRmodel

Simulation function for IQRmodels. Able to handle dosing events etc.

sim_IQRmodel(
  model,
  simtime = NULL,
  IC = NULL,
  parameters = NULL,
  dosingTable = NULL,
  eventTable = NULL,
  FLAGsensitivity = FALSE,
  FLAGuseSensEq = TRUE,
  sensParams = NULL,
  FLAGoutputsOnly = FALSE,
  opt_eventTimes = NULL,
  opt_method_stiff = TRUE,
  opt_abstol = 1e-06,
  opt_reltol = 1e-06,
  opt_minstep = 0,
  opt_maxstep = 0,
  opt_initstep = 0,
  opt_maxnumsteps = 1e+05,
  opt_maxerrtestfails = 50,
  opt_maxorder_stiff = 5,
  opt_maxorder_nonstiff = 12,
  opt_maxconvfails = 10,
  opt_maxnonlineariter = 3,
  opt_usesymjac = TRUE,
  opt_sens_simultaneous = FALSE,
  opt_sens_errcon = FALSE,
  opt_sens_maxnonlineariter = 3,
  verbose = FALSE,
  FLAGprogressBar = FALSE
)

Arguments

model

An IQRmodel

simtime

Simulation time vector. If scalar provided then 1001 simulation steps will be used. If not provided seq(0,20, length.out = 1000) will be used if no dosingTable or eventTable provided. If not provided and a dosingTable or eventTable is provide then seq(0,1.5x the max dosing/event time,1000) is used.

   In the case an eventTable is provided simtime can be provided as a list
   with as many entries as IDs in the eventTable. Simulation for the different
   IDs will then be done with the individual time vectors in the simtime list.
   Matching between elements in the simtime list and the eventTable will be
   done by IDs in the eventTable and names of the simtime list entries.
   If simtime not provided as list it will be used for all subjects in the
   eventTable.

   IMPORTANT: If event tables are used for simulation then individual simtime
   is adjusted to start at the first TIME entry in the individual event table.
   This is important to correctly assign regression parameters at the first event.

IC

Named vector with numeric initial conditions for ALL states. If not provided the initial conditions stored in the model will be used as defaults. Important: If initial conditions are provided, then these need to be NUMERIC and be provided for ALL states! If the model contains non-numeric initial conditions, these will be ignored. Basically, user provided initial conditions overwrite all other settings. If the model itself does contain non-numeric initial conditions, then it might be more useful to change these via parameter settings, using the "parameters" input argument. If the eventTable input argument is defined, the IC input argument is not allowed to be provided. In this case ICs are either as defined in the model or can be defined by parameters (using non- numerical initial conditions in the model).

parameters

A named parameter vector to be used for simulation. Named parameters need to be present in the model. If an event table is provided as input argument then these parameters argument defines only the initial set of parameters that might be changed by the event table. In case the event table specifies a population simulation (ID column present) then the parameters argument is used to set the same values for all IDs. If different values are to be set then this needs to be done in the event table.

dosingTable

An IQRdosing object. Should not be provided if argument eventTable is defined. A dosingTable allows to define a dosing scenario for a simulation of a single subject. Please refer to the function IQRdosing to learn more about dosing tables.

eventTable

An IQReventTable object. Should not be used if argument dosingTable is defined. An eventTable allows to define dosing and regression parameter scenarios where the regression parameters can also vary over time. Additionally, it allows to perform population simulations. An ID column needs to be present in the eventTable to identify individual subjects. Please refer to the function IQReventTable to learn more about event tables.

FLAGsensitivity

If TRUE, then parameter sensitivity trajectories are calculated for each state.

FLAGuseSensEq

If TRUE, then the analytic sensitivity equations will be used for the sensitivity integration (if analytic solutions can be derived). If analytic solutions can not be derived, a numerical solution will be used. Interestingly, the numeric solution is sometimes faster, so this is used as the default setting.

sensParams

Vector with parameter names for which to calculate sensitivities. If not provided, all parameters in the model will be used. If the model has already been prepared with same sensParams, no recompilation needed.

FLAGoutputsOnly

Flag allowing to skip the return of states, variables, reactions, state sensitivities. Only outputs defined as OUTPU* in the model and potentially their parameter sensitivities will be returned.

opt_eventTimes

Vector with time steps that should correspond to event times in the model. These need to be provided to ensure correct sensitivity calculation. If a model contains state events and this vector is not provided it will be asked for by throwing an error.

opt_method_stiff

Flag (FALSE: non-stiff, TRUE: stiff)

opt_abstol

Double value for absolute tolerance

opt_reltol

Double value for relative tolerance

opt_minstep

Double value for minimal integrator step-size

opt_maxstep

Double value for maximal integrator step-size

opt_initstep

Double value for initial step-size to be attempted

opt_maxnumsteps

Integer value for maximum number of steps between two outputs

opt_maxerrtestfails

Integer value for maximum number of error test failures in one step

opt_maxorder_stiff

Integer value for maximum order of linear multistep method for STIFF solver (BDF)

opt_maxorder_nonstiff

Integer value for maximum order of linear multistep method for NONSTIFF solver (Adams)

opt_maxconvfails

Integer value for maximum number of nonlinear solver convergence failures in one step

opt_maxnonlineariter

Integer value for maximum number of nonlinear solver iterations permitted per step

opt_usesymjac

Flag if symbolic Jacobian should be used (if available)

opt_sens_simultaneous

Flag to use CV_SIMULTANEOUS (TRUE) or CV_STAGGERED (FALSE) for sensitivity calculations

opt_sens_errcon

Flag indicating if sensitivity variables included into error control strategy (TRUE) or not (FALSE)

opt_sens_maxnonlineariter

Integer value for maximum number of nonlinear solver iterations for sensitivity variables permitted per step

verbose

Flag for outputting additional diagnostic information

FLAGprogressBar

If TRUE then showing a progressbar for event-table simulations with more than 5 subjects

Value

Dataframe with simulation results. If a simulation fails, the incidence is printed to the standard output and NULL is returned.