DI_data_manipulation: Data manipulation function
In DImodels: Diversity-Interactions (DI) Models

DI_data_manipulation

R Documentation

Data manipulation function

Description

This function can be used to compute additional variables for the various types of interactions among pairs of species proportions. These variables are defined following Kirwan et al 2007 and 2009, and Connolly et al 2013.

The variables are denoted:

AV and E: the average pairwise interaction variable (AV) and a scaled version of it (E), each a single variable. The variable AV is the sum of products of the proportions of each pair of species in the mixture. The variable E is a scaled version of AV that ranges between 0 (for a monoculture community) to 1 for the equi-proportional mixture of all species in the pool.

FG: the functional group interaction variables. There is a variable for (within) each functional group and one for (between) each pair of functional groups, i.e., if there are two functional groups, there will be three functional group interaction variables, while if there are three functional groups, there will be six functional group interaction variables.

ADD: the additive species interaction variables, one for each species.

FULL: all individual pairwise interactions. There will be s*(s-1)/2 new variables created, where s is the number of species in the pool.

By default, the interaction variables described above are created with theta = 1, but a different value of theta can also be specified (Connolly et al 2013).

Usage

DI_data(prop, FG, data, theta = 1, what = c("E","AV","FG","ADD","FULL"))

Arguments

`prop`	A vector of column names identifying the species proportions in the dataset. For example, if the species proportions columns are labelled p1 to p4, then `prop = c("p1","p2","p3","p4")`. The column numbers in which the proportions are stored can also be referred to, for example, `prop = 4:7` for the `Switzerland` data.
`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, it could be `FG = c("G","G","L","L")`, where G stands for grass and L stands for legume. This argument is required when `"FG"` is included in the `what` argument.
`data`	Specify the dataset, for example, `data = Switzerland`. The dataset name should not appear in quotes.
`theta`	Interaction variables will be computed with the theta power, equal to the value specified, on all `pipj` components of each interaction variable, with default value one. For example, with three species `AV = p1p2 + p1p3 + p2p3` and if computed with `theta` = 0.5, this becomes `(p1p2)^0.5 + (p1p3)^0.5 + (p2*p3)^0.5`.
`what`	The interactions to be computed. By default each set of variables will be computed: AV, E, FG (if `FG` argument specified), ADD and FULL. Individual sets can be selected. For example, `what = c("FULL")` or `what = c("AV", "FULL")`.

Details

What are 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. 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 the DI_data function.

Before using the DI_data function, check that the species proportions in each row of 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.

When is the DI_data function needed?

It is not required to use the DI_data function if using the autoDI function, or the DImodel option in the DI function, as they will automatically create the species interaction variables needed. If using species interaction variables in the extra_formula or custom_formula options in DI, then it is required to have the variables already in the dataset and DI_data can do that.

Short worked example to illustrate how the DI_data function works

The code to implement this example is provided in the 'Examples' section.

Assume four species with initial proportions in two communities: (0.1, 0.2, 0.3, 0.4) and (0.25, 0.25, 0.25, 0.25), with FG = c("G","G","L","L").

For community 1: (0.1,0.2,0.3,0.4), assuming theta = 1, the data preparation functions will compute the following additional variables (details in Kirwan et al 2007 and 2009):

AV = 0.1*0.2 + 0.1*0.3 + 0.1*0.4 + 0.2*0.3 + 0.2*0.4 + 0.3*0.4 = 0.35

E = (2s/(s-1))*AV = 0.9333

p1_add = 0.1 * (1 - 0.1) = 0.09

p2_add = 0.2 * (1 - 0.2) = 0.16

p3_add = 0.3 * (1 - 0.3) = 0.21

p4_add = 0.4 * (1 - 0.4) = 0.24

bfg_G_L = 0.1*0.3 + 0.1*0.4 + 0.2*0.3 + 0.2*0.4 = 0.21

wfg_G = 0.1*0.2 = 0.02

wfg_L = 0.3*0.4 = 0.12

For community 1: (0.1,0.2,0.3,0.4), assuming theta = 0.5, the data preparation functions will compute the follow additional variables (details in Connolly et al 2013):

AV = (0.1*0.2)^0.5 + (0.1*0.3)^0.5 + (0.1*0.4)^0.5 + (0.2*0.3)^0.5 + (0.2*0.4)^0.5 + (0.3*0.4)^0.5 = 1.3888

E =(2s/(s-1))*AV = 3.7035

p1_add = 0.1^0.5 * (0.2^0.5 + 0.3^0.5 + 0.4^0.5) = 0.5146

p2_add = 0.2^0.5 * (0.1^0.5 + 0.3^0.5 + 0.4^0.5) = 0.6692

p3_add = 0.3^0.5 * (0.1^0.5 + 0.2^0.5 + 0.4^0.5) = 0.7646

p4_add = 0.4^0.5 * (0.1^0.5 + 0.2^0.5 + 0.3^0.5) = 0.8293

bfg_G_L = (0.1*0.3)^0.5 + (0.1*0.4)^0.5 + (0.2*0.3)^0.5 + (0.2*0.4)^0.5 = 0.9010

wfg_G = (0.1*0.2)^0.5 = 0.1414

wfg_L = (0.3*0.4)^0.5 = 0.3464

When using the DI_data function to create interactions for theta values for a value different from 1, it is recommended to rename the new interaction variables to include _theta.

The data manipulation values for community 2 (0.25, 0.25, 0.25,0.25) can be seen when the 'Examples' section code is run.

Value

DI_data returns a named list with one or more the following components (depending on the specification of the what argument:

`E`	a numeric vector containing the evenness interaction variable
`AV`	a numeric vector containing the average pairwise interaction variable
`FG`	a matrix containing the functional group-related interaction variables
`ADD`	a matrix containing the additive species contributions interaction variables
`FULL`	a matrix containing all pairwise interactions

Author(s)

Rafael A. Moral, John Connolly and Caroline Brophy

References

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, A Lüscher, MT Sebastia, JA Finn, RP Collins, C Porqueddu, A Helgadottir, OH Baadshaug, C Brophy, C Coran, S Dalmannsdottir, I Delgado, A Elgersma, M Fothergill, BE Frankow-Lindberg, P Golinski, P Grieu, AM Gustavsson, M Höglind, O Huguenin-Elie, C Iliadis, M Jørgensen, Z Kadziuliene, T Karyotis, T Lunnan, M Malengier, S Maltoni, V Meyer, D Nyfeler, P Nykanen-Kurki, J Parente, HJ Smit, U Thumm, & J Connolly (2007) Evenness drives consistent diversity effects in intensive grassland systems across 28 European sites. Journal of Ecology, 95, 530-539.

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.

Examples

################################
  
#### Data manipulation for the Switzerland dataset
  
## 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)
  
  
## Create FG interaction variables and incorporate them into a new data frame Switzerland2.
## Switzerland2 will contain the new variables:  bfg_G_L, wfg_G and 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)
  
  
## Create FG interaction variables and incorporate them into a new data frame Switzerland3.
## Use theta = 0.5.
  FG_matrix <- DI_data(prop = c("p1","p2","p3","p4"), FG = c("G","G","L","L"), 
                       data = Switzerland, what = "FG", theta = 0.5)
  Switzerland3 <- data.frame(Switzerland, FG_matrix)
## Add "_theta" to the new interaction variables to differentiate from when theta = 1
  names(Switzerland3)[9:11] <- paste0(names(Switzerland3)[9:11], "_theta") 


#### All interactions can be added to a new dataset all together:

## Create all interactions and add them to a new data frame called Switzerland4
  newlist <- DI_data(prop = c("p1","p2","p3","p4"), FG = c("G","G","L","L"), data = Switzerland, 
                     what = c("E", "AV", "FG", "ADD", "FULL"))
  Switzerland4 <- data.frame(Switzerland, "E" = newlist$E, "AV" = newlist$AV, newlist$FG, 
                             newlist$ADD, newlist$FULL)

  
#### Or the various interactions can also be added to a new dataset individually:
  
## Create the average pairwise interaction and evenness variables
##  and store them in a new data frame called Switzerland5.
## Switzerland5 will contain the new variables: AV, E
  E_variable <- DI_data(prop = c("p1","p2","p3","p4"), data = Switzerland, what = "E")
  AV_variable <- DI_data(prop = c("p1","p2","p3","p4"), data = Switzerland, what = "AV")
  Switzerland5 <- data.frame(Switzerland, "AV" = AV_variable, "E" = E_variable)
  
## Create the functional group variables and add them to Switzerland5.
## In the FG names vector: G stands for grass, L stands for legume.
## Switzerland5 will contain: bfg_G_L, wfg_G and wfg_L
  FG_matrix <- DI_data(prop = 4:7, FG = c("G","G","L","L"), data = Switzerland, what = "FG")
  Switzerland5 <- data.frame(Switzerland5, FG_matrix)
  
## Create the additive species variables and add them to Switzerland5.
## Switzerland5 will contain the new variables: p1_add, p2_add, p3_add and p4_add.
  ADD_matrix <- DI_data(prop = c("p1","p2","p3","p4"), data = Switzerland, what = "ADD")
  Switzerland5 <- data.frame(Switzerland5, ADD_matrix)
  
## Create all pairwise interaction variables and add them to Switzerland5.
## Switzerland5 will contain the new variables: p1.p2, p1.p3, p1.p4, p2.p3, p2.p4, p3.p4.
  FULL_matrix <- DI_data(prop = c("p1","p2","p3","p4"), data = Switzerland, what = "FULL")
  Switzerland5 <- data.frame(Switzerland5, FULL_matrix)
  
################################
  

################################ 
  
#### Short worked example (as illustrated the Details section)
  
## Create a dataframe
  p1 <- c(0.1, 0.25)
  p2 <- c(0.2, 0.25)
  p3 <- c(0.3, 0.25)
  p4 <- c(0.4, 0.25)
  minidataset1 <- data.frame(p1,p2,p3,p4)
  
## Check the rows sum to 1
  rowSums(minidataset1[1:4]) 
  
## Create the FG variables, assume two functional groups and theta = 1
  FG_matrix <- DI_data(prop = c("p1","p2","p3","p4"), FG = c("G","G","L","L"),
                       data = minidataset1, what = "FG")
  minidataset2 <- data.frame(minidataset1, FG_matrix)
  
## Create the FG variables, assume two functional groups and theta = 0.5
  FG_matrix <- DI_data(prop = c("p1","p2","p3","p4"), FG = c("G","G","L","L"), 
                       data = minidataset1, what = "FG", theta = 0.5)
  minidataset3 <- data.frame(minidataset1, FG_matrix)
## Create the ADD variables, assume theta = 0.5
  ADD_matrix <- DI_data(prop = c("p1","p2","p3","p4"), 
                        data = minidataset1, what = "ADD", theta = 0.5)
  minidataset3 <- data.frame(minidataset3, ADD_matrix)
## Add "_theta" to the new interaction variables to differentiate from when theta = 1
  names(minidataset3)[5:11] <- paste0(names(minidataset3)[5:11], "_theta")   

  
################################

DImodels documentation built on May 29, 2024, 7:05 a.m.