varpart {vegan} | R Documentation

## Partition the Variation of Community Matrix by 2, 3, or 4 Explanatory Matrices

### Description

The function partitions the variation of response table Y with respect to two, three, or four explanatory tables, using redundancy analysis ordination (RDA). If Y contains a single vector, partitioning is by partial regression. Collinear variables in the explanatory tables do NOT have to be removed prior to partitioning.

### Usage

    varpart(Y, X, ..., data, transfo, scale = FALSE)
    showvarparts(parts, labels, ...)
    ## S3 method for class 'varpart234':
    plot(x, cutoff = 0, digits = 1, ...)

### Arguments

`Y` | Data frame or matrix containing the response data table. In community ecology, that table is often a site-by-species table.
`X` | Two to four explanatory models, variables or tables. These can be defined in three alternative ways: (1) one-sided model formulae beginning with `~` and then defining the model, (2) name of a single numeric variable, or (3) name of data frame or matrix with numeric variables. The model formulae can have factors, interaction terms and transformations of variables. The names of the variables in the model formula are found in data frame given in `data` argument, and if not found there, in the user environment. Single numeric variables, data frames or matrices are found in the user environment. All entries till the next argument (`data` or `transfo`) are interpreted as explanatory models, and the names of these arguments cannot be abbreviated nor omitted.
`data` | The data frame with the variables used in the formulae in `X`.
`transfo` | Transformation for `Y` (community data) using `decostand`. All alternatives in `decostand` can be used, and those preserving Euclidean metric include `"hellinger"`, `"chi.square"`, `"total"`, `"norm"`.
`scale` | Should the columns of `Y` be standardized to unit variance
`parts` | Number of explanatory tables (circles) displayed.
`labels` | Labels used for displayed fractions. Default is to use the same letters as in the printed output.
`x` | The `varpart` result.
`cutoff` | The values below `cutoff` will not be displayed.
`digits` | The number of significant digits; the number of decimal places is at least one higher.
`...` | Other parameters passed to functions.

### Details

The functions partition the variation in `Y` into components accounted for by two to four explanatory tables and their combined effects. If `Y` is a multicolumn data frame or matrix, the partitioning is based on redundancy analysis (RDA, see `rda`), and if `Y` is a single variable, the partitioning is based on linear regression. A simplified, fast version of RDA is used (function `simpleRDA2`). The actual calculations are done in fucntions `varpart2` to `varpart4`, but these are not intended to be called directly by the user.

The function primarily uses adjusted R squares to assess the partitions explained by the explanatory tables and their combinations, because this is the only unbiased method (Peres-Neto et al., submitted). The raw R squares for basic fractions are also displayed, but these are biased estimates of variation explained by the explanatory table.

The identifiable fractions are designated by lower case alphabets. The meaning of the symbols can be found in the separate document "partionining.pdf" (which can be read using `vegandocs`), or can be displayed graphically using function `showvarparts`.

A fraction is testable if it can be directly expressed as an RDA model. In these cases the printed output also displays the corresponding RDA model using notation where explanatory tables after `|` are conditions (partialled out; see `rda` for details). Although single fractions can be testable, this does not mean that all fractions simultaneously can be tested, since there number of testable fractions is higher than the number of estimated models.

An abridged explanation of the alphabetic symbols for the individual fractions follows, but computational details should be checked in "partitioning.pdf" (readable with `vegandocs`) or in the source code.

With two explanatory tables, the fractions explained uniquely by each of the two tables are `[a]` and `[c]`, and their joint effect is `[b]` following Borcard et al. (1992).

With three explanatory tables, the fractions explained uniquely by each of the three tables are `[a]` to `[c]`, joint fractions between two tables are `[d]` to `[f]`, and the joint fraction between all three tables is `[g]`.

With four explanatory tables, the fractions explained uniquely by each of the four tables are `[a]` to `[d]`, joint fractions between two tables are `[e]` to `[j]`, joint fractions between three variables are `[k]` to `[n]`, and the joint fraction between all four tables is `[o]`.

There is a `plot` function that displays the Venn diagram and labels each intersection (individual fraction) with the adjusted R squared if this is higher than `cutoff`. A helper function `showvarpart` displays the fraction labels.

### Value

Function `varpart` returns an object of class `"varpart"` with items `scale` and `transfo` (can be missing) which hold information on standardizations, `tables` which contains names of explanatory tables, and `call` with the function `call`. The function `varpart` calls function `varpart2`, `varpart3` or `varpart4` which return an object of class `"varpart234"` and saves its result in the item `part`. The items in this object are:

`SS.Y` | Sum of squares of matrix `Y`.
`n` | Number of observations (rows).
`nsets` | Number of explanatory tables
`bigwarning` | Warnings on collinearity.
`fract` | Basic fractions from all estimated constrained models.
`indfract` | Invididual fractions or all possible subsections in the Venn diagram (see `showvarparts`).
`contr1` | Fractions that can be found after conditioning on single explanatory table in models with three or four explanatory tables.
`contr2` | Fractions that can be found after conditioning on two explanatory tables in models with four explanatory tables.

### Fraction Data Frames

Items `fract`, `indfract`, `contr1` and `contr2` are all data frames with items:

Df
  Degrees of freedom of numerator of the F-statististic for the fraction.
R.square
  Raw R-squared. This is calculated only for `fract` and this is `NA` in other items.
Adj.R.square
  Adjusted R-squared.
Testable
  If the fraction can be expressed as a (partial) RDA model, it is directly `Testable`, and this field is `TRUE`. In that case the fraction label also gives the specification of the testable RDA model.

### Note

You can use command `vegandocs` to display document "partitioning.pdf" which presents Venn diagrams showing the fraction names in partitioning the variation of Y with respect to 2, 3, and 4 tables of explanatory variables, as well as the equations used in variation partitioning.

The functions frequently give negative estimates of variation. Adjusted R-squares can be negative for any fraction; unadjusted R squares of testable fractions always will be non-negative. Non-testable fractions cannot be found directly, but by subtracting different models, and these subtraction results can be negative. The fractions are orthogonal, or linearly independent, but more complicated or nonlinear dependencies can cause negative non-testable fractions.

The current function will only use RDA in multivariate partitioning. It is much more complicated to estimate the adjusted R-squares for CCA, and unbiased analysis of CCA is not currently implemented.

### Author(s)

Pierre Legendre, Departement de Sciences Biologiques, Universite de Montreal, Canada. Adapted to vegan by Jari Oksanen.

### References

(a) References on variation partioning

Borcard, D., P. Legendre & P. Drapeau. 1992. Partialling out the spatial component of ecological variation. Ecology 73: 1045–1055.

Legendre, P. & L. Legendre. 1998. Numerical ecology, 2nd English edition. Elsevier Science BV, Amsterdam.

(b) Reference on transformations for species data

Legendre, P. and E. D. Gallagher. 2001. Ecologically meaningful transformations for ordination of species data. Oecologia 129: 271–280.

(c) Reference on adjustment of the bimultivariate redundancy statistic

Peres-Neto, P., P. Legendre, S. Dray and D. Borcard. 2006. Variation partioning of species data matrices: estimation and comparison of fractions. Ecology 87: 2614–2625.

### See Also

For analysing testable fractions, see `rda` and `anova.cca`. For data transformation, see `decostand`. Function `inertcomp` gives (unadjusted) components of variation for each species or site separately.

### Examples

    data(mite)
    data(mite.env)
    data(mite.pcnm)

    ## See detailed documentation:
    ## Not run:
    vegandocs("partition")
    ## End(Not run)

    # Two explanatory matrices -- Hellinger-transform Y
    # Formula shortcut "~ ." means: use all variables in 'data'.
    mod <- varpart(mite, ~ ., mite.pcnm, data=mite.env, transfo="hel")
    mod
    showvarparts(2)
    plot(mod)
    # Alternative way of to conduct this partitioning
    # Change the data frame with factors into numeric model matrix
    mm <- model.matrix(~ SubsDens + WatrCont + Substrate + Shrub + Topo, mite.env)[,-1]
    mod <- varpart(decostand(mite, "hel"), mm, mite.pcnm)
    # Test fraction [a] using RDA:
    rda.result <- rda(decostand(mite, "hell"), mm, mite.pcnm)
    anova(rda.result, step=200, perm.max=200)

    # Three explanatory matrices
    mod <- varpart(mite, ~ SubsDens + WatrCont, ~ Substrate + Shrub + Topo,
       mite.pcnm, data=mite.env, transfo="hel")
    mod
    showvarparts(3)
    plot(mod)
    # An alternative formulation of the previous model using
    # matrices mm1 amd mm2 and Hellinger transformed species data
    mm1 <- model.matrix(~ SubsDens + WatrCont, mite.env)[,-1]
    mm2 <- model.matrix(~ Substrate + Shrub + Topo, mite.env)[, -1]
    mite.hel <- decostand(mite, "hel")
    mod <- varpart(mite.hel, mm1, mm2, mite.pcnm)
    # Use RDA to test fraction [a]
    rda.result <- rda(mite.hel, mm1, cbind(mm2, mite.pcnm))
    anova(rda.result, step=200, perm.max=200)

    # Four explanatory tables
    mod <- varpart(mite, ~ SubsDens + WatrCont, ~Substrate + Shrub + Topo,
      mite.pcnm[,1:11], mite.pcnm[,12:22], data=mite.env, transfo="hel")
    mod
    plot(mod)
    # Show values for all partitions by putting 'cutoff' low enough:
    plot(mod, cutoff = -Inf, cex = 0.7)

[Package vegan version 1.8-8 Index]