DI {DImodels}  R Documentation 
This function will fit a wide range of DiversityInteractions (DI) models, one at a time. It provides some assisted automated ways to fit DI models, and includes the flexibility to extend DI models in several directions.
DI(y, block, density, prop, treat, FG, DImodel, extra_formula, custom_formula,
data, estimate_theta = FALSE)
The minimum required arguments to use DI are either:
Argument DImodel
with data
, y
and prop
, or
Argument custom_formula
with data
.
The DImodel
argument allows fitting of DI models via a range of 'tag' options that determine the form of the species interactions terms (the tags, described below, are STR
, ID
, AV
, FG
, ADD
and FULL
) and extra terms can be added to the model using the extra_formula
argument. Using the argument custom_formula
requires full specification of the model to be fitted using standard lm
or glm
syntax.
y 
The column name of the response vector, which must be in quotes, for example, 
block 
The name of the block variable (if present), which must be in quotes, for example, 
density 
The name of the density variable (if present), which must be in quotes, for example, 
prop 
A vector of s column names identifying the species proportions in each community in the dataset. For example, if the species proportions columns are labelled p1 to p4, then 
treat 
The name of a column in the dataset containing the value of a treatment factor or covariate. The treatment name must be included in quotes, for example,

FG 
If species are classified by g functional groups, this argument takes a text list (of length s) of the functional group to which each species belongs. For example, for four grassland species with two grasses and two legumes: FG could be

DImodel 
This argument is chosen (over
Each of the following includes the species proportions as specified in
The DImodel tag should appear in quotes, for example, 
extra_formula 
In conjunction with 
custom_formula 
To specify your own DI model, write your own model formula using the 
data 
Specify the dataset, for example, 
estimate_theta 
By default, theta (the power parameter on all 
What are 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. We recommend that users of the DImodels
package read the short introduction to DI models (available at: DImodels
). Further information on DI models is available in Kirwan et al 2009 and Connolly et al 2013.
Checks on data prior to using DI
.
Before using DI
, check that the species proportions for each row in your dataset sum to one. See the 'Examples' section for code to do this. An error message will be generated if the proportions don't sum to one.
How does the DI
function work?
The DI
function provides wide flexibility in the types of DiversityInteractions (DI) models that can be fitted. There are two ways to fit models in DI
: 1) using DImodel
, possibly augmented by extra_formula
, or 2) using custom_formula
. Models are estimated using iteratively reweighted least squares, via the glm
package, when the option estimate_theta = FALSE
.
Consider the following DI model, for example (in R formula syntax):
y ~ p1 + p2 + p3 + treatment + p1:p2 + p1:p3 + p2:p3 + p1:p2:treatment + p1:p3:treatment + p2:p3:treatment
This model can be fitted using DImodel
and extra_formula
:
DI(y = "y", prop = c("p1", "p2", "p3"), treat = "nitrogen", DImodel = "FULL", extra_formula = ~ p1:p2:treatment + p1:p3:treatment + p2:p3:treatment, data = datasetname)
or, by specifying all of the terms in the model using custom_formula
:
DI(custom_formula = y ~ p1 + p2 + p3 + treatment + p1:p2 + p1:p3 + p2:p3 + p1:p2:treatment + p1:p3:treatment + p2:p3:treatment, data = datasetname)
We recommend to use DImodel
where possible, to augment with extra_formula
where required, and to only use custom_formula
when DImodel
plus extra_formula
is insufficient.
Including theta in DI models
A nonlinear parameter \theta
can be included in DI models as a power on all pi*pj
components of each pairwise interaction variable. For example (in R formula syntax):
y ~ p1 + p2 + p3 + (p1:p2)^theta + (p1:p3)^theta + (p2:p3)^theta
for the full pairwise interaction model. Including \theta
alters the contribution of the interaction term to the response (Connolly et al 2013).
By default, the value of \theta
is 1. By specifying estimate_theta = TRUE
within DI
, a value of \theta
will be estimated using profile likelihood over the space \theta
= 0.01 to 1.5. The option estimate_theta = TRUE
can only be used with DImodel
, it is not available when using custom_formula
.
As a general guideline to testing if \theta
is required, we recommend:
1) finding the best form of the species interaction terms assuming theta = 1, and then,
2) testing if theta differs from 1.
If no species interaction terms are needed, then there is no need to do any testing for theta.
A model object of class "glm"
including the components detailed in glm
, plus the following:
DIcall 
the call of the 
DIinternalcall 
an internal call made within the DI model fitting process 
Rafael A. Moral, John Connolly and Caroline Brophy
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.
Other examples using DI
:
The Bell
dataset examples.
The sim1
dataset examples.
The sim2
dataset examples.
The sim3
dataset examples.
The sim4
dataset examples.
The sim5
dataset examples.
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)
## Fit the FG DImodel, with factors density and treatment, and with theta = 1
m1 < DI(y = "yield", density = "density", prop = 4:7, treat = "nitrogen",
FG = c("G","G","L","L"), DImodel = "FG", data = Switzerland)
summary(m1)
## Fit the FG DImodel, with factors density and treatment, and theta estimated
m2 < DI(y = "yield", density = "density", prop = 4:7, treat = "nitrogen",
FG = c("G","G","L","L"), DImodel = "FG", data = Switzerland, estimate_theta = TRUE)
summary(m2)
## Test if the identity effects interact with nitrogen (and main effect of nitrogen excluded)
m3 < DI(y = "yield", density = "density", prop = 4:7, FG = c("G", "G", "L", "L"), DImodel = "FG",
extra_formula = ~ (p1 + p2 + p3 + p4):nitrogen, data = Switzerland)
summary(m3)
## Fit the average pairwise model and check for a quadratic term using extra_formula.
## Need to create AV variable to be included in extra_formula and put in new dataset Switzerland2.
AV_variable < DI_data(prop = c("p1","p2","p3","p4"), data = Switzerland, what = "AV")
Switzerland2 < data.frame(Switzerland, "AV" = AV_variable)
m4 < DI(y = "yield", density = "density", prop = 4:7, DImodel = "AV",
extra_formula = ~ I(AV**2), data = Switzerland2)
summary(m4)
## Using the custom_formula option to fit some, but not all, of the FG interactions.
## Fit the FG DImodel using custom_formula, with factors density and treatment, and theta = 1.
## Need to create functional group interaction variables for inclusion in custom_formulaand put
## in new dataset Switzerland3.
FG_matrix < DI_data(prop = 4:7, FG = c("G","G","L","L"), data = Switzerland, what = "FG")
Switzerland3 < data.frame(Switzerland, FG_matrix)
m5 < DI(y = "yield", prop = c("p1","p2","p3","p4"),
custom_formula = yield ~ 0 + p1 + p2 + p3 + p4 + bfg_G_L + wfg_G
+ density + nitrogen,
data = Switzerland3)
summary(m5)