# vegan: ordination and diversity analysis for community ecologists

> vegan is one of those packages that a field takes for granted, and the readme has a habit that says something about its maintainers: the vignettes include one on the design decisions and the implementation, and another is a frequently asked questions document that lives on a website rather than in the package. The software is thirty years old and still being revised, which for a scientific package is the point rather than a problem.

**vegandevs/vegan** — R package for community ecologists: popular ordination methods, ecological null models & diversity analysis

- Repository: https://github.com/vegandevs/vegan
- Website: https://vegandevs.github.io/vegan/
- Stars: 549 · Forks: 113
- Language: R
- License: GPL-2.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/vegandevs-vegan

## What the package is

vegan is an R package for community ecologists, and its own subtitle says what it does: ordination methods, diversity analysis and other functions for community and vegetation ecologists.

That is a narrow domain, and the narrowness is the point. Community ecology studies which species live together, and the two questions that come up constantly are how the species' composition varies across sites or samples, which is ordination, and how diverse each site is, which is the diversity analysis. Both have dozens of competing formulations, both have contested defaults, and both are the kind of thing a field expects to be implemented once, carefully, by people who care about the statistics.

The package also does ecological null models, which is the statistical testing side of the same questions: given the species in a site, how unusual is the pattern of co-occurrence? That requires generating random communities under a null and comparing, and the choice of null is a scientific decision with consequences.

So the package is a set of implementations that a field has agreed to use, and the interesting engineering question is not what it does but how it has stayed usable for three decades. The release history is the answer: a series of patch releases in the two series, with the most recent on the package archive a few weeks before the last push, and a long tail of earlier ones. A package whose version numbers are in the two series and whose releases come every few months is a package that is still being corrected, not one that is being frozen.

The readme is for the development version, and it says so, and it points at the package archive for the stable one. The badges tell the same story from several angles: the check status for the platforms, the current version on the archive, the download count, a status badge from the small-universe mirror, and a badge for the project's own universe instance.

The licence is the second version of the copyleft one, which is the right choice for a package that a research group is expected to extend, and the site is published from a documentation generator configuration in the repository rather than hosted elsewhere.

## The vignettes, and the one about design decisions

The vignettes are the most informative part of the readme, because their titles are a statement of what the package thinks a user needs to be taught.

There is an introduction to ordination, which is the entry point for somebody who has a community matrix and does not know which ordination to reach for. There is a document on the partitioning of variation, which is the technical heart of the package: when you run an ordination you are decomposing variation, and the ways of doing that give different answers, and the readme treats that subject as worth a document of its own.

There is a document on diversity analysis in the package, and then there are the two that set this package apart from the crowd.

The first is a document on design decisions and implementation. A scientific package that publishes a vignette explaining why its methods are implemented the way they are, and where it departs from the literature, is doing something that most packages do not: it is telling a user what the numbers mean before the user has to find out by reading the source.

That matters more in ecology than in most fields, because the conventions in this literature differ between textbooks. Two books can define the same diversity index differently, and the difference is invisible unless somebody says which definition is in the code. A vignette that states the decisions is a way of removing a whole class of confusion, and it is also a way of making the package teachable rather than merely usable.

The second is the frequently asked questions document, and the way it is delivered is worth noting. It is a page on the package's own website rather than a file in the repository, which is a sign of a long-lived document that is revised on its own schedule rather than with the code. A frequently asked questions document for a thirty-year-old package is itself an artefact of that age: it accumulates the questions that the documentation did not answer, and it is a record of what practitioners actually get stuck on.

So the readme's list of documents is not a manual and not a tutorial series. It is the shortest path from a community matrix to a defensible analysis, and it assumes a reader who knows the field and needs the package's conventions, not a reader who needs the field explained.

## Three ways to install, and what each one assumes

The installation section is unusually thorough, and the three routes are worth reading as three different assumptions about the reader.

The first is the source route, and the readme describes it with a small self-deprecating phrase: the usual git and build-then-install dance on the cloned repository, or on downloaded sources. The assumption here is that you have a working development toolchain, and the readme says so: you need to be able to install packages from source for this to work, and without the relevant developer tools you will not be able to install the package this way. That warning is the useful part. A source install of a package with compiled code on a machine without a compiler fails in a way that is easy to misread, and saying it in advance saves an afternoon.

The second route exists for people who have the developer tools but do not want a local source tree to keep up to date.

```r
install.packages("remotes")
remotes::install_github("vegandevs/vegan")
```

The third is for people who just want a binary version, installed exactly as they would from the main archive.

```r
install.packages('vegan',
    repos = c('https://vegandevs.r-universe.dev','https://cloud.r-project.org'))
```

That third snippet is the one with a detail worth understanding, because the vector of two repository addresses is not a list of alternatives, it is an ordered preference. The first address is the project's own universe instance, and the second is the main archive. The package manager takes the package from the first repository that has it, and falls back to the second if it does not.

For a binary install, that ordering is exactly right. The project's own instance is where the newest build is, and the main archive is the safety net, and a user who wants the archived version can simply install from that one alone. The same call with the order reversed would give the archived version and skip the newer one, which would make the project's own instance pointless.

So the three routes are a genuine three-way choice: the newest source with the most work, the newest source with less work, and a binary from the project's own build service. The readme's ordering of them, from most manual to least, matches the order in which the toolchain gets harder.

## The repository, and what the directory names say

The top level is the standard layout of an R package, and going through it tells you what kind of package this is.

The metadata files are the familiar ones: a description file carrying the package metadata, a namespace file, a licence file, a change log, and a readme. There is a file telling the build system which files to leave out of the source package, which is the mechanism by which development-only material stays out of what gets published, and a file of attributes for line endings.

The source directory is where the R code lives. The tests directory is where the test suite is, and the presence of a dedicated test directory rather than test files scattered next to the functions is the modern convention that keeps the package tidy.

Two directories carry most of the information. The vignettes directory is where those five documents live, and a package that ships a substantial set of vignettes is a package where documentation is part of the deliverable rather than an afterthought. And the source directory for compiled code, which is the answer to the question of why an R package for numerical ecology has native code in it.

That last one is worth a paragraph. Ordination on a large community matrix is a matter of singular value decompositions and eigen decompositions, and diversity indices over thousands of samples are loops, and in an interpreted language those are slow enough to change the shape of an analysis. The compiled code is not there for novelty; it is there so that the analyses a field actually runs finish in reasonable time.

The data directory is the other one worth noting. A package that ships datasets is a package whose examples are runnable against real data rather than against three invented rows, and in a scientific package that matters, because the point of an example is that a reader can check the output against something real.

The installed files directory holds what is copied into the user's installation as it is, which is where things like citation files and package level templates live. And the configuration for the documentation site generator sits at the root next to the readme, which means the site you are reading is built from the same tree as the package.

The continuous integration configuration is visible in the badge, and the check is the standard one for R packages, which runs the build and the checks on multiple platforms. For a package with compiled code and a long history of platform-specific fixes, that badge is the most reassuring thing on the page.

## The long tail, and what it means for your analysis

There is one more thing to say about this package, and it is a practical point rather than a historical one.

The version numbering is in the two series with patch releases, and the change log is in the repository. For a scientific package, the version a paper was written against matters, because the defaults in this literature are not all stable. The choice of which distance measure to use by default, how a null model samples, what a permutation test does at the boundary of the data: these are the kinds of decisions that get revised when somebody points out a problem, and a revised default changes results.

That is why the documentation set includes a document on design decisions. If you are reading a ten-year-old paper that used this package and you are re-running its analysis, the document that tells you which decisions were in force then is worth more than the function reference.

The second practical point is the difference between the development version and the archived one. The readme is the development site, and the vignettes are published from the project's own universe instance, which is where the development documentation lives. A reader who wants the vignettes that match the version in their analysis should look at the version-specific documentation, and a reader who wants the current state of the arguments should look here. The project maintains both, which is work that nobody notices until it stops.

And the third is the scale of adoption. The download badge on the readme is a count of downloads from the main archive, which for a package in a specialised field is a rough proxy for the number of working ecologists who use it. A package with that many downloads and a thirty-year history has been through the kind of scrutiny that finds the errors, and the version numbers in the two series are the receipt.

So the practical summary of this package is: it is old, it is careful, it is documented by people who expect to be read by other scientists, and the two things you should do before trusting a number from it are to check which version produced it and to read the vignette on design decisions.

## Conclusion

vegan fits a community ecologist who needs ordination, diversity indices and null model tests and does not want to write them, and fits a statistician who wants to read how the methods are implemented before using them. It does not fit somebody who wants a modern machine learning alternative. Verify first which version your analysis was written against, because the package has been revised for three decades and the defaults have moved, and that you read the partitioning vignette if you are comparing ordination methods, since the readme treats that as a document worth reading on its own rather than as a manual.

## FAQ

### What does the vegan R package do?

It provides ordination methods, diversity analysis and ecological null models for community and vegetation ecologists. The ordination side decomposes variation in a species-by-site matrix, the diversity side computes the indices used to summarise a site's species composition, and the null models test how unusual an observed pattern of co-occurrence is.

### Which vignettes does the vegan package publish?

An introduction to ordination, a document on the partitioning of variation, a document on diversity analysis, one on design decisions and implementation, and a frequently asked questions document. The design decisions one is the unusual entry, because it tells a user where the package's methods depart from the conventions of the literature.

### How do I install the development version of vegan?

Either build it from a cloned repository with the standard build and install commands, which needs the developer tools for compiling packages, or use the remotes package to install directly from the repository, which avoids keeping a local source tree up to date. A binary version is also available from the project's own package repository.

### Why does vegan include compiled code?

Because ordination on a large community matrix means eigen decompositions and singular value decompositions, and diversity indices over many samples means loops, and in an interpreted language those are slow enough to change the shape of an analysis. The native code exists so that the analyses the field actually runs finish in a reasonable time.

### How often is vegan released?

Often, and for a long time. The version numbers are in the two series and the release history shows patch releases every few months across many years, with the most recent on the package archive shortly before the last change to the repository. It is a package that is still being corrected rather than one that has been frozen.

## Sources

- [License: GPL-2.0](https://github.com/vegandevs/vegan/blob/master/LICENSE)
- [Project website](https://vegandevs.github.io/vegan/)
- [README](https://github.com/vegandevs/vegan/blob/master/README.md)
- [Releases](https://github.com/vegandevs/vegan/releases)
- [vegandevs/vegan on GitHub](https://github.com/vegandevs/vegan)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/vegandevs-vegan