biocore/scikit-bio — pull request #637 by jairideout (2014-08-21 22:12:24+00:00)
Title: Add basic 3-D scatterplot functionality to OrdinationResults

# Not ready for merge

I have a couple of questions I'd like to resolve first (posted at the bottom).

# Description

Added basic 3-D scatterplot support using matplotlib to `skbio.stats.ordination.OrdinationResults.plot`. Points can optionally be colored by metadata in a `DataFrame`. Both categorical and continuous data are supported, as well as matplotlib colormaps and specifying which coordinates to plot on which axis.

`OrdinationResults` can also be automatically viewed as PNG/SVG within the IPython Notebook (via `_repr_png_` and `_repr_svg`). Public properties (`png` and `svg`) are also provided to allow direct access to these rendering methods.

**Note:** As noted in the method docstring, this functionality is meant to be very basic and *does not* attempt to replicate [EMPeror](http://biocore.github.io/emperor/). The functionality here is mainly for quick, convenient inspection of ordination results, e.g., within the IPython Notebook. Further customization, generation of high-quality figures, etc. should still happen within EMPeror.

# Demo

The examples in this demo use data from the *88 Soils* study. Assume we have PCoA results stored in a variable `pcoa_results` and metadata in a `DataFrame` named `df`.

We can directly inspect the object to see an SVG rendering of the plot without any metadata:

![screen shot 2014-08-21 at 2 36 57 pm](https://cloud.githubusercontent.com/assets/1847232/4003912/59c59ebc-297b-11e4-96ea-6cbf51129ecb.png)

To generate a matplotlib scatterplot with numeric metadata (pH):

![screen shot 2014-08-21 at 2 43 03 pm](https://cloud.githubusercontent.com/assets/1847232/4004028/30fd8868-297c-11e4-834c-249e1dc9d17c.png)

Plotting categorical data (feature):

![screen shot 2014-08-21 at 2 48 02 pm](https://cloud.githubusercontent.com/assets/1847232/4004094/e57af9b0-297c-11e4-84fc-4063e4853070.png)

# Questions

1. Should `axis1`, `axis2`, and `axis3` parameters be replaced with a tuple `(axis1, axis2, axis3)`? Then the default would be `(0, 1, 2)`.

2. The axis labels are currently hardcoded to be `'PC %d' % axis1 + 1`, etc. This is specific to PCoA results, but right now we're using `OrdinationResults` to store four different ordination techniques. I'm not sure how best to handle this: does it make sense to have a `PCoAResults` subclass that provides this plotting functionality? If not, how should the axis labels be handled for other types of ordination results? See the `TODO` comment in the code for where this is happening.

3. `cmap` currently defaults to the colormap specified the user's matplotlib rc file. The colormap is used for both numeric and categorical data. Thus, the default colorbar may be better for numeric data instead of categorical data (or vice versa). Should the code be updated to choose a sane colormap based on whether the data is numeric or categorical, or should it continue to use whatever the user's defined in their rc file? In either case, I think we should always allow the user to specify the exact colormap they want -- I'm only concerned about the default behavior here.

4. The plots render correctly within the IPython Notebook, but when plotted within Sphinx (e.g., when the docs are generated), the legends are cut off:

![screen shot 2014-08-21 at 3 08 05 pm](https://cloud.githubusercontent.com/assets/1847232/4004310/ab1c3092-297f-11e4-91bd-92b6d9092853.png)

Does anyone know how to fix this? I messed around with it for awhile but couldn't get it to work.

Fixes #518.

Side note: I'm hoping to add a recipe to the [scikit-bio cookbook](https://github.com/biocore/scikit-bio-cookbook) soon that highlights this functionality.