% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/fit.R
\name{mmrm_control}
\alias{mmrm_control}
\title{Control Parameters for Fitting an MMRM}
\usage{
mmrm_control(
  n_cores = 1L,
  method = c("Satterthwaite", "Kenward-Roger", "Residual", "Between-Within"),
  vcov = NULL,
  start = std_start,
  accept_singular = TRUE,
  drop_visit_levels = TRUE,
  disable_theta_vcov = FALSE,
  emmeans_gcomp_vars = NULL,
  ...,
  optimizers = h_get_optimizers(...)
)
}
\arguments{
\item{n_cores}{(\code{count})\cr number of cores to be used.}

\item{method}{(\code{string})\cr adjustment method for degrees of freedom.}

\item{vcov}{(\code{string})\cr coefficients covariance matrix adjustment method.}

\item{start}{(\code{NULL}, \code{numeric} or \code{function})\cr optional start values for variance
parameters. See details for more information.}

\item{accept_singular}{(\code{flag})\cr whether singular design matrices are reduced
to full rank automatically and additional coefficient estimates will be missing.}

\item{drop_visit_levels}{(\code{flag})\cr whether to drop levels for visit variable,
if visit variable is a factor, see details.}

\item{disable_theta_vcov}{(\code{flag})\cr whether to disable calculation of
variance-covariance matrix for variance parameters. This can speed up fitting
when there are many variance parameters, see details.}

\item{emmeans_gcomp_vars}{(\code{character} or \code{NULL})\cr names of variables to
treat as fixed in the G-computation correction for emmeans. When non-\code{NULL},
enables the correction in \code{\link{emmeans_support}}, producing the average
treatment effect (ATE) with corrected standard errors. The visit variable
(identified from the covariance structure) is computed separately per
level. All other named variables are treated as intervention (subjects
pooled across levels). All variables not named are averaged over using
each subject's actual values.}

\item{...}{additional arguments passed to \code{\link[=h_get_optimizers]{h_get_optimizers()}}.}

\item{optimizers}{(\code{list})\cr optimizer specification, created with \code{\link[=h_get_optimizers]{h_get_optimizers()}}.
Please note that optimizers using the Hessian will not be compatible with
\code{disable_theta_vcov = TRUE} and an error will be raised in that case.}
}
\value{
List of class \code{mmrm_control} with the control parameters.
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}}
Fine-grained specification of the MMRM fit details is possible using this
control function.
}
\details{
For example, if the data only has observations at visits \code{VIS1}, \code{VIS3} and \code{VIS4}, by default
they are treated to be equally spaced, the distance from \code{VIS1} to \code{VIS3}, and from \code{VIS3} to \code{VIS4},
are identical. However, you can manually convert this visit into a factor, with
\code{levels = c("VIS1", "VIS2", "VIS3", "VIS4")}, and also use \code{drop_visits_levels = FALSE},
then the distance from \code{VIS1} to \code{VIS3} will be double, as \code{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.
\itemize{
\item The \code{method} and \code{vcov} arguments specify the degrees of freedom and coefficients
covariance matrix adjustment methods, respectively.
\itemize{
\item Allowed \code{vcov} includes: "Asymptotic", "Kenward-Roger", "Kenward-Roger-Linear", "Empirical" (CR0),
"Empirical-Jackknife" (CR3), and "Empirical-Bias-Reduced" (CR2).
\item Allowed \code{method} includes: "Satterthwaite", "Kenward-Roger", "Between-Within" and "Residual".
\item If \code{method} is "Kenward-Roger" then only "Kenward-Roger" or "Kenward-Roger-Linear" are allowed for \code{vcov}.
}
\item The \code{vcov} argument can be \code{NULL} to use the default covariance method depending on the \code{method}
used for degrees of freedom, see the following table:\tabular{ll}{
   \code{method} \tab Default \code{vcov} \cr
   Satterthwaite \tab Asymptotic \cr
   Kenward-Roger \tab Kenward-Roger \cr
   Residual \tab Empirical \cr
   Between-Within \tab Asymptotic \cr
}

\item Please note that "Kenward-Roger" for "Unstructured" covariance gives different results
compared to SAS; Use "Kenward-Roger-Linear" for \code{vcov} instead for better matching
of the SAS results.
\item The argument \code{start} is used to facilitate the choice of initial values for fitting the model.
If \code{function} is provided, make sure its parameter is a valid element of \code{mmrm_tmb_data}
or \code{mmrm_tmb_formula_parts} and it returns a numeric vector.
By default or if \code{NULL} is provided, \code{std_start} will be used.
Other implemented methods include \code{emp_start}.
\item Disabling the \code{theta_vcov} calculation can speed up the fitting process when there are many variance
parameters. However, this has also drawbacks. We can no longer check that the variance parameter estimates
are indeed at a local maximum of the log-likelihood surface, and therefore convergence issues might go unnoticed.
In addition, some covariance matrix adjustment methods (e.g., Kenward-Roger) require \code{theta_vcov} to be calculated.
These will then raise errors.
}
}
\examples{
mmrm_control(
  optimizer_fun = stats::optim,
  optimizer_args = list(method = "L-BFGS-B")
)
}
