Repository: pandas-dev/pandas

Issue:
Deprecating the trellis rplot module
Original title: rplot.rst needs cleaning up

---

http://pandas.pydata.org/pandas-docs/dev/rplot.html

plot style, dimensions, grids, legend.



Discussion:
@cpcloud doc-man?

Sure! Good a time as any to learn this dark corner of pandas :)

I'll clean this up, but IMHO I think the rplot functionality should be deprecated in the next major release of pandas (1.0). Nobody really maintains this. The paucity of issues about rplot suggests that this doesn't see much use in the wild either. Just my 2c.

@jtratner @jreback @y-p thoughts?

rplot is really _useful_ (and I ported it back to an earlier release because I wanted to use it for a project) but it's slow, somewhat visually unappealing, and (at least for me) hard to figure out how to tweak.

What if we split off visualization into a separate library that pandas would keep as a dep (i.e., the plotting module would provide `plot()` and allied methods)? We could then have a separate set of maintainers take primary responsibility for that module (and be able to more easily bring in the kinds of things that @olgabot, @TomAugspurger  and I believe @JanSchulz have worked on on and off).

Alternatively, I get the sense that rplot was trying to bring in some of the concepts that the `ggplot` port would now cover, so maybe we could bring it in that way.

or even if we didn't split it off, just give a few people the responsibility for focusing on pandas visualizations and emphasizing making them look good.

I think it would make sense to split most of the plotting (from pandas and statsmodels) off into two projects (one ggplot-codeing-style like, one matplotlib-coding-style like). There are currently so many (matplotlib-based and otherwise -> JS, d3,...) python plotting libs showing up, it looks like some consolidation would be nice to not waste so much effort...

Plus right now you can drop in rplot as far back as 0.11 and it'll work, so
already seems like viz isn't strongly tied into pandas internals.

ggplot2 does indeed have very strong support for faceting so if this was available elsewhere rplot _is_ 
somewhat redundant. 

Anyway, as I said elsewhere, my view is that pandas shouldn't focus on viz if a suitable alternative emerges.
That wasn't the case 2-3 years ago but things may be slowly changing. Viz is certainly important enough 
to have it's own space.

I looked around, there a bunch of libraries at this point, many of which use pandas internally (e.g., [seaborn](https://github.com/mwaskom/seaborn)) so I don't really think it makes sense to go start something new. It would be nice to standardize on one or two though.

Coming back to this older thread (as there was a discussion on the docs of it in #8351): I think it is a good time to reconsider the status of the trellis plotting interface in pandas (tools/rplot.py) and the arguments made above:
- as @cpcloud mentions above, nobody really maintains or enhances this. And hasn't changed the last year since that comment (https://github.com/pydata/pandas/commits/master/pandas/tools/rplot.py). While there are some open issues with bugs about this.
- above there was spoken about splitting it off in seperate projects (eg a ggplot-like one). In the meantime, I think, these projects have already emerged, most notably in python-ggplot and seaborn I think (among probably others)

**So**: would deprecating the trellis rplot interface in pandas make sense?

@orbitfold You are the original author of this I think. What is your opinion on this? 
@jtratner @JanSchulz 

As proposed by @TomAugspurger in #8351, we could make a doc section showing for each example of the current pandas trellis interface, how to do the equivalent using python-ggplot and/or seaborn for easy transitioning.

I think you summed up the current situation pretty well: seaborn has trellis plots and it seems that much of the work on "matplotlib style higher plotting functions" is going into that library.

As someone looked into how much this interface is actually used? SO?

SO search on "[pandas] rplot" gives one question (and one answer to another question): http://stackoverflow.com/search?q=[pandas]+rplot (and other similar searches did no yield more)

older thread but anybody for killing trellis plotting in 0.16.0 and just pointing to seaborn?

We should at least start warning / deprecating.

yes let's do that at least (maybe a nice box at the top of the section)

@TomAugspurger Did you already have some examples of how to do it in seaborn? I vaguely can remember you posted it once in an issue? 
@JanSchulz would you be interested in giving some examples of `ggplot`? So basically for some of the current examples, just give the exact equivalent in ggplot


Resolving patch:
diff --git a/pandas/tools/rplot.py b/pandas/tools/rplot.py
--- a/pandas/tools/rplot.py
+++ b/pandas/tools/rplot.py
@@ -1,4 +1,5 @@
 import random
+import warnings
 from copy import deepcopy
 from pandas.core.common import _values_from_object
 
@@ -9,6 +10,16 @@
 # * Make sure legends work properly
 #
 
+
+warnings.warn("\n"
+              "The rplot trellis plotting interface is deprecated and will be "
+              "removed in a future version. We refer to external packages "
+              "like seaborn for similar but more refined functionality. \n\n"
+              "See our docs http://pandas.pydata.org/pandas-docs/stable/visualization.html#rplot "
+              "for some example how to convert your existing code to these "
+              "packages.", FutureWarning)
+
+
 class Scale:
     """
     Base class for mapping between graphical and data attributes.


Test patch: