\input texinfo

@macro pkg {p}
@strong{\p\}
@end macro

@c %**start of header
@setfilename FAQ-@pkg{vegan}.info
@settitle @pkg{vegan} FAQ
@setchapternewpage on
@set FAQ_YEAR 2015
@afourpaper
@c %**end of header

@copying
@ifnottex
This document contains answers to some of the most frequently asked
questions about R package @pkg{vegan}. 
@end ifnottex

@quotation
This work is licensed under the Creative Commons Attribution 3.0
License. To view a copy of this license, visit
@uref{http://creativecommons.org/licenses/by/3.0/} or send a letter to
Creative Commons, 543 Howard Street, 5th Floor, San Francisco,
California, 94105, USA.

Copyright @copyright{} 2008-2015 vegan development team
@end quotation
@end copying

@dircategory Programming
@direntry
* R @pkg{vegan} FAQ: (FAQ-@pkg{vegan}).             FAQ for R package @pkg{vegan}.
@end direntry

@finalout

@titlepage
@title @pkg{vegan} @acronym{FAQ}
@subtitle Frequently Asked Questions on R package @pkg{vegan}
@author Jari Oksanen

@vskip 0pt plus 1fill
@insertcopying
@end titlepage

@ifnothtml
@contents
@end ifnothtml


@ifnottex
@node Top, Introduction, (dir), (dir)
@top @pkg{vegan} FAQ
@insertcopying
@end ifnottex




@menu
* Introduction::
* Ordination::
* Other analysis methods ::
@end menu

@node Introduction, Ordination, Top, Top
@chapter Introduction

@menu
* What is @pkg{vegan}?::
* What is R?::
* How to obtain @pkg{vegan} and R?::
* What R packages @pkg{vegan} depends on?::
* What other packages are available for ecologists?::
* What other documentation is available for @pkg{vegan}?::
* Is there a Graphical User Interface (GUI) for @pkg{vegan}?::
* How to cite @pkg{vegan}?::
* How to build @pkg{vegan} from sources?::
* Are there binaries for devel versions?::
* Can I use @pkg{vegan} in Mac?::
* How to report a bug in @pkg{vegan}?::
* Is it a bug or a feature?::
* Can I contribute to @pkg{vegan}?::
@end menu

@node What is @pkg{vegan}?, What is R?, Introduction, Introduction
@section What is @pkg{vegan}?

@pkg{Vegan} is an R package for community ecologists. It contains the most
popular methods of multivariate analysis needed in analysing ecological
communities, and tools for diversity analysis, and other potentially
useful functions.  @pkg{Vegan} is not self-contained but it must be run under
R statistical environment, and it also depends on many other R
packages. @pkg{Vegan} is @uref{http://www.gnu.org/philosophy/free-sw.html, free
software} and distributed under
@uref{http://www.gnu.org/licenses/gpl.html, ,GPL2 license}.

@node What is R?, How to obtain @pkg{vegan} and R?, What is @pkg{vegan}?, Introduction
@section What is R?

R is a system for statistical computation and graphics.  It consists of
a language plus a run-time environment with graphics, a debugger, access
to certain system functions, and the ability to run programs stored in
script files.

R has a home page at @uref{http://www.R-project.org/}.  It is
@uref{http://www.gnu.org/philosophy/free-sw.html, free software}
distributed under a @acronym{GNU}-style
@uref{http://www.gnu.org/copyleft/copyleft.html, copyleft}, and an
official part of the @uref{http://www.gnu.org/, @acronym{GNU}} project
(``@acronym{GNU} S'').

@node How to obtain @pkg{vegan} and R?, What R packages @pkg{vegan} depends on?, What is R?, Introduction
@section How to obtain @pkg{vegan} and R?

Both R and latest release version of @pkg{vegan} can be obtained through
@uref{http://cran.r-project.org,,CRAN}. Unstable development version of
@pkg{vegan} can be obtained through
@uref{https://github.com/vegandevs/vegan,,GitHub}. Formerly @pkg{vegan}
was developed in 
@uref{http://r-forge.r-project.org/projects/vegan/,,R-Forge},
but after moving to @uref{https://github.com/vegandevs/vegan,,GitHub}
the R-Forge repository may be out of date.

@node What R packages @pkg{vegan} depends on?, What other packages are available for ecologists?, How to obtain @pkg{vegan} and R?, Introduction
@section What R packages @pkg{vegan} depends on?

@pkg{Vegan} depends on the @pkg{permute} package which will provide
advanced and flexible permutation routines for @pkg{vegan}. The
@pkg{permute} package is developed together with @pkg{vegan} in
@uref{https://github.com/gavinsimpson/permute,,GitHub}. 

Some individual @pkg{vegan} functions depend on packages @pkg{MASS},
@pkg{mgcv}, @pkg{cluster}, @pkg{lattice} and @pkg{tcltk}.  These all are
base or recommended R packages that should be available in every R
installation. @pkg{Vegan} declares these as suggested or imported
packages, and you can install @pkg{vegan} and use most of its functions
without these packages.

@pkg{Vegan} is accompanied with a supporting package @pkg{vegan3d} for
three-dimensional and dynamic plotting. The @pkg{vegan3d} package needs
non-standard packages @pkg{rgl} and @pkg{scatterplot3d}.

@node What other packages are available for ecologists?, What other documentation is available for @pkg{vegan}?, What R packages @pkg{vegan} depends on?, Introduction
@section What other packages are available for ecologists?

@acronym{CRAN} @uref{http://cran.r-project.org/src/contrib/Views/,,Task
Views} include entries like @code{Environmetrics}, @code{Multivariate}
and @code{Spatial} that describe several useful packages and functions.
If you install R package @pkg{ctv}, you can inspect Task Views from your
R session, and automatically install sets of most important packages.

@node What other documentation is available for @pkg{vegan}?, Is there a Graphical User Interface (GUI) for @pkg{vegan}?, What other packages are available for ecologists?, Introduction
@section What other documentation is available for @pkg{vegan}?

@pkg{Vegan} is a fully documented R package with standard help pages.  These
are the most authoritative sources of documentation (and as a last
resource you can use the force and the read the source, as @pkg{vegan} is open
source).  @pkg{Vegan} package ships with other documents which can be read
with @code{vegandocs} command (documented in the @pkg{vegan} help).  The
documents included in the @pkg{vegan} package are
@itemize
@item
@pkg{Vegan} @code{NEWS}
@item 
@pkg{Vegan} @code{ChangeLog}.
@item
This document (@code{FAQ-vegan.pdf}).
@item
Short introduction to basic ordination methods in @pkg{vegan}
(@code{intro-vegan.pdf}).
@item
Introduction to diversity methods in @pkg{vegan} (@code{diversity-vegan.pdf}).
@item 
Discussion on design decisions in @pkg{vegan} (@code{decision-vegan.pdf}).
@item
Description of variance partition procedures in function
@code{varpart} (@code{partitioning.pdf}).
@end itemize


Web documents outside the package include:
@itemize

@item
@uref{https://github.com/vegandevs/vegan}: @pkg{vegan} homepage.
@item
@uref{http://cc.oulu.fi/~jarioksa/opetus/metodi/vegantutor.pdf}: @pkg{vegan}
tutorial.

@end itemize

@node Is there a Graphical User Interface (GUI) for @pkg{vegan}?, How to cite @pkg{vegan}?, What other documentation is available for @pkg{vegan}?, Introduction
@section Is there a Graphical User Interface (GUI) for @pkg{vegan}?

Roeland Kindt has made package @pkg{BiodiversityR} which provides a
GUI for @pkg{vegan}. The package is available at 
@uref{http://cran.r-project.org/src/contrib/Descriptions/BiodiversityR.html,,CRAN}.
It is not a mere GUI for @pkg{vegan}, but adds some new functions and
complements @pkg{vegan} functions in order to provide a 
workbench for biodiversity analysis. You can install @pkg{BiodiversityR} using
@code{install.packages("BiodiversityR")} or graphical package
management menu in R. The GUI works on Windows, MacOS X and Linux.

@node How to cite @pkg{vegan}?, How to build @pkg{vegan} from sources?, Is there a Graphical User Interface (GUI) for @pkg{vegan}?, Introduction
@section How to cite @pkg{vegan}? 

Use command @code{citation("vegan")} in R to see the recommended
citation to be used in publications. 

@node How to build @pkg{vegan} from sources?, Are there binaries for devel versions?, How to cite @pkg{vegan}?, Introduction
@section How to build @pkg{vegan} from sources?

In general, you do not need to build @pkg{vegan} from sources, but binary
builds of release versions are available through
@uref{http://cran.r-project.org/,,CRAN} for Windows and MacOS X.  If you
use some other operating systems, you may have to use source packages.
@pkg{Vegan} is a standard R package, and can be built like instructed in R
documentation.  @pkg{Vegan} contains source files in C and @acronym{FORTRAN},
and you need appropriate compilers (which may need more work in Windows
and MacOS X).

@node Are there binaries for devel versions?, Can I use @pkg{vegan} in Mac?, How to build @pkg{vegan} from sources?, Introduction
@section Are there binaries for devel versions?

@uref{http://r-forge.r-project.org/projects/vegan/,,R-Forge} runs daily
tests on the devel package, and if passed, it builds source package
together with Windows binaries. However, the R-Forge may be out of date,
because @pkg{vegan} is mainly developed in
@uref{https://github.com/vegandevs/vegan,,GitHub}. You can install R-Forge
packages within R with command 
@code{install.packages("vegan", repos="http://r-forge.r-project.org/")}.
If you use GUI menu entry, you must select or define the R-Forge
repository. 

@node Can I use @pkg{vegan} in Mac?, How to report a bug in @pkg{vegan}?, Are there binaries for devel versions?, Introduction
@section Can I use @pkg{vegan} in Mac?

Yes, you can, and @pkg{vegan} binaries are available for Mac through
@uref{http://cran.r-project.org,,CRAN}. However, in some cases you may
need to install extra tools packages available in
@uref{http://cran.r-project.org/bin/macosx/tools/,,MacOS tools} pages:
If you use function such as @code{orditkplot} that need @code{Tcl/Tk}
you may need to install @code{tcltk} package. No Mac binaries of
development versions are available in any repository we know. 

@node How to report a bug in @pkg{vegan}?, Is it a bug or a feature?, Can I use @pkg{vegan} in Mac?, Introduction
@section How to report a bug in @pkg{vegan}?

If you think you have found a bug in @pkg{vegan}, you should report it to
@pkg{vegan} maintainers or developers.  The preferred forum to report
bugs is @uref{https://github.com/vegandevs/vegan/issues,,GitHub}. The
bug report should be so detailed 
that the bug can be replicated and corrected.  Preferably, you should
send an example that causes a bug.  If it needs a data set that is not
available in R, you should send a minimal data set as well. You also
should paste the output or error message in your message.  You also
should specify which version of @pkg{vegan} you used.

Bug reports are welcome: they are the only way to make @pkg{vegan} non-buggy.

Please note that you shall not send bug reports to R mailing lists,
since @pkg{vegan} is not a standard R package.

@node Is it a bug or a feature?, Can I contribute to @pkg{vegan}?, How to report a bug in @pkg{vegan}?, Introduction
@section Is it a bug or a feature?

It is not necessarily a bug if some function gives different
results than you expect: That may be a deliberate design decision. It
may be useful to check the documentation of the function to see what
was the intended behaviour. It may also happen that function has an
argument to switch the behaviour to match your expectation. For
instance, function @code{vegdist} always calculates quantitative
indices (when this is possible). If you expect it to calculate a
binary index, you should use argument @code{binary = TRUE}.

@node Can I contribute to @pkg{vegan}?,  , Is it a bug or a feature?, Introduction
@section Can I contribute to @pkg{vegan}?

@pkg{Vegan} is dependent on user contribution.  All feedback is welcome.  If
you have problems with @pkg{vegan}, it may be as simple as incomplete
documentation, and we shall do our best to improve the documents.

Feature requests also are welcome, but they are not necessarily
fulfilled.  A new feature will be added if it is easy to do and it looks
useful, or if you submit code. 

If you can write code yourself, the best forum to contribute to vegan is
@uref{https://github.com/vegandevs/vegan,,GitHub}. 

@node Ordination, Other analysis methods , Introduction, Top
@chapter Ordination

@menu
* I have only numeric and positive data but @pkg{vegan} still complains::
* Can I analyse binary or cover class data?::
* Why dissimilarities in @pkg{vegan} differ from other sources?::
* Why NMDS stress is sometimes 0.1 and sometimes 10?::
* I get zero stress but no convergent solutions in @code{metaMDS}::
* Zero dissimilarities in isoMDS::
* I have heard that you cannot fit environmental vectors or surfaces to NMDS results which only have rank-order scores::
* Where can I find numerical scores of ordination axes?::
* How the RDA results are scaled?::
* cca fails with ``data.frame expected'' or ``"site.env" missing''::
* Ordination fails with ``Error in La.svd''::
* Variance explained by ordination axes::
* Can I have random effects in constrained ordination or in @code{adonis}?::
* Is it possible to have passive points in ordination?::
* Class variables and dummies::
* How are environmental arrows scaled?::
* I want to use Helmert or sum contrasts::
* What are aliased variables and how to see them?::
* Plotting aliased variables::
* Restricted permutations in @pkg{vegan}::
* How to use different plotting symbols in ordination graphics?::
* How to avoid cluttered ordination graphs?::
* Can I flip an axis in ordination diagram?::
* Can I zoom into an ordination plot?::
@end menu

@node  I have only numeric and positive data but @pkg{vegan} still complains, Can I analyse binary or cover class data?, Ordination, Ordination
@comment  node-name,  next,  previous,  up
@section I have only numeric and positive data but @pkg{vegan} still complains

You are wrong! Computers are painfully pedantic, and if they find
non-numeric or negative data entries, you really have them. Check your
data. Most common reasons for non-numeric data are that row names were
read as a non-numeric variable instead of being used as row names (check
argument @code{row.names} in reading the data), or that the column names
were interpreted as data (check argument @code{header = TRUE} in reading
the data). Another common reason is that you had empty cells in your
input data, and these were interpreted as missing values.

@node Can I analyse binary or cover class data?, Why dissimilarities in @pkg{vegan} differ from other sources?, I have only numeric and positive data but @pkg{vegan} still complains, Ordination
@section Can I analyse binary or cover class data?

Yes. Most @pkg{vegan} methods can handle binary data or cover abundance data.
Most statistical tests are based on permutation, and do not make
distributional assumptions.  There are some methods (mainly in diversity
analysis) that need count data.  These methods check that input data are
integers, but they may be fooled by cover class data.

@node Why dissimilarities in @pkg{vegan} differ from other sources?, Why NMDS stress is sometimes 0.1 and sometimes 10?, Can I analyse binary or cover class data?, Ordination
@section Why dissimilarities in @pkg{vegan} differ from other sources?

Most commonly the reason is that other software use presence--absence
data whereas @pkg{vegan} used quantitative data.  Usually @pkg{vegan} indices are
quantitative, but you can use argument @code{binary = TRUE} to make them
presence--absence.  However, the index name is the same in both cases,
although different names usually occur in literature.  For instance,
Jaccard index actually refers to the binary index, but @pkg{vegan} uses
name @code{"jaccard"} for the quantitative index, too.

Another reason may be that indices indeed are defined differently,
because people use same names for different indices.

@node Why NMDS stress is sometimes 0.1 and sometimes 10?, I get zero stress but no convergent solutions in @code{metaMDS}, Why dissimilarities in @pkg{vegan} differ from other sources?, Ordination
@section Why @acronym{NMDS} stress is sometimes 0.1 and sometimes 10?

Stress is a proportional measure of badness of fit. The proportions can
be expressed either as parts of one or as percents.  Function
@code{isoMDS} (@pkg{MASS} package) uses percents, and function @code{monoMDS}
(@pkg{vegan} package) uses proportions, and therefore the same stress is 100
times higher in @code{isoMDS}. The results of @code{goodness} function
also depend on the definition of stress, and the same @code{goodness} is
100 times higher in @code{isoMDS} than in @code{monoMDS}.  Both of these
conventions are equally correct.

@node I get zero stress but no convergent solutions in @code{metaMDS}, Zero dissimilarities in isoMDS, Why NMDS stress is sometimes 0.1 and sometimes 10?, Ordination
@section I get zero stress but no convergent solutions in @code{metaMDS}

Most common reason is that you have too few observations for your
@acronym{NMDS}. For @code{n} observations (points) and @code{k}
dimensions you need to estimate @code{n*k} parameters (ordination
scores) using @code{n*(n-1)/2} dissimilarities.  For @code{k} dimensions
you must have @code{n > 2*k + 1}, or for two dimensions at least six
points.  In some degenerate situations you may need even a larger number
of points.  If you have a lower number of points, you can find an
undefined number of perfect (stress is zero) but different solutions.
Conventional wisdom due to Kruskal is that you should have @code{n > 4*k
+ 1} points for @code{k} dimensions.  A typical symptom of insufficient
data is that you have (nearly) zero stress but no two convergent
solutions.  In those cases you should reduce the number of dimensions
(@code{k}) and with very small data sets you should not use @code{NMDS},
but rely on metric methods.

It seems that local and hybrid scaling with @code{monoMDS} have similar
lower limits in practice (although theoretically they could differ).
However, higher number of dimensions can be used in metric scaling, both
with @code{monoMDS} and in principal coordinates analysis
(@code{cmdscale} in @pkg{stats}, @code{wcmdscale} in @pkg{vegan}).

@node Zero dissimilarities in isoMDS, I have heard that you cannot fit environmental vectors or surfaces to NMDS results which only have rank-order scores, I get zero stress but no convergent solutions in @code{metaMDS}, Ordination
@section Zero dissimilarities in isoMDS

Function @code{metaMDS} uses function @code{monoMDS} as its default
method for @acronym{NMDS}, and this function can handle zero
dissimilarities. Alternative function @code{isoMDS} cannot handle zero
dissimilarities. If you want to use @code{isoMDS}, you can use argument
@code{zerodist = "add"} in @code{metaMDS} to handle zero
dissimilarities.  With this argument, zero dissimilarities are replaced
with a small positive value, and they can be handled in @code{isoMDS}.
This is a kluge, and some people do not like this. A more principal
solution is to remove duplicate sites using R command @code{unique}.
However, after some standardizations or with some dissimilarity indices,
originally non-unique sites can have zero dissimilarity, and you have to
resort to the kluge (or work harder with your data). Usually it is
better to use @code{monoMDS}.

@node I have heard that you cannot fit environmental vectors or surfaces to NMDS results which only have rank-order scores, Where can I find numerical scores of ordination axes?, Zero dissimilarities in isoMDS, Ordination
@section I have heard that you cannot fit environmental vectors or surfaces to NMDS results which only have rank-order scores

Claims like this have indeed been at large in the Internet, but they are
based on grave misunderstanding and are plainly wrong. @acronym{NMDS}
ordination results are strictly metric, and in @pkg{vegan}
@code{metaMDS} and @code{monoMDS} they are even strictly Euclidean. The
method is called ``non-metric'' because the Euclidean distances in
ordination space have a non-metric rank-order relationship to community
dissimilarities. You can inspect this non-linear step curve using
function @code{stressplot} in @pkg{vegan}. Because the ordination scores
are strictly Euclidean, it is correct to use @pkg{vegan} functions
@code{envfit} and @code{ordisurf} with @acronym{NMDS} results.

@node Where can I find numerical scores of ordination axes?, How the RDA results are scaled?, I have heard that you cannot fit environmental vectors or surfaces to NMDS results which only have rank-order scores, Ordination
@section Where can I find numerical scores of ordination axes?

Normally you can use function @code{scores} to extract ordination scores
for any ordination method. The @code{scores} function can also find
ordination scores for many non-@pkg{vegan} functions such as for
@code{prcomp} and @code{princomp} and for some @pkg{ade4} functions.

In some cases the ordination result object stores raw scores, and
the axes are also scaled appropriate when you access them with
@code{scores}.  For instance, in @code{cca} and @code{rda} the
ordination object has only so-called normalized scores, and they are
scaled for ordination plots or for other use when they are accessed with
@code{scores}. 

@node How the RDA results are scaled?, cca fails with ``data.frame expected'' or ``"site.env" missing'', Where can I find numerical scores of ordination axes?, Ordination
@section How the @acronym{RDA} results are scaled?

The scaling or @acronym{RDA} results indeed differ from most other
software packages. The scaling of @acronym{RDA} is such a complicated
issue that it cannot be explained in this @acronym{FAQ}, but it is
explained in a separate @acronym{pdf} document on ``Design decision and
implementation details in vegan'' that you can read with @pkg{vegan}
command @code{vegandocs("decision")}.

@node cca fails with ``data.frame expected'' or ``"site.env" missing'', Ordination fails with ``Error in La.svd'', How the RDA results are scaled?, Ordination
@section cca fails with ``data.frame expected'' or ``"site.env" missing''

This is not a @pkg{vegan} error message, but it comes from the
@code{cca} function in the @pkg{ade4} package. There is an unfortunate
name clash, and if you have loaded @pkg{ade4} after @pkg{vegan}, the
@pkg{ade4} version of @code{cca} will mask the @pkg{vegan} version. You
can use the @pkg{vegan} version using command @code{vegan::cca()}. If
you do not need package @pkg{ade4}, you can detach it with command
@code{detach(package:ade4)}.

@node Ordination fails with ``Error in La.svd'', Variance explained by ordination axes, cca fails with ``data.frame expected'' or ``"site.env" missing'', Ordination
@section Ordination fails with ``Error in La.svd''

Constrained ordination (@code{cca}, @code{rda}, @code{capscale}) will
sometimes fail with error message 
@code{Error in La.svd(x, nu, nv): error code 1 from Lapack routine 'dgesdd'.}  

It seems that the basic problem is in the @code{svd} function of
@code{LAPACK} that is used for numerical analysis in R.  @code{LAPACK}
is an external library that is beyond the control of package developers
and R core team so that these problems may be unsolvable. It seems that
the problems with the @code{LAPACK} code are so common that even the
help page of @code{svd} warns about them

Reducing the range of constraints (environmental variables) helps
sometimes. For instance, multiplying constraints by a constant < 1. This
rescaling does not influence the numerical results of constrained
ordination, but it can complicate further analyses when values of
constraints are needed, because the same scaling must be applied
there. We can only hope that this problem is fixed in the future
versions of R and @code{LAPACK}.

@node Variance explained by ordination axes, Can I have random effects in constrained ordination or in @code{adonis}?, Ordination fails with ``Error in La.svd'', Ordination
@section Variance explained by ordination axes.

In general, @pkg{vegan} does not directly give any statistics on the
``variance explained'' by ordination axes or by the constrained axes.
This is a design decision: I think this information is normally useless
and often misleading.  In community ordination, the goal typically is
not to explain the variance, but to find the ``gradients'' or main
trends in the data.  The ``total variation'' often is meaningless, and
all proportions of meaningless values also are meaningless.  Often a
better solution explains a smaller part of ``total variation''.  For
instance, in unstandardized principal components analysis most of the
variance is generated by a small number of most abundant species, and
they are easy to ``explain'' because data really are not very
multivariate.  If you standardize your data, all species are equally
important.  The first axes explains much less of the ``total
variation'', but now they explain all species equally, and results
typically are much more useful for the whole community.  Correspondence
analysis uses another measure of variation (which is not variance), and
again it typically explains a ``smaller proportion'' than principal
components but with a better result.  Detrended correspondence analysis
and nonmetric multidimensional scaling even do not try to ``explain''
the variation, but use other criteria.  All methods are incommensurable,
and it is impossible to compare methods using ``explanation of
variation''.

If you still want to get ``explanation of variation'' (or a deranged
editor requests that from you), it is possible to get this information
for some methods:
@itemize
@item Eigenvector methods:
Functions @code{rda}, @code{cca} and @code{capscale} give the variation
of conditional (partialled), constrained (canonical) and residual
components, but you must calculate the proportions by hand.  Function
@code{eigenvals} extracts the eigenvalues, and
@code{summary(eigenvals(ord))} reports the proportions explained in the
result object @code{ord}.  Function @code{RsquareAdj} gives the
R-squared and adjusted R-squared (if available) for constrained
components.  Function @code{goodness} gives the same statistics for
individual species or sites (species are unavailable with
@code{capscale}). In addition, there is a special function
@code{varpart} for unbiased partitioning of variance between up to four
separate components in redundancy analysis.

@item Detrended correspondence analysis (function @code{decorana}).
The total amount of variation is undefined in detrended correspondence
analysis, and therefore proportions from total are unknown and
undefined.  @acronym{DCA} is not a method for decomposition of
variation, and therefore these proportions would not make sense either.

@item Nonmetric multidimensional scaling. 
@acronym{NMDS} is a method for nonlinear mapping, and the concept of
of variation explained does not make sense.  However, 1 - stress^2
transforms nonlinear stress into quantity analogous to squared
correlation coefficient.  Function @code{stressplot} displays the
nonlinear fit and gives this statistic.

@end itemize

@node Can I have random effects in constrained ordination or in @code{adonis}?, Is it possible to have passive points in ordination?, Variance explained by ordination axes, Ordination
@section Can I have random effects in constrained ordination or in @code{adonis}?

No. Strictly speaking, this is impossible. However, you can define
models that respond to similar goals as random effects models, although
they strictly speaking use only fixed effects.

Constrained ordination functions @code{cca}, @code{rda} and
@code{capscale} can have @code{Condition()} terms in their formula. The
@code{Condition()} define partial terms that are fitted before other
constraints and can be used to remove the effects of background
variables, and their contribution to decomposing inertia (variance) is
reported separately.  These partial terms are often regarded as similar
to random effects, but they are still fitted in the same way as other
terms and strictly speaking they are fixed terms.

Function @code{adonis} evaluates terms sequentially. In a model with
right-hand-side @code{~ A + B} the effects of @code{A} are evaluated
first, and the effects of @code{B} after removing the effects of
@code{A}. Sequential tests are also available in @code{anova} function
for constrained ordination results by setting argument @code{by = "term"}.  
In this way, the first terms can serve in a similar role as
random effects, although they are fitted in the same way as all other
terms, and strictly speaking they are fixed terms.

All permutation tests in @pkg{vegan} are based on the @pkg{permute}
package that allows constructing various restricted permutation
schemes. For instance, you can set levels of @code{plots} or
@code{blocks} for a factor regarded as a random term.

A major reason why real random effects models are impossible in most
@pkg{vegan} functions is that their tests are based on the permutation
of the data. The data are given, that is fixed, and therefore
permutation tests are basically tests of fixed terms on fixed data.
Random effect terms would require permutations of data with a random
component instead of the given, fixed data, and such tests are not
available in @pkg{vegan}.

@node Is it possible to have passive points in ordination?, Class variables and dummies, Can I have random effects in constrained ordination or in @code{adonis}?, Ordination
@section Is it possible to have passive points in ordination?

@pkg{Vegan} does not have a concept of passive points, or a point that should
only little influence the ordination results. However, you can add
points to eigenvector methods using @code{predict} functions with
@code{newdata}.  You can first perform an ordination without some
species or sites, and then you can find scores for all points using your
complete data as @code{newdata}.  The @code{predict} functions are
available for basic eigenvector methods in @pkg{vegan} (@code{cca},
@code{rda}, @code{decorana}, for an up-to-date list, use command
@code{methods("predict")}). You also can simulate the passive points in
R by using low weights to row and columns (this is the method used in
software with passive points). For instance, the following command makes
row 3 ``passive'': @code{dune[3,] <- 0.001*dune[3,]}.


@node Class variables and dummies, How are environmental arrows scaled?, Is it possible to have passive points in ordination?, Ordination
@section Class variables and dummies

You should define a class variable as an R @code{factor}, and @pkg{vegan} will
automatically handle them with formula interface.  You also can define
constrained ordination without formula interface, but then you must
code your class variables by hand.

R (and @pkg{vegan}) knows both unordered and ordered factors.  Unordered
factors are internally coded as dummy variables, but one redundant
level is removed or aliased.  With default contrasts, the removed
level is the first one.  Ordered factors are expressed as polynomial
contrasts. Both of these contrasts explained in standard R
documentation. 


@node How are environmental arrows scaled?, I want to use Helmert or sum contrasts, Class variables and dummies, Ordination
@section How are environmental arrows scaled?

The printed output of @code{envfit} gives the direction cosines which
are the coordinates of unit length arrows. For plotting, these are
scaled by their correlation (square roots of column @code{r2}). You can
see the scaled lengths of @code{envfit} arrows using command
@code{scores}.

The scaled environmental vectors from @code{envfit} and the arrows for
continuous environmental variables in constrained ordination
(@code{cca}, @code{rda}, @code{capscale}) are adjusted to fill the
current graph.  The lengths of arrows do not have fixed meaning with
respect to the points (species, sites), but they can only compared
against each other, and therefore only their relative lengths are
important.

If you want change the scaling of the arrows, you can use @code{text}
(plotting arrows and text) or @code{points} (plotting only arrows)
functions for constrained ordination. These functions have argument
@code{arrow.mul} which sets the multiplier.  The @code{plot} function
for @code{envfit} also has the @code{arrow.mul} argument to set the
arrow multiplier.  If you save the invisible result of the constrained
ordination @code{plot} command, you can see the value of the currently
used @code{arrow.mul} which is saved as an attribute of @code{biplot}
scores.

Function @code{ordiArrowMul} is used to find the scaling for the
current plot. You can use this function to see how arrows would be
scaled:
@example
sol <- cca(varespec)
ef <- envfit(sol ~ ., varechem)
plot(sol)
ordiArrowMul(scores(ef, display="vectors"))
@end example

@node I want to use Helmert or sum contrasts, What are aliased variables and how to see them?, How are environmental arrows scaled?, Ordination
@section I want to use Helmert or sum contrasts

@code{@pkg{vegan}} uses standard R utilities for defining
contrasts. The default in standard installations is to use treatment
contrasts, but you can change the behaviour globally setting
@code{options} or locally by using keyword @code{contrasts}. Please
check the R help pages and user manuals for details.

@node What are aliased variables and how to see them?, Plotting aliased variables, I want to use Helmert or sum contrasts, Ordination
@section What are aliased variables and how to see them?

Aliased variable has no information because it can be expressed with
the help of other variables.  Such variables are automatically removed
in constrained ordination in @pkg{vegan}.  The aliased variables can be
redundant levels of factors or whole variables.

@pkg{Vegan} function @code{alias} gives the defining equations for aliased
variables.  If you only want to see the names of aliased variables or
levels in solution @code{sol}, use @code{alias(sol, names.only=TRUE)}.

@node Plotting aliased variables, Restricted permutations in @pkg{vegan}, What are aliased variables and how to see them?, Ordination
@section Plotting aliased variables

You can fit vectors or class centroids for aliased variables using
@code{envfit} function.  The @code{envfit} function uses weighted
fitting, and the fitted vectors are identical to the vectors in
correspondence analysis.

@node Restricted permutations in @pkg{vegan}, How to use different plotting symbols in ordination graphics?, Plotting aliased variables, Ordination
@section Restricted permutations in @pkg{vegan}

@pkg{Vegan} uses @pkg{permute} package in all its permutation tests.
The @pkg{permute} package will allow restricted permutation designs for
time series, line transects, spatial grids and blocking factors. The
construction of restricted permutation schemes is explained in the
manual page @code{permutations} in @pkg{vegan} and in the documentation
of the @pkg{permute} package.

@node How to use different plotting symbols in ordination graphics?, How to avoid cluttered ordination graphs?, Restricted permutations in @pkg{vegan}, Ordination
@section How to use different plotting symbols in ordination graphics?

The default ordination @code{plot} function is intended for fast
plotting and it is not very configurable. To use different plotting
symbols, you should first create and empty ordination plot with
@code{plot(..., type="n")}, and then add @code{points} or @code{text} to
the created empty frame (here @code{...} means other arguments you want
to give to your @code{plot} command). The @code{points} and @code{text}
commands are fully configurable, and allow different plotting symbols
and characters.

@node How to avoid cluttered ordination graphs?, Can I flip an axis in ordination diagram?, How to use different plotting symbols in ordination graphics?, Ordination
@section How to avoid cluttered ordination graphs?

If there is a really high number of species or sites, the graphs often
are congested and many labels are overwritten. It may be impossible to
have complete readable graphics with some data sets. Below we give a
brief overview of tricks you can use. Gavin Simpson's blog
@uref{http://www.fromthebottomoftheheap.net,, From the bottom of the
heap} has a series of articles on ``decluttering ordination plots'' with
more detailed discussion and examples.
@itemize

@item 
Use only points, possibly with different types if you do not need
to see the labels. You may need to first create an empty plot using
@code{plot(..., type="n")}, if you are not satisfied with the default
graph. (Here and below  @code{...} means other arguments you want
to give to your @code{plot} command.)

@item 
Use points and add labels to desired points using interactive
@code{identify} command if you do not need to see all labels.

@item 
Add labels using function @code{ordilabel} which uses non-transparent
background to the text. The labels still shadow each other, but the
uppermost labels are readable. Argument @code{priority} will help in
displaying the most interesting labels (see
@uref{http://www.fromthebottomoftheheap.net/2013/01/12/decluttering-ordination-plots-in-vegan-part-1-ordilabel/,,Decluttering
blog, part 1}).

@item 
Use @code{orditorp} function that uses labels only if these can be
added to a graph without overwriting other labels, and points otherwise,
if you do not need to see all labels. You must first create an empty
plot using  @code{plot(..., type="n")}, and then add labels or points
with @code{orditorp} (see
@uref{http://www.fromthebottomoftheheap.net/2013/01/13/decluttering-ordination-plots-in-vegan-part-2-orditorp/,,Decluttering
blog}). 

@item 
Use @code{ordipointlabel} which uses points and text labels to the
points, and tries to optimize the location of the text to minimize the
overlap (see
@uref{http://www.fromthebottomoftheheap.net/2013/06/27/decluttering-ordination-plots-in-vegan-part-3-ordipointlabel/,,
Decluttering blog}).

@item
Ordination @code{text} and @code{points} functions have argument
@code{select} that can be used for full control of selecting items
plotted as text or points.

@item 
Use interactive @code{orditkplot} function that lets you drag
labels of points to better positions if you need to see all labels. Only
one set of points can be used (see
@uref{http://www.fromthebottomoftheheap.net/2013/12/31/decluttering-ordination-in-vegan-part-4-orditkplot/,,Decluttering
blog}).

@item 
Most @code{plot} functions allow you to zoom to a part of the
graph using @code{xlim} and @code{ylim} arguments to reduce clutter in
congested areas.  

@end itemize

@node  Can I flip an axis in ordination diagram?, Can I zoom into an ordination plot?, How to avoid cluttered ordination graphs?, Ordination
@comment  node-name,  next,  previous,  up 
@section Can I flip an axis in ordination diagram?

Use @code{xlim} or @code{ylim} with flipped limits. If you have model
@code{mod <- cca(dune)} you can flip the first axis with @code{plot(mod,
xlim = c(3, -2))}.

@node  Can I zoom into an ordination plot?,  , Can I flip an axis in ordination diagram?, Ordination
@comment  node-name,  next,  previous,  up
@section Can I zoom into an ordination plot?
You can use @code{xlim} and @code{ylim} arguments in @code{plot} or
@code{ordiplot} to zoom into ordination diagrams. Normally you must set
both @code{xlim} and @code{ylim} because ordination plots will keep the
equal aspect ratio of axes, and they will fill the graph so that the
longer axis will fit. 

Dynamic zooming can be done with function @code{orditkplot}. You can
directly save the edited @code{orditkplot} graph in various graphic
formats, or you can export the graph object back to R and use
@code{plot} to display the results. 

@node Other analysis methods ,  , Ordination, Top
@chapter Other analysis methods

@menu
* Is there TWINSPAN?::
* Why restricted permutation does not influence adonis results?::
* How is deviance calculated?::
@end menu

@node Is there TWINSPAN?, Why restricted permutation does not influence adonis results?, Other analysis methods , Other analysis methods
@section Is there TWINSPAN?

No.  It may be possible to port @acronym{TWINSPAN} to @pkg{vegan}, but it is
not among the @pkg{vegan} top priorities.  If anybody wants to try porting, I
will be happy to help.  @acronym{TWINSPAN} has a very permissive
license, and it would be completely legal to port the function into R.

@node  Why restricted permutation does not influence adonis results?, How is deviance calculated?, Is there TWINSPAN?, Other analysis methods
@comment  node-name,  next,  previous,  up
@section Why restricted permutation does not influence adonis results?
The permutation scheme influences the permutation distribution of the
statistics and probably the significance levels, but does not influence
the calculation of the statistics.


@node How is deviance calculated?,  , Why restricted permutation does not influence adonis results?, Other analysis methods
@section How is deviance calculated?

Some @pkg{vegan} functions, such as @code{radfit} use base R facility of
@code{family} in maximum likelihood estimation.  This allows use of
several alternative error distributions, among them @code{"poisson"}
and @code{"gaussian"}. The R @code{family} also defines the
deviance.  You can see the equations for deviance with commands like
@code{poisson()$dev} or @code{gaussian()$dev}.  

In general, deviance is 2 times log.likelihood 
shifted so that models with exact fit have zero deviance.


@bye
