Control Parameters for Fitting an MMRM

Fine-grained specification of the MMRM fit details is possible using this control function.

Usage

mmrm_control(
  n_cores = 1L,
  method = c("Satterthwaite", "Kenward-Roger", "Kenward-Roger-Linear"),
  start = NULL,
  accept_singular = TRUE,
  drop_visit_levels = TRUE,
  ...,
  optimizers = h_get_optimizers(...)
)

Arguments

n_cores

(int)
number of cores to be used.

method

(string)
adjustment method for degrees of freedom and coefficients covariance matrix.

start

(numeric or NULL)
optional start values for variance parameters.

accept_singular

(flag)
whether singular design matrices are reduced to full rank automatically and additional coefficient estimates will be missing.

drop_visit_levels

(flag)
whether to drop levels for visit variable, if visit variable is a factor, see details.

...

additional arguments passed to h_get_optimizers().

optimizers

(list)
optimizer specification, created with h_get_optimizers().

Value

List of class mmrm_control with the control parameters.

Details

The drop_visit_levels flag will decide whether unobserved visits will be kept for analysis. For example, if the data only has observations at visits VIS1, VIS3 and VIS4, by default they are treated to be equally spaced, the distance from VIS1 to VIS3, and from VIS3 to VIS4, are identical. However, you can manually convert this visit into a factor, with levels = c("VIS1", "VIS2", "VIS3", "VIS4"), and also use drop_visits_levels = FALSE, then the distance from VIS1 to VIS3 will be double, as VIS2 is a valid visit. However, please be cautious because this can lead to convergence failure when using an unstructured covariance matrix and there are no observations at the missing visits.

Examples

mmrm_control(
  optimizer_fun = stats::optim,
  optimizer_args = list(method = "L-BFGS-B")
)
#> $optimizers
#> $optimizers$custom_optimizer
#> function (par, fn, gr = NULL, ..., method = c("Nelder-Mead", 
#>     "BFGS", "CG", "L-BFGS-B", "SANN", "Brent"), lower = -Inf, 
#>     upper = Inf, control = list(), hessian = FALSE) 
#> {
#>     fn1 <- function(par) fn(par, ...)
#>     gr1 <- if (!is.null(gr)) 
#>         function(par) gr(par, ...)
#>     method <- match.arg(method)
#>     if ((any(lower > -Inf) || any(upper < Inf)) && !any(method == 
#>         c("L-BFGS-B", "Brent"))) {
#>         warning("bounds can only be used with method L-BFGS-B (or Brent)")
#>         method <- "L-BFGS-B"
#>     }
#>     npar <- length(par)
#>     con <- list(trace = 0, fnscale = 1, parscale = rep.int(1, 
#>         npar), ndeps = rep.int(0.001, npar), maxit = 100L, abstol = -Inf, 
#>         reltol = sqrt(.Machine$double.eps), alpha = 1, beta = 0.5, 
#>         gamma = 2, REPORT = 10, warn.1d.NelderMead = TRUE, type = 1, 
#>         lmm = 5, factr = 1e+07, pgtol = 0, tmax = 10, temp = 10)
#>     nmsC <- names(con)
#>     if (method == "Nelder-Mead") 
#>         con$maxit <- 500
#>     if (method == "SANN") {
#>         con$maxit <- 10000
#>         con$REPORT <- 100
#>     }
#>     con[(namc <- names(control))] <- control
#>     if (length(noNms <- namc[!namc %in% nmsC])) 
#>         warning("unknown names in control: ", paste(noNms, collapse = ", "))
#>     if (con$trace < 0) 
#>         warning("read the documentation for 'trace' more carefully")
#>     else if (method == "SANN" && con$trace && as.integer(con$REPORT) == 
#>         0) 
#>         stop("'trace != 0' needs 'REPORT >= 1'")
#>     if (method == "L-BFGS-B" && any(!is.na(match(c("reltol", 
#>         "abstol"), namc)))) 
#>         warning("method L-BFGS-B uses 'factr' (and 'pgtol') instead of 'reltol' and 'abstol'")
#>     if (npar == 1 && method == "Nelder-Mead" && isTRUE(con$warn.1d.NelderMead)) 
#>         warning("one-dimensional optimization by Nelder-Mead is unreliable:\nuse \"Brent\" or optimize() directly")
#>     if (npar > 1 && method == "Brent") 
#>         stop("method = \"Brent\" is only available for one-dimensional optimization")
#>     lower <- as.double(rep_len(lower, npar))
#>     upper <- as.double(rep_len(upper, npar))
#>     res <- if (method == "Brent") {
#>         if (any(!is.finite(c(upper, lower)))) 
#>             stop("'lower' and 'upper' must be finite values")
#>         res <- optimize(function(par) fn(par, ...)/con$fnscale, 
#>             lower = lower, upper = upper, tol = con$reltol)
#>         names(res)[names(res) == c("minimum", "objective")] <- c("par", 
#>             "value")
#>         res$value <- res$value * con$fnscale
#>         c(res, list(counts = c(`function` = NA, gradient = NA), 
#>             convergence = 0L, message = NULL))
#>     }
#>     else .External2(C_optim, par, fn1, gr1, method, con, lower, 
#>         upper)
#>     if (hessian) 
#>         res$hessian <- .External2(C_optimhess, res$par, fn1, 
#>             gr1, con)
#>     res
#> }
#> <bytecode: 0x5635d7a19ff8>
#> <environment: namespace:stats>
#> attr(,"args")
#> attr(,"args")$control
#> list()
#> 
#> attr(,"args")$method
#> [1] "L-BFGS-B"
#> 
#> attr(,"class")
#> [1] "partial"  "function"
#> 
#> 
#> $start
#> NULL
#> 
#> $accept_singular
#> [1] TRUE
#> 
#> $method
#> [1] "Satterthwaite"
#> 
#> $n_cores
#> [1] 1
#> 
#> $drop_visit_levels
#> [1] TRUE
#> 
#> attr(,"class")
#> [1] "mmrm_control"