Package 'VetResearchLMM'

Title: Linear Mixed Models: An Introduction with Applications in Veterinary Research
Description: Data sets and analyses of Duchateau, Janssen and Rowlands (1998, ISBN:92-9146-038-9) "Linear Mixed Models: An Introduction with Applications in Veterinary Research", with an own engine for linear mixed models that gives the results of SAS PROC MIXED and PROC GLM: restricted and full maximum likelihood and Type 3 moment estimation of variance components; random coefficients with variance-component or unstructured covariance; compound-symmetry, first-order autoregressive, spatial power and unstructured residual covariance; the fixed-effects solution in the overparameterised coding; Type 3 and Type 1 tests with containment, residual, between-within, Satterthwaite (1946) <doi:10.2307/3002019> and Kenward and Roger (1997) <doi:10.2307/2533558> degrees of freedom; estimates and contrasts in the broad and narrow inference spaces; least-squares means with multiple comparisons; best linear unbiased predictions; expected mean squares; information criteria and likelihood ratio tests. Every published result of the book is reproduced and checked. With 'ggplot2' graphics, a plain-language interpretation of every result and a built-in 'shiny' application.
Authors: Muhammad Yaseen [aut, cre] (ORCID: <https://orcid.org/0000-0002-5923-1714>), Luc Duchateau [ctb], Paul Janssen [ctb], John Rowlands [ctb]
Maintainer: Muhammad Yaseen <[email protected]>
License: GPL-2
Version: 2.0.0
Built: 2026-11-10 19:44:39 UTC
Source: https://github.com/myaseen208/vetresearchlmm

Help Index


Plot a result

Description

autoplot() methods for the results of VetResearchLMM; plot() draws the same figures. A fit shows its residuals (which = "residuals", "qq" or "observed"); least-squares means and estimates show their confidence limits; predictions of random effects are drawn as a caterpillar plot; a comparison shows the information criteria.

Usage

autoplot.vlm_result(object, which = NULL, ...)

Arguments

object

a result of a function of the package.

which

for vlm_fit() results, "residuals" (default), "qq" or "observed".

...

not used.

Value

A ggplot object.

Author(s)

Muhammad Yaseen ([email protected])

See Also

Other VetResearchLMM utilities: vlm_app(), vlm_cite(), vlm_interpret(), vlm_notation(), vlm_reference(), vlm_save(), vlm_theme()

Examples

fs <-
  vlm_fit(
      fixed    = Ww ~ 1
    , data     = ex127
    , random   = ~ sire
    , repeated = NULL
    , method   = "REML"
    , ddfm     = "default"
    , type     = 3
    , class    = NULL
    , bound    = TRUE
    , control  = list()
    )
ggplot2::autoplot(
    object = vlm_blup(
        fit   = fs
      , level = 0.95
      )
  )

Estimated marginal means for a fitted mixed model

Description

Computes estimated marginal means, or pairwise comparisons of them, for a fitted linear mixed model. For a model fitted by lme4::lmer(), lmerTest::lmer() or nlme::lme() the optional package emmeans does the work, as in version 1.1.0; for a result of vlm_fit() the least-squares means of vlm_lsmeans() are returned.

Usage

emmeans_mixed_model(
  model,
  specs,
  pairwise = FALSE,
  method = "pairwise",
  adjust = "tukey",
  ...
)

## Default S3 method:
emmeans_mixed_model(
  model,
  specs,
  pairwise = FALSE,
  method = "pairwise",
  adjust = "tukey",
  ...
)

## S3 method for class 'vlm_fit'
emmeans_mixed_model(
  model,
  specs,
  pairwise = FALSE,
  method = "pairwise",
  adjust = "tukey",
  ...
)

Arguments

model

a fitted model: a result of vlm_fit(), or a model from lme4::lmer(), lmerTest::lmer() or nlme::lme().

specs

specifications of the marginal means, such as ~ dose or ~ dose | Drug.

pairwise

logical; FALSE returns the means, TRUE the contrasts (pairwise differences).

method

contrast method passed to emmeans::contrast() (default "pairwise"); a vlm_fit result always uses pairwise differences.

adjust

multiplicity adjustment (default "tukey"; NULL leaves it to emmeans).

...

further arguments passed to emmeans::emmeans().

Details

Estimated marginal means (least-squares means) average the model predictions over the levels of the other factors with equal weights. For a vlm_fit result, specs gives the effect (for example ~ dose | Drug or ~ Drug:dose); pairwise = TRUE adds all pairwise differences with the adjustment adjust ("tukey", "bonferroni", "sidak" or "none").

Value

For a vlm_fit result, a vlm_lsmeans result (see vlm_lsmeans()); otherwise an emmGrid object of emmeans.

Author(s)

Muhammad Yaseen ([email protected])

References

Lenth, R. V. (2024). emmeans: Estimated Marginal Means, aka Least-Squares Means. R package.

Duchateau, L., Janssen, P. and Rowlands, G. J. (1998). Linear Mixed Models. An Introduction with Applications in Veterinary Research. International Livestock Research Institute, Nairobi.

See Also

vlm_lsmeans, report_mixed_model

Other VetResearchLMM inference: report_mixed_model(), vlm_blup(), vlm_estimate(), vlm_lsmeans()

Examples

fm <-
  vlm_fit(
      fixed    = Pcv ~ Drug + dose + Drug:dose
    , data     = ex125
    , random   = ~ Region + Region:Drug
    , repeated = NULL
    , method   = "REML"
    , ddfm     = "default"
    , type     = 3
    , class    = NULL
    , bound    = TRUE
    , control  = list()
    )
emmeans_mixed_model(
    model    = fm
  , specs    = ~ dose | Drug
  , pairwise = TRUE
  , method   = "pairwise"
  , adjust   = "tukey"
  )

Example 1.2.1: comparing three doses of a drug

Description

Packed cell volume (PCV, %) of trypanosome-infected animals before and one month after a low, medium or high dose of Berenil: a completely randomised design (Table 1.2.1 and Appendix A of the book).

Usage

ex121

Format

A data frame with 14 rows and 5 variables:

animals

animal number within its dose group.

dose

dose: H (high), L (low) or M (medium).

PCV1

PCV at treatment.

PCV2

PCV one month after treatment.

PCVdiff

change in PCV, PCV2 - PCV1.

Source

Duchateau, L., Janssen, P. and Rowlands, G. J. (1998). Linear Mixed Models. An Introduction with Applications in Veterinary Research. International Livestock Research Institute, Nairobi. Appendix A.

See Also

Examp2.2.1.7

Other VetResearchLMM data: ex122, ex123, ex124, ex125, ex126, ex127, ex31, ex32, ex33

Examples

str(ex121)
tapply(X = ex121$PCVdiff, INDEX = ex121$dose, FUN = mean)

Example 1.2.2: comparing two doses of a drug in a randomised block design

Description

Change in packed cell volume (PCV, %) one month after a low or high dose of Berenil, five animals per dose in each of three herds; the herds are blocks (Table 1.2.2 and Appendix A of the book). New in version 2.0.0.

Usage

ex122

Format

A data frame with 30 rows and 3 variables:

herd

herd (block): 1 to 3.

dose

dose: H (high) or L (low).

PCVdif

change in PCV.

Source

Duchateau, L., Janssen, P. and Rowlands, G. J. (1998). Linear Mixed Models. An Introduction with Applications in Veterinary Research. International Livestock Research Institute, Nairobi. Appendix A.

See Also

Examp2.3.2

Other VetResearchLMM data: ex121, ex123, ex124, ex125, ex126, ex127, ex31, ex32, ex33

Examples

str(ex122)

Example 1.2.3: comparing two drugs with herds as experimental units

Description

Change in packed cell volume (PCV, %) of seven animals in each of four herds; Berenil was given to two herds and Samorin to the other two, so herds are nested in drug (Table 1.2.3 and Appendix A of the book). New in version 2.0.0.

Usage

ex123

Format

A data frame with 28 rows and 3 variables:

herd

herd: 1 to 4.

drug

drug: Berenil or Samorin.

PCVdif

change in PCV.

Source

Duchateau, L., Janssen, P. and Rowlands, G. J. (1998). Linear Mixed Models. An Introduction with Applications in Veterinary Research. International Livestock Research Institute, Nairobi. Appendix A.

See Also

Examp2.3.2

Other VetResearchLMM data: ex121, ex122, ex124, ex125, ex126, ex127, ex31, ex32, ex33

Examples

str(ex123)

Example 1.2.4: two drugs at two doses with two sizes of experimental units

Description

Change in packed cell volume (PCV, %) of animals in four herds: the drug is given to whole herds (two herds per drug) and the dose to animals within a herd (Table 1.2.4 and Appendix A of the book).

Usage

ex124

Format

A data frame with 40 rows and 4 variables:

herd

herd: 1 to 4 (nested in drug).

drug

drug: Berenil or Samorin.

dose

dose: h (high) or l (low).

PCVdif

change in PCV.

Source

Duchateau, L., Janssen, P. and Rowlands, G. J. (1998). Linear Mixed Models. An Introduction with Applications in Veterinary Research. International Livestock Research Institute, Nairobi. Appendix A.

See Also

Examp1.3.2

Other VetResearchLMM data: ex121, ex122, ex123, ex125, ex126, ex127, ex31, ex32, ex33

Examples

str(ex124)

Example 1.2.5: two drugs at two doses in a split-plot design

Description

Average packed cell volume (PCV, %) of animals in six regions; in each region one herd received Berenil and one Samorin (main plots), and within a herd one group of animals received the high and one the low dose (subplots) (Table 1.2.5 and Appendix A of the book).

Usage

ex125

Format

A data frame with 24 rows and 4 variables:

Region

region: 1 to 6.

Drug

drug: BERENIL or samorin.

dose

dose: h (high) or l (low).

Pcv

average PCV.

Source

Duchateau, L., Janssen, P. and Rowlands, G. J. (1998). Linear Mixed Models. An Introduction with Applications in Veterinary Research. International Livestock Research Institute, Nairobi. Appendix A.

See Also

Examp2.4.2.2, Examp2.5.1.1, Examp2.6.1

Other VetResearchLMM data: ex121, ex122, ex123, ex124, ex126, ex127, ex31, ex32, ex33

Examples

str(ex125)

Example 1.2.6: variation in ELISA data

Description

Optical density (OD) of an ELISA for four untreated animals, measured at 11 times with two blood samples each time: a random effects model for the sources of variation (Table 1.2.6 and Appendix A of the book). New in version 2.0.0.

Usage

ex126

Format

A data frame with 88 rows and 4 variables:

time

time point: 1 to 11.

replicat

blood sample at the time point: 1 or 2.

anim_id

animal: 1 to 4.

OD

optical density.

Source

Duchateau, L., Janssen, P. and Rowlands, G. J. (1998). Linear Mixed Models. An Introduction with Applications in Veterinary Research. International Livestock Research Institute, Nairobi. Appendix A.

See Also

Examp2.3.2

Other VetResearchLMM data: ex121, ex122, ex123, ex124, ex125, ex127, ex31, ex32, ex33

Examples

str(ex126)

Example 1.2.7: helminth resistance in sheep

Description

Weaning weight (kg) of lambs, offspring of eight sires, under high helminth challenge (Table 1.2.7 and Appendix A of the book).

Usage

ex127

Format

A data frame with 43 rows and 2 variables:

sire

sire: 1 to 8.

Ww

weaning weight.

Source

Duchateau, L., Janssen, P. and Rowlands, G. J. (1998). Linear Mixed Models. An Introduction with Applications in Veterinary Research. International Livestock Research Institute, Nairobi. Appendix A.

See Also

Examp2.4.3.1

Other VetResearchLMM data: ex121, ex122, ex123, ex124, ex125, ex126, ex31, ex32, ex33

Examples

str(ex127)

Example 3.1: two drugs and their doses, herds nested in drug (part of the data)

Description

Packed cell volume (PCV, %) at treatment and one month later; Berenil (at two doses) and Samorin (one dose) were given to animals in herds nested in drug. The book prints only part of the data (a few animals per herd and dose); these 38 rows are that part, so the analyses of Example 3.1 run but do not reproduce the printed results.

Usage

ex31

Format

A data frame with 38 rows and 6 variables:

herd

herd within drug: 1 to 4 (herds with the same number but another drug are different herds).

animal_id

animal.

PCV1

PCV at treatment.

PCV2

PCV one month after treatment.

dose

dose within drug: 1 or 2 (Samorin has dose 1 only).

drug

drug: BERENIL or SAMORIN.

Source

Duchateau, L., Janssen, P. and Rowlands, G. J. (1998). Linear Mixed Models. An Introduction with Applications in Veterinary Research. International Livestock Research Institute, Nairobi. Appendix A.

See Also

Examp3.1

Other VetResearchLMM data: ex121, ex122, ex123, ex124, ex125, ex126, ex127, ex32, ex33

Examples

str(ex31)

Example 3.2: weaning weights of lambs by breed and sire (part of the data)

Description

Weaning weight (kg) of lambs of six breeds, with sex and age at weaning, for the complete offspring of a few sires per breed. The book prints only this part of the data, so the analyses of Example 3.2 run but do not reproduce the printed results.

Usage

ex32

Format

A data frame with 65 rows and 5 variables:

breed

breed: 1 to 6.

sire_id

sire (nested in breed).

sex

sex: F or M.

agew

age at weaning (days).

Ww

weaning weight.

Source

Duchateau, L., Janssen, P. and Rowlands, G. J. (1998). Linear Mixed Models. An Introduction with Applications in Veterinary Research. International Livestock Research Institute, Nairobi. Appendix A.

See Also

Examp3.2

Other VetResearchLMM data: ex121, ex122, ex123, ex124, ex125, ex126, ex127, ex31, ex33

Examples

str(ex32)

Example 3.3: breed differences in susceptibility to trypanosomosis

Description

Packed cell volume (PCV, %) of six Boran and six N'Dama cattle measured 14 times over 35 days after a trypanosome infection: repeated measures (Example 1.2.8 and Appendix A of the book). Version 2.0.0 corrects three typing errors of version 1.1.0 against the book (two measurement days and one animal identifier).

Usage

ex33

Format

A data frame with 168 rows and 4 variables:

animal_id

animal.

breed

breed: BO (Boran) or ND (N'Dama).

time

day after infection.

PCV

packed cell volume.

Source

Duchateau, L., Janssen, P. and Rowlands, G. J. (1998). Linear Mixed Models. An Introduction with Applications in Veterinary Research. International Livestock Research Institute, Nairobi. Appendix A.

See Also

Examp3.3

Other VetResearchLMM data: ex121, ex122, ex123, ex124, ex125, ex126, ex127, ex31, ex32

Examples

str(ex33)

Example 1.3.2: expected mean squares in the fixed and the mixed model

Description

Drugs are given to whole herds and doses to animals within herds (ex124). With herd random, drug is tested against herd within drug (Table 1.3.2.2); with one observation deleted the two expected mean squares no longer match (Table 1.3.2.3: 9.7143 and 9.7222), so the F test is only approximate.

Author(s)

Muhammad Yaseen ([email protected])

References

Duchateau, L., Janssen, P. and Rowlands, G. J. (1998). Linear Mixed Models. An Introduction with Applications in Veterinary Research. International Livestock Research Institute, Nairobi.

See Also

vlm_ems, vlm_fit, ex124

Other VetResearchLMM examples: Examp2.2.1.7, Examp2.3.2, Examp2.4.2.2, Examp2.4.3.1, Examp2.5.1.1, Examp2.5.2.1, Examp2.5.3.1, Examp2.5.4.1, Examp2.6.1, Examp3.1, Examp3.2, Examp3.3

Examples

# SAS program of the book (Appendix B):
#   proc glm data=ex124;
#     class herd dose drug;
#     model PCVdif = drug herd(drug) dose dose*drug;
#     random herd(drug) / test;
#   run;

em <-
  vlm_ems(
      fixed  = PCVdif ~ drug + drug:herd + dose + dose:drug
    , data   = ex124
    , random = ~ drug:herd
    , type   = 3
    , class  = "herd"
    )
em

# one observation deleted (Table 1.3.2.3)
em1 <-
  vlm_ems(
      fixed  = PCVdif ~ drug + drug:herd + dose + dose:drug
    , data   = ex124[-1, ]
    , random = ~ drug:herd
    , type   = 3
    , class  = "herd"
    )
em1$coefficients

# the mixed model analysis that replaces it
fm <-
  vlm_fit(
      fixed    = PCVdif ~ drug + dose + drug:dose
    , data     = ex124
    , random   = ~ drug:herd
    , repeated = NULL
    , method   = "REML"
    , ddfm     = "satterth"
    , type     = 3
    , class    = "herd"
    , bound    = TRUE
    , control  = list()
    )
fm$tests

Example 2.2.1.7: one-way analysis of variance, an estimate and a contrast

Description

The three doses of ex121 compared by the fixed effects model: F = 14.36 on 2 and 11 df, and the low dose against the mean of the medium and high doses, -3.68 with standard error 0.937 (F = 15.44).

Author(s)

Muhammad Yaseen ([email protected])

References

Duchateau, L., Janssen, P. and Rowlands, G. J. (1998). Linear Mixed Models. An Introduction with Applications in Veterinary Research. International Livestock Research Institute, Nairobi.

See Also

vlm_ems, vlm_estimate, ex121

Other VetResearchLMM examples: Examp1.3.2, Examp2.3.2, Examp2.4.2.2, Examp2.4.3.1, Examp2.5.1.1, Examp2.5.2.1, Examp2.5.3.1, Examp2.5.4.1, Examp2.6.1, Examp3.1, Examp3.2, Examp3.3

Examples

# SAS program of the book (Appendix B):
#   proc glm data=ex121;
#     class dose;
#     model PCVdif = dose;
#     estimate 'l vs mh' dose -0.5 1 -0.5;
#     contrast 'l vs mh' dose -0.5 1 -0.5;
#   run;

em <-
  vlm_ems(
      fixed  = PCVdiff ~ dose
    , data   = ex121
    , random = NULL
    , type   = 3
    , class  = NULL
    )
em

fm <-
  vlm_fit(
      fixed    = PCVdiff ~ dose
    , data     = ex121
    , random   = NULL
    , repeated = NULL
    , method   = "REML"
    , ddfm     = "default"
    , type     = 3
    , class    = NULL
    , bound    = TRUE
    , control  = list()
    )
# dose levels: H, L, M
vlm_estimate(
    fit    = fm
  , L      = list("l vs mh" = list(dose = c(-0.5, 1, -0.5)))
  , random = NULL
  , level  = 0.95
  )
vlm_contrast(
    fit = fm
  , L   = list("l vs mh" = list(dose = c(-0.5, 1, -0.5)))
  )

Example 2.3.2: the mixed model descriptions of Chapter 2

Description

The models of Section 2.3.2 for the examples of Chapter 1: a randomised block design with random herds (ex122), herds nested in drug (ex123), two sizes of experimental units (ex124) and the random effects model of the ELISA data (ex126), in which animals and times are random and the overall mean is the only fixed effect. New in version 2.0.0.

Author(s)

Muhammad Yaseen ([email protected])

References

Duchateau, L., Janssen, P. and Rowlands, G. J. (1998). Linear Mixed Models. An Introduction with Applications in Veterinary Research. International Livestock Research Institute, Nairobi.

See Also

vlm_fit, ex122, ex123, ex126

Other VetResearchLMM examples: Examp1.3.2, Examp2.2.1.7, Examp2.4.2.2, Examp2.4.3.1, Examp2.5.1.1, Examp2.5.2.1, Examp2.5.3.1, Examp2.5.4.1, Examp2.6.1, Examp3.1, Examp3.2, Examp3.3

Examples

# SAS program of the book (Appendix B):
#   proc mixed data=ex126;
#     class anim_id time;
#     model OD = ;
#     random anim_id time;
#   run;

f122 <-
  vlm_fit(
      fixed    = PCVdif ~ dose
    , data     = ex122
    , random   = ~ herd
    , repeated = NULL
    , method   = "REML"
    , ddfm     = "default"
    , type     = 3
    , class    = NULL
    , bound    = TRUE
    , control  = list()
    )
f122$covariance
f123 <-
  vlm_fit(
      fixed    = PCVdif ~ drug
    , data     = ex123
    , random   = ~ drug:herd
    , repeated = NULL
    , method   = "REML"
    , ddfm     = "default"
    , type     = 3
    , class    = NULL
    , bound    = TRUE
    , control  = list()
    )
f123$tests
f126 <-
  vlm_fit(
      fixed    = OD ~ 1
    , data     = ex126
    , random   = ~ anim_id + time
    , repeated = NULL
    , method   = "REML"
    , ddfm     = "default"
    , type     = 3
    , class    = "time"
    , bound    = TRUE
    , control  = list()
    )
f126$covariance
vlm_interpret(
    x     = f126
  , alpha = 0.05
  , top   = 3
  )

Example 2.4.2.2: ML and REML estimates of variance components

Description

The split-plot data ex125: REML gives 5.151 (region), 0.387 (herd within region) and 2.096 (residual); ML gives the smaller 4.292, 0.322 and 1.747 (Table 2.4.2.1), because it ignores the degrees of freedom used by the fixed effects. The Type 3 (moment) estimates equal REML here, as the data are balanced.

Author(s)

Muhammad Yaseen ([email protected])

References

Duchateau, L., Janssen, P. and Rowlands, G. J. (1998). Linear Mixed Models. An Introduction with Applications in Veterinary Research. International Livestock Research Institute, Nairobi.

See Also

vlm_fit, ex125

Other VetResearchLMM examples: Examp1.3.2, Examp2.2.1.7, Examp2.3.2, Examp2.4.3.1, Examp2.5.1.1, Examp2.5.2.1, Examp2.5.3.1, Examp2.5.4.1, Examp2.6.1, Examp3.1, Examp3.2, Examp3.3

Examples

# SAS program of the book (Appendix B):
#   proc mixed data=ex125 method=ml;   * and method=reml;
#     class drug dose region;
#     model pcv = drug dose drug*dose;
#     random region drug*region;
#   run;

ml <-
  vlm_fit(
      fixed    = Pcv ~ Drug + dose + Drug:dose
    , data     = ex125
    , random   = ~ Region + Region:Drug
    , repeated = NULL
    , method   = "ML"
    , ddfm     = "default"
    , type     = 3
    , class    = NULL
    , bound    = TRUE
    , control  = list()
    )
reml <-
  vlm_fit(
      fixed    = Pcv ~ Drug + dose + Drug:dose
    , data     = ex125
    , random   = ~ Region + Region:Drug
    , repeated = NULL
    , method   = "REML"
    , ddfm     = "default"
    , type     = 3
    , class    = NULL
    , bound    = TRUE
    , control  = list()
    )
mom <-
  vlm_fit(
      fixed    = Pcv ~ Drug + dose + Drug:dose
    , data     = ex125
    , random   = ~ Region + Region:Drug
    , repeated = NULL
    , method   = "Type3"
    , ddfm     = "default"
    , type     = 3
    , class    = NULL
    , bound    = TRUE
    , control  = list()
    )
cbind(ML = ml$covariance$estimate, REML = reml$covariance$estimate, Type3 = mom$covariance$estimate)

# the same model with lme4 (optional)
if (requireNamespace("lme4", quietly = TRUE)) {
  lm4 <-
    lme4::lmer(
        formula = Pcv ~ Drug * dose + (1 | Region / Drug)
      , data    = ex125
      , REML    = TRUE
      )
  print(lme4::VarCorr(lm4), comp = "Variance")
}

Example 2.4.3.1: best linear unbiased prediction of sire effects

Description

The random sire model of ex127: REML variances 3.685 (sire) and 3.542 (residual), overall mean 13.97, and the prediction 3.16 for sire 4, a shrunken version of its mean deviation 17.63 - 13.97.

Author(s)

Muhammad Yaseen ([email protected])

References

Duchateau, L., Janssen, P. and Rowlands, G. J. (1998). Linear Mixed Models. An Introduction with Applications in Veterinary Research. International Livestock Research Institute, Nairobi.

See Also

vlm_blup, ex127

Other VetResearchLMM examples: Examp1.3.2, Examp2.2.1.7, Examp2.3.2, Examp2.4.2.2, Examp2.5.1.1, Examp2.5.2.1, Examp2.5.3.1, Examp2.5.4.1, Examp2.6.1, Examp3.1, Examp3.2, Examp3.3

Examples

# SAS program of the book (Appendix B):
#   proc mixed data=ex127;
#     class sire;
#     model ww = ;
#     random sire / solution;
#   run;

fs <-
  vlm_fit(
      fixed    = Ww ~ 1
    , data     = ex127
    , random   = ~ sire
    , repeated = NULL
    , method   = "REML"
    , ddfm     = "default"
    , type     = 3
    , class    = NULL
    , bound    = TRUE
    , control  = list()
    )
fs$fixed
vlm_blup(
    fit   = fs
  , level = 0.95
  )

# the same model with lme4 (optional)
if (requireNamespace("lme4", quietly = TRUE)) {
  lm4 <-
    lme4::lmer(
        formula = Ww ~ 1 + (1 | sire)
      , data    = ex127
      , REML    = TRUE
      )
  print(lme4::VarCorr(lm4), comp = "Variance")
}

Example 2.5.1.1: generalised least-squares estimates of the fixed effects

Description

The solution for the fixed effects of ex125 with the last level of each effect set to zero: 17.13, 7.15, 4.35 and -3.18, with the variances 1.27, 0.83, 0.70 and 1.40 of their estimates (the COVB matrix).

Author(s)

Muhammad Yaseen ([email protected])

References

Duchateau, L., Janssen, P. and Rowlands, G. J. (1998). Linear Mixed Models. An Introduction with Applications in Veterinary Research. International Livestock Research Institute, Nairobi.

See Also

vlm_fit, ex125

Other VetResearchLMM examples: Examp1.3.2, Examp2.2.1.7, Examp2.3.2, Examp2.4.2.2, Examp2.4.3.1, Examp2.5.2.1, Examp2.5.3.1, Examp2.5.4.1, Examp2.6.1, Examp3.1, Examp3.2, Examp3.3

Examples

# SAS program of the book (Appendix B):
#   proc mixed data=ex125;
#     class drug dose region;
#     model pcv = drug dose drug*dose / solution covb;
#     random region drug*region;
#   run;

fm <-
  vlm_fit(
      fixed    = Pcv ~ Drug + dose + Drug:dose
    , data     = ex125
    , random   = ~ Region + Region:Drug
    , repeated = NULL
    , method   = "REML"
    , ddfm     = "default"
    , type     = 3
    , class    = NULL
    , bound    = TRUE
    , control  = list()
    )
fm$fixed
fm$fixed$se^2

Example 2.5.2.1: cell means as estimable functions

Description

The four drug-by-dose means of ex125 (25.45, 24.28, 21.48 and 17.13) and their variance 1.27, as least-squares means.

Author(s)

Muhammad Yaseen ([email protected])

References

Duchateau, L., Janssen, P. and Rowlands, G. J. (1998). Linear Mixed Models. An Introduction with Applications in Veterinary Research. International Livestock Research Institute, Nairobi.

See Also

vlm_lsmeans, ex125

Other VetResearchLMM examples: Examp1.3.2, Examp2.2.1.7, Examp2.3.2, Examp2.4.2.2, Examp2.4.3.1, Examp2.5.1.1, Examp2.5.3.1, Examp2.5.4.1, Examp2.6.1, Examp3.1, Examp3.2, Examp3.3

Examples

# SAS program of the book (Appendix B):
#   proc mixed data=ex125;
#     class drug dose region;
#     model pcv = drug dose drug*dose;
#     random region drug*region;
#     lsmeans drug*dose;
#   run;

fm <-
  vlm_fit(
      fixed    = Pcv ~ Drug + dose + Drug:dose
    , data     = ex125
    , random   = ~ Region + Region:Drug
    , repeated = NULL
    , method   = "REML"
    , ddfm     = "default"
    , type     = 3
    , class    = NULL
    , bound    = TRUE
    , control  = list()
    )
vlm_lsmeans(
    fit    = fm
  , specs  = ~ Drug:dose
  , at     = NULL
  , diff   = FALSE
  , adjust = "none"
  , level  = 0.95
  )

Example 2.5.3.1: confidence intervals with Satterthwaite degrees of freedom

Description

Four linear combinations of the fixed effects of ex125: their variances 0.478, 1.0975, 0.698 and 1.272 combine the variance components, and their Satterthwaite degrees of freedom (5, 6.2, 10 and 8.2) the degrees of freedom of the mean squares of Table 2.5.3.1.

Author(s)

Muhammad Yaseen ([email protected])

References

Duchateau, L., Janssen, P. and Rowlands, G. J. (1998). Linear Mixed Models. An Introduction with Applications in Veterinary Research. International Livestock Research Institute, Nairobi.

See Also

vlm_estimate, vlm_ems, ex125

Other VetResearchLMM examples: Examp1.3.2, Examp2.2.1.7, Examp2.3.2, Examp2.4.2.2, Examp2.4.3.1, Examp2.5.1.1, Examp2.5.2.1, Examp2.5.4.1, Examp2.6.1, Examp3.1, Examp3.2, Examp3.3

Examples

# SAS program of the book (Appendix B):
#   proc mixed data=ex125;
#     class drug dose region;
#     model pcv = drug dose drug*dose / ddfm=satterth;
#     random region drug*region;
#     estimate 'drug dif' drug -1 1 drug*dose -0.5 -0.5 0.5 0.5;
#     estimate 'Samorin mean' intercept 1 drug 0 1 dose 0.5 0.5 drug*dose 0 0 0.5 0.5;
#     estimate 'Samorin HvsL' dose 1 -1 drug*dose 0 0 1 -1;
#     estimate 'Samorin high' intercept 1 drug 0 1 dose 1 0 drug*dose 0 0 1 0;
#   run;

fm <-
  vlm_fit(
      fixed    = Pcv ~ Drug + dose + Drug:dose
    , data     = ex125
    , random   = ~ Region + Region:Drug
    , repeated = NULL
    , method   = "REML"
    , ddfm     = "satterth"
    , type     = 3
    , class    = NULL
    , bound    = TRUE
    , control  = list()
    )
vlm_estimate(
    fit    = fm
  , L      = list(
          "drug dif"     = list(Drug = c(-1, 1), "Drug:dose" = c(-0.5, -0.5, 0.5, 0.5))
        , "Samorin mean" = list(Intercept = 1, Drug = c(0, 1),
                                dose = c(0.5, 0.5), "Drug:dose" = c(0, 0, 0.5, 0.5))
        , "Samorin HvsL" = list(dose = c(1, -1), "Drug:dose" = c(0, 0, 1, -1))
        , "Samorin high" = list(Intercept = 1, Drug = c(0, 1),
                                dose = c(1, 0), "Drug:dose" = c(0, 0, 1, 0))
        )
  , random = NULL
  , level  = 0.95
  )

# the mean squares and their expectations (Table 2.5.3.1)
em <-
  vlm_ems(
      fixed  = Pcv ~ Region + Drug + Region:Drug + dose + Drug:dose
    , data   = ex125
    , random = ~ Region + Region:Drug
    , type   = 3
    , class  = NULL
    )
em

Example 2.5.4.1: broad and narrow inference spaces

Description

The mean of Samorin in ex125: its variance is 1.0975 when regions and herds are random (broad space) and 0.175 for the six regions and herds of the study (narrow space), as in the fixed effects model.

Details

The narrow-space estimate adds the random effects averaged over the observed levels (the part of an ESTIMATE statement after the vertical bar in SAS); the fixed effects model with regions and herds fixed gives the same standard error.

Author(s)

Muhammad Yaseen ([email protected])

References

Duchateau, L., Janssen, P. and Rowlands, G. J. (1998). Linear Mixed Models. An Introduction with Applications in Veterinary Research. International Livestock Research Institute, Nairobi.

See Also

vlm_estimate, ex125

Other VetResearchLMM examples: Examp1.3.2, Examp2.2.1.7, Examp2.3.2, Examp2.4.2.2, Examp2.4.3.1, Examp2.5.1.1, Examp2.5.2.1, Examp2.5.3.1, Examp2.6.1, Examp3.1, Examp3.2, Examp3.3

Examples

# SAS program of the book (Appendix B):
#   proc mixed data=ex125;
#     class drug dose region;
#     model pcv = drug dose drug*dose / ddfm=satterth;
#     random region drug*region;
#     estimate 'Samorin mean' intercept 1 drug 0 1 dose 0.5 0.5 drug*dose 0 0 0.5 0.5;
#   run;
#   proc glm data=ex125;
#     class drug dose region;
#     model pcv = region drug drug*region dose drug*dose;
#     estimate 'Samorin mean' intercept 1 drug 0 1 dose 0.5 0.5 drug*dose 0 0 0.5 0.5;
#   run;

fm <-
  vlm_fit(
      fixed    = Pcv ~ Drug + dose + Drug:dose
    , data     = ex125
    , random   = ~ Region + Region:Drug
    , repeated = NULL
    , method   = "REML"
    , ddfm     = "satterth"
    , type     = 3
    , class    = NULL
    , bound    = TRUE
    , control  = list()
    )
vlm_estimate(
    fit    = fm
  , L      = list(
          "broad"  = list(Intercept = 1, Drug = c(0, 1),
                          dose = c(0.5, 0.5), "Drug:dose" = c(0, 0, 0.5, 0.5))
        , "narrow" = list(Intercept = 1, Drug = c(0, 1),
                          dose = c(0.5, 0.5), "Drug:dose" = c(0, 0, 0.5, 0.5))
        )
  , random = list(
          "narrow" = list(Region = rep(1 / 6, 6), "Region:Drug" = rep(c(0, 1 / 6), 6))
        )
  , level  = 0.95
  )

# the fixed effects model: regions and herds fixed
ff <-
  vlm_fit(
      fixed    = Pcv ~ Region + Drug + Region:Drug + dose + Drug:dose
    , data     = ex125
    , random   = NULL
    , repeated = NULL
    , method   = "REML"
    , ddfm     = "default"
    , type     = 3
    , class    = "Region"
    , bound    = TRUE
    , control  = list()
    )
vlm_estimate(
    fit    = ff
  , L      = list(
          "Samorin mean" = list(Intercept = 1, Region = rep(1 / 6, 6), Drug = c(0, 1),
                                "Region:Drug" = rep(c(0, 1 / 6), 6), dose = c(0.5, 0.5),
                                "Drug:dose" = c(0, 0, 0.5, 0.5))
        )
  , random = NULL
  , level  = 0.95
  )

Example 2.6.1: F tests of general linear hypotheses

Description

The drug difference of ex125 (estimate -5.56, variance 0.478, F on 1 and 5 df) and the joint test that the four cell means are equal: F = 31.2 on 3 and 7.14 df, p = 0.0002.

Author(s)

Muhammad Yaseen ([email protected])

References

Duchateau, L., Janssen, P. and Rowlands, G. J. (1998). Linear Mixed Models. An Introduction with Applications in Veterinary Research. International Livestock Research Institute, Nairobi.

See Also

vlm_contrast, ex125

Other VetResearchLMM examples: Examp1.3.2, Examp2.2.1.7, Examp2.3.2, Examp2.4.2.2, Examp2.4.3.1, Examp2.5.1.1, Examp2.5.2.1, Examp2.5.3.1, Examp2.5.4.1, Examp3.1, Examp3.2, Examp3.3

Examples

# SAS program of the book (Appendix B):
#   proc mixed data=ex125;
#     class drug dose region;
#     model pcv = drug dose drug*dose / ddfm=satterth;
#     random region drug*region;
#     contrast 'drug dif' drug -1 1 drug*dose -0.5 -0.5 0.5 0.5;
#     contrast 'all' drug 1 -1 dose 0 0 drug*dose 0.5 0.5 -0.5 -0.5,
#                    drug 0 0 dose 1 -1 drug*dose 0.5 -0.5 0.5 -0.5,
#                    drug 0 0 dose 0 0 drug*dose 0.5 -0.5 -0.5 0.5;
#   run;

fm <-
  vlm_fit(
      fixed    = Pcv ~ Drug + dose + Drug:dose
    , data     = ex125
    , random   = ~ Region + Region:Drug
    , repeated = NULL
    , method   = "REML"
    , ddfm     = "satterth"
    , type     = 3
    , class    = NULL
    , bound    = TRUE
    , control  = list()
    )
vlm_contrast(
    fit = fm
  , L   = list(
          "drug dif" = list(Drug = c(-1, 1), "Drug:dose" = c(-0.5, -0.5, 0.5, 0.5))
        , "all"      = list(
              list(Drug = c(1, -1), "Drug:dose" = c(0.5, 0.5, -0.5, -0.5))
            , list(dose = c(1, -1), "Drug:dose" = c(0.5, -0.5, 0.5, -0.5))
            , list("Drug:dose" = c(0.5, -0.5, -0.5, 0.5))
            )
        )
  )

Example 3.1: a designed experiment with doses nested in drug and a covariate

Description

Berenil at two doses and Samorin at one dose, given to animals in herds nested in drug (ex31). Model 1 compares the three treatments; Model 2 adds the PCV at treatment as a covariate with a common slope; Model 3 allows a slope per treatment and compares the treatments at PCV1 = 18. The book prints only part of the data, so the numbers differ from those of the book.

Author(s)

Muhammad Yaseen ([email protected])

References

Duchateau, L., Janssen, P. and Rowlands, G. J. (1998). Linear Mixed Models. An Introduction with Applications in Veterinary Research. International Livestock Research Institute, Nairobi.

See Also

vlm_fit, vlm_lsmeans, ex31

Other VetResearchLMM examples: Examp1.3.2, Examp2.2.1.7, Examp2.3.2, Examp2.4.2.2, Examp2.4.3.1, Examp2.5.1.1, Examp2.5.2.1, Examp2.5.3.1, Examp2.5.4.1, Examp2.6.1, Examp3.2, Examp3.3

Examples

# SAS program of the book (Appendix B):
#   proc mixed data=ex31;
#     class drug dose herd;
#     model PCV2 = drug dose(drug) / solution ddfm=satterth;
#     random herd(drug);
#     estimate 'Mean Samorin' intercept 1 drug 0 1 dose(drug) 0 0 1;
#     estimate 'Berenil 2 doses' dose(drug) 1 -1 0;
#     estimate 'Ber vs Sam at dose 1' drug 1 -1 dose(drug) 1 0 -1;
#     contrast 'some difference' drug 1 -1 dose(drug) 0.5 0.5 -1, drug 0 0 dose(drug) 1 -1 0;
#     lsmeans dose(drug);
#   run;
#   * Model 3: model PCV2 = drug dose(drug) PCV1*dose(drug); lsmeans dose(drug) / at PCV1=18;

m1 <-
  vlm_fit(
      fixed    = PCV2 ~ drug + drug:dose
    , data     = ex31
    , random   = ~ drug:herd
    , repeated = NULL
    , method   = "REML"
    , ddfm     = "satterth"
    , type     = 3
    , class    = c("herd", "dose")
    , bound    = TRUE
    , control  = list()
    )
m1$tests
vlm_estimate(
    fit    = m1
  , L      = list(
          "Mean Samorin"         = list(Intercept = 1, drug = c(0, 1), "drug:dose" = c(0, 0, 1))
        , "Berenil 2 doses"      = list("drug:dose" = c(1, -1, 0))
        , "Ber vs Sam at dose 1" = list(drug = c(1, -1), "drug:dose" = c(1, 0, -1))
        )
  , random = NULL
  , level  = 0.95
  )
vlm_contrast(
    fit = m1
  , L   = list(
          "some difference" = list(
              list(drug = c(1, -1), "drug:dose" = c(0.5, 0.5, -1))
            , list("drug:dose" = c(1, -1, 0))
            )
        )
  )
vlm_lsmeans(
    fit    = m1
  , specs  = ~ drug:dose
  , at     = NULL
  , diff   = FALSE
  , adjust = "none"
  , level  = 0.95
  )
m2 <-
  vlm_fit(
      fixed    = PCV2 ~ PCV1 + drug + drug:dose
    , data     = ex31
    , random   = ~ drug:herd
    , repeated = NULL
    , method   = "REML"
    , ddfm     = "satterth"
    , type     = 3
    , class    = c("herd", "dose")
    , bound    = TRUE
    , control  = list()
    )
m2$fixed
m3 <-
  vlm_fit(
      fixed    = PCV2 ~ drug + drug:dose + PCV1:drug:dose
    , data     = ex31
    , random   = ~ drug:herd
    , repeated = NULL
    , method   = "REML"
    , ddfm     = "satterth"
    , type     = 3
    , class    = c("herd", "dose")
    , bound    = TRUE
    , control  = list()
    )
vlm_lsmeans(
    fit    = m3
  , specs  = ~ drug:dose
  , at     = list(PCV1 = 18)
  , diff   = FALSE
  , adjust = "none"
  , level  = 0.95
  )

Example 3.2: sires nested in breed, heritability and breed comparisons

Description

Weaning weights of lambs (ex32) with sex, age and breed fixed and sires within breed random: the heritability h2=4σs2/(σs2+σ2)h^2 = 4\sigma_s^2/(\sigma_s^2 + \sigma^2), Tukey-Kramer comparisons of the breeds and the predicted breeding values of the sires. The book prints only part of the data, so the numbers differ from those of the book (for this part the sire variance is estimated as zero).

Author(s)

Muhammad Yaseen ([email protected])

References

Duchateau, L., Janssen, P. and Rowlands, G. J. (1998). Linear Mixed Models. An Introduction with Applications in Veterinary Research. International Livestock Research Institute, Nairobi.

See Also

vlm_lsmeans, vlm_blup, ex32

Other VetResearchLMM examples: Examp1.3.2, Examp2.2.1.7, Examp2.3.2, Examp2.4.2.2, Examp2.4.3.1, Examp2.5.1.1, Examp2.5.2.1, Examp2.5.3.1, Examp2.5.4.1, Examp2.6.1, Examp3.1, Examp3.3

Examples

# SAS program of the book (Appendix B):
#   proc mixed data=ex32;
#     class sex sire_id breed;
#     model ww = sex agew breed / solution ddfm=satterth;
#     random sire_id(breed) / solution;
#     lsmeans breed / adjust=tukey;
#   run;

fm <-
  vlm_fit(
      fixed    = Ww ~ sex + agew + breed
    , data     = ex32
    , random   = ~ breed:sire_id
    , repeated = NULL
    , method   = "REML"
    , ddfm     = "satterth"
    , type     = 3
    , class    = "breed"
    , bound    = TRUE
    , control  = list()
    )
v <- fm$covariance$estimate
h2 <- 4 * v[1] / sum(v)
h2
vlm_lsmeans(
    fit    = fm
  , specs  = ~ breed
  , at     = NULL
  , diff   = TRUE
  , adjust = "tukey"
  , level  = 0.95
  )
vlm_blup(
    fit   = fm
  , level = 0.95
  )

Example 3.3: covariance structures for repeated measures

Description

PCV of 12 animals of two breeds measured 14 times (ex33). Model 1 has a random animal effect, equivalent to compound symmetry (variances 5.478 and 4.965; -2 restricted log-likelihood 783.451); Model 2 has first-order autoregressive errors (rho = 0.621, residual 10.191; 793.139); Model 3 has a random intercept and slope per animal with an unstructured covariance (12.46, -0.2551, 0.005758 and residual 4.353).

Author(s)

Muhammad Yaseen ([email protected])

References

Duchateau, L., Janssen, P. and Rowlands, G. J. (1998). Linear Mixed Models. An Introduction with Applications in Veterinary Research. International Livestock Research Institute, Nairobi.

See Also

vlm_random, vlm_repeated, vlm_compare, ex33

Other VetResearchLMM examples: Examp1.3.2, Examp2.2.1.7, Examp2.3.2, Examp2.4.2.2, Examp2.4.3.1, Examp2.5.1.1, Examp2.5.2.1, Examp2.5.3.1, Examp2.5.4.1, Examp2.6.1, Examp3.1, Examp3.2

Examples

# SAS program of the book (Appendix B):
#   proc mixed data=ex33; class breed anim_id; model pcv = breed breed*time / solution;
#     random anim_id(breed) / solution;                               * Model 1;
#     repeated / type=cs sub=anim_id(breed) r;                         * Model 1, second form;
#     repeated / type=ar(1) sub=anim_id(breed) r;                      * Model 2;
#     random intercept time / type=un sub=anim_id(breed) solution;     * Model 3;
#   run;

m1 <-
  vlm_fit(
      fixed    = PCV ~ breed + breed:time
    , data     = ex33
    , random   = ~ animal_id:breed
    , repeated = NULL
    , method   = "REML"
    , ddfm     = "default"
    , type     = 3
    , class    = NULL
    , bound    = TRUE
    , control  = list()
    )
m1$fixed
vlm_blup(
    fit   = m1
  , level = 0.95
  )
cs <-
  vlm_fit(
      fixed    = PCV ~ breed + breed:time
    , data     = ex33
    , random   = NULL
    , repeated = vlm_repeated(
          type    = c("vc", "cs", "ar1", "sp_pow", "un")[2]
        , subject = ~ animal_id:breed
        , order   = NULL
        )
    , method   = "REML"
    , ddfm     = "default"
    , type     = 3
    , class    = NULL
    , bound    = TRUE
    , control  = list()
    )
cs$fit
m1c <-
  vlm_fit(
      fixed    = PCV ~ time + breed + breed:time
    , data     = ex33
    , random   = ~ animal_id:breed
    , repeated = NULL
    , method   = "REML"
    , ddfm     = "default"
    , type     = 3
    , class    = NULL
    , bound    = TRUE
    , control  = list()
    )
m1c$tests
ar <-
  vlm_fit(
      fixed    = PCV ~ breed + breed:time
    , data     = ex33
    , random   = NULL
    , repeated = vlm_repeated(
          type    = c("vc", "cs", "ar1", "sp_pow", "un")[3]
        , subject = ~ animal_id:breed
        , order   = ~ time
        )
    , method   = "REML"
    , ddfm     = "default"
    , type     = 3
    , class    = NULL
    , bound    = TRUE
    , control  = list()
    )
ar$covariance
rc <-
  vlm_fit(
      fixed    = PCV ~ breed + breed:time
    , data     = ex33
    , random   = vlm_random(
          effects = ~ 1 + time
        , subject = ~ animal_id:breed
        , type    = c("vc", "un")[2]
        )
    , repeated = NULL
    , method   = "REML"
    , ddfm     = "default"
    , type     = 3
    , class    = NULL
    , bound    = TRUE
    , control  = list()
    )
rc$covariance
vlm_compare(
    CS   = cs
  , AR1  = ar
  , RC   = rc
  , test = TRUE
  )

# the same model with lme4 (optional)
if (requireNamespace("lme4", quietly = TRUE)) {
  lm4 <-
    lme4::lmer(
        formula = PCV ~ breed + breed:time + (1 | animal_id)
      , data    = ex33
      , REML    = TRUE
      )
  print(lme4::VarCorr(lm4), comp = "Variance")
}

Report a fitted mixed model

Description

Gives a narrative report of a fitted model. For a result of vlm_fit() it is the plain-language interpretation of vlm_interpret(); for other models the optional package report writes the report, as in version 1.1.0.

Usage

report_mixed_model(model, ...)

## Default S3 method:
report_mixed_model(model, ...)

## S3 method for class 'vlm_fit'
report_mixed_model(model, ...)

Arguments

model

a fitted model: a result of vlm_fit() or a model supported by report.

...

further arguments passed to report::report() or to vlm_interpret().

Value

A vlm_interpretation object for a vlm_fit result; otherwise the object returned by report::report().

Author(s)

Muhammad Yaseen ([email protected])

References

Makowski, D., Ben-Shachar, M. S., Patil, I. and Luedecke, D. (2023). Automated results reporting as a practical tool to improve reproducibility and methodological best practices adoption. R package report.

See Also

vlm_interpret, emmeans_mixed_model

Other VetResearchLMM inference: emmeans_mixed_model(), vlm_blup(), vlm_estimate(), vlm_lsmeans()

Examples

fm <-
  vlm_fit(
      fixed    = Pcv ~ Drug + dose + Drug:dose
    , data     = ex125
    , random   = ~ Region + Region:Drug
    , repeated = NULL
    , method   = "REML"
    , ddfm     = "default"
    , type     = 3
    , class    = NULL
    , bound    = TRUE
    , control  = list()
    )
report_mixed_model(
    model = fm
  )

Linear mixed models in a web browser

Description

vlm_app() starts the application of VetResearchLMM: choose a data set of the book (or upload a CSV file), fit a linear mixed model with random effects and a residual covariance structure, and obtain least-squares means, estimates and contrasts, predictions of random effects, the analysis of variance with expected mean squares, and a comparison of covariance structures. Every example of the book can be loaded with one click. Each result page shows an interpretation computed from the results (vlm_interpret()), the output as R prints it, formatted tables, plots and the R code that repeats the analysis, each with a Copy button.

Usage

vlm_app(launch.browser = interactive(), ...)

vlm_app_object()

Arguments

launch.browser

passed to shiny::runApp(): TRUE (default in an interactive session) opens the application in the web browser.

...

further arguments to shiny::runApp(), such as port.

Details

The application needs the suggested packages shiny, bslib and DT. Plots are sent to the browser as WebP images when magick is installed (PNG otherwise) and can be downloaded as PNG, PDF or WebP. Estimates and contrasts are typed as in SAS: label: effect coefficients effect coefficients, one per line, with rows of a contrast separated by commas.

Value

vlm_app() is called for its side effect and returns the value of shiny::runApp() when the application is closed; vlm_app_object() returns the application object (for shiny::runApp(), shiny::testServer() or deployment on a server).

Author(s)

Muhammad Yaseen ([email protected])

See Also

vlm_fit, vlm_lsmeans, vlm_ems

Other VetResearchLMM utilities: autoplot.vlm_result(), vlm_cite(), vlm_interpret(), vlm_notation(), vlm_reference(), vlm_save(), vlm_theme()

Examples

if (interactive()) {
  vlm_app(
      launch.browser = TRUE
    )
}

Best linear unbiased predictions of the random effects

Description

The predictions u^=G^Z⊤V^−1(y−Xβ^)\widehat{\mathbf{u}} = \widehat{\mathbf{G}}\mathbf{Z}^{\top}\widehat{\mathbf{V}}^{-1} (\mathbf{y} - \mathbf{X}\widehat{\boldsymbol{\beta}}) of the random effects of a fitted model, with the standard errors of prediction diag(C22)\sqrt{\mathrm{diag}(\mathbf{C}_{22})}, t tests and prediction limits: the solution for random effects of SAS PROC MIXED.

Usage

vlm_blup(fit, level = 0.95)

## Default S3 method:
vlm_blup(fit, level = 0.95)

Arguments

fit

a result of vlm_fit().

level

confidence level of the prediction limits (default 0.95).

Details

For a single random factor with nin_i observations on level ii, the prediction reduces to

s^i=niσ^s2niσ^s2+σ^2(yˉi⋅−μ^),\widehat{s}_i = \frac{n_i\widehat{\sigma}_s^2}{n_i\widehat{\sigma}_s^2 + \widehat{\sigma}^2} (\bar{y}_{i\cdot} - \widehat{\mu}),

a shrinkage of the level mean towards the overall mean (Example 2.4.3.1 of the book). The degrees of freedom are the residual ones, or Satterthwaite ones (numerical derivatives of the prediction-error variance) with ddfm = "satterth" or "kr".

Value

A list of class c("vlm_blup", "vlm_result", "list") with blup (effect, subject, level, prediction, standard error of prediction, df, t, p and limits).

Author(s)

Muhammad Yaseen ([email protected])

References

Duchateau, L., Janssen, P. and Rowlands, G. J. (1998). Linear Mixed Models. An Introduction with Applications in Veterinary Research. International Livestock Research Institute, Nairobi. Section 2.4.3.

Henderson, C. R. (1975). Best linear unbiased estimation and prediction under a selection model. Biometrics, 31, 423-447.

See Also

vlm_fit

Other VetResearchLMM inference: emmeans_mixed_model(), report_mixed_model(), vlm_estimate(), vlm_lsmeans()

Examples

# Example 2.4.3.1: PROC MIXED; CLASS sire; MODEL ww = ; RANDOM sire / SOLUTION;
fs <-
  vlm_fit(
      fixed    = Ww ~ 1
    , data     = ex127
    , random   = ~ sire
    , repeated = NULL
    , method   = "REML"
    , ddfm     = "default"
    , type     = 3
    , class    = NULL
    , bound    = TRUE
    , control  = list()
    )
bl <-
  vlm_blup(
      fit   = fs
    , level = 0.95
    )
bl

References of a result or of the package

Description

vlm_cite() gives the references of the methods behind a result of the package, or every reference of the package, as text or BibTeX. citation("VetResearchLMM") cites the package and the book.

Usage

vlm_cite(x = NULL, style = c("text", "bibtex"))

## Default S3 method:
vlm_cite(x = NULL, style = c("text", "bibtex"))

Arguments

x

a result of a function of the package, or NULL (default) for every reference.

style

"text" (default) or "bibtex".

Value

An object of class bibentry (printed in the chosen style).

Author(s)

Muhammad Yaseen ([email protected])

See Also

Other VetResearchLMM utilities: autoplot.vlm_result(), vlm_app(), vlm_interpret(), vlm_notation(), vlm_reference(), vlm_save(), vlm_theme()

Examples

vlm_cite(
    x     = NULL
  , style = "text"
  )

Compare fitted models

Description

Compares several fits of vlm_fit() by their (restricted) log-likelihoods and information criteria, and tests each model against the one before it by a likelihood ratio test: the comparison of covariance structures of Example 3.3 of the book (compound symmetry, first-order autoregressive, random coefficients).

Usage

vlm_compare(..., test = TRUE)

## Default S3 method:
vlm_compare(..., test = TRUE)

Arguments

...

two or more results of vlm_fit(), optionally named.

test

logical; add likelihood ratio tests of each model against the previous one (default TRUE).

Details

With ℓ\ell the maximised (restricted) log-likelihood and dd the number of covariance parameters (plus the rank of X\mathbf{X} for ML), AIC=−2ℓ+2dAIC = -2\ell + 2d, AICC=−2ℓ+2dn∗/(n∗−d−1)AICC = -2\ell + 2dn^*/(n^* - d - 1) and BIC=−2ℓ+dlog⁡sBIC = -2\ell + d\log s, where n∗=N−rank(X)n^* = N - \mathrm{rank}(\mathbf{X}) for REML (NN for ML) and ss is the number of subjects. The likelihood ratio statistic of two nested models is −2(ℓ0−ℓ1)-2(\ell_0 - \ell_1), referred to χd1−d02\chi^2_{d_1 - d_0}; when the larger model adds one variance component, the null value lies on the boundary and p_boundary gives the p-value of the 50:50 mixture of χ02\chi^2_0 and χ12\chi^2_1 (Self and Liang 1987). REML likelihoods are comparable only between models with the same fixed effects; the test is then left out.

Value

A list of class c("vlm_compare", "vlm_result", "list") with models (one row per model: method, number of covariance parameters, -2 log-likelihood, AIC, AICC, BIC and the test against the previous model).

Author(s)

Muhammad Yaseen ([email protected])

References

Duchateau, L., Janssen, P. and Rowlands, G. J. (1998). Linear Mixed Models. An Introduction with Applications in Veterinary Research. International Livestock Research Institute, Nairobi. Section 3.4.

Self, S. G. and Liang, K.-Y. (1987). Asymptotic properties of maximum likelihood estimators and likelihood ratio tests under nonstandard conditions. Journal of the American Statistical Association, 82, 605-610.

See Also

vlm_fit

Other VetResearchLMM models: vlm_ems(), vlm_fit(), vlm_random()

Examples

cs <-
  vlm_fit(
      fixed    = PCV ~ breed + breed:time
    , data     = ex33
    , random   = NULL
    , repeated = vlm_repeated(
          type    = c("vc", "cs", "ar1", "sp_pow", "un")[2]
        , subject = ~ animal_id:breed
        , order   = NULL
        )
    , method   = "REML"
    , ddfm     = "default"
    , type     = 3
    , class    = NULL
    , bound    = TRUE
    , control  = list()
    )
ar <-
  vlm_fit(
      fixed    = PCV ~ breed + breed:time
    , data     = ex33
    , random   = NULL
    , repeated = vlm_repeated(
          type    = c("vc", "cs", "ar1", "sp_pow", "un")[3]
        , subject = ~ animal_id:breed
        , order   = NULL
        )
    , method   = "REML"
    , ddfm     = "default"
    , type     = 3
    , class    = NULL
    , bound    = TRUE
    , control  = list()
    )
rc <-
  vlm_fit(
      fixed    = PCV ~ breed + breed:time
    , data     = ex33
    , random   = vlm_random(
          effects = ~ 1 + time
        , subject = ~ animal_id:breed
        , type    = c("vc", "un")[2]
        )
    , repeated = NULL
    , method   = "REML"
    , ddfm     = "default"
    , type     = 3
    , class    = NULL
    , bound    = TRUE
    , control  = list()
    )
vlm_compare(
    CS   = cs
  , AR1  = ar
  , RC   = rc
  , test = TRUE
  )

Analysis of variance with expected mean squares

Description

The analysis of variance of a linear model fitted by ordinary least squares, with the expected mean squares of each source when some effects are random, F tests built from the appropriate (synthesised) error terms with Satterthwaite degrees of freedom, and the method-of-moments (Type 3) estimates of the variance components. This is SAS PROC GLM with a RANDOM statement and the TEST option (Examples 1.3.2 and 2.5.3.1 of the book).

Usage

vlm_ems(fixed, data, random = NULL, type = 3, class = NULL)

## Default S3 method:
vlm_ems(fixed, data, random = NULL, type = 3, class = NULL)

Arguments

fixed

two-sided formula with every effect of the model, random effects included, in SAS MODEL order (for example PCVdif ~ drug + drug:herd + dose + dose:drug).

data

a data frame with the variables.

random

one-sided formula of the effects of fixed that are random (for example ~ drug:herd); NULL for a fixed-effects analysis.

type

type of sums of squares: 3 (default) or 1.

class

optional character vector of numeric variables to treat as classification variables.

Details

The sum of squares of a source is a quadratic form SS=y⊤AySS = \mathbf{y}^{\top}\mathbf{A}\mathbf{y}: for Type 3, A=XCL⊤(LCL⊤)−1LCX⊤\mathbf{A} = \mathbf{X}\mathbf{C}\mathbf{L}^{\top}(\mathbf{L}\mathbf{C}\mathbf{L}^{\top})^{-1}\mathbf{L} \mathbf{C}\mathbf{X}^{\top} with C=(X⊤X)−1\mathbf{C} = (\mathbf{X}^{\top}\mathbf{X})^{-1} in the sum-to-zero coding and L\mathbf{L} selecting the columns of the source; for Type 1, the projection on the columns added by the source. With random effects uk∼N(0,σk2I)\mathbf{u}_k \sim N(\mathbf{0}, \sigma_k^2\mathbf{I}) of design Zk\mathbf{Z}_k,

E(MS)=σ2+∑ktr(Zk⊤AZk)DF σk2+Q(fixed).E(MS) = \sigma^2 + \sum_k \frac{\mathrm{tr}(\mathbf{Z}_k^{\top}\mathbf{A}\mathbf{Z}_k)}{DF}\,\sigma_k^2 + Q(\mathrm{fixed}).

The error term of a source is the combination ∑rarMSr\sum_r a_r MS_r of mean squares of other random sources and the residual whose expectation equals that of the source under the null hypothesis; its degrees of freedom are (∑rarMSr)2/∑r(arMSr)2/DFr(\sum_r a_r MS_r)^2 / \sum_r (a_r MS_r)^2 / DF_r (Satterthwaite 1946). Equating the mean squares of the random sources and the error to their expectations gives the Type 3 estimates of the variance components.

Value

A list of class c("vlm_ems", "vlm_result", "list") with anova (source, df, sum of squares, mean square, expected mean square, F, error degrees of freedom and p-value), coefficients (the coefficients of the variance components in each expected mean square), error_terms (the combination of mean squares used as the error of each test) and components (Type 3 estimates of the variance components).

Author(s)

Muhammad Yaseen ([email protected])

References

Duchateau, L., Janssen, P. and Rowlands, G. J. (1998). Linear Mixed Models. An Introduction with Applications in Veterinary Research. International Livestock Research Institute, Nairobi. Section 1.3.2 and Appendix G.

Satterthwaite, F. E. (1946). An approximate distribution of estimates of variance components. Biometrics Bulletin, 2, 110-114.

See Also

vlm_fit

Other VetResearchLMM models: vlm_compare(), vlm_fit(), vlm_random()

Examples

# Example 1.3.2: PROC GLM; CLASS herd dose drug; MODEL PCVdif = drug herd(drug) dose dose*drug;
# RANDOM herd(drug) / TEST;
em <-
  vlm_ems(
      fixed  = PCVdif ~ drug + drug:herd + dose + dose:drug
    , data   = ex124
    , random = ~ drug:herd
    , type   = 3
    , class  = "herd"
    )
em

# one observation deleted: the expected mean squares of drug and herd(drug) no longer match
# (Table 1.3.2.3)
em1 <-
  vlm_ems(
      fixed  = PCVdif ~ drug + drug:herd + dose + dose:drug
    , data   = ex124[-1, ]
    , random = ~ drug:herd
    , type   = 3
    , class  = "herd"
    )
em1$coefficients

Estimates and contrasts of fixed (and random) effects

Description

vlm_estimate() gives estimates of linear combinations l⊤β\mathbf{l}^{\top}\boldsymbol{\beta} (the ESTIMATE statement of SAS PROC MIXED), optionally including random effects k⊤u\mathbf{k}^{\top}\mathbf{u} (the narrow or intermediate inference space). vlm_contrast() gives F tests of sets of linear combinations Lβ=0\mathbf{L}\boldsymbol{\beta} = \mathbf{0} (the CONTRAST statement).

Usage

vlm_estimate(fit, L, random = NULL, level = 0.95)

## Default S3 method:
vlm_estimate(fit, L, random = NULL, level = 0.95)

vlm_contrast(fit, L)

## Default S3 method:
vlm_contrast(fit, L)

Arguments

fit

a result of vlm_fit().

L

for vlm_estimate(): a named list of estimates, each a named list of effect coefficients (such as list(Drug = c(-1, 1), "Drug:dose" = c(-0.5, -0.5, 0.5, 0.5))) or a numeric vector over all columns of the solution. For vlm_contrast(): a named list of contrasts, each one such row or a list of rows.

random

optional named list (names as in L) of random-effect coefficients for the narrow inference space: each a named list of random effects (as in the effect column of vlm_blup()) with coefficients over their levels.

level

confidence level (default 0.95).

Details

Coefficients are given per effect as in SAS, in the order of the levels in the solution table (fit$fixed); missing trailing coefficients are zero. The variance of an estimate is l⊤C11l+2l⊤C12k+k⊤C22k\mathbf{l}^{\top}\mathbf{C}_{11}\mathbf{l} + 2\mathbf{l}^{\top}\mathbf{C}_{12}\mathbf{k} + \mathbf{k}^{\top}\mathbf{C}_{22}\mathbf{k}, where C11=(X⊤V−1X)−\mathbf{C}_{11} = (\mathbf{X}^{\top}\mathbf{V}^{-1} \mathbf{X})^{-}, C12=−C11X⊤V−1ZG\mathbf{C}_{12} = -\mathbf{C}_{11}\mathbf{X}^{\top}\mathbf{V}^{-1}\mathbf{Z}\mathbf{G} and C22=G−GZ⊤PZG\mathbf{C}_{22} = \mathbf{G} - \mathbf{G}\mathbf{Z}^{\top}\mathbf{P}\mathbf{Z}\mathbf{G} (Henderson's mixed model equations). The F statistic of a contrast is

F=(Lβ^)⊤(LC11L⊤)−1(Lβ^)rank(L),F = \frac{(\mathbf{L}\widehat{\boldsymbol{\beta}})^{\top}(\mathbf{L}\mathbf{C}_{11}\mathbf{L}^{\top})^{-1} (\mathbf{L}\widehat{\boldsymbol{\beta}})}{\mathrm{rank}(\mathbf{L})},

with the denominator degrees of freedom of the fit. Rows that are not estimable give NA.

Value

A list of class c("vlm_estimate", "vlm_result", "list") with estimates (label, estimate, standard error, df, t, p, confidence limits and inference space) and L; or of class c("vlm_contrast", "vlm_result", "list") with contrasts (label, numerator and denominator df, F and p).

Author(s)

Muhammad Yaseen ([email protected])

References

Duchateau, L., Janssen, P. and Rowlands, G. J. (1998). Linear Mixed Models. An Introduction with Applications in Veterinary Research. International Livestock Research Institute, Nairobi. Sections 2.5 and 2.6.

McLean, R. A., Sanders, W. L. and Stroup, W. W. (1991). A unified approach to mixed linear models. The American Statistician, 45, 54-64.

See Also

vlm_lsmeans, vlm_fit

Other VetResearchLMM inference: emmeans_mixed_model(), report_mixed_model(), vlm_blup(), vlm_lsmeans()

Examples

fm <-
  vlm_fit(
      fixed    = Pcv ~ Drug + dose + Drug:dose
    , data     = ex125
    , random   = ~ Region + Region:Drug
    , repeated = NULL
    , method   = "REML"
    , ddfm     = "satterth"
    , type     = 3
    , class    = NULL
    , bound    = TRUE
    , control  = list()
    )
# Example 2.5.3.1: ESTIMATE statements (levels: Drug BERENIL samorin, dose h l)
es <-
  vlm_estimate(
      fit    = fm
    , L      = list(
          "drug dif"     = list(Drug = c(-1, 1), "Drug:dose" = c(-0.5, -0.5, 0.5, 0.5))
        , "Samorin mean" = list(Intercept = 1, Drug = c(0, 1),
                                dose = c(0.5, 0.5), "Drug:dose" = c(0, 0, 0.5, 0.5))
        , "Samorin HvsL" = list(dose = c(1, -1), "Drug:dose" = c(0, 0, 1, -1))
        , "Samorin high" = list(Intercept = 1, Drug = c(0, 1),
                                dose = c(1, 0), "Drug:dose" = c(0, 0, 1, 0))
        )
    , random = NULL
    , level  = 0.95
    )
es

# Example 2.6.1: CONTRAST statements
ct <-
  vlm_contrast(
      fit = fm
    , L   = list(
          "drug dif" = list(Drug = c(-1, 1), "Drug:dose" = c(-0.5, -0.5, 0.5, 0.5))
        , "all"      = list(
              list(Drug = c(1, -1), "Drug:dose" = c(0.5, 0.5, -0.5, -0.5))
            , list(dose = c(1, -1), "Drug:dose" = c(0.5, -0.5, 0.5, -0.5))
            , list("Drug:dose" = c(0.5, -0.5, -0.5, 0.5))
            )
        )
    )
ct

Fit a linear mixed model

Description

Fits the linear mixed model y=Xβ+Zu+e\mathbf{y} = \mathbf{X}\boldsymbol{\beta} + \mathbf{Z}\mathbf{u} + \mathbf{e} by restricted maximum likelihood (REML), maximum likelihood (ML) or the method of moments on Type 3 mean squares, and gives the results of SAS PROC MIXED: covariance parameter estimates with standard errors, the solution for the fixed effects in the overparameterised coding, Type 3 (or Type 1) tests with containment, residual, between-within, Satterthwaite or Kenward-Roger denominator degrees of freedom, and fit statistics. It is the engine behind every analysis of the book of Duchateau, Janssen and Rowlands (1998).

Usage

vlm_fit(
  fixed,
  data,
  random = NULL,
  repeated = NULL,
  method = c("REML", "ML", "Type3"),
  ddfm = c("default", "contain", "residual", "betwithin", "satterth", "kr"),
  type = 3,
  class = NULL,
  bound = TRUE,
  control = list()
)

## Default S3 method:
vlm_fit(
  fixed,
  data,
  random = NULL,
  repeated = NULL,
  method = c("REML", "ML", "Type3"),
  ddfm = c("default", "contain", "residual", "betwithin", "satterth", "kr"),
  type = 3,
  class = NULL,
  bound = TRUE,
  control = list()
)

Arguments

fixed

two-sided formula of the response and the fixed effects, such as Pcv ~ Drug * dose; terms are kept in the order written, as in a SAS MODEL statement (a/b gives a + a:b).

data

a data frame (or data.table) with the variables.

random

NULL, a one-sided formula of random variance components (each term one component, such as ~ Region + Region:Drug), a vlm_random() specification, or a list of these.

repeated

NULL or a vlm_repeated() specification of the residual covariance.

method

"REML" (default), "ML" or "Type3".

ddfm

denominator degrees of freedom: "default", "contain", "residual", "betwithin", "satterth" or "kr", the DDFM= keywords of SAS.

type

type of the tests of fixed effects: 3 (default) or 1 (sequential).

class

optional character vector of numeric variables to treat as classification variables (factors), like the SAS CLASS statement. Non-numeric variables and the variables of random effects and subjects are always classification variables.

bound

logical; keep variance estimates non-negative (default TRUE; FALSE is the SAS NOBOUND option).

control

list with maxit (default 200), tol (default 10−1210^{-12}) and start (starting values of the covariance parameters, in the order of the covariance table).

Details

With u∼N(0,G)\mathbf{u} \sim N(\mathbf{0}, \mathbf{G}) and e∼N(0,R)\mathbf{e} \sim N(\mathbf{0}, \mathbf{R}) independent, V=ZGZ⊤+R\mathbf{V} = \mathbf{Z}\mathbf{G}\mathbf{Z}^{\top} + \mathbf{R} depends on the covariance parameters θ\boldsymbol{\theta}. With P=rank(X)P = \mathrm{rank}(\mathbf{X}) and NN observations, the REML log-likelihood is

ℓR(θ)=−12{(N−P)log⁡(2π)+log⁡∣V∣+log⁡∣X⊤V−1X∣+r⊤V−1r},\ell_R(\boldsymbol{\theta}) = -\frac{1}{2}\left\{(N - P)\log(2\pi) + \log|\mathbf{V}| + \log|\mathbf{X}^{\top}\mathbf{V}^{-1}\mathbf{X}| + \mathbf{r}^{\top}\mathbf{V}^{-1}\mathbf{r}\right\},

with r=y−Xβ^\mathbf{r} = \mathbf{y} - \mathbf{X}\widehat{\boldsymbol{\beta}}; the ML log-likelihood drops the third term and uses NN in the first. It is maximised by Newton steps with the average-information matrix 12y⊤PViPVjPy\frac{1}{2}\mathbf{y}^{\top}\mathbf{P}\mathbf{V}_i\mathbf{P}\mathbf{V}_j\mathbf{P}\mathbf{y}, where Vi=∂V/∂θi\mathbf{V}_i = \partial\mathbf{V}/\partial\theta_i and P=V−1−V−1X(X⊤V−1X)−X⊤V−1\mathbf{P} = \mathbf{V}^{-1} - \mathbf{V}^{-1}\mathbf{X}(\mathbf{X}^{\top}\mathbf{V}^{-1}\mathbf{X})^{-}\mathbf{X}^{\top}\mathbf{V}^{-1}, with step halving and variances kept non-negative (unless bound = FALSE). The fixed effects are the generalised least-squares solution

β^=(X⊤V^−1X)−X⊤V^−1y\widehat{\boldsymbol{\beta}} = (\mathbf{X}^{\top}\widehat{\mathbf{V}}^{-1}\mathbf{X})^{-} \mathbf{X}^{\top}\widehat{\mathbf{V}}^{-1}\mathbf{y}

in the overparameterised coding (one column per level), with the generalised inverse that sets aliased levels to zero, as SAS does. Standard errors of the covariance parameters come from the observed information.

Type 3 tests use the sum-to-zero coding of each effect (the SAS Type 3 hypothesis when every cell is observed). The denominator degrees of freedom (ddfm) are: "contain", the rank contribution of the random effects that contain the fixed effect, or N−rank[X Z]N - \mathrm{rank}[\mathbf{X}\ \mathbf{Z}] if none does; "residual", N−rank[X Z]N - \mathrm{rank}[\mathbf{X}\ \mathbf{Z}]; "betwithin", the between- and within-subject parts of the residual degrees of freedom; "satterth", ν=2{l⊤Cl}2/g⊤Ag\nu = 2\{\mathbf{l}^{\top}\mathbf{C}\mathbf{l}\}^2 / \mathbf{g}^{\top}\mathbf{A}\mathbf{g}, with g\mathbf{g} the gradient of l⊤Cl\mathbf{l}^{\top}\mathbf{C}\mathbf{l} in θ\boldsymbol{\theta} and A\mathbf{A} the asymptotic covariance of θ^\widehat{\boldsymbol{\theta}} (Giesbrecht and Burns 1985; Fai and Cornelius 1996 for several rows); "kr", the adjusted covariance and scaled F of Kenward and Roger (1997). "default" chooses as SAS: containment with random effects, between-within with a residual structure only, residual otherwise.

Method "Type3" (random variance components only) equates the Type 3 mean squares of the random effects to their expectations (vlm_ems()); negative solutions are set to zero.

Value

A list of class c("vlm_fit", "vlm_result", "list") with covariance (covariance parameter estimates, standard errors and Wald Z tests), fixed (solution for the fixed effects), tests (tests of the fixed effects), fit (fit statistics) and dimensions; the call is kept in attr(, "call"). Further analyses of the fit: vlm_lsmeans(), vlm_estimate(), vlm_contrast(), vlm_blup(), vlm_compare() and vlm_interpret().

Author(s)

Muhammad Yaseen ([email protected])

References

Duchateau, L., Janssen, P. and Rowlands, G. J. (1998). Linear Mixed Models. An Introduction with Applications in Veterinary Research. International Livestock Research Institute, Nairobi.

Patterson, H. D. and Thompson, R. (1971). Recovery of inter-block information when block sizes are unequal. Biometrika, 58, 545-554.

Kenward, M. G. and Roger, J. H. (1997). Small sample inference for fixed effects from restricted maximum likelihood. Biometrics, 53, 983-997.

See Also

vlm_random, vlm_lsmeans, vlm_estimate, vlm_ems

Other VetResearchLMM models: vlm_compare(), vlm_ems(), vlm_random()

Examples

# Example 2.5.1.1: PROC MIXED; CLASS drug dose region; MODEL pcv = drug dose drug*dose / SOLUTION;
# RANDOM region drug*region;
fm <-
  vlm_fit(
      fixed    = Pcv ~ Drug + dose + Drug:dose
    , data     = ex125
    , random   = ~ Region + Region:Drug
    , repeated = NULL
    , method   = "REML"
    , ddfm     = "satterth"
    , type     = 3
    , class    = NULL
    , bound    = TRUE
    , control  = list()
    )
fm
fm$covariance
fm$fixed

# Example 3.3, Model 2: first-order autoregressive residuals within an animal
ar <-
  vlm_fit(
      fixed    = PCV ~ breed + breed:time
    , data     = ex33
    , random   = NULL
    , repeated = vlm_repeated(
          type    = c("vc", "cs", "ar1", "sp_pow", "un")[3]
        , subject = ~ animal_id:breed
        , order   = ~ time
        )
    , method   = "REML"
    , ddfm     = "default"
    , type     = 3
    , class    = NULL
    , bound    = TRUE
    , control  = list()
    )
ar$covariance
ar$fit

Plain-language interpretation of a result

Description

vlm_interpret() turns a result of the package into a short report: a headline, findings, recommendations and cautions, computed from its numbers, with the sources of the method. It covers vlm_fit(), vlm_lsmeans(), vlm_estimate(), vlm_contrast(), vlm_blup(), vlm_ems() and vlm_compare().

Usage

vlm_interpret(x, alpha = 0.05, top = 3L, ...)

## Default S3 method:
vlm_interpret(x, alpha = 0.05, top = 3L, ...)

## S3 method for class 'vlm_interpretation'
print(x, ...)

## S3 method for class 'vlm_interpretation'
format(x, style = c("text", "markdown"), width = getOption("width", 80L), ...)

Arguments

x

a result of a function of the package.

alpha

significance level used in the sentences (default 0.05).

top

number of levels named in the findings (default 3).

...

unused.

style

"text" (default) or "markdown".

width

line width of the text (default getOption("width")).

Value

An object of class "vlm_interpretation": a list with analysis, title, headline, findings, recommendations, cautions, facts (the numbers behind the sentences), guide (how to read the method) and sources. format() gives it as text or Markdown.

Author(s)

Muhammad Yaseen ([email protected])

See Also

vlm_cite, vlm_app

Other VetResearchLMM utilities: autoplot.vlm_result(), vlm_app(), vlm_cite(), vlm_notation(), vlm_reference(), vlm_save(), vlm_theme()

Examples

fm <-
  vlm_fit(
      fixed    = Pcv ~ Drug + dose + Drug:dose
    , data     = ex125
    , random   = ~ Region + Region:Drug
    , repeated = NULL
    , method   = "REML"
    , ddfm     = "satterth"
    , type     = 3
    , class    = NULL
    , bound    = TRUE
    , control  = list()
    )
vlm_interpret(
    x     = fm
  , alpha = 0.05
  , top   = 3
  )

Least-squares means

Description

Least-squares means (estimated marginal means) of a classification effect of a fitted model, with their standard errors, degrees of freedom and confidence limits, and optionally all pairwise differences with a multiple comparison adjustment: the LSMEANS statement of SAS PROC MIXED.

Usage

vlm_lsmeans(
  fit,
  specs,
  at = NULL,
  diff = FALSE,
  adjust = c("none", "tukey", "bonferroni", "sidak"),
  level = 0.95
)

## Default S3 method:
vlm_lsmeans(
  fit,
  specs,
  at = NULL,
  diff = FALSE,
  adjust = c("none", "tukey", "bonferroni", "sidak"),
  level = 0.95
)

Arguments

fit

a result of vlm_fit().

specs

the effect: a character string such as "Drug:dose" or a one-sided formula such as ~ Drug:dose (all its variables must be classification variables of the fixed part).

at

optional named list of covariate values (default: the means of the covariates).

diff

logical; also give all pairwise differences (default FALSE).

adjust

multiple comparison adjustment of the differences: "none", "tukey", "bonferroni" or "sidak".

level

confidence level (default 0.95).

Details

The least-squares mean of a level combination is l⊤β^\mathbf{l}^{\top}\widehat{\boldsymbol{\beta}}, where l\mathbf{l} has 1 for the intercept and the matching levels, equal weights 1/m1/m over the mm levels (or cells) of the other factors of each effect, and the mean of each covariate (or the value in at) for covariate columns. Its variance is l⊤(X⊤V^−1X)−l\mathbf{l}^{\top}(\mathbf{X}^{\top} \widehat{\mathbf{V}}^{-1}\mathbf{X})^{-}\mathbf{l}, the broad-inference-space variance. Non-estimable means are returned as NA. With adjust = "tukey", p-values of the differences come from the studentised range distribution (Tukey-Kramer), P(Qk,ν>2∣t∣)P(Q_{k,\nu} > \sqrt{2}|t|), and the confidence limits use qk,ν(1−α)/2q_{k,\nu}(1-\alpha)/\sqrt{2}.

Value

A list of class c("vlm_lsmeans", "vlm_result", "list") with lsmeans, diffs (NULL unless diff = TRUE) and L (the coefficient rows).

Author(s)

Muhammad Yaseen ([email protected])

References

Duchateau, L., Janssen, P. and Rowlands, G. J. (1998). Linear Mixed Models. An Introduction with Applications in Veterinary Research. International Livestock Research Institute, Nairobi. Sections 2.5.2 and 3.3.

Searle, S. R., Speed, F. M. and Milliken, G. A. (1980). Population marginal means in the linear model: an alternative to least squares means. The American Statistician, 34, 216-221.

See Also

vlm_fit, vlm_estimate

Other VetResearchLMM inference: emmeans_mixed_model(), report_mixed_model(), vlm_blup(), vlm_estimate()

Examples

fm <-
  vlm_fit(
      fixed    = Pcv ~ Drug + dose + Drug:dose
    , data     = ex125
    , random   = ~ Region + Region:Drug
    , repeated = NULL
    , method   = "REML"
    , ddfm     = "satterth"
    , type     = 3
    , class    = NULL
    , bound    = TRUE
    , control  = list()
    )
# Example 2.5.2.1: LSMEANS drug*dose
lm1 <-
  vlm_lsmeans(
      fit    = fm
    , specs  = ~ Drug:dose
    , at     = NULL
    , diff   = TRUE
    , adjust = "tukey"
    , level  = 0.95
    )
lm1

Notation of VetResearchLMM

Description

The symbols used in the help pages and vignettes of VetResearchLMM, with their meaning and the argument or result component that holds them. The notation follows one rule throughout: scalars are upper-case letters in normal face (PP, RR), indices lower-case italic (i,ji, j), vectors lower-case bold (y\mathbf{y}, β\boldsymbol{\beta}) and matrices upper-case bold (X\mathbf{X}, Σ\boldsymbol{\Sigma}).

Usage

vlm_notation(format = c("table", "path", "tex"))

Arguments

format

"table" (default: a data.table with columns symbol (LaTeX), text (plain text), kind (scalar, index, vector, matrix, set, function, operator), meaning and argument), "path" (the path of notation.csv) or "tex" (the path of Notations.tex, the notation appendix used in the articles).

Value

See format.

Author(s)

Muhammad Yaseen ([email protected])

See Also

Other VetResearchLMM utilities: autoplot.vlm_result(), vlm_app(), vlm_cite(), vlm_interpret(), vlm_reference(), vlm_save(), vlm_theme()

Examples

vlm_notation(
    format = "table"
  )

Random-effects and residual covariance structures

Description

vlm_random() declares random coefficients for a subject (the RANDOM ... / SUBJECT= TYPE= statement of SAS PROC MIXED), and vlm_repeated() declares the covariance structure of the residuals within a subject (the REPEATED / SUBJECT= TYPE= statement). Both are passed to vlm_fit().

Usage

vlm_random(effects = ~1, subject, type = c("vc", "un"))

vlm_repeated(
  type = c("vc", "cs", "ar1", "sp_pow", "un"),
  subject,
  order = NULL
)

Arguments

effects

one-sided formula of the random coefficients, such as ~ 1 + time (random intercept and slope) or ~ 1.

subject

one-sided formula of the subject, such as ~ animal_id:breed; its variables are treated as classification variables and their combination identifies a subject.

type

"vc" (variance components, independent coefficients; the default of vlm_random()) or "un" (unstructured) for vlm_random(); "vc", "cs", "ar1", "sp_pow" or "un" for vlm_repeated().

order

one-sided formula of the time (or order) variable within a subject, such as ~ time; required for "sp_pow" and "un"; for "ar1" the data order within a subject is used when it is NULL.

Details

A random coefficient specification adds, for subject ss with design rows zsi⊤\mathbf{z}_{si}^{\top} (the values of effects for observation ii), the term zsi⊤bs\mathbf{z}_{si}^{\top}\mathbf{b}_s with bs∼N(0,G0)\mathbf{b}_s \sim N(\mathbf{0}, \mathbf{G}_0) independent between subjects. With type = "vc", G0\mathbf{G}_0 is diagonal (one variance per effect); with type = "un" it is unstructured and its parameters are reported as UN(1,1)UN(1,1), UN(2,1)UN(2,1), UN(2,2)UN(2,2), ..., as in SAS.

The residual structures for the observations of one subject, with tit_i the order (or time) of observation ii, are

vc: σ2I,cs: σ1J+σ2I,ar1: σ2ρ∣ri−rj∣,sp_pow: σ2ρ∣ti−tj∣,un: σtitj,\mathrm{vc}:\ \sigma^2\mathbf{I},\qquad \mathrm{cs}:\ \sigma_1\mathbf{J} + \sigma^2\mathbf{I},\qquad \mathrm{ar1}:\ \sigma^2\rho^{|r_i - r_j|},\qquad \mathrm{sp\_pow}:\ \sigma^2\rho^{|t_i - t_j|},\qquad \mathrm{un}:\ \sigma_{t_i t_j},

where rir_i is the rank of tit_i among the distinct times in the data, J\mathbf{J} a matrix of ones and σ1\sigma_1 the compound-symmetry covariance. Observations of different subjects are independent.

Value

An object of class vlm_random or vlm_repeated: a list with the arguments.

Author(s)

Muhammad Yaseen ([email protected])

References

Duchateau, L., Janssen, P. and Rowlands, G. J. (1998). Linear Mixed Models. An Introduction with Applications in Veterinary Research. International Livestock Research Institute, Nairobi. Section 3.4.

Littell, R. C., Milliken, G. A., Stroup, W. W. and Wolfinger, R. D. (1996). SAS System for Mixed Models. SAS Institute, Cary, NC.

See Also

vlm_fit

Other VetResearchLMM models: vlm_compare(), vlm_ems(), vlm_fit()

Examples

# random intercept and slope per animal, unstructured covariance (Example 3.3, Model 3)
ri <-
  vlm_random(
      effects = ~ 1 + time
    , subject = ~ animal_id:breed
    , type    = "un"
    )
ri

# first-order autoregressive residuals within an animal (Example 3.3, Model 2)
ar <-
  vlm_repeated(
      type    = "ar1"
    , subject = ~ animal_id:breed
    , order   = ~ time
    )
ar

Published values used by the tests and vignettes

Description

Reads inst/extdata/reference.csv: one row per published number, with its source, the R call that recomputes it with this package (call), the expression that extracts the number from the result (extract, in terms of x), the printed value and the digits to compare. The same file drives the test of published values and the vignette that reproduces the published examples. Each distinct call is evaluated once.

Usage

vlm_reference(source = NULL, evaluate = FALSE, level = 1)

Arguments

source

optional regular expression; keep rows whose source matches.

evaluate

logical; evaluate the rows and add columns computed and agrees (default FALSE).

level

largest level evaluated (1 = fast rows, 2 = slow rows; default 1); rows above it get NA.

Value

A data.table with columns id, source, quantity, call, extract, value, digits, level, note (and computed, agrees).

Author(s)

Muhammad Yaseen ([email protected])

See Also

Other VetResearchLMM utilities: autoplot.vlm_result(), vlm_app(), vlm_cite(), vlm_interpret(), vlm_notation(), vlm_save(), vlm_theme()

Examples

ref <-
  vlm_reference(
      source   = NULL
    , evaluate = FALSE
    , level    = 1
    )
ref

vlm_reference(
    source   = "."
  , evaluate = TRUE
  , level    = 1
  )

Save a figure (vector PDF by default)

Description

A wrapper of ggsave with the defaults of the package: a vector PDF through cairo_pdf (embedded fonts, correct glyphs), A4 landscape (11.69 x 8.27 inches) and 600 dpi for raster formats. The device follows the file extension for other formats (.png, .svg, .tiff, ...).

Usage

vlm_save(
  plot = ggplot2::last_plot(),
  filename,
  path = NULL,
  width = 11.69,
  height = 8.27,
  units = c("in", "cm", "mm"),
  dpi = 600,
  scale = 1,
  device = NULL,
  limitsize = TRUE,
  ...
)

## Default S3 method:
vlm_save(
  plot = ggplot2::last_plot(),
  filename,
  path = NULL,
  width = 11.69,
  height = 8.27,
  units = c("in", "cm", "mm"),
  dpi = 600,
  scale = 1,
  device = NULL,
  limitsize = TRUE,
  ...
)

Arguments

plot

a ggplot object, for example the result of plot() on a VetResearchLMM result (default: the last plot).

filename

file name; its extension chooses the format.

path

directory to save in (default NULL: the working directory or the path in filename).

width, height

size (default 11.69 x 8.27, A4 landscape, in units).

units

"in" (default), "cm" or "mm".

dpi

resolution for raster formats (default 600).

scale

multiplicative scaling factor (default 1).

device

NULL (default: cairo_pdf for .pdf, otherwise chosen from the extension) or a device function or name, passed to ggsave(). A file name ending in .webp gives a WebP image (drawn as PNG, then converted without loss by the suggested package magick; about half the size of the PNG).

limitsize

logical; refuse images larger than 50 x 50 inches (default TRUE).

...

passed to ggsave.

Value

The file name, invisibly.

Author(s)

Muhammad Yaseen ([email protected])

See Also

Other VetResearchLMM utilities: autoplot.vlm_result(), vlm_app(), vlm_cite(), vlm_interpret(), vlm_notation(), vlm_reference(), vlm_theme()

Examples

library(ggplot2)
p <-
  ggplot(data = data.frame(x = 1:10, y = (1:10)^2), mapping = aes(x = x, y = y)) +
  geom_line() +
  vlm_theme(
      base_size       = 11
    , base_family     = "serif"
    , ticks_inward    = TRUE
    , legend_position = "bottom"
    )
f <- tempfile(fileext = ".pdf")
vlm_save(
    plot      = p
  , filename  = f
  , path      = NULL
  , width     = 11.69
  , height    = 8.27
  , units     = c("in", "cm", "mm")[1]
  , dpi       = 600
  , scale     = 1
  , device    = NULL
  , limitsize = TRUE
  )
vlm_save(
    plot      = p
  , filename  = basename(f)
  , path      = tempdir()
  , width     = 11.69
  , height    = 8.27
  , units     = c("in", "cm", "mm")[1]
  , dpi       = 600
  , scale     = 1
  , device    = grDevices::cairo_pdf
  , limitsize = TRUE
  )
vlm_save(
    plot      = p
  , filename  = tempfile(fileext = ".png")
  , path      = NULL
  , width     = 6
  , height    = 4
  , units     = c("in", "cm", "mm")[1]
  , dpi       = 300
  , scale     = 1
  , device    = NULL
  , limitsize = TRUE
  )

ggplot2 theme of VetResearchLMM

Description

The theme used by every plot() method of VetResearchLMM (identical in all packages of the author): theme_classic with a serif font, black axis lines, ticks pointing inwards and no grid, close to the look of TikZ/pgfplots figures in LaTeX documents. The plot() methods also use scales::pretty_breaks(n = 10) on every continuous axis. Save figures with vlm_save.

Usage

vlm_theme(
  base_size = 11,
  base_family = "serif",
  ticks_inward = TRUE,
  legend_position = "bottom"
)

Arguments

base_size

base font size in points (default 11).

base_family

font family (default "serif"; for example "Latin Modern Roman" when installed, to match LaTeX documents).

ticks_inward

logical; ticks point into the panel, as in pgfplots (default TRUE).

legend_position

position of the legend (default "bottom").

Value

A ggplot2 theme.

Author(s)

Muhammad Yaseen ([email protected])

See Also

Other VetResearchLMM utilities: autoplot.vlm_result(), vlm_app(), vlm_cite(), vlm_interpret(), vlm_notation(), vlm_reference(), vlm_save()

Examples

library(ggplot2)
p <-
  ggplot(data = data.frame(x = 1:20, y = cumsum(sin(1:20))), mapping = aes(x = x, y = y)) +
  geom_line()
p +
  vlm_theme(
      base_size       = 11
    , base_family     = "serif"
    , ticks_inward    = TRUE
    , legend_position = "bottom"
    )
p +
  vlm_theme(
      base_size       = 12
    , base_family     = "serif"
    , ticks_inward    = FALSE
    , legend_position = "right"
    ) +
  scale_x_continuous(breaks = scales::pretty_breaks(n = 10))

Methods for VetResearchLMM results

Description

The analysis functions of VetResearchLMM return the named list they have always returned, now with the class c("vlm_<analysis>", "vlm_result", "list"). Components are read as before (x$ANOVA, x[["Means"]]); the methods below print, summarise and plot the result and turn any component into a data.table.

Usage

## S3 method for class 'vlm_result'
print(x, digits = 4L, ...)

## S3 method for class 'vlm_result'
summary(object, ...)

## S3 method for class 'summary.vlm_result'
print(x, ...)

## S3 method for class 'vlm_result'
format(x, ...)

## S3 method for class 'vlm_result'
as.data.table(x, keep.rownames = FALSE, ..., component = 1L)

## S3 method for class 'vlm_result'
as.data.frame(x, row.names = NULL, optional = FALSE, ..., component = 1L)

## S3 method for class 'vlm_result'
plot(x, ...)

Arguments

x, object

a VetResearchLMM result.

digits

significant digits of printed numbers (default 4).

...

passed on (to print() of the components, or to the plotting function for plot()).

keep.rownames, row.names, optional

as in data.table::as.data.table() and as.data.frame(); row names of a matrix or data frame component are always kept, in a first column term.

component

name or number of the component to convert (default: the first one).

Value

print() returns x invisibly; summary() an object of class summary.vlm_result; format() a character string; as.data.table() and as.data.frame() the chosen component as a table; plot() a ggplot object.

Author(s)

Muhammad Yaseen ([email protected])