ENH: plotting methods can unpack labeled data

.gitignore

@@ -13,6 +13,7 @@
 .project
 .pydevproject
 .swp
+.idea
 
 # Compiled source #
 ###################

.travis.yml

@@ -26,6 +26,7 @@ env:
     - secure: "dfjNqGKzQG5bu3FnDNwLG8H/C4QoieFo4PfFmZPdM2RY7WIzukwKFNT6kiDfOrpwt+2bR7FhzjOGlDECGtlGOtYPN8XuXGjhcP4a4IfakdbDfF+D3NPIpf5VlE6776k0VpvcZBTMYJKNFIMc7QPkOwjvNJ2aXyfe3hBuGlKJzQU="
     - BUILD_DOCS=false
     - NUMPY=numpy
+    - PANDAS=
     - NPROC=2
     - TEST_ARGS=--no-pep8
 
@@ -36,7 +37,7 @@ matrix:
     - python: 2.6
       env: NUMPY=numpy==1.6 MOCK=mock==1.0.1
     - python: 2.7
-      env: MOCK=mock
+      env: MOCK=mock PANDAS=pandas
     - python: 3.3
     - python: 3.4
     - python: 2.7
@@ -62,7 +63,7 @@ install:
     pip install --upgrade setuptools
   # Install only from travis wheelhouse
   - if [ -z "$PRE" ]; then
-        wheelhouse_pip_install python-dateutil $NUMPY pyparsing pillow sphinx!=1.3.0;
+        wheelhouse_pip_install python-dateutil $NUMPY $PANDAS pyparsing pillow sphinx!=1.3.0;
     else
         pip install $PRE python-dateutil $NUMPY pyparsing pillow sphinx!=1.3.0;
     fi

boilerplate.py

@@ -8,6 +8,7 @@
 itself, whereas the generatable content must be edited via templates in
 this file.
 
+This file is python 3 only due to the use of `inspect`
 """
 # We did try to do the wrapping the smart way,
 # with callable functions and new.function, but could never get the
@@ -209,7 +210,12 @@ def format_value(value):
                 mappable = ''
 
             # Get argspec of wrapped function
-            args, varargs, varkw, defaults = inspect.getargspec(getattr(Axes, func))
+            base_func = getattr(Axes, func)
+            has_data = 'data' in inspect.signature(base_func).parameters
+            work_func = inspect.unwrap(base_func)
+
+            args, varargs, varkw, defaults = inspect.getargspec(work_func)
+
             args.pop(0)  # remove 'self' argument
             if defaults is None:
                 defaults = ()
@@ -222,6 +228,15 @@ def format_value(value):
                     def_edited.append(val)
                 defaults = tuple(def_edited)
 
+            # Add a data keyword argument if needed (fmt is PLOT_TEMPLATE) and
+            # possible (if *args is used, we can't just add a data
+            # argument in front of it since it would gobble one of the
+            # arguments the user means to pass via *args)
+            # This needs to be done here so that it goes into call
+            if not varargs and fmt is PLOT_TEMPLATE and has_data:
+                args.append('data')
+                defaults = defaults + (None,)
+
             # How to call the wrapped function
             call = []
             for i, arg in enumerate(args):
@@ -230,6 +245,14 @@ def format_value(value):
                 else:
                     call.append('%s=%s' % (arg, arg))
 
+            # remove the data keyword as it was needed above to go into the
+            # call but should go after `hold` in the signature.
+            # This is janky as all get out, but hopefully boilerplate will
+            # be retired soon.
+            if not varargs and fmt is PLOT_TEMPLATE and has_data:
+                args.pop()
+                defaults = defaults[:-1]
+
             if varargs is not None:
                 call.append('*' + varargs)
             if varkw is not None:
@@ -249,6 +272,9 @@ def format_value(value):
             elif fmt is PLOT_TEMPLATE:
                 args.append('hold')
                 defaults = defaults + (None,)
+                if has_data:
+                    args.append('data')
+                    defaults = defaults + (None,)
                 sethold = ''
 
             # Now we can build the argspec for defining the wrapper

doc/users/whats_new/2015-07-30_unpack_labeled_data.rst

@@ -0,0 +1,36 @@
+Working with labeled data like pandas DataFrames
+------------------------------------------------
+Plot methods which take arrays as inputs can now also work with labeled data
+and unpack such data.
+
+This means that the following two examples produce the same plot:
+
+Example ::
+
+    df = pandas.DataFrame({"var1":[1,2,3,4,5,6], "var2":[1,2,3,4,5,6]})
+    plt.plot(df["var1"], df["var2"])
+
+
+Example ::
+
+    plt.plot("var1", "var2", data=df)
+
+This works for most plotting methods, which expect arrays/sequences as
+inputs.  ``data`` can be anything which supports ``__getitem__``
+(``dict``, ``pandas.DataFrame``, ``h5py``, ...) to access ``array`` like
+values with string keys.
+
+In addition to this, some other changes were made, which makes working with
+labeled data (ex ``pandas.Series``) easier:
+
+* For plotting methods with ``label`` keyword argument, one of the
+  data inputs is designated as the label source.  If the user does not
+  supply a ``label`` that value object will be introspected for a
+  label, currently by looking for a ``name`` attribute.  If the value
+  object does not have a ``name`` attribute but was specified by as a
+  key into the ``data`` kwarg, then the key is used.  In the above
+  examples, this results in an implicit ``label="var2"`` for both
+  cases.
+
+* ``plot()`` now uses the index of a ``Series`` instead of
+  ``np.arange(len(y))``, if no ``x`` argument is supplied.