Usage
mmrm_control(
n_cores = 1L,
method = c("Satterthwaite", "Kenward-Roger", "Residual", "Between-Within"),
vcov = NULL,
start = NULL,
accept_singular = TRUE,
drop_visit_levels = TRUE,
...,
optimizers = h_get_optimizers(...)
)
Arguments
- n_cores
(
count
)
number of cores to be used.- method
(
string
)
adjustment method for degrees of freedom.- vcov
(
string
)
coefficients covariance matrix adjustment method.- start
(
numeric
orNULL
)
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 withh_get_optimizers()
.
Details
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.
The
method
andvcov
arguments specify the degrees of freedom and coefficients covariance matrix adjustment methods, respectively. Allowedvcov
includes: "Asymptotic", "Kenward-Roger", "Kenward-Roger-Linear", "Empirical" (CR0), "Empirical-Jackknife" (CR2), and "Empirical-Bias-Reduced" (CR3). Allowedmethod
includes: "Satterthwaite", "Kenward-Roger", "Between-Within" and "Residual". Ifmethod
is "Kenward-Roger" then only "Kenward-Roger" or "Kenward-Roger-Linear" are allowed forvcov
.The
vcov
argument can beNULL
to use the default covariance method depending on themethod
used for degrees of freedom, see the following table: |method
| Defaultvcov
| |-----------|----------| |Satterthwaite| Asymptotic| |Kenward-Roger| Kenward-Roger| |Residual| Empirical| |Between-Within| Asymptotic|Please note that "Kenward-Roger" for "Unstructured" covariance gives different results compared to SAS; Use "Kenward-Roger-Linear" for
vcov
instead for better matching of the SAS results.
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: 0x56067f1d9770>
#> <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"
#>
#> $vcov
#> [1] "Asymptotic"
#>
#> $n_cores
#> [1] 1
#>
#> $drop_visit_levels
#> [1] TRUE
#>
#> attr(,"class")
#> [1] "mmrm_control"