Fit nonlinear mixed models with SAEM

+ + +

This function uses saemix::saemix() as a backend for fitting nonlinear mixed +effects models created from mmkin row objects using the Stochastic Approximation +Expectation Maximisation algorithm (SAEM).

+ +

saem(object, ...)
+
+# S3 method for mmkin
+saem(
+  object,
+  transformations = c("mkin", "saemix"),
+  degparms_start = numeric(),
+  test_log_parms = TRUE,
+  conf.level = 0.6,
+  solution_type = "auto",
+  nbiter.saemix = c(300, 100),
+  control = list(displayProgress = FALSE, print = FALSE, nbiter.saemix = nbiter.saemix,
+    save = FALSE, save.graphs = FALSE),
+  fail_with_errors = TRUE,
+  verbose = FALSE,
+  quiet = FALSE,
+  ...
+)
+
+# S3 method for saem.mmkin
+print(x, digits = max(3, getOption("digits") - 3), ...)
+
+saemix_model(
+  object,
+  solution_type = "auto",
+  transformations = c("mkin", "saemix"),
+  degparms_start = numeric(),
+  test_log_parms = FALSE,
+  conf.level = 0.6,
+  verbose = FALSE,
+  ...
+)
+
+saemix_data(object, verbose = FALSE, ...)

+ +

Arguments

object: An mmkin row object containing several fits of the same +mkinmod model to different datasets
...: Further parameters passed to saemix::saemixModel.
transformations: Per default, all parameter transformations are done +in mkin. If this argument is set to 'saemix', parameter transformations +are done in 'saemix' for the supported cases. Currently this is only +supported in cases where the initial concentration of the parent is not fixed, +SFO or DFOP is used for the parent and there is either no metabolite or one.
degparms_start: Parameter values given as a named numeric vector will +be used to override the starting values obtained from the 'mmkin' object.
test_log_parms: If TRUE, an attempt is made to use more robust starting +values for population parameters fitted as log parameters in mkin (like +rate constants) by only considering rate constants that pass the t-test +when calculating mean degradation parameters using mean_degparms.
conf.level: Possibility to adjust the required confidence level +for parameter that are tested if requested by 'test_log_parms'.
solution_type: Possibility to specify the solution type in case the +automatic choice is not desired
nbiter.saemix: Convenience option to increase the number of +iterations
control: Passed to saemix::saemix.
fail_with_errors: Should a failure to compute standard errors +from the inverse of the Fisher Information Matrix be a failure?
verbose: Should we print information about created objects of +type saemix::SaemixModel and saemix::SaemixData?
quiet: Should we suppress the messages saemix prints at the beginning +and the end of the optimisation process?
x: An saem.mmkin object to print
digits: Number of digits to use for printing

Value

An S3 object of class 'saem.mmkin', containing the fitted +saemix::SaemixObject as a list component named 'so'. The +object also inherits from 'mixed.mmkin'. +An saemix::SaemixModel object. +An saemix::SaemixData object.

Details

An mmkin row object is essentially a list of mkinfit objects that have been +obtained by fitting the same model to a list of datasets using mkinfit.

Starting values for the fixed effects (population mean parameters, argument +psi0 of saemix::saemixModel() are the mean values of the parameters found +using mmkin.

Examples

# \dontrun{
+ds <- lapply(experimental_data_for_UBA_2019[6:10],
+ function(x) subset(x$data[c("name", "time", "value")]))
+names(ds) <- paste("Dataset", 6:10)
+f_mmkin_parent_p0_fixed <- mmkin("FOMC", ds,
+  state.ini = c(parent = 100), fixed_initials = "parent", quiet = TRUE)
+f_saem_p0_fixed <- saem(f_mmkin_parent_p0_fixed)
+#>  
+#> Error in rxModelVars_(obj): Not compatible with STRSXP: [type=NULL].
+
+f_mmkin_parent <- mmkin(c("SFO", "FOMC", "DFOP"), ds, quiet = TRUE)
+f_saem_sfo <- saem(f_mmkin_parent["SFO", ])
+#>  
+#> Error in rxModelVars_(obj): Not compatible with STRSXP: [type=NULL].
+f_saem_fomc <- saem(f_mmkin_parent["FOMC", ])
+#>  
+#> Error in rxModelVars_(obj): Not compatible with STRSXP: [type=NULL].
+f_saem_dfop <- saem(f_mmkin_parent["DFOP", ])
+#>  
+#> Error in rxModelVars_(obj): Not compatible with STRSXP: [type=NULL].
+
+# The returned saem.mmkin object contains an SaemixObject, therefore we can use
+# functions from saemix
+library(saemix)
+#> Loading required package: npde
+#> 
+#> Attaching package: ‘npde’
+#> The following object is masked from ‘package:nlmixr’:
+#> 
+#>     warfarin
+#> Package saemix, version 3.0
+#>   please direct bugs, questions and feedback to emmanuelle.comets@inserm.fr
+#> 
+#> Attaching package: ‘saemix’
+#> The following objects are masked from ‘package:npde’:
+#> 
+#>     kurtosis, skewness
+#> The following object is masked from ‘package:RxODE’:
+#> 
+#>     phi
+compare.saemix(f_saem_sfo$so, f_saem_fomc$so, f_saem_dfop$so)
+#> Error in compare.saemix(f_saem_sfo$so, f_saem_fomc$so, f_saem_dfop$so): object 'f_saem_sfo' not found
+plot(f_saem_fomc$so, plot.type = "convergence")
+#> Error in h(simpleError(msg, call)): error in evaluating the argument 'x' in selecting a method for function 'plot': object 'f_saem_fomc' not found
+plot(f_saem_fomc$so, plot.type = "individual.fit")
+#> Error in h(simpleError(msg, call)): error in evaluating the argument 'x' in selecting a method for function 'plot': object 'f_saem_fomc' not found
+plot(f_saem_fomc$so, plot.type = "npde")
+#> Error in h(simpleError(msg, call)): error in evaluating the argument 'x' in selecting a method for function 'plot': object 'f_saem_fomc' not found
+plot(f_saem_fomc$so, plot.type = "vpc")
+#> Error in h(simpleError(msg, call)): error in evaluating the argument 'x' in selecting a method for function 'plot': object 'f_saem_fomc' not found
+
+f_mmkin_parent_tc <- update(f_mmkin_parent, error_model = "tc")
+f_saem_fomc_tc <- saem(f_mmkin_parent_tc["FOMC", ])
+#>  
+#> Error in rxModelVars_(obj): Not compatible with STRSXP: [type=NULL].
+compare.saemix(f_saem_fomc$so, f_saem_fomc_tc$so)
+#> Error in compare.saemix(f_saem_fomc$so, f_saem_fomc_tc$so): object 'f_saem_fomc' not found
+
+sfo_sfo <- mkinmod(parent = mkinsub("SFO", "A1"),
+  A1 = mkinsub("SFO"))
+#> Temporary DLL for differentials generated and loaded
+fomc_sfo <- mkinmod(parent = mkinsub("FOMC", "A1"),
+  A1 = mkinsub("SFO"))
+#> Temporary DLL for differentials generated and loaded
+dfop_sfo <- mkinmod(parent = mkinsub("DFOP", "A1"),
+  A1 = mkinsub("SFO"))
+#> Temporary DLL for differentials generated and loaded
+# The following fit uses analytical solutions for SFO-SFO and DFOP-SFO,
+# and compiled ODEs for FOMC that are much slower
+f_mmkin <- mmkin(list(
+    "SFO-SFO" = sfo_sfo, "FOMC-SFO" = fomc_sfo, "DFOP-SFO" = dfop_sfo),
+  ds, quiet = TRUE)
+# saem fits of SFO-SFO and DFOP-SFO to these data take about five seconds
+# each on this system, as we use analytical solutions written for saemix.
+# When using the analytical solutions written for mkin this took around
+# four minutes
+f_saem_sfo_sfo <- saem(f_mmkin["SFO-SFO", ])
+#>  
+#> Error in rxModelVars_(obj): Not compatible with STRSXP: [type=NULL].
+f_saem_dfop_sfo <- saem(f_mmkin["DFOP-SFO", ])
+#>  
+#> Error in rxModelVars_(obj): Not compatible with STRSXP: [type=NULL].
+# We can use print, plot and summary methods to check the results
+print(f_saem_dfop_sfo)
+#> Error in h(simpleError(msg, call)): error in evaluating the argument 'x' in selecting a method for function 'print': object 'f_saem_dfop_sfo' not found
+plot(f_saem_dfop_sfo)
+#> Error in h(simpleError(msg, call)): error in evaluating the argument 'x' in selecting a method for function 'plot': object 'f_saem_dfop_sfo' not found
+summary(f_saem_dfop_sfo, data = TRUE)
+#> Error in h(simpleError(msg, call)): error in evaluating the argument 'object' in selecting a method for function 'summary': object 'f_saem_dfop_sfo' not found
+
+# The following takes about 6 minutes
+#f_saem_dfop_sfo_deSolve <- saem(f_mmkin["DFOP-SFO", ], solution_type = "deSolve",
+#  control = list(nbiter.saemix = c(200, 80), nbdisplay = 10))
+
+#saemix::compare.saemix(list(
+#  f_saem_dfop_sfo$so,
+#  f_saem_dfop_sfo_deSolve$so))
+
+# If the model supports it, we can also use eigenvalue based solutions, which
+# take a similar amount of time
+#f_saem_sfo_sfo_eigen <- saem(f_mmkin["SFO-SFO", ], solution_type = "eigen",
+#  control = list(nbiter.saemix = c(200, 80), nbdisplay = 10))
+# }
+

+ +

Fit nonlinear mixed models with SAEM

Arguments

Value

Details

See also

Examples