designCRD {pwr4exp} | R Documentation |
Creation of Standard Experimental Designs
Description
These functions facilitate the creation of standard experimental designs commonly used in agricultural studies for power analysis. Unlike mkdesign which requires a pre-existing data frame, these functions allow users to directly specify key design characteristics to generate experimental layouts. Quantitative parameters describing fixed and random effects remain consistent with those in mkdesign.
Usage
designCRD(
treatments,
label,
replicates,
formula,
beta = NULL,
means = NULL,
sigma2,
template = FALSE,
REML = TRUE
)
designRCBD(
treatments,
label,
blocks,
formula,
beta = NULL,
means = NULL,
vcomp,
sigma2,
template = FALSE,
REML = TRUE
)
designLSD(
treatments,
label,
squares = 1,
reuse = c("row", "col", "both"),
formula,
beta = NULL,
means = NULL,
vcomp,
sigma2,
template = FALSE,
REML = TRUE
)
designCOD(
treatments,
label,
squares = 1,
formula,
beta = NULL,
means = NULL,
vcomp,
sigma2,
template = FALSE,
REML = TRUE
)
designSPD(
trt.main,
trt.sub,
label,
replicates,
formula,
beta = NULL,
means = NULL,
vcomp,
sigma2,
template = FALSE,
REML = TRUE
)
Arguments
treatments |
An integer vector where each element represents the number of levels
of the corresponding treatment factor. A single integer (e.g., |
label |
Optional. A list of character vectors, each corresponding to a treatment factor.
The name of each vector specifies the factor's name, and its elements provide the labels for that factor's levels.
If no labels are provided, default labels will be used. For a single treatment factor, the default is
|
replicates |
The number of experimental units per treatment in a completely randomized design or the number of experimental units (main plots) per treatment of main plot factors. |
formula |
A right-hand-side formula specifying the model for testing treatment effects, with terms on the right of ~ , following lme4::lmer syntax for random effects. If not specified, a default formula with main effects and all interactions is used internally. |
beta |
One of the optional inputs for fixed effects. A vector of model coefficients where factor variable coefficients correspond to dummy variables created using treatment contrast (stats::contr.treatment). |
means |
One of the optional inputs for fixed effects.
A vector of marginal or conditioned means (if factors have interactions).
Regression coefficients are required for numerical variables.
Either |
sigma2 |
error variance. |
template |
Default is |
REML |
Specifies whether to use REML or ML information matrix. Default is |
blocks |
The number of blocks. |
vcomp |
A vector of variance-covariance components for random effects, if present. The values must follow a strict order. See mkdesign. |
squares |
The number of replicated squares. By default, 1, i.e., no replicated squares. |
reuse |
A character string specifying how to replicate squares when there are multiple squares. Options are: "row" for reusing row blocks, "col" for reusing column blocks, or "both" for reusing both row and column blocks to replicate a single square. |
trt.main |
An integer-valued vector specifying the treatment structure at
main plot level for a split plot design, similar to |
trt.sub |
An integer-valued vector specifying the treatment structure at
sub plot level for a split plot design, similar to |
Details
Each function creates a standard design as described below:
designCRD
Completely Randomized Design. By default, the model formula is
~ trt
for one factor and~ facA*facB
for two factors, unless explicitly specified. If thelabel
argument is provided, the formula is automatically updated with the specified treatment factor names.designRCBD
Randomized Complete Block Design. Experimental units are grouped into blocks, with each treatment appearing exactly once per block (i.e., no replicates per treatment within a block). The default model formula is
~ trt + (1|block)
for one factor and~ facA*facB + (1|block)
for two factors. Iflabel
is provided, the fixed effect parts of the formula are automatically updated with the specified names. The block factor is named "block" and not changeable.designLSD
Latin Square Design. The default formula is
~ trt + (1|row) + (1|col)
for one factor and~ facA*facB + (1|row) + (1|col)
for two factors. Iflabel
is provided, the fixed effect parts of the formula are automatically updated with the specified names. The names of row ("row") and column ("col") block factors are not changeable.designCOD
Crossover Design, which is a special case of LSD with time periods and individuals as blocks. Period blocks are reused when replicating squares. The default formula is
~ trt + (1|subject) + (1|period)
for one factor and~ facA*facB + (1|subject) + (1|period)
for two factors. Iflabel
is provided, the fixed effect parts of the formula are automatically updated with the specified names. Note that "subject" and "period" are the names for the two blocking factors and cannot be changed.designSPD
Split Plot Design. The default formula includes the main effects of all treatment factors at both the main and sub-plot levels, their interactions, and the random effects of main plots:
~ . + (1|mainplot)
. Iflabel
is provided, the fixed effect parts of the formula are automatically updated with the specified names. The experimental unit at the main plot level (i.e., the block factor at the subplot level) is always named as "mainplot".
Value
A list object containing all essential components for power calculation. This includes:
Structural components (deStruct): including the data frame, design matrices for fixed and random effects, variance-covariance matrices for random effects and residuals, etc.
Internally calculated higher-level parameters (deParam), including variance-covariance matrix of beta coefficients (vcov_beta), variance-covariance matrix of variance parameters (vcov_varpar), gradient matrices (Jac_list), etc.
See Also
mkdesign, pwr.anova, pwr.contrast
Examples
# Evaluate the power of a CRD with one treatment factor
## Create a design object
crd <- designCRD(
treatments = 4, # 4 levels of one treatment factor
replicates = 12, # 12 units per level, 48 units totally
means = c(30, 28, 33, 35), # means of the 4 levels
sigma2 = 10 # error variance
)
## power of omnibus test
pwr.anova(crd)
## power of contrast
pwr.contrast(crd, which = "trt", contrast = "pairwise") # pairwise comparisons
pwr.contrast(crd, which = "trt", contrast = "poly") # polynomial contrasts
# More examples are available in `vignette("pwr4exp")`
# and on https://an-ethz.github.io/pwr4exp/