compare_communities: Compare communities and assign compact letter displays (CLD)

In DImodels: Diversity-Interactions (DI) Models

Compare communities and assign compact letter displays (CLD)

Description

compare_communities performs comparisons between species and assigns each a compact letter display (CLD) using glht and multcompLetters for a model object created by the DI or autoDI functions.

Usage

compare_communities(object, data, ref = NULL, 
                    adjust = formals(multcomp::adjusted)$type, 
                    verbose = FALSE, alpha.level = 0.05,
                    Letters = c(letters, LETTERS, "."),
                    ...)

Arguments

object	A model output which is the output of DI or autoDI.
data	A data.frame containing the proportions for the species communities which are to be compared. Any additional variables such as specific values for a treatment variable can also be specified.
ref	An optional argument specifying a particular to be considered a reference. If specified, all comparisons would be made with respect to this community, as opposed to pairwise comparisons.
adjust	A character string specifying the p-value adjustment method to be used to account for multiple comparisons. All arguments supported by the adjusted are supported. The default is "single-step" adjustment.
verbose	A boolean (TRUE/FALSE) value indicating whether to print the internally generated contrast matrix. Default is TRUE
alpha.level	A value between 0 and 1, specifying the singificance level for the comparisons. Defaults to 0.05.
Letters	The characters to be assigned to the communities to indicate significant differences. Defaults to lowercase latin characters (i.e., a, b, c, etc.).
...	Additional arguments passed to the glht, adjusted, or multcompLetters functions

Details

The contrasts are calculated and tested using the glht function in the multcomp package while the cld letters are assigned using the multcompLetters function from multcompView. The rownames of the specified data.frame are used to identify the communities and are labelled 1, 2, ..., n, etc. by default, but this can be changed by updating the rownames of the specified data.frame.

Note: If any variables needed for making predictions are missing in 'data', the would be assumed to be at their median value (if numeric) or base level (if categorical). Specify the values for all variables manually to perform comparisons at a specific level of any categorical variable (treatment for example).

Value

An list containing the following objects is returned.

Contrasts	An object of class summary.glht containing the summary of the specific comparisons performed internally for assigning the compact display letters.
CLD	An object of class multcompLetters with compact letters assigned to each species community based on the p-values shown in the 'Contrasts' object.

Author(s)

Rafael A. Moral, John Connolly, Rishabh Vishwakarma and Caroline Brophy

References

Piepho, Hans-Peter (2004) "An Algorithm for a Letter-Based Representation of All-Pairwise Comparisons", Journal of Computational and Graphical Statistics, 13(2)456-466.

Torsten Hothorn, Frank Bretz and Peter Westfall (2008). Simultaneous Inference in General Parametric Models. Biometrical Journal 50(3), 346–363.

Frank Bretz, Torsten Hothorn and Peter Westfall (2010), Multiple Comparisons Using R, CRC Press, Boca Raton.

Jason C. Hsu (1996), Multiple Comparisons. Chapman & Hall, London.

Kirwan L, J Connolly, JA Finn, C Brophy, A Lüscher, D Nyfeler and MT Sebastia (2009) Diversity-interaction modelling - estimating contributions of species identities and interactions to ecosystem function. Ecology, 90, 2032-2038.

See Also

DI autoDI contrasts_DI glht adjusted multcompLetters

Examples

## Load the Switzerland data
  data(Switzerland)
## Summarise the Switzerland data
  summary(Switzerland)

## Fit a DI model
  m1 <- DI(y = "yield", prop = 4:7, treat = 'nitrogen', DImodel = 'AV',
  density = 'density', estimate_theta = FALSE, data = Switzerland)
  summary(m1)
  
## Basic comparison of the first five observations in the Switzeraland data
  head(Switzerland, 5)
  compare_communities(m1, data = Switzerland[1:5, ])

## The pairiwise comparisons between each community as well as the cld letters are returned.

## By default, single-step p-value adjustments are performed to account for multiple comparisons. 
## This can be changed using adjust argument. For example, "none" would perform no adjustment
  compare_communities(m1, data = Switzerland[1:5, ],
                      adjust = "none")

## Bonferroni adjustment
  compare_communities(m1, data = Switzerland[1:5, ],
                      adjust = "bonferroni")
                      
## If any variable needed for predictions is missing in the data, 
## a warning will be thrown and sensible values will be used.   
## In this example, we only specify the species proportions and nothing for nitrogen and density
  compare_communities(m1, data = Switzerland[1:5, 4:7],
                      adjust = "bonferroni")
                      
## The alpha.level and symbols to be used for cld can be changed as follows
  compare_communities(m1, data = Switzerland[1:5, ], 
                      adjust = "none", alpha.level = 0.01,
                      Letters = LETTERS)

## Change row.names of data to get informative labels for the tests
  comp_data <- Switzerland[1:5, ]
  rownames(comp_data) <- c("p1_dom", "p2_dom", "p3_dom", "p4_dom", "Centroid")
  
  compare_communities(m1, data = comp_data, 
                      adjust = "none", alpha.level = 0.01,
                      Letters = LETTERS)

## Comparisons can also be performed against a specific community as reference 
## using the `ref` argument. Using "Centroid" as ref in this example, 
## can also be specified using the row number, i.e., 5
  compare_communities(m1, data = comp_data, ref = 5,    
                      adjust = "none", 
                      Letters = LETTERS)

DImodels documentation built on Aug. 21, 2025, 5:53 p.m.