# envfit: Fits an Environmental Vector or Factor onto an Ordination In vegan: Community Ecology Package

## Description

The function fits environmental vectors or factors onto an ordination. The projections of points onto vectors have maximum correlation with corresponding environmental variables, and the factors show the averages of factor levels.

## Usage

 ``` 1 2 3 4 5 6 7 8 9 10 11 12``` ```## Default S3 method: envfit(ord, env, permutations = 999, strata = NULL, choices=c(1,2), display = "sites", w = weights(ord), na.rm = FALSE, ...) ## S3 method for class 'formula' envfit(formula, data, ...) ## S3 method for class 'envfit' plot(x, choices = c(1,2), labels, arrow.mul, at = c(0,0), axis = FALSE, p.max = NULL, col = "blue", bg, add = TRUE, ...) ## S3 method for class 'envfit' scores(x, display, choices, ...) vectorfit(X, P, permutations = 0, strata = NULL, w, ...) factorfit(X, P, permutations = 0, strata = NULL, w, ...) ```

## Arguments

 `ord` An ordination object or other structure from which the ordination `scores` can be extracted (including a data frame or matrix of scores). `env` Data frame, matrix or vector of environmental variables. The variables can be of mixed type (factors, continuous variables) in data frames. `X` Matrix or data frame of ordination scores. `P` Data frame, matrix or vector of environmental variable(s). These must be continuous for `vectorfit` and factors or characters for `factorfit`. `permutations` a list of control values for the permutations as returned by the function `how`, or the number of permutations required, or a permutation matrix where each row gives the permuted indices. Set `permutations = 0` to skip permutations. `formula, data` Model `formula` and data. `na.rm` Remove points with missing values in ordination scores or environmental variables. The operation is casewise: the whole row of data is removed if there is a missing value and `na.rm = TRUE`. `x` A result object from `envfit`. For `ordiArrowMul` and `ordiArrowTextXY` this must be a two-column matrix (or matrix-like object) containing the coordinates of arrow heads on the two plot axes, and other methods extract such a structure from the `envfit` results. `choices` Axes to plotted. `labels` Change plotting labels. The argument should be a list with elements `vectors` and `factors` which give the new plotting labels. If either of these elements is omitted, the default labels will be used. If there is only one type of elements (only `vectors` or only `factors`), the labels can be given as vector. The default labels can be displayed with `labels` command. `arrow.mul` Multiplier for vector lengths. The arrows are automatically scaled similarly as in `plot.cca` if this is not given and `add = TRUE`. `at` The origin of fitted arrows in the plot. If you plot arrows in other places then origin, you probably have to specify `arrrow.mul`. `axis` Plot axis showing the scaling of fitted arrows. `p.max` Maximum estimated P value for displayed variables. You must calculate P values with setting `permutations` to use this option. `col` Colour in plotting. `bg` Background colour for labels. If `bg` is set, the labels are displayed with `ordilabel` instead of `text`. See Examples for using semitransparent background. `add` Results added to an existing ordination plot. `strata` An integer vector or factor specifying the strata for permutation. If supplied, observations are permuted only within the specified strata. `display` In fitting functions these are ordinary site scores or linear combination scores (`"lc"`) in constrained ordination (`cca`, `rda`, `capscale`). In `scores` function they are either `"vectors"` or `"factors"` (with synonyms `"bp"` or `"cn"`, resp.). `w` Weights used in fitting (concerns mainly `cca` and `decorana` results which have nonconstant weights). `...` Parameters passed to `scores`.

## Details

Function `envfit` finds vectors or factor averages of environmental variables. Function `plot.envfit` adds these in an ordination diagram. If `X` is a `data.frame`, `envfit` uses `factorfit` for `factor` variables and `vectorfit` for other variables. If `X` is a matrix or a vector, `envfit` uses only `vectorfit`. Alternatively, the model can be defined a simplified model `formula`, where the left hand side must be an ordination result object or a matrix of ordination scores, and right hand side lists the environmental variables. The formula interface can be used for easier selection and/or transformation of environmental variables. Only the main effects will be analysed even if interaction terms were defined in the formula.

The printed output of continuous variables (vectors) gives the direction cosines which are the coordinates of the heads of unit length vectors. In `plot` these are scaled by their correlation (square root of the column `r2`) so that “weak” predictors have shorter arrows than “strong” predictors. You can see the scaled relative lengths using command `scores`. The `plot`ted (and scaled) arrows are further adjusted to the current graph using a constant multiplier: this will keep the relative `r2`-scaled lengths of the arrows but tries to fill the current plot. You can see the multiplier using `ordiArrowMul(result_of_envfit)`, and set it with the argument `arrow.mul`.

Functions `vectorfit` and `factorfit` can be called directly. Function `vectorfit` finds directions in the ordination space towards which the environmental vectors change most rapidly and to which they have maximal correlations with the ordination configuration. Function `factorfit` finds averages of ordination scores for factor levels. Function `factorfit` treats ordered and unordered factors similarly.

If `permutations` > 0, the ‘significance’ of fitted vectors or factors is assessed using permutation of environmental variables. The goodness of fit statistic is squared correlation coefficient (r^2). For factors this is defined as r^2 = 1 - ss_w/ss_t, where ss_w and ss_t are within-group and total sums of squares. See `permutations` for additional details on permutation tests in Vegan.

User can supply a vector of prior weights `w`. If the ordination object has weights, these will be used. In practise this means that the row totals are used as weights with `cca` or `decorana` results. If you do not like this, but want to give equal weights to all sites, you should set `w = NULL`. The weighted fitting gives similar results to biplot arrows and class centroids in `cca`. For complete similarity between fitted vectors and biplot arrows, you should set `display = "lc"` (and possibly `scaling = 2`).

The lengths of arrows for fitted vectors are automatically adjusted for the physical size of the plot, and the arrow lengths cannot be compared across plots. For similar scaling of arrows, you must explicitly set the `arrow.mul` argument in the `plot` command; see `ordiArrowMul` and `ordiArrowTextXY`.

The results can be accessed with `scores.envfit` function which returns either the fitted vectors scaled by correlation coefficient or the centroids of the fitted environmental variables.

## Value

Functions `vectorfit` and `factorfit` return lists of classes `vectorfit` and `factorfit` which have a `print` method. The result object have the following items:

 `arrows` Arrow endpoints from `vectorfit`. The arrows are scaled to unit length. `centroids` Class centroids from `factorfit`. `r` Goodness of fit statistic: Squared correlation coefficient `permutations` Number of permutations. `control` A list of control values for the permutations as returned by the function `how`. `pvals` Empirical P-values for each variable.

Function `envfit` returns a list of class `envfit` with results of `vectorfit` and `envfit` as items.

Function `plot.envfit` scales the vectors by correlation.

## Note

Fitted vectors have become the method of choice in displaying environmental variables in ordination. Indeed, they are the optimal way of presenting environmental variables in Constrained Correspondence Analysis `cca`, since there they are the linear constraints. In unconstrained ordination the relation between external variables and ordination configuration may be less linear, and therefore other methods than arrows may be more useful. The simplest is to adjust the plotting symbol sizes (`cex`, `symbols`) by environmental variables. Fancier methods involve smoothing and regression methods that abound in R, and `ordisurf` provides a wrapper for some.

## Author(s)

Jari Oksanen. The permutation test derives from the code suggested by Michael Scroggie.

A better alternative to vectors may be `ordisurf`.

## Examples

 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35``` ```data(varespec) data(varechem) library(MASS) ord <- metaMDS(varespec) (fit <- envfit(ord, varechem, perm = 999)) scores(fit, "vectors") plot(ord) plot(fit) plot(fit, p.max = 0.05, col = "red") ## Adding fitted arrows to CCA. We use "lc" scores, and hope ## that arrows are scaled similarly in cca and envfit plots ord <- cca(varespec ~ Al + P + K, varechem) plot(ord, type="p") fit <- envfit(ord, varechem, perm = 999, display = "lc") plot(fit, p.max = 0.05, col = "red") ## Class variables, formula interface, and displaying the ## inter-class variability with `ordispider', and semitransparent ## white background for labels (semitransparent colours are not ## supported by all graphics devices) data(dune) data(dune.env) attach(dune.env) ord <- cca(dune) fit <- envfit(ord ~ Moisture + A1, dune.env, perm = 0) plot(ord, type = "n") ordispider(ord, Moisture, col="skyblue") points(ord, display = "sites", col = as.numeric(Moisture), pch=16) plot(fit, cex=1.2, axis=TRUE, bg = rgb(1, 1, 1, 0.5)) ## Use shorter labels for factor centroids labels(fit) plot(ord) plot(fit, labels=list(factors = paste("M", c(1,2,4,5), sep = "")), bg = rgb(1,1,0,0.5)) detach(dune.env) ```

### Example output

```Loading required package: permute
This is vegan 2.4-3
Square root transformation
Wisconsin double standardization
Run 0 stress 0.1843196
Run 1 stress 0.2386162
Run 2 stress 0.2140424
Run 3 stress 0.2141096
Run 4 stress 0.2335639
Run 5 stress 0.2265716
Run 6 stress 0.2094761
Run 7 stress 0.2254456
Run 8 stress 0.1974407
Run 9 stress 0.2325123
Run 10 stress 0.1843196
... New best solution
... Procrustes: rmse 1.758584e-05  max resid 6.905317e-05
... Similar to previous best
Run 11 stress 0.195049
Run 12 stress 0.2354621
Run 13 stress 0.2145795
Run 14 stress 0.2166094
Run 15 stress 0.2422932
Run 16 stress 0.2263597
Run 17 stress 0.1852397
Run 18 stress 0.2152708
Run 19 stress 0.2050707
Run 20 stress 0.267362
*** Solution reached

***VECTORS

NMDS1    NMDS2     r2 Pr(>r)
N        -0.05039 -0.99873 0.2080  0.101
P         0.68715  0.72652 0.1755  0.135
K         0.82741  0.56161 0.1657  0.154
Ca        0.75022  0.66118 0.2810  0.033 *
Mg        0.69688  0.71718 0.3493  0.008 **
S         0.27641  0.96104 0.1774  0.127
Al       -0.83763  0.54625 0.5155  0.002 **
Fe       -0.86176  0.50732 0.3999  0.005 **
Mn        0.80224 -0.59700 0.5322  0.001 ***
Zn        0.66533  0.74655 0.1779  0.119
Mo       -0.84871  0.52886 0.0517  0.564
Baresoil  0.87195 -0.48960 0.2494  0.040 *
Humdepth  0.92627 -0.37686 0.5591  0.001 ***
pH       -0.79905  0.60127 0.2625  0.039 *
---
Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1
Permutation: free
Number of permutations: 999

NMDS1      NMDS2
N        -0.02298243 -0.4555318
P         0.28786999  0.3043624
K         0.33677266  0.2285862
Ca        0.39766734  0.3504696
Mg        0.41185372  0.4238519
S         0.11640862  0.4047417
Al       -0.60138592  0.3921850
Fe       -0.54497790  0.3208271
Mn        0.58527476 -0.4355458
Zn        0.28061460  0.3148670
Mo       -0.19291014  0.1202102
Baresoil  0.43546052 -0.2445131
Humdepth  0.69257033 -0.2817812
pH       -0.40937530  0.3080495
\$vectors
[1] "A1"

\$factors
[1] "Moisture1" "Moisture2" "Moisture4" "Moisture5"
```

vegan documentation built on May 31, 2017, 4:08 a.m.