Skip to contents

Pre-Experimental Design Decision Engine & Protocol Assistant (A Priori Planning)

Source: R/plan_experiment.R
plan_experiment.Rd

Provides rigorous, academic decision criteria to select the correct experimental design (DCA/CRD, DBCA/RCBD, Factorial DCA/DBCA, Split-Plot, Split-Split-Plot, Latin Square, or Repeated Measures). Prevents common agronomic mistakes such as confusing multi-factor designs with Split-Plot, pseudoreplication, or unneeded blocking.

Usage

plan_experiment(
  setting = c("greenhouse", "field", "growth_chamber", "laboratory"),
  treatments = list(),
  whole_plot_factor = NULL,
  sub_plot_factor = NULL,
  sub_sub_plot_factor = NULL,
  spatial_gradients = c("none", "unidirectional", "bidirectional", "table_to_table"),
  longitudinal_time = FALSE,
  target_cv = 10,
  desired_power = 0.8
)

Arguments

setting

Environmental setting: `"greenhouse"` (invernadero), `"field"` (campo), `"growth_chamber"` (camara de cultivo / fitotron), or `"laboratory"` (laboratorio / placas in vitro).

treatments

Named list of treatment factor names and their levels.

whole_plot_factor

Optional character string specifying a factor with HARD physical application constraints (e.g., `"temperature"`, `"irrigation"`, `"tillage"` that MUST be applied to whole tables/chambers/strips). IMPORTANT: Only specify if a factor cannot be randomized pot-by-pot!

sub_plot_factor

Optional character string for factors randomized within whole plots.

sub_sub_plot_factor

Optional character string for 3-way split-split-plot trials.

spatial_gradients

Character string specifying environmental heterogeneity: `"none"` (completely homogeneous: growth chamber, uniform petri dishes), `"unidirectional"` (1 gradient: distance from evaporative cooling pads, heaters, light slope), `"table_to_table"` (discrete greenhouse benches / tables with microclimate differences), `"bidirectional"` (2 orthogonal gradients: rows along light + columns along ventilation).

longitudinal_time

Logical, whether the same plants/pots are measured repeatedly over time (default = `FALSE`).

target_cv

Expected coefficient of variation (CV%) based on previous trials (default = 10%).

desired_power

Target statistical power (default = 0.80).

Value

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

recommended_design

Canonical name of the optimal experimental design.

analysis_paradigm

Recommended statistical framework: Classical ANOVA (lm/aov) vs. Linear Mixed Model (lme4).

decision_criteria

Rigorous justification explaining why this design was selected and why alternatives were rejected.

blocking_strategy

Practical instructions on how to set up blocks, benches, and pot allocations.

min_replications

Recommended minimum number of replications to ensure Error df >= 12.

total_experimental_units

Total number of pots / plots required.

model_formula_preview

Exact R formulas for both Classical ANOVA and Mixed Models.

critical_warnings

Crucial warnings to avoid pseudoreplication, confounding, or misclassification.

Examples

# Scenario 1: Homogeneous chamber -> DCA (Completely Randomized)
plan_crd <- plan_experiment(
  setting = "growth_chamber",
  treatments = list(fertilizer = c("N0", "N50", "N100", "N150")),
  spatial_gradients = "none"
)
print(plan_crd)
#> 
#> ======================================================================
#>   agriDesignR: Experimental Design Decision Engine
#> ======================================================================
#>   Target Setting   : GROWTH_CHAMBER
#>   Factor Structure : 1-Way Factorial (4 combinations: fertilizer)
#>   Spatial Gradient : none
#>   RECOMMENDED PLAN : Completely Randomized Design (DCA / CRD, 1 Factor)
#> 
#> 
#> 1. Rigorous Decision Rationale (Why this design?)
#> ----------------------------------------------------------------------
#>   Selected because the experimental environment is completely homogeneous (e.g. fully controlled growth chamber, in vitro petri dishes, uniform growth medium). No blocking is required; all experimental units are allocated completely at random.
#> 
#> 
#> 2. Statistical Modeling Strategy (Classical ANOVA vs. Mixed Models)
#> ----------------------------------------------------------------------
#>   - Recommended Paradigm: Classical 1-Way / Multi-Way ANOVA (lm / aov)
#>   - Classical ANOVA Form: lm(response ~ fertilizer)
#>   - Mixed Model Form (LMM): response ~ fertilizer  (LMM not needed; classical ANOVA is optimal)
#> 
#> 
#> 3. Practical Layout & Replication Protocol
#> ----------------------------------------------------------------------
#>   - No blocking required. All experimental units (pots/dishes) have equal probability of receiving any treatment.
#>   - Minimum Replications (b/r) : >= 4 replicates (ensuring Error df >= 12)
#>   - Total Experimental Units   : 16 pots / plots
#> 
#> 
#> [WARN] Methodological Warnings & Common Pitfalls
#> ----------------------------------------------------------------------
#>   [!] Why DCA over DBCA? If the room is homogeneous, creating arbitrary blocks consumes degrees of freedom from the residual error, REDUCING statistical power.
#>   [!] Rotate pot positions periodically (e.g. weekly) inside the chamber to average out minor edge micro-gradients.
#> 
#> ======================================================================
#>   Tip: Use 'generate_layout()' to create randomized greenhouse pot maps and planting CSVs.
#> 

# Scenario 2: Greenhouse benches -> DBCA (Randomized Complete Block)
plan_rcbd <- plan_experiment(
  setting = "greenhouse",
  treatments = list(genotype = paste0("G", 1:5)),
  spatial_gradients = "table_to_table"
)
print(plan_rcbd)
#> 
#> ======================================================================
#>   agriDesignR: Experimental Design Decision Engine
#> ======================================================================
#>   Target Setting   : GREENHOUSE
#>   Factor Structure : 1-Way Factorial (5 combinations: genotype)
#>   Spatial Gradient : table_to_table
#>   RECOMMENDED PLAN : Randomized Complete Block Design (DBCA / RCBD, 1 Factor)
#> 
#> 
#> 1. Rigorous Decision Rationale (Why this design?)
#> ----------------------------------------------------------------------
#>   Selected because discrete greenhouse tables/benches introduce microclimatic heterogeneity. Each table acts as a complete Block. ALL 5 treatment combinations are randomized COMPLETELY and independently within EACH table.
#> 
#> 
#> 2. Statistical Modeling Strategy (Classical ANOVA vs. Mixed Models)
#> ----------------------------------------------------------------------
#>   - Recommended Paradigm: Classical 2-Way ANOVA (lm / aov) or Linear Mixed Model (lme4)
#>   - Classical ANOVA Form: lm(response ~ block + genotype)
#>   - Mixed Model Form (LMM): response ~ genotype + (1 | block)
#> 
#> 
#> 3. Practical Layout & Replication Protocol
#> ----------------------------------------------------------------------
#>   - Place 1 full replication of all 5 treatment combinations inside each block/table. Never place all replicates of Treatment A on Table 1 and Treatment B on Table 2 (total confounding).
#>   - Minimum Replications (b/r) : >= 4 replicates (ensuring Error df >= 12)
#>   - Total Experimental Units   : 20 pots / plots
#> 
#> 
#> [WARN] Methodological Warnings & Common Pitfalls
#> ----------------------------------------------------------------------
#>   [!] Why DBCA over Split-Plot? Because both factors CAN be randomized independently inside each table. This yields a single, smaller error term (MSE) without sacrificing power.
#>   [!] Avoid pseudoreplication: multiple measurements on the same plant/pot are subsamples, not true independent replicates.
#> 
#> ======================================================================
#>   Tip: Use 'generate_layout()' to create randomized greenhouse pot maps and planting CSVs.
#> 

# Scenario 3: Real physical restriction -> Split-Plot
plan_sp <- plan_experiment(
  setting = "greenhouse",
  treatments = list(temp = c("22C", "36C"), genotype = paste0("G", 1:5)),
  whole_plot_factor = "temp",
  sub_plot_factor = "genotype",
  spatial_gradients = "table_to_table"
)
print(plan_sp)
#> 
#> ======================================================================
#>   agriDesignR: Experimental Design Decision Engine
#> ======================================================================
#>   Target Setting   : GREENHOUSE
#>   Factor Structure : 2-Way Factorial (10 combinations: temp x genotype)
#>   Spatial Gradient : table_to_table
#>   RECOMMENDED PLAN : Split-Plot Design (Parcelas Divididas, 2 Factores)
#> 
#> 
#> 1. Rigorous Decision Rationale (Why this design?)
#> ----------------------------------------------------------------------
#>   Selected strictly due to a HARD PHYSICAL CONSTRAINT in randomization. Factor 'temp' cannot be randomized independently pot-by-pot (e.g. chamber/table heating, macro-tunnel, flood irrigation). It is applied to whole plots (Error A), while 'genotype' is randomized as sub-plots within whole plots (Error B).
#> 
#> 
#> 2. Statistical Modeling Strategy (Classical ANOVA vs. Mixed Models)
#> ----------------------------------------------------------------------
#>   - Recommended Paradigm: Mixed-Effects Model (lme4 with Kenward-Roger) or Split-Plot ANOVA (aov Error term)
#>   - Classical ANOVA Form: aov(response ~ block + temp * genotype + Error(block/temp))
#>   - Mixed Model Form (LMM): response ~ temp * genotype + (1 | block) + (1 | block:temp)
#> 
#> 
#> 3. Practical Layout & Replication Protocol
#> ----------------------------------------------------------------------
#>   - Each greenhouse table or chamber group acts as a Block containing both whole-plot levels. Individual pots inside act as sub-plots.
#>   - Minimum Replications (b/r) : >= 4 replicates (ensuring Error df >= 12)
#>   - Total Experimental Units   : 40 pots / plots
#> 
#> 
#> [WARN] Methodological Warnings & Common Pitfalls
#> ----------------------------------------------------------------------
#>   [!] RIGOROUS RULE: Do NOT use Split-Plot merely because you have 2 factors! If both factors can be randomized independently pot-by-pot, you MUST use a standard Factorial DBCA (RCBD), which is statistically more powerful for the main factor.
#>   [!] Ensure at least 4 blocks so that Error A degrees of freedom (b - 1)(a - 1) >= 3.
#> 
#> ======================================================================
#>   Tip: Use 'generate_layout()' to create randomized greenhouse pot maps and planting CSVs.
#>