biocore/scikit-bio — pull request #416 by ElBrogrammer (2014-06-10 03:26:00+00:00)
Title: Add Mantel test to distance-based stats subpackage

# Intro
Added `skbio.math.stats.distance.mantel` function. This function is meant to provide a low-level, simple API to run a Mantel test on two distance matrices.

The primary inputs are two distance matrices of the same shape. These can be ``array_like``, including nested Python lists, ``ndarray``s, or ``DistanceMatrix`` instances. Optional parameters allow control of the correlation coefficient (Pearson and Spearman correlation are currently supported), number of permutations, and alternative hypothesis.

I'm planning on adding a higher-level interface that performs filtering/reordering of inputs, supports more than two matrices for pairwise comparisons, etc. but figured it'd be good to get this reviewed/merged first.

# Example
Run a Mantel test over two 3x3 distance matrices using Pearson correlation and a two-sided test with 999 permutations:

```python
from skbio.math.stats.distance import mantel
x = [[0, 1, 2],
[1, 0, 3],
[2, 3, 0]]
y = [[0, 2, 7],
[2, 0, 6],
[7, 6, 0]]
mantel(x, y)
(0.7559289460184544, 0.654)
```

# What else changed?

- When constructing a `DistanceMatrix`, IDs are now optional. If not provided, monotonically-increasing integers (cast as strings) are used as the IDs.

- Added `DistanceMatrix.permute` method.

- Moved `bioenv` method out of `skbio.math.stats.distance.base` into its own `_bioenv` submodule (similar to what I did with `_mantel`). `nosetests --with-doctest` doesn't like having functions named the same as the module that they live in (see https://github.com/nose-devs/nose/issues/92).