biocore/scikit-bio — pull request #402 by ElBrogrammer (2014-05-29 18:48:08+00:00)
Title: Add bioenv method to distance-based stats

# Intro
Added a `bioenv` function to the distance-based stats package. The implementation and interface is modeled after R's `vegan::bioenv` function; all unit test and doctest results were verified against that implementation. This method is also known as BIO-ENV or BEST (QIIME uses the latter name).

The implementation here is meant to replace the existing implementation in QIIME (`qiime.stats.Best`). That implementation is slower, incorrect (it doesn't scale the environmental variables before computing the Euclidean distances), and its interface and results are a bit awkward to deal with. Once this is merged, I'll update QIIME to use this implementation.

# Example
Assume we've loaded a distance matrix `dm`, e.g., containing UniFrac distances between microbial community samples, and a pandas data frame `df`, e.g., containing (numeric) environmental metadata. We can use `bioenv` to find the "best" subset of environmental variables that are correlated with community distances. That is, `bioenv` finds the subset of environmental variables whose Euclidean distances are maximally rank-correlated with the community distances in `dm`. It does this for each possible subset size, ranging from 1 to the total number of variables (inclusive).

In this example, we have a data frame with 6 variables of interest:

```
In [7]: bioenv(dm, df)
Out[7]:
size correlation
vars
P 1 0.251630
P, Al 2 0.400378
P, Ca, Al 3 0.400481
P, Ca, pH, Al 4 0.361875
log(N), P, Ca, pH, Al 5 0.321552
log(N), P, K, Ca, pH, Al 6 0.282181

[6 rows x 2 columns]
```

We can see that the combination of P, Ca, and Al has the highest correlation with the community distances.

The output is a pandas data frame, which renders nicely in a variety of contexts (e.g., in the IPython Notebook) and organizes the results in a similar manner to `vegan::bioenv`.