Skip to contents

Fit Intelligent Experimental Models with Multi-Engine Support and Assumption Diagnostics

Source: R/fit_experiment.R
fit_experiment.Rd

Fits appropriate linear, mixed-effects, generalized mixed-effects, or non-parametric models (`lme4`, `nlme`, `glmmTMB`, `base`/`lm`, or `nonparametric`) according to the detected experimental topology, calculates Type III ANOVA tables with Kenward-Roger/Satterthwaite degrees of freedom, and performs a comprehensive audit of statistical assumptions.

Usage

fit_experiment(
  object = NULL,
  data = NULL,
  response = NULL,
  treatment = NULL,
  block = NULL,
  main_plot = NULL,
  sub_plot = NULL,
  sub_sub_plot = NULL,
  time = NULL,
  subject = NULL,
  covariates = NULL,
  engine = c("auto", "lme4", "nlme", "glmmTMB", "lm", "base", "nonparametric"),
  reml = TRUE,
  df_method = c("auto", "Kenward-Roger", "Satterthwaite"),
  family = "auto",
  weights = NULL,
  correlation = NULL,
  na.action = stats::na.omit,
  ...,
  block_as = c("auto", "random", "fixed")
)

Arguments

object

An object of class `"agri_suggested_model"` (from suggest_model), `"agri_design_check"` (from check_design), or `NULL`.

data

A `data.frame` or `tibble` (required if `object` does not contain data or if specifying directly).

response

Optional character string specifying response variable name.

treatment

Optional character vector specifying treatment factors.

block

Optional character string specifying blocking factor.

main_plot

Optional character string specifying whole-plot factor for split-plot.

sub_plot

Optional character string specifying sub-plot factor for split-plot.

sub_sub_plot

Optional character string for split-split-plot.

time

Optional character string for repeated measures time factor.

subject

Optional character string for repeated measures subject/pot factor.

covariates

Optional character vector of continuous baseline covariates.

engine

Character string specifying the modeling engine: `"auto"` (default: selects optimal engine based on design and family), `"lme4"` (via lmerTest::lmer or lme4::glmer), `"nlme"` (via nlme::lme or nlme::gls), `"glmmTMB"` (via glmmTMB::glmmTMB), `"lm"` / `"base"` (standard Linear Model / Classical ANOVA via stats::lm), or `"nonparametric"` (Kruskal-Wallis or Friedman rank-sum test).

reml

Logical, whether to use Restricted Maximum Likelihood (REML) estimation (default = `TRUE`).

df_method

Character string for degrees of freedom approximation: `"auto"`, `"Kenward-Roger"`, or `"Satterthwaite"`.

family

Character string specifying distribution family (`"auto"`, `"gaussian"`, `"poisson"`, `"nbinom2"`, `"gamma"`, `"beta"`, `"binomial"`).

weights

Optional variance weighting structure (e.g. for `nlme` or `glmmTMB`).

correlation

Optional correlation structure (e.g. nlme::corAR1() for repeated measures).

na.action

Action to take for missing values (default = stats::na.omit).

...

Additional arguments passed to the underlying model fitting function.

block_as

Character string specifying how to treat the block factor: "auto" (default: fixed when fewer than five blocks, otherwise random), "random" (force (1 | block)), or "fixed" (force a fixed block term).

Value

An S3 object of class `"agri_fitted_model"` containing:

model

The fitted model object from the chosen engine.

engine

The R package engine used for fitting.

design_type

Detected canonical experimental design.

anova_table

Type III ANOVA / Deviance / Kruskal-Wallis significance table.

assumptions

Comprehensive audit of residuals, homoscedasticity, normality, and singularities.

df_method

Degrees of freedom approximation method used.

call

The executed model call.

data

The dataset used for fitting.

Examples

data(wheat_splitplot, package = "agriDesignR")
fit <- fit_experiment(
  data = wheat_splitplot,
  response = "grain_yield",
  main_plot = "temperature",
  sub_plot = "genotype",
  block = "block"
)
print(fit)
#> 
#> ======================================================================
#>   agriDesignR: Fitted Experimental Model Engine
#> ======================================================================
#>   Design Layout   : Split-Plot Design (Parcelas Divididas)
#>   Model Class     : LMM (Linear Mixed-Effects Model)
#>   Engine / Family : lme4 (gaussian)
#>   Fixed Formula   : grain_yield ~ temperature * genotype
#>   Random Terms    : (1 | block) + (1 | block:temperature)
#> 
#>   Health Check    : [!] MILD DEVIATIONS DETECTED (Robust under ANOVA)
#>     - Normality       : [PASSED] Residuals follow a normal distribution (Shapiro-Wilk W = 0.98, p = 0.6964).
#>     - Homoscedasticity: [ACCEPTABLE] Moderate variance spread across groups (Variance ratio = 21.36x, Levene p = 0.18). ANOVA F-tests remain robust when group sizes are balanced.
#> 
#> Type III ANOVA / Deviance Significance Table
#> ----------------------------------------------------------------------
#> Type III Analysis of Variance Table with Kenward-Roger's method
#>                       Sum Sq Mean Sq NumDF DenDF F value    Pr(>F)    
#> temperature           359.95  359.95     1     3  75.346  0.003217 ** 
#> genotype             1584.58  396.15     4    24  82.923 1.086e-13 ***
#> temperature:genotype  238.75   59.69     4    24  12.494 1.238e-05 ***
#> ---
#> Signif. codes:  0 ‘***’ 0.001 ‘**’ 0.01 ‘*’ 0.05 ‘.’ 0.1 ‘ ’ 1
#> 
#> ======================================================================
#>   Tip: Use 'summary(fit)' for parameter estimates, 'plot(fit)' for 4-panel residual graphs,
#>        or 'remedy(fit)' if assumption violations require transformations or varIdent.
#> 
anova(fit)
#> Type III Analysis of Variance Table with Kenward-Roger's method
#>                       Sum Sq Mean Sq NumDF DenDF F value    Pr(>F)    
#> temperature           359.95  359.95     1     3  75.346  0.003217 ** 
#> genotype             1584.58  396.15     4    24  82.923 1.086e-13 ***
#> temperature:genotype  238.75   59.69     4    24  12.494 1.238e-05 ***
#> ---
#> Signif. codes:  0 ‘***’ 0.001 ‘**’ 0.01 ‘*’ 0.05 ‘.’ 0.1 ‘ ’ 1