mwaskom/seaborn — pull request #106 by mwaskom (2014-02-14 06:48:07+00:00)
Title: WIP: Omnibus enhancements to linear model plotting and structured plot grids

This has a few large changes all at once, as they are interrelated:

- The `FacetGrid` class, which abstracts the data-aware structured grid out of the previous version of `lmplot` such that it can be used to facet arbitrary plots very easily. There are a few other nice new things about `FacetGrid`, primarily that it can draw its legend outside of the axes, and `despine` is called automatically.

- Correspondingly, the `lmplot` and `regplot` functions have been completely rewritten to take advantage of this new machinery. The `lmplot` interface should mostly be the same, save a few things that were broken in the interest of making progress on unifying APIs across the package, and a couple of advantages here and there. There is a more dramatic change to `regplot`, which now is an "Axes-level" function. This should be good going forward in that `regplot` and `lmplot` can do all the same things (plot with different regression models, remove confounding variables, etc.), but `regplot` can now do them flexibly into an existing Axes. It also means that `lmplot` is just a thin wrapper around `regplot` and `FacetGrid`, making for overall much cleaner code. As discussed in #101, this will mean the current behavior of `regplot` will vanish on `master` for a while, but the next task will be to introduce `jointplot` which will return the marginal histrograms, etc.

- There are three new related functions, `barplot`, `jointplot`, and `factorplot` for visualizing linear models with discrete or categorical independent variables. The `barplot` and `jointplot` functions have a similar relationship to `factorplot` that `regplot` has to `lmplot`, although `factorplot` can also draw boxplots. (The current `boxplot` API cannot be straightforwardly used with `FacetGrid`, but the addition of `kind="box"` in `factorplot` should avoid the need to break it.

- As a an internal detail, the implementation of the new plotting functions has been changed substantially, with the outward facing interface functions serving as very lightweight wrappers around new `_Plotter` objects. This has overall allowed for *much* cleaner code, and importantly, far better unittest test coverage of the internal computations. Going forward, this is how I would like all, or most, of the plotting code to work. We'll continue to test the docs using `ipnbdoctest.py` (which I also intend to separate out and release as a standalone tool, when I get a chance), but this relieves a lot of the pressure on the docs to also serve as a test suite.

The major remaining task is to update the docs to reflect the changes. In the meantime, my [Titanic](http://nbviewer.ipython.org/8224591 notebook shows off most of the goodies.

This is going to continue to get rounded out over the next few days/weeks, but all of the heavy lifting is done. The tests fail because it breaks the docs and I have not updated them yet, but all of the new code is well-covered by unit-tests, which pass.

Also, at some point the commit history got borked, but I didn't catch it until later. The diff is clean, so I'm inclined to leave it, but if there is weather git guru who wants to help me drop the duplicated commits that would be excellent.

I'd definitely like some adventurous users to try this out before I merge to help me round out the corners of the APIs, and see if anything obvious is missing. @twiecki I know you were working on this branch before, it should be pretty stable now. @olgabot, there's stuff in here you've expressed interest in previously.