FamLMMFit: A 'FamModelFit' subclass specialized for linear mixed models

In kinnamon-lab/FamMix: Regression Modeling for Family-Based Genetic Studies

Description

A specialized subclass of the FamModelFit abstract class for linear mixed model results. Methods of this subclass can be used to print model results in a nice format, access model objects, perform inference on general contrasts, and perform likelihood ratio tests on variance parameters. Due to reliance on the internal structures of other objects, the object generator function is not exported, and instances of the FamLMMFit class can be initizalized only from within functions in the FamModel namespace.

Super class

FamModel::FamModelFit -> FamLMMFit

Methods

Public methods

• FamLMMFit$new()

• FamLMMFit$get_formula()

• FamLMMFit$get_model_res()

• FamLMMFit$get_objfun()

• FamLMMFit$get_objfun_par_names()

• FamLMMFit$print()

• FamLMMFit$get_h2_a_lrts()

• FamLMMFit$clone()

Inherited methods

• FamModel::FamModelFit$contrast()

• FamModel::FamModelFit$get_V_theta_hat()

• FamModel::FamModelFit$get_data()

• FamModel::FamModelFit$get_optres()

• FamModel::FamModelFit$get_theta_hat()

---

Method new()

Constructs a new instance of this class

Usage

FamLMMFit$new(data, formula, objfun, optres)

Arguments

data

The FamData object that produced this model fit.

formula

The Formula::Formula object that describes the model.

objfun

A TMB::MakeADFun() object that has already been run through an optimizer. This object is expected to have a "type" attribute of "LMM-SA".

optres

A list from the optimizer function detailing results. This list is expected to have an attribute "opttype" that contains a string identifying the function used for optimization.

Details

Due to their reliance on the internal structures of other objects, instances of the FamLMMFit class can be initizalized only from within functions in the FamModel namespace.

---

Method get_formula()

Returns the Formula::Formula object used to construct the instance.

Usage

FamLMMFit$get_formula()

---

Method get_model_res()

Returns the original data with fitted values, residuals, and diagnostics.

Usage

FamLMMFit$get_model_res(all = FALSE)

Arguments

all

If FALSE (default), include only observations that contributed to the model fit. If TRUE, include all observations in the FamData object data member. This can be useful for generating a data set to refit the model without certain outliers. Fitted values, residuals, and diagnostics columns will have NA values for observations that did not contribute to the model fit.

Details

See vignette("linear_mixed_models") for a detailed description of each residual and diagnostic, suggestions for its use, and relevant references.

Returns

A data.table containing the data member of the FamData object used to fit this model with the following additional columns (notation defined in vignette("linear_mixed_models")):

• mu_hat: The fitted population mean, \hat{μ}_{ij}.

• eta_hat: The mean conditional upon the data in the proband, \hat{η}_{ij}. These are defined for family members (j \neq j_i) only and are NA in the proband.

• r_c_hat: The estimated Cholesky residuals, \hat{r}_{\mathrm{c}, ij}. These are defined for family members (j \neq j_i) only and are NA in the proband.

• r_s_hat: The estimated Pearson-type conditional residuals, \hat{r}_{\mathrm{s}, ij}. These are defined for family members (j \neq j_i) only and are NA in the proband.

• c_star_hat: Family-level chi-square goodness of fit statistic, \hat{c}^{*}_{i}. The same value is provided for each family member.

• c_star_hat_df: Degrees of freedom for \hat{c}^{*}_{i}, which is equal to the number of non-probands in the family. The same value is provided for each family member.

• p_c_star_hat: Probability of obtaining a deviate as or more extreme than \hat{c}^{*}_{i}, \hat{p}_{\hat{c}^{*}_{i}}. The same value is provided for each family member.

• r_star_hat: Individual-level goodness of fit statistic, \hat{r}^{*}_{ij}. These are defined for family members (j \neq j_i) only and are NA in the proband.

---

Method get_objfun()

Returns TMB::MakeADFun() object used to construct the instance.

Usage

FamLMMFit$get_objfun()

---

Method get_objfun_par_names()

Returns a vector of names derived from the original formula that map to each element of objfun$par.

Usage

FamLMMFit$get_objfun_par_names()

---

Method print()

Prints contents of FamLMMFit objects with nice formatting.

Usage

FamLMMFit$print(...)

Arguments

...

Arguments passed on to print_ests().

---

Method get_h2_a_lrts()

Perform likelihood ratio test(s) for no polygenic effect(s)

Usage

FamLMMFit$get_h2_a_lrts(print = TRUE, use_cached = TRUE, ...)

Arguments

print

If TRUE (default), prints the likelihood ratio test results in a nice format.

use_cached

If TRUE (default), use cached likelihood ratio test results if any exist. Otherwise, new likelihood ratio tests will be run, and these results will replace any in the cache.

...

Additional parameters to pass to the control list for optim() with method = "L-BGFS-B". Note that parscale and fnscale cannot be modified.

Details

Tests that each narrow-sense heritability parameter is zero individually using a likelihood ratio test. See vignette("linear_mixed_models") for a detailed description of the methods used. By default, results are cached in the FamLMMFit object after the first call to avoid redundant optimizations on subsequent calls.

Returns

A data.table containing likelihood ratio test results, invisibly.

---

Method clone()

The objects of this class are cloneable with this method.

Usage

FamLMMFit$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

kinnamon-lab/FamMix documentation built on April 23, 2021, 2:03 p.m.