---
title: "Introduction to VetResearchLMM"
format:
  html:
    toc: true
    number-sections: true
    css: styles.css
execute:
  warning: false
  message: false
---

<!--
%\VignetteIndexEntry{Introduction to VetResearchLMM}
%\VignetteEngine{quarto::html}
%\VignetteEncoding{UTF-8}
-->

```{r}
#| include: false
library(methods)
if (requireNamespace("lme4", quietly = TRUE)) library(lme4)
if (requireNamespace("lmerTest", quietly = TRUE)) library(lmerTest)
load_book_data <- function(name) {
  load(file.path("..", "data", paste0(name, ".RData")), envir = parent.frame())
}
for (dataset_name in c("ex121", "ex124", "ex125", "ex127", "ex31", "ex32", "ex33")) {
  load_book_data(dataset_name)
}
```

## Scope

`VetResearchLMM` contains datasets and R examples for Duchateau, Janssen, and
Rowlands (1998), *Linear Mixed Models: An Introduction with Applications in
Veterinary Research*. The package is designed for applied users who want to
work through the book examples in R while preserving the statistical intent of
the original SAS analyses.

The package does not define a large modelling API. Instead, it provides:

- book datasets in `data/`
- example help pages such as `?Examp2.4.2.2`
- `collapse::fmutate()` preprocessing patterns in modernized examples
- `report_mixed_model()` for optional easystats-style fitted model reports
- tests that guard the documented dataset structure
- regression checks for readable numerical targets from the book

Current package maintenance includes the School of Mathematical and
Statistical Sciences, Clemson University.

## Included Data

```{r}
data.frame(
  dataset = c("ex121", "ex124", "ex125", "ex127", "ex31", "ex32", "ex33"),
  rows = c(
    nrow(ex121), nrow(ex124), nrow(ex125), nrow(ex127),
    nrow(ex31), nrow(ex32), nrow(ex33)
  ),
  columns = c(
    ncol(ex121), ncol(ex124), ncol(ex125), ncol(ex127),
    ncol(ex31), ncol(ex32), ncol(ex33)
  )
)
```

## Working With an Example

Example 2.2.1.7 studies hypothesis testing for dose effects in the `ex121`
data. The book reports an F statistic near 14.36 for the dose effect. The R
analysis reproduces that value to rounding precision.

```{r}
fit_ex2217 <- stats::aov(PCVdiff ~ dose, data = ex121)
if (requireNamespace("report", quietly = TRUE)) {
  report::report(fit_ex2217)
}
stats::anova(fit_ex2217)
```

The same dataset can be viewed graphically before modelling.

```{r}
if (requireNamespace("ggplot2", quietly = TRUE)) {
  ggplot2::ggplot(ex121, ggplot2::aes(x = dose, y = PCVdiff)) +
    ggplot2::geom_point(size = 2) +
    ggplot2::stat_summary(
      fun = mean,
      geom = "point",
      size = 3,
      shape = 18,
      color = "#1f78b4"
    ) +
    ggplot2::labs(
      x = "Dose",
      y = "Change in packed cell volume",
      title = "Packed cell volume response by dose"
    ) +
    ggplot2::theme_minimal()
}
```

## Book Verification Note

The bundled PDF is a scanned Google Books PDF with no extractable text. Exact
automated comparison against every printed value is therefore not possible
without OCR. The package tests verify the examples where the printed targets
are readable from page images, and the remaining examples are checked by model
specification and successful execution.