GridLMM_ML: Find the (Restricted) Maximim Likelihood solution to a linear...

In deruncie/GridLMM: Efficient Mixed Models for GWAS with multiple Random Effects

Find the (Restricted) Maximim Likelihood solution to a linear mixed model by grid search

Description

Uses the GridLMM approach to find the ML or REML solution to variance componenents of a linear mixed model.

Usage

GridLMM_ML(
  formula,
  data,
  weights = NULL,
  relmat = NULL,
  normalize_relmat = TRUE,
  initial_step = 0.5,
  tolerance = 0.01,
  ML = T,
  REML = T,
  V_setup = NULL,
  save_V_folder = NULL,
  diagonalize = T,
  mc.cores = my_detectCores(),
  verbose = T
)

Arguments

formula	A two-sided linear formula as used in lmer describing the fixed-effects and random-effects of the model on the RHS and the response on the LHS. Note: correlated random-effects are not implemented, so using one or two vertical bars (|) or one is identical. At least one random effect is needed.
data	A data frame containing the variables named in formula.
weights	An optional vector of observation-specific weights.
relmat	A list of matrices that are proportional to the (within) covariance structures of the group level effects. The names of the matrices should correspond to the columns in data that are used as grouping factors. All levels of the grouping factor should appear as rownames of the corresponding matrix.
normalize_relmat	Should the relmats be normalized to mean(diag)==1?
initial_step	See Details.
tolerance	See Details.
ML	If TRUE, ML solutions will be found.
REML	If TRUE, REML solutions will be found.
V_setup	Optional. A list produced by a GridLMM function containing the pre-processed V decompositions for each grid vertex, or the information necessary to create this. Generally saved from a previous run of GridLMM on the same data.
save_V_folder	Optional. A character vector giving a folder to save pre-processed V decomposition files for future / repeated use. If null, V decompositions are stored in memory
diagonalize	If TRUE and the model includes only a single random effect, the "GEMMA" trick will be used to diagonalize V. This is done by calculating the SVD of K, which can be slow for large samples.
mc.cores	Number of cores to use for parallel evaluations.
verbose	Should progress be printed to the screen?

Details

Note: this is not a particularly efficient technique for a single model. However, the calculations for each grid vertex can be re-used in later fits (ex. GWAS). This function is used internally by other GridLMM functions to find starting values.

The function uses a hill-climbing heuristic on the grid. It starts be evaluating a grid with a step size of initial_step h^2 units. It then halves the step size and evaluates all grid vertices adjacent to the grid vertex with the highest ML (and/or REML) value. If a new maximum is found, the grid vertices adjacent to the new maximum are evaluated. This is repeated until no new maximum is found. At this point, if the step size is smaller than tolerance, the algorithm stops. Otherwise, the step size is halved again and the algorithm repeats.

Value

A list with two elements:

results	A data frame with each row a ML or REML solution, and columns giving additional statistics and parameter values.
V_setup	The V_setup object for this model. Can be re-passed to this function (or other GridLMM functions) to re-fit the model to the same data.

deruncie/GridLMM documentation built on May 2, 2023, 7:18 p.m.