remix: REMixed algorithm

Description

Regularization and Estimation in Mixed effects model.

Usage

remix(
  project = NULL,
  final.project = NULL,
  dynFUN,
  y,
  ObsModel.transfo,
  alpha,
  lambda,
  eps1 = 10^(-2),
  eps2 = 10^(-1),
  selfInit = FALSE,
  pop.set1 = NULL,
  pop.set2 = NULL,
  pop.set3 = NULL,
  prune = NULL,
  n = NULL,
  parallel = TRUE,
  ncores = NULL,
  print = TRUE,
  verbose = FALSE,
  digits = 3,
  trueValue = NULL,
  finalSAEM = FALSE,
  test = TRUE,
  max.iter = +Inf,
  p.max = 0.05
)

Value

a list of outputs of final project and through the iteration :

finalRes: containing loglikelihood LL and penalized loglikelihood LL.pen values, final population parameters param and final regularization parameters alpha values, number of iterations iter and time needed , if computed, the estimated standard errors standardError and if test computed, the final results before test saemBeforeTest ;
iterOutputs: the list of all remix outputs, i.e. parameters, lieklihood, SAEM estimates and convergence criterion value over the iteration.

Arguments

project

directory of the Monolix project (in .mlxtran). If NULL, the current loaded project is used (default is NULL).

final.project

directory of the final Monolix project (default add "_upd" to the Monolix project).

dynFUN

function computing the dynamics of interest for a set of parameters. This function need to contain every sub-function that it may needs (as it is called in a foreach loop). The output of this function need to return a data.frame with time as first columns and named dynamics in other columns. It must take in input :

parms

a named vector of parameter.

time

vector a timepoint.

See dynFUN_demo, model.clairon, model.pasin or model.pk for examples.

initial condition of the mechanism model, conform to what is asked in dynFUN. If regressor used in Monolix provided a named list of vector of individual initial conditions. Each vector need to be of length 1 (same for all), or exactly the numbre of individuals (range in the same order as their id).

ObsModel.transfo

list containing two lists of transformations and two vectors linking each transformations to their observation model name in the Monolix project. The list should include identity transformations and be named S and R. The two vectors should be named linkS and linkR.

Both S (for the direct observation models) and linkS, as well as R (for latent process models) and linkR, must have the same length.

S: a list of transformations for the direct observation models. Each transformation corresponds to a variable $Y_p=h_p(S_p)$, where the name indicates which dynamic is observed (from dynFUN);
linkS: a vector specifying the observation model names (that is used in the monolix project, alpha1, etc.) for each transformation, in the same order as in S;

R

similarly, a list of transformations for the latent process models. Although currently there is only one latent dynamic, each $s_k, k\leq K$ transformation corresponds to the same dynamic but may vary for each $Y_k$ observed. The names should match the output from dynFUN;

linkR

a vector specifying the observation model names for each transformation, in the same order as in R.

alpha

named list of named vector "alpha0", "alpha1" (all alpha1 are mandatory). The name of alpha$alpha0 and alpha$alpha1 are the observation model names from the monolix project to which they are linked (if the observations models are defined whithout intercept, alpha$alpha0 need to be set to the vector NULL).

lambda

penalization parameter $\lambda$.

eps1

integer (>0) used to define the convergence criteria for the regression parameters.

eps2

integer (>0) used to define the convergence criteria for the likelihood.

selfInit

logical, if the SAEM is already done in the monolix project should be use as the initial point of the algorithm (if FALSE, SAEM is automatically compute according to pop.set1 settings ; if TRUE, a SAEM through monolix need to have been launched).

pop.set1

population parameters setting for initialisation (see details).

pop.set2

population parameters setting for iterations.

pop.set3

population parameters setting for final estimation.

prune

percentage for prunning ($\in[0;1]$) in the Adaptative Gauss-Hermite algorithm used to compute the log-likelihood and its derivates (see gh.LL).

number of points for gaussian quadrature (see gh.LL).

parallel

logical, if the computation should be done in parallel when possible (default TRUE).

ncores

number of cores for parallelization (default NULL and detectCores is used).

logical, if the results and algotihm steps should be displayed in the console (default to TRUE).

verbose

logical, if progress bar should be printed when possible.

digits

number of digits to print (default to 3).

trueValue

-for simulation purposes- named vector of true value for parameters.

finalSAEM

logical, if a final SAEM should be launch with respect to the final selected set.

test

if Wald test should be computed at the end of the iteration.

max.iter

maximum number of iterations (default 20).

p.max

maximum value to each for wald test p.value (default 0.05).

Details

See REMixed-package for details on the model. For population parameter estimation settings, see (<https://monolixsuite.slp-software.com/r-functions/2024R1/setpopulationparameterestimationsettings>).

Examples

Run this code

if (FALSE) {
project <- getMLXdir()

ObsModel.transfo = list(S=list(AB=log10),
                        linkS="yAB",
                        R=rep(list(S=function(x){x}),5),
                        linkR = paste0("yG",1:5))

alpha=list(alpha0=NULL,
           alpha1=setNames(paste0("alpha_1",1:5),paste0("yG",1:5)))

y = c(S=5,AB=1000)
lambda = 382.22

res = remix(project = project,
            dynFUN = dynFUN_demo,
            y = y,
            ObsModel.transfo = ObsModel.transfo,
            alpha = alpha,
            selfInit = TRUE,
            eps1=10**(-2),
            eps2=1,
            lambda=lambda)

summary(res)

trueValue = read.csv(paste0(dirname(project),"/demoSMLX/Simulation/populationParameters.txt"))

plotSAEM(res,paramToPlot = c("delta_S_pop","phi_S_pop","delta_AB_pop"),trueValue=trueValue)
}