simulx: Simulation of mixed effects models and longitudinal data

View source: R/simulxR.R

simulxR Documentation

Simulation of mixed effects models and longitudinal data

Description

Compute predictions and sample data from Mlxtran and R models

Usage

simulx(
  model = NULL,
  parameter = NULL,
  covariate = NULL,
  output = NULL,
  treatment = NULL,
  regressor = NULL,
  occasion = NULL,
  varlevel = NULL,
  group = NULL,
  project = NULL,
  nrep = 1,
  npop = NULL,
  fim = NULL,
  saveSmlxProject = NULL,
  result.file = NULL,
  addlines = NULL,
  settings = NULL
)

Arguments

model

a Mlxtran model used for the simulation. It can be a text file or an outut of the inLine function.

parameter

One of

  • a vector of parameters with their names and values,

  • a dataframe with parameters defined for each id or each pop

  • a string, path to a data frame (csv or txt file)

  • a string corresponding to the parameter elements automatically generated by monolix (only when simulation is based on a Monolix project). One of the following mlx parameter elements: "mlx_Pop", "mlx_PopUncertainSA", "mlx_PopUncertainLin", "mlx_PopIndiv", "mlx_PopIndivCov","mlx_CondMean", "mlx_EBEs","mlx_CondDistSample"

covariate

One of

  • a vector of covariates with their names and values.

  • a dataframe with covariates defined for each id

  • a string, path to a data frame (csv or txt file)

  • a string corresponding to the covariate elements automatically generated by monolix (only when simulation is based on a Monolix project). One of the following mlx covariate elements: "mlx_Cov" and "mlx_CovDist"

output

output or list of outputs. An output can be defined by

  • a string corresponding to the output elements automatically generated by monolix (only when simulation is based on a Monolix project) - the format is mlx_nameofoutput.

  • a list with fields

    • name: a vector of output names

    • time:

      • a vector of times

      • a dataframe with columns id, time (columns lloq, uloq, limit are optional)

      • a string, path to a data frame (csv or txt file)

    • lloq: lower limit of quantification (when time is a vector of times)

    • uloq: upper limit of quantification (when time is a vector of times)

    • limit: lower bound of the censoring interval (when time is a vector of times)

treatment

treatment or list of treatments. A treatment can be defined by

  • A list with fields

    • time : a vector of input times,

    • amount : a scalar or a vector of amounts,

    • rate : a scalar or a vector of infusion rates (default=Inf),

    • tinf : a scalar or a vector of infusion times (default=0),

    • washout : a scalar or a vector of boolean (default=F),

    • adm : (or type) the administration type (default=1),

    • repeats : the treatment cycle (optional), a vector with fields

      • cycleDuration : the duration of a cycle,

      • NumberOfRepetitions : the number of cycle repetition

    • probaMissDose: the probability to miss each dose (optional).

  • a dataframe with treatments defined for each id

  • a string, path to a data frame (csv or txt file)

  • a string corresponding to the treatment elements automatically generated by monolix (only when simulation is based on a Monolix project) - for example mlx_Adm1.

regressor

treatment or list of treatments. A treatment can be defined by

  • A list with fields

    • name : a vector of regressor names,

    • time : a vector of times,

    • value : a vector of values.

  • A dataframe with columns id, time, and regressor values

  • a string, path to a data frame (csv or txt file)

occasion

An occasion can be defined by

  • A list with fields

    • name : name of the variable which defines the occasions,

    • time : a vector of times (beginnings of occasions)

  • A dataframe with columns id, time, occasion

  • a string, path to a data frame (csv or txt file)

  • "none", to delete an occasion structure

varlevel

deprecated, use occasion instead.

group

a list, or a list of lists, with fields:

  • size : size of the group (default=1),

  • parameter : if different parameters per group are defined,

  • covariate : if different covariates per group are defined,

  • output : if different outputs per group are defined,

  • treatment : if different treatments per group are defined,

  • regressor : if different regression variables per group are defined.

"level" field is not supported anymore in RsSimulx.

project

the name of a Monolix project

nrep

Samples with or without uncertainty depending which element is given as "parameter".

npop

deprecated, Set parameter = "mlx_popUncertainSA" or "mlx_popUncertainLin" instead.

fim

deprecated, Set parameter = "mlx_popUncertainSA" or "mlx_popUncertainLin" instead.

saveSmlxProject

If specified, smlx project will be save in the path location (by default smlx project is not saved)

result.file

deprecated

addlines

a list with fields:

  • formula: string, or vector of strings, to be inserted .

"section", "block" field are not supported anymore in RsSimulx. You only need to specify a formula. The additional lines will be added in a new section EQUATION.

settings

a list of optional settings

  • seed: initialization of the random number generator (integer) (by default a random seed will be generated)

  • id.out: add (TRUE) / remove (FALSE) columns id and group when only one element (N = 1 or group = 1) (default=FALSE)

  • kw.max: deprecated.

  • replacement : deprecated, use samplingMethod instead

  • samplingMethod: str, Sampling method used for the simulation. One of "keepOrder", "withReplacement", "withoutReplacement" (default "keepOrder")

  • out.trt: TRUE/FALSE (default = TRUE) output of simulx includes treatment

  • out.reg: TRUE/FALSE (default = TRUE) output of simulx includes regressors

  • sharedIds: Vector of Elements that share ids. Available types are "covariate", "output", "treatment", "regressor", "population", "individual" (default c())

  • sameIndividualsAmongGroups: boolean, if True same individuals will be simulated among all groups (default False)

  • exportData: boolean, if True and if a path to save the smlx project (saveSmlxProject) is specified, export the simulated dataset (smlx project directory/Simulation/simulatedData.txt) (default False)

  • regressorInterpolationMethod: interpolation method for missing regressors. One of "lastCarriedForward" (default), "linearInterpolation"

Details

simulx takes advantage of the modularity of hierarchical models for simulating different components of a model: models for population parameters, individual covariates, individual parameters and longitudinal data.

Furthermore, simulx allows to draw different types of longitudinal data, including continuous, count, categorical, and time-to-event data.

The models are encoded using either the model coding language ‘⁠Mlxtran⁠’. ‘⁠Mlxtran⁠’ models are automatically converted into C++ codes, compiled on the fly and linked to R using the ‘⁠RJSONIO⁠’ package. That allows one to implement very easily complex models and to take advantage of the numerical sovers used by the C++ ‘⁠mlxLibrary⁠’.

See http://simulx.lixoft.com for more details.

Value

A list of data frames. Each data frame is an output of simulx

Examples

## Not run: 
myModel <- inlineModel("
[LONGITUDINAL]
input = {A, k, c, a}
EQUATION:
t0    = 0
f_0   = A
ddt_f = -k*f/(c+f)
DEFINITION:
y = {distribution=normal, prediction=f, sd=a}
[INDIVIDUAL]
input = {k_pop, omega}
DEFINITION:
k = {distribution=lognormal, prediction=k_pop, sd=omega}
")

f <- list(name='f', time=seq(0, 30, by=0.1))
y <- list(name='y', time=seq(0, 30, by=2))
parameter <- c(A=100, k_pop=6, omega=0.3, c=10, a=2)

res <- simulx(model     = myModel,
              parameter = parameter,
              occasion  = data.frame(time=c(0, 0), occ=c(1, 2)),
              output    = list(f,y),
              group     = list(size=4),
              saveSmlxProject = "./project.smlx")

res <- simulx(model     = myModel,
              parameter = parameter,
              occasion  = data.frame(time = c(0, 0, 0, 0),
                                     occ1 = c(1, 1, 2, 2),
                                     occ2 = c(1, 2, 3, 4)),
              output    = list(f,y),
              group     = list(size=4))
              
res <- simulx(model     = myModel,
              parameter = parameter,
              output    = list(f,y),
              group     = list(size=4))

plot(ggplotmlx() + geom_line(data=res$f, aes(x=time, y=f, colour=id)) +
     geom_point(data=res$y, aes(x=time, y=y, colour=id)))
print(res$parameter)


## End(Not run)


RsSimulx documentation built on June 22, 2024, 9:36 a.m.

Related to simulx in RsSimulx...