Skip to contents

Suggest Statistically Sound Model Specification Based on Experimental Design

Source: R/suggest_model.R
suggest_model.Rd

Translates experimental design topology (treatments, blocking, split-plot errors, repeated measures, and covariates) into appropriate model formulas for standard R engines, providing explicit comparisons between **Classical ANOVA (`aov`/`lm`)** and **Linear Mixed Models (`lme4`/`nlme`)**.

Usage

suggest_model(
  design = 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,
  block_as = c("auto", "random", "fixed"),
  family = "auto"
)

Arguments

design

An object of class `"agri_design_check"` returned by check_design, or `NULL` if data arguments are supplied directly.

data

Optional `data.frame` if `design` is not provided.

response

Optional character string if `design` is not provided.

treatment

Optional character vector of treatments if `design` is not provided.

block

Optional character string of block factor.

main_plot

Optional character string of main-plot factor in split-plot.

sub_plot

Optional character string of sub-plot factor in split-plot.

sub_sub_plot

Optional character string of sub-sub-plot factor.

time

Optional character string of time factor in repeated measures.

subject

Optional character string of subject / pot ID in repeated measures.

covariates

Optional character vector of continuous baseline covariates.

block_as

Character string specifying how to treat the block factor: `"auto"` (default: random if >= 5 blocks, fixed if < 5 blocks to avoid singularity), `"random"` (force random effect `(1|block)`), or `"fixed"` (force fixed effect `+ block`).

family

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

Value

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

model_class

Type of model suggested (`"LM"`, `"LMM"`, `"GLMM"`, or `"GLS"`).

recommended_engine

Primary recommended R package (`"lme4"`, `"nlme"`, `"glmmTMB"`, or `"base"`).

fixed_formula

Formula object for fixed effects.

fixed_formula_str

Character representation of fixed formula.

random_formula

Formula object or character specification for random effects.

random_formula_lme4

Character representation of lme4 random structure.

call_classical_aov

Ready-to-run Classical ANOVA call with standard F-tests.

call_lme4

Executable R call for `lme4::lmer` or `lme4::glmer`.

call_nlme

Executable R call for `nlme::lme` or `nlme::gls`.

call_glmmTMB

Executable R call for `glmmTMB::glmmTMB`.

df_method

Recommended degrees of freedom approximation (`"Kenward-Roger"` or `"Satterthwaite"`).

paradigm_guidance

Clear guidance on when to choose Classical ANOVA vs. Mixed Models.

justification

Step-by-step statistical and agronomic rationale.

cautions

Alerts regarding degrees of freedom, sample size, or boundary singularities.

code_snippet

Ready-to-run R script.

Examples

data(wheat_splitplot, package = "agriDesignR")
diag <- check_design(
  data = wheat_splitplot,
  response = "grain_yield",
  main_plot = "temperature",
  sub_plot = "genotype",
  block = "block"
)
sugg <- suggest_model(diag)
print(sugg)
#> 
#> ======================================================================
#>   agriDesignR: Model Recommendation & Syntax Engine
#> ======================================================================
#>   Target Design   : Split-Plot Design (Parcelas Divididas)
#>   Recommended Form: LMM (Linear Mixed-Effects Model)
#>   Primary Engine  : lme4
#>   Assumed Family  : gaussian
#> 
#> 
#> 1. Decision Guidance: Classical ANOVA vs. Mixed Models
#> ----------------------------------------------------------------------
#>   - WHEN TO USE CLASSICAL ANOVA (aov / lm): When data are balanced, blocks are treated as fixed environmental controls, and standard F-tests are required for agronomy thesis/paper tables.
#> - WHEN TO USE MIXED MODELS (lme4): When data have missing plots/unbalance, hierarchical whole-plot nesting (Split-Plot), random block sampling, or non-Gaussian count/proportion distributions.
#> 
#> 
#> 2. Statistical Model Rationale
#> ----------------------------------------------------------------------
#>   - Split-Plot Hierarchy: Error A (whole-plot error) is modeled by '(1 | block:temperature)' testing factor 'temperature'. Sub-plot error (Error B) is captured by the residual variance.
#>   - Degrees of Freedom: Kenward-Roger approximation (via pbkrtest / lmerTest / emmeans), optimal for small sample sizes and split-plot structures.
#> 
#> 
#> 3. Ready-to-Run R Code (Classical & Mixed Options)
#> ----------------------------------------------------------------------
#> # ------------------------------------------------------------
#> # Option A: Classical ANOVA (stats::aov / lm)
#> # ------------------------------------------------------------
#> fit_aov <- stats::aov(grain_yield ~ block + temperature * genotype + Error(block/temperature), data = wheat_splitplot)
#> summary(fit_aov)
#> TukeyHSD(fit_aov) # Classical Tukey comparisons
#> 
#> # ------------------------------------------------------------
#> # Option B: Linear Mixed Model (lme4 / Kenward-Roger)
#> # ------------------------------------------------------------
#> fit_lmm <- lme4::lmer(grain_yield ~ temperature * genotype + (1 | block) + (1 | block:temperature), data = wheat_splitplot, REML = TRUE)
#> car::Anova(fit_lmm, type = 'III', test.statistic = 'F')
#> emmeans::emmeans(fit_lmm, pairwise ~ temperature, adjust = 'tukey')
#> 
#> 
#> ======================================================================
#>