DImodels-package {DImodels}R Documentation

Diversity-Interactions (DI) Models


The 'DImodels' package is suitable for analysing data from biodiversity and ecosystem function studies using the Diversity-Interactions (DI) modelling approach introduced by Kirwan et al. (2009) <doi:10.1890/08-1684.1>. Suitable data will contain proportions for each species and a community-level response variable, and may also include additional factors, such as blocks or treatments. The package can perform data manipulation tasks, such as computing pairwise interactions (the DI_data() function), can perform an automated model selection process (the autoDI() function) and has the flexibility to fit a wide range of user-defined DI models (the DI() function).


Introduction to Diversity-Interactions models

Diversity-Interactions (DI) models (Kirwan et al 2009) are a set of tools for analysing and interpreting data from experiments that explore the effects of species diversity on community-level responses; for example, the effect of increasing community diversity on biomass production in a grassland ecosystem. Most analyses of diversity experiments quantify community diversity in terms of species richness, the number of species present. The DI method modifies this presence/absence approach in mixed communities by taking species relative abundance in the community into account. So, instead of ignoring differences in community responses across communities with the same species but with different species relative abundances, the DI approach aims to understand and explain these differences.

What variables will a suitable dataset contain?

The DI approach assesses the effect of species diversity on a community response over a period of time. For data from a biodiversity study with S species to be suited to the DI approach, the variables that are required on each experimental unit are:

  1. A set of proportions p1, p2, ... , pS that characterise the proportions of each species at a defined starting point in time. These proportions (or relative abundances) of species in the community (pi for the ith species) range between 0 (absence) and 1 (monoculture - the only species present) and the sum of all the pi values for a community is always 1.

  2. A community-level response variable, recorded a period of time after the initial species proportions were recorded.

The dataset may also contain other variables such as a block, density or treatments.

What are Diversity-Interactions models?

A DI model typically has three components and takes the form:

y = Identities + Interactions + Structures + \epsilon

where y is a community-level response, the Identities are the effects of species identities and enter the model as individual species proportions at the beginning of the time period, the Interactions are the interactions among the species proportions, while Structures include other experimental structures such as blocks, treatments or density. In a three species system, with an experimental blocking structure, a possible DI model is:

y = \beta_1p1 + \beta_2p2 + \beta_3p3 + \delta_{12}p1p2 + \delta_{13}p1p3 + \delta_{23}p2p3 + \alpha_k + \epsilon

Where p1, p2 and p3 are the species proportions of species 1, 2 and 3 respectively, and \alpha_k is the effect of block k. The error term \epsilon is usually assumed to be normally distributed with mean 0 and constant variance (and assumed independent and identically distributed).

In a monoculture of the ith species, the expected performance of y in block k is \beta_i. In mixture, the Identities component provides the expected performance as a weighted average of monoculture responses, and the Interactions component is added to it to give the overall expected performance of the mixed community. The Interactions component addresses the question: do mixed communities perform differently from what might be expected from the weighted averaging of monoculture performances? Note that in Kirwan et al 2009 the Interactions component is referred to as the diversity effect, however, here we use the more general term "Interactions", since the interpretation of how species diversity affects the response is a combination of both the Identities and Interactions components. The community with the best overall performance may depend on both the Identities and Interactions and will rarely be the community with the largest net interactions effect. The equation above provides an example of a DI model where there is a unique interaction term for each pair of species. It is possible to test various constraints among interactions, some of which may be motivated by the context of the data (Kirwan et al 2009).

The Interactions component may also include an non-linear exponent parameter \theta on each pipj term, where a value different to one allows the importance and impact of interaction terms to be altered (Connolly et al 2013).

What can the DImodels package do?

The DI approach is a full regression method where the response of the community is characterised by the effects of diversity variables such as Identities and Interactions components, and by experimental structural variables such as blocks, density and treatments. All of these may be important determinants of response and so should be included in the analysis of community responses. The DImodels package aims to make it easier to analyse data using DI models.

Currently, the DImodels package contains three main functions: autoDI, DI and DI_data. Here we give a brief overview of each, and link to the respective help files for further information.

auto_DI: This function gives a simple overview of the successive contribution of the Structures, Identities and Interactions components to the model via an automated model selection process. It will identify the 'best' model from a (limited) subset of all possible DI models. However, autoDI may need to be supplemented by more refined analysis, for example, auto_DI does not test for interactions between the terms in the Structures and Identities components. It can also only facilitate one block, one density and one treatment variable. However, it is a very useful starting point for DI model exploration. Further information at: autoDI.

DI: This function can fit a wide range of DI models and includes the flexibility to test for multiple treatments or additional interactions, for example, between terms in the Identities and Structures components. The DI function fits one user-defined DI model at a time, and it allows for flexibility in the form of the model through a combination of in-built argument options and additional user-defined options. Further information at: DI.

DI_data: This function can compute various forms of interactions among the pi variables. This function is not required when using autoDI, or for the in-built argument options in DI, but may be needed when specifying additional user-defined options in DI. Further information at: DI_data and for examples of when it is required see DI.

There are three other functions:

  1. theta_CI can fit a confidence interval to the parameter theta, when it has been estimated using either autoDI or DI,

  2. DI_compare that can compare a fitted DI model to the 'reference' model (see autoDI) for details about the reference model), and

  3. update_DI that can update a fitted DI model passing different values to one or more arguments (see update_DI) for details).

Challenges with fitting and interpreting Diversity-Interactions models

Analysing data using DI methods can be tricky for people familiar with ordinary regression models and the DImodels package aims to make analysis easier. The difficulties lie in:

  1. The lack of familiarity in dealing with the Identities component variables pi, which must sum to 1. This constraint can lead to interpretative issues, and estimation problems with some widely used R software.

  2. The novelty of specifying the Interactions components in terms of many pairwise interaction terms whose numbers may greatly increase with S. The number of pairwise terms can often be reduced by identifying biologically meaningful patterns among them, for example, through functional grouping of species. This may greatly reduce the number of coefficients to be estimated and interpreted in the model (Kirwan et al, 2009).

  3. The introduction of a power coefficient theta (\theta) for all pairwise interaction terms (Connolly et al, 2013). This parameter can be very useful in describing the effect of community evenness on community response, i.e., whether response changes rapidly or slowly across communities where the relative abundance of species changes from being equal for all species to dominance by one or more species.

Limitations of the DImodels package

Currently, the DImodels package does not support multivariate responses or repeated measurements on the same experimental unit. It also does not currently support the random effects approach to modelling pairwise interactions that was developed by Brophy et al 2017.


Rafael de Andrade Moral [aut, cre], John Connolly [aut], Rishabh Vishwakarma [ctb], Caroline Brophy [aut]

Maintainer: Rafael de Andrade Moral <rafael.deandrademoral@mu.ie>


Brophy C, A Dooley, L Kirwan, JA Finn, J McDonnell, T Bell, MW Cadotte and J Connolly. (2017) Biodiversity and ecosystem function: Making sense of numerous species interactions in multi-species communities. Ecology 98, 1771-1778.

Connolly J, T Bell, T Bolger, C Brophy, T Carnus, JA Finn, L Kirwan, F Isbell, J Levine, A Lüscher, V Picasso, C Roscher, MT Sebastia, M Suter and A Weigelt (2013) An improved model to predict the effects of changing biodiversity levels on ecosystem function. Journal of Ecology, 101, 344-355.

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

autoDI DI DI_data theta_CI

Example datasets: The Bell dataset. The sim1 dataset. The sim2 dataset. The sim3 dataset. The sim4 dataset. The sim5 dataset. The Switzerland dataset.


## Load the Switzerland data
## Check that the proportions sum to 1 (required for DI models)
## p1 to p4 are in the 4th to 7th columns in Switzerland
  Switzerlandsums <- rowSums(Switzerland[4:7])
## Example of autoDI
  auto1 <- autoDI(y = "yield", density = "density", prop = c("p1","p2","p3","p4"), 
                  treat = "nitrogen", FG = c("G","G","L","L"), data = Switzerland, 
                  selection = "Ftest")
## Example of DI
  m1 <- DI(y = "yield", density = "density", prop = 4:7, treat = "nitrogen", 
           FG = c("G","G","L","L"), DImodel = "FG", data = Switzerland)
## Example of DI_data.
## Create interaction variables and incorporate them into a new data frame Switzerland2.
## Switzerland2 will contain the new variables:  AV, E, p1_add, p2_add, p3_add, p4_add, 
##  bfg_G_L, wfg_G, wfg_L.
  FG_matrix <- DI_data(prop = c("p1","p2","p3","p4"), FG = c("G","G","L","L"),  
                       data = Switzerland, what = "FG")
  Switzerland2 <- data.frame(Switzerland, FG_matrix)

[Package DImodels version 1.3 Index]