envfit                 package:vegan                 R Documentation

_F_i_t_s _a_n _E_n_v_i_r_o_n_m_e_n_t_a_l _V_e_c_t_o_r _o_r _F_a_c_t_o_r _o_n_t_o _a_n _O_r_d_i_n_a_t_i_o_n

_D_e_s_c_r_i_p_t_i_o_n:

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

_U_s_a_g_e:

     ## Default S3 method:
     envfit(X, P, permutations = 0, strata, choices=c(1,2), ...)
     ## S3 method for class 'formula':
     envfit(formula, data, ...)
     ## S3 method for class 'envfit':
     plot(x, choices = c(1,2), arrow.mul, at = c(0,0), axis = FALSE, 
         p.max = NULL, col = "blue", add = TRUE, ...)
     ## S3 method for class 'envfit':
     scores(x, display, choices, ...)
     vectorfit(X, P, permutations = 0, strata, choices=c(1,2),
           display = c("sites", "lc"), w = weights(X), ...)
     factorfit(X, P, permutations = 0, strata, choices=c(1,2),
           display = c("sites", "lc"), w = weights(X), ...)

_A_r_g_u_m_e_n_t_s:

       X: Ordination configuration.

       P: Matrix or vector of environmental variable(s). 

permutations: Number of permutations for assessing significance of
          vectors or factors.

formula, data: Model  'formula' and data.  

       x: A result object from 'envfit'.

 choices: Axes to plotted.

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.

     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'.

_D_e_t_a_i_l_s:

     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. 

     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.

     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. This means that sites with lower totals will have lower
     weights. 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 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.

_V_a_l_u_e:

     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.

   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.

_N_o_t_e:

     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.

_A_u_t_h_o_r(_s):

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

_S_e_e _A_l_s_o:

     A better alternative to vectors may be 'ordisurf'.

_E_x_a_m_p_l_e_s:

     data(varespec)
     data(varechem)
     library(MASS)
     ord <- metaMDS(varespec)
     (fit <- envfit(ord, varechem, perm = 1000))
     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 = 1000, display = "lc")
     plot(fit, p.max = 0.05, col = "red")
     ## Class variables, formula interface, and displaying the
     ## inter-class variability with `ordispider'
     data(dune)
     data(dune.env)
     attach(dune.env)
     ord <- cca(dune)
     fit <- envfit(ord ~ Moisture + A1, dune.env)
     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)

