nested.update: Update procD.lm objects with nested effects

Description

This function is used to update procD.lm objects for fixed effects with nested random effects (nested design)

Usage

nested.update(P, f1)

Arguments

A procD.lm object

A right-hand or full formula for one factor nested within another; e.g., ~ A/B or ~B + A/B

Details

This functions serves as a helper function when linear models have nested (hierarchical) structure. It is used on procD.lm objects that were formerly evaluated with type I sums of squares (SS), as is typical with models with only fixed effects. Using a formula for nested effects, this function identifies the fixed and random SS in the random outcomes used to generate the procD.lm object, and updates the F-values, Z-scores, and P-values based on F values adjusted to be MS fixed/MS random (nested). This is accomplished by generating random values for each iteration previously used in the procD.lm object.

This function can be used recursively for multiple updates, when multiple nested effects are used. The function can currently only handle single factors nested within other single factors.

Function returns the same list as procD.lm but with new random F values and Cohen's f-squared values substituted The ANOVA table is updated in terms of F-values, Z-scores, and P-values. Z-scores are re-calculated for all effects to be consistent with the type of distribution used. If either Cohen's f-squared values or F values were originally chosen, the same distributions are used in the update; if SS values were originally chosen, the distribution is changed to Cohen's f-squared to calculate Z-scores. This change assures consistency in effect size estimation, as the effectthat is updated cannot have an effect size based on SS.

It is important that the formula is input correctly. It can be input as one of the following four styles:

~ fixed/random

~ fixed + fixed/random

The two formulae above achieve the same model terms for the expanded model: ~ fixed + fixed:random

~ random + fixed/random

~ random + fixed + fixed/random

The two formulae above achieve the same model terms for the expanded model: ~ random + fixed + random:fixed

The procD.lm object will be updated in the same way with either of the approaches. First, the F-value for the fixed term will be adjusted as MS-fixed/MS-interaction for every random permutation. Second, the P-value for the fixed effect will be estimated from this new distribution of F-values. Although the function will try to catch improper formulae and alert the user, it is possible the function will work with an improper formula. Thus, adherence to one of the formulae above is recommended for best results.

Effect sizes (Z scores) are based on either the distribution of random F values or a distribution of Cohen's f-squared values, calculated in every pemutation. An attempt will be made to preserve the effect size type used in the previous procD.lm or procD.pgls analysis. However, an analysis performed in procD.lm using effect size calculated from random SS values will be updated to use random Cohen's f-squared values for all effects, to avoid having effect sizes measured from different distributions in the same analysis.

References

Collyer, M.L., D.J. Sekora, and D.C. Adams. 2015. A method for analysis of phenotypic change for phenotypes described by high-dimensional data. Heredity. 115:357-365.

Examples

Run this code

# NOT RUN {
data(larvalTails)
Y.gpa <- gpagen(larvalTails$landmarks)
gdf <- geomorph.data.frame(Y.gpa, Treatment = larvalTails$Treatment, Family = larvalTails$Family)

# Model with fixed and nested effects
tailANOVA <- procD.lm(coords ~ Treatment/Family, iter=99, RRPP=TRUE, data=gdf)
summary(tailANOVA)

# Update for nested effects
tailANOVA <- nested.update(tailANOVA, ~ Treatment/Family)
summary(tailANOVA)

# Model with random, fixed, and nested effects
tailANOVA <- procD.lm(coords ~ Family + Treatment/Family, iter=99, RRPP=TRUE, data=gdf)
summary(tailANOVA)

# Update for nested effects
tailANOVA <- nested.update(tailANOVA, ~ Family + Treatment/Family)
summary(tailANOVA)

# One needs to be careful using this function!

tailANOVA <- procD.lm(coords ~ Csize * Treatment/Family, iter=99, RRPP=TRUE, data=gdf)

# This will not work: tailANOVA <- nested.update(tailANOVA, ~ Treatment/Family) 
# The updated terms must be included as part of the original terms

tailANOVA <- procD.lm(coords ~ Csize + Treatment/Family, iter=99, RRPP=TRUE, data=gdf)
summary(tailANOVA)

# Now the format will allow an update

tailANOVA <- nested.update(tailANOVA, ~ Treatment/Family) 

summary(tailANOVA)
# }