Skip to contents

Fit an MMRM

Source: R/fit.R
mmrm.Rd

[Experimental]

This is the main function fitting the MMRM.

Usage

mmrm(
  formula,
  data,
  weights = NULL,
  covariance = NULL,
  reml = TRUE,
  control = mmrm_control(...),
  ...
)

Arguments

formula

(formula)
the model formula, see details.

data

(data)
the data to be used for the model.

weights

(vector)
an optional vector of weights to be used in the fitting process. Should be NULL or a numeric vector.

covariance

(cov_struct)
a covariance structure type definition as produced with cov_struct(), or value that can be coerced to a covariance structure using as.cov_struct(). If no value is provided, a structure is derived from the provided formula.

reml

(flag)
whether restricted maximum likelihood (REML) estimation is used, otherwise maximum likelihood (ML) is used.

control

(mmrm_control)
fine-grained fitting specifications list created with mmrm_control().

...

arguments passed to mmrm_control().

Value

An mmrm object.

Details

The formula typically looks like: FEV1 ~ RACE + SEX + ARMCD * AVISIT + us(AVISIT | USUBJID) so specifies response and covariates as usual, and exactly one special term defines which covariance structure is used and what are the time point and subject variables. The covariance structures in the formula can be found in covariance_types.

The time points have to be unique for each subject. That is, there cannot be time points with multiple observations for any subject. The rationale is that these observations would need to be correlated, but it is not possible within the currently implemented covariance structure framework to do that correctly. Moreover, for non-spatial covariance structures, the time variable must be a factor variable.

When optimizer is not set, first the default optimizer (L-BFGS-B) is used to fit the model. If that converges, this is returned. If not, the other available optimizers from h_get_optimizers(), including BFGS, CG and nlminb are tried (in parallel if n_cores is set and not on Windows). If none of the optimizers converge, then the function fails. Otherwise the best fit is returned.

Note that fine-grained control specifications can either be passed directly to the mmrm function, or via the control argument for bundling together with the mmrm_control() function. Both cannot be used together, since this would delete the arguments passed via mmrm.

Note

The mmrm object is also an mmrm_fit and an mmrm_tmb object, therefore corresponding methods also work (see mmrm_tmb_methods).

Additional contents depend on the choice of the adjustment method:

  • If Satterthwaite adjustment is used, the Jacobian information jac_list is included.

  • If Kenward-Roger adjustment is used, kr_comp contains necessary components and beta_vcov_adj includes the adjusted coefficients covariance matrix.

Use of the package emmeans is supported, see emmeans_support.

NA values are always omitted regardless of na.action setting.

When the number of visit levels is large, it usually requires large memory to create the covariance matrix. By default, the maximum allowed visit levels is 100, and if there are more visit levels, a confirmation is needed if run interactively. You can use options(mmrm.max_visits = <target>) to increase the maximum allowed number of visit levels. In non-interactive sessions the confirmation is not raised and will directly give you an error if the number of visit levels exceeds the maximum.

Examples

fit <- mmrm(
  formula = FEV1 ~ RACE + SEX + ARMCD * AVISIT + us(AVISIT | USUBJID),
  data = fev_data
)

# Direct specification of control details:
fit <- mmrm(
  formula = FEV1 ~ RACE + SEX + ARMCD * AVISIT + us(AVISIT | USUBJID),
  data = fev_data,
  weights = fev_data$WEIGHTS,
  method = "Kenward-Roger"
)

# Alternative specification via control argument (but you cannot mix the
# two approaches):
fit <- mmrm(
  formula = FEV1 ~ RACE + SEX + ARMCD * AVISIT + us(AVISIT | USUBJID),
  data = fev_data,
  control = mmrm_control(method = "Kenward-Roger")
)