biocore/scikit-bio — pull request #283 by ElBrogrammer (2014-04-21 21:14:36+00:00)
Title: Do you even alpha diversity, bro?

Preamble
------------
I'm about the biggest hypocrite out there by submitting this pull request; *apologies in advance* for the extreme length. **Not ready for merge!**

What is this?
----------------
I added a new subpackage `skbio.maths.diversity.alpha` with various alpha diversity metrics ported from PyCogent. I only ported ones that were being imported in QIIME, which ends up being most of them. You can access these measures like so:

```python
from skbio.maths.diversity.alpha import observed_species, chao1
observed_species([42, 42, 42])

# import all public alpha diversity measures, ignoring any private helper functions
from skbio.maths.diversity.alpha import *
ace([0,1,2,3])
```

Most of the simple alpha diversity measures are actually located in `skbio.maths.diversity.alpha.base`, and more complicated ones are in their own modules, e.g., `skbio.maths.diversity.alpha.chao1`. However, all public functions are available in `skbio.maths.diversity.alpha`, so from a user's standpoint they aren't exposed to the additional structure.

I modeled the subpackage structure, docstrings, input validation, etc. around scipy's `scipy.spatial.distance` subpackage (which has a large number of distance functions, similar in concept to what we have here).

What changed in the port?
----------------------------------
I updated a large portion of the code to be cleaner, more numpythonic, and efficient, though **there are several places I didn't touch** (e.g., `skbio.maths.diversity.alpha.lladser`). I'd like to clean up some of the more complicated functions, but wanted to get a pull request out so ~~bros~~ devs could start reviewing.

I added numpydoc docstrings to every public function and many of the private ones (these are pretty minimal right now, but most have references at least).

There's also centralized validation/conversion of input so Python data structures and numpy vectors are supported by all measures, and errors are handled in a consistent manner.

What still needs to be done?
------------------------------------
- [ ] add usage examples (at least a few to the top-level subpackage `__init__.py`)
- [ ] follow up with original authors regarding a few of the methods
- [ ] clean up some of the untouched code
- [ ] convert monospace equations to latex equations