RRPP (version 0.6.1)

pairwise: Pairwise comparisons of lm.rrpp fits

Description

Function generates distributions of pairwise statistics for a lm.rrpp fit and returns important statistics for hypothesis tests.

Usage

pairwise(
  fit,
  fit.null = NULL,
  groups,
  covariate = NULL,
  print.progress = FALSE
)

Arguments

fit

A linear model fit using lm.rrpp.

fit.null

An alternative linear model fit to use as a null model for RRPP, if the null model of the fit is not desired. Note, for FRPP this argument should remain NULL and FRPP must be established in the lm.rrpp fit (RRPP = FALSE). If the null model is uncertain, using reveal.model.designs will help elucidate the inherent null model used.

groups

A factor or vector that is coercible into a factor, describing the levels of the groups for which to find LS means or slopes. Normally this factor would be part of the model fit, but it is not necessary for that to be the case in order to obtain results.

covariate

A numeric vector for which to calculate slopes for comparison If NULL, LS means will be calculated instead of slopes. Normally this variable would be part of the model fit, but it is not necessary for that to be the case in order to obtain results.

print.progress

If a null model fit is provided, a logical value to indicate whether analytical results progress should be printed on screen. Unless large data sets are analyzed, this argument is probably not helpful.

Value

An object of class pairwise is a list containing the following

LS.means

LS means for groups, across permutations.

slopes

Slopes for groups, across permutations.

means.dist

Pairwise distances between means, across permutations.

means.vec.cor

Pairwise vector correlations between means, across permutations.

slopes.lengths

Slope lengths, by group, across permutations.

slopes.dist

Pairwise distances between slope lengths, across permutations.

slopes.vec.cor

Pairwise vector correlations between slope vectors, across permutations.

n

Sample size

p

Data dimensions; i.e., variable number

PermInfo

Information for random permutations, passed on from lm.rrpp fit and possibly modified if an alternative null model was used.

Details

Based on an lm.rrpp fit, this function will find fitted values over all permutations and based on a grouping factor, calculate either least squares (LS) means or slopes, and pairwise statistics among them. Pairwise statistics have two flavors: distances and vector correlations (or angles). The distance statistics calculate either the length of vectors between LS mean vectors or the absolute difference between slope vector lengths. The vector correlations are the inner product of vectors that have been transformed to unit length. The arccosine (acos) of this value is the angle between vectors, which can be expressed in radians or degrees, and is used as a test statistic (with the null hypothesis that vectors are parallel; angle = 0). Over all permutations, these values can be calculated to generate random distributions using the null model. The null model is defined via lm.rrpp, but one can also use an alternative null model as an optional argument. In this case, residual randomization in the permutation procedure (RRPP) will be performed using the alternative null model to generate fitted values. If full randomization of values (FRPP) is preferred, it must be established in the lm.rrpp fit and an alternative model should not be chosen.

Observed statistics, effect sizes, P-values, and one-tailed confidence limits based on the confidence requested will be summarized with the summary.pairwise function. The summary.pairwise function will allow one to select between distance or vector correlation tests, whether angles are measured in radians or degrees, and the level of confidence for the test. Confidence limits are inherently one-tailed as the statistics are similar to absolute values. For example, a distance is analogous to an absolute difference. Therefore, the one-tailed confidence limits are more akin to two-tailed hypothesis tests. (A comparable example is to use the absolute value of a t-statistic, in which case the distribution has a lower bound of 0.) If rather than comparing the LS means or slopes, one wishes to compare the dispersion of residuals among groups, given the model, an option for comparing variances is also available. Variance degrees of freedom equal n, the group size, rather than n-1, as the purpose is to compare mean dispersion in the sample. (Additionally, tests with one subject in a group are possible, or at least not a hindrance to the analysis.)

If data are univariate, test.type = 'cor' should not be chosen because the vector correlation between univariate vectors is always 1. Rather, cor.type = 'dist' will return the absolute difference between slopes or between means. Please note that this function will generate results if test.type = 'cor' for univariate data, but the results will not make much sense.

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.

Adams, D.C and M.L. Collyer. 2018. Multivariate phylogenetic anova: group-clade aggregation, biological challenges, and a refined permutation procedure. Evolution. In press.

See Also

advanced.procD.lm within geomorph; lm.rrpp for model fits

Examples

# NOT RUN {
# Examples use geometric morphometric data on pupfishes
# See the package, geomorph, for details about obtaining such data

# Body Shape Analysis (Multivariate)----------------------------------------------------

data("Pupfish")

# Note:

dim(Pupfish$coords) # highly multivariate!

Pupfish$logSize <- log(Pupfish$CS) # better to not have functions in formulas

# Note: one should use all dimensions of the data but with this example, there are many
# Thus, only three principal components will be used for demonstration purposes.

Pupfish$Y <- prcomp(Pupfish$coords)$x[, 1:3]

## Pairwise comparisons of LS means

# Note: one should increase RRPP iterations but a smaller number is used here for demonstration 
# efficiency.  Generally, iter = 999 will take less
# than 1s for these examples with a modern computer.

fit1 <- lm.rrpp(Y ~ logSize + Sex * Pop, SS.type = "I", 
data = Pupfish, print.progress = FALSE, iter = 499) 
summary(fit1, formula = FALSE)
anova(fit1) 

pup.group <- interaction(Pupfish$Sex, Pupfish$Pop)
pup.group
PW1 <- pairwise(fit1, groups = pup.group)
PW1
summary(PW1, confidence = 0.95, test.type = "dist") # distances between means
summary(PW1, confidence = 0.95, test.type = "dist", stat.table = FALSE)
summary(PW1, confidence = 0.95, test.type = "VC", 
   angle.type = "deg") # correlation between mean vectors (angles in degrees)

# Can also compare the dispersion around means

summary(PW1, confidence = 0.95, test.type = "var")

## Pairwise comparisons of slopes

fit2 <- lm.rrpp(Y ~ logSize * Sex * Pop, SS.type = "I", 
data = Pupfish, print.progress = FALSE, iter = 199) 
summary(fit2, formula = FALSE)
anova(fit1, fit2)

# Using a null fit that excludes all factor-covariate interactions, not just the last one  

PW2 <- pairwise(fit2, fit.null = fit1, groups = pup.group, 
covariate = Pupfish$logSize, print.progress = FALSE) 
PW2
summary(PW2, confidence = 0.95, test.type = "dist") # distances between slope vector lengths
summary(PW2, confidence = 0.95, test.type = "dist", stat.table = FALSE)
summary(PW2, confidence = 0.95, test.type = "VC",
   angle.type = "deg") # correlation between slope vectors (and angles)
   
# Can also compare the dispersion around group slopes

summary(PW2, confidence = 0.95, test.type = "var")

# }