DImodelspackage {DImodels}  R Documentation 
DiversityInteractions (DI) Models
Description
The 'DImodels' package is suitable for analysing data from biodiversity and ecosystem function studies using the DiversityInteractions (DI) modelling approach introduced by Kirwan et al. (2009) <doi:10.1890/081684.1>. Suitable data will contain proportions for each species and a communitylevel 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 userdefined DI models (the DI() function).
Details
Introduction to DiversityInteractions models
DiversityInteractions (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 communitylevel 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:
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 thepi
values for a community is always 1.A communitylevel 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 DiversityInteractions models?
A DI model typically has three components and takes the form:
y = Identities + Interactions + Structures + \epsilon
where y is a communitylevel 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 nonlinear 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 userdefined DI model at a time, and it allows for flexibility in the form of the model through a combination of inbuilt argument options and additional userdefined 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 inbuilt argument options in DI
, but may be needed when specifying additional userdefined options in DI
. Further information at: DI_data
and for examples of when it is required see DI
.
There are three other functions:

theta_CI
can fit a confidence interval to the parameter theta, when it has been estimated using eitherautoDI
orDI
, 
DI_compare
that can compare a fitted DI model to the 'reference' model (seeautoDI
) for details about the reference model), and 
update_DI
that can update a fitted DI model passing different values to one or more arguments (seeupdate_DI
) for details).
Challenges with fitting and interpreting DiversityInteractions 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:
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.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).
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.
Author(s)
Rafael de Andrade Moral [aut, cre], John Connolly [aut], Rishabh Vishwakarma [ctb], Caroline Brophy [aut]
Maintainer: Rafael de Andrade Moral <rafael.deandrademoral@mu.ie>
References
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 multispecies communities. Ecology 98, 17711778.
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, 344355.
Kirwan L, J Connolly, JA Finn, C Brophy, A Lüscher, D Nyfeler and MT Sebastia (2009) Diversityinteraction modelling  estimating contributions of species identities and interactions to ecosystem function. Ecology, 90, 20322038.
See Also
Example datasets:
The Bell
dataset.
The sim1
dataset.
The sim2
dataset.
The sim3
dataset.
The sim4
dataset.
The sim5
dataset.
The Switzerland
dataset.
Examples
## Load the Switzerland data
data(Switzerland)
## 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])
summary(Switzerlandsums)
## 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")
summary(auto1)
## Example of DI
m1 < DI(y = "yield", density = "density", prop = 4:7, treat = "nitrogen",
FG = c("G","G","L","L"), DImodel = "FG", data = Switzerland)
summary(m1)
## 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)