WIP: add to TOC, redo examples

phobson · phobson · commit 3013010ee419 · 2016-10-18T22:49:30.000-07:00
diff --git a/doc/devel/MEP/MEP28.rst b/doc/devel/MEP/MEP28.rst
@@ -216,25 +216,65 @@ There are two possible approaches to #2. The first and most direct would
 be to mirror the new ``transform_in`` and ``tranform_out`` parameters of
 ``cbook.boxplot_stats`` in ``Axes.boxplot`` and pass them directly.
 
-.. python:
-   fig, ax = plt.subplots()
-   data = mylib.load_data()
-   ax.boxplot(data, ..., transform_in=np.log, transform_out=np.exp)
-
 The second approach would be to add ``statfxn`` and ``statfxn_args``
 parameters to ``Axes.boxplot``. Under this implementation, the default
 value of ``statfxn`` would be ``cbook.boxplot_stats``, but users could
 pass their own function. Then ``transform_in`` and ``tranform_out`` would
 then be passed as elements of the ``statfxn_args`` parameter.
 
-Using matplotlib's stats function, this would look similar to this:
+.. python:
+   def boxplot_stats(data, ..., transform_in=None, transform_out=None):
+       if transform_in is None:
+           transform_in = lambda x: x
+
+       if transform_out is None:
+           transform_out = lambda x: x
+
+       output = []
+       for _d in data:
+           d = transform_in(_d)
+           stat_dict = do_stats(d)
+           for key, value in stat_dict.item():
+               if key != 'label':
+                   stat_dict[key] = transform_out(value)
+           output.append(d)
+       return output
+
+
+    class Axes(...):
+        def boxplot_option1(data, ..., transform_in=None, transform_out=None):
+            stats = cbook.boxplot_stats(data, ...,
+                                        transform_in=transform_in,
+                                        transform_out=transform_out)
+            return self.bxp(stats, ...)
+
+        def boxplot_option2(data, ..., statfxn=None, **statopts):
+            if statfxn is None:
+                statfxn = boxplot_stats
+            stats = statfxn(data, **statopts)
+            return self.bxp(stats, ...)
+
+Both cases would allow users to do the following:
 
 .. python:
-   fig, ax = plt.subplots()
-   statopts = dict(transform_in=np.log, transform_out=np.exp)
-   ax.boxplot(data, ..., statfxn_args=statopts)
+   fig, ax1 = plt.subplots()
+   artists1 = ax1.boxplot_optionX(data, transform_in=np.log,
+                                  transform_out=np.exp)
+
 
-Or more alternatively (depending on the implementation)
+But Option Two lets a user write a completely custom stat function
+(e.g., ``my_box_stats``) with fancy BCA confidence intervals and the
+whiskers set differently depending on some attribute of the data.
+
+This is available under the current API:
+
+.. python:
+   fig, ax1 = plt.subplots()
+   my_stats = my_box_stats(data, bootstrap_method='BCA',
+                           whisker_method='dynamic')
+   ax1.bxp(my_stats)
+
+And would be more concise with Option Two
 
 .. python:
    fig, ax = plt.subplots()
@@ -244,30 +284,22 @@ Or more alternatively (depending on the implementation)
 Users could also pass their own function to compute the stats:
 
 .. python:
-   from mylib import box_stats
-   fig, ax = plt.subplots()
-   statopts = dict(option1=True, niter_bootstrap=10000, bs_method='bca')
-   ax.boxplot(data, ..., statfxn=box_stats, statfxn_args=statopts)
-   ## or:
-   # ax.boxplot(data, ..., statfxn=box_stats, **statopts)
-
-The second approach is by far more flexible, though could probably be
-considered more advanced usage. The first approach, though more limited,
-would likely cover a majority of the use cases.
+   fig, ax1 = plt.subplots()
+   ax1.boxplot(data, statfxn=my_box_stats, bootstrap_method='BCA',
+               whisker_method='dynamic')
 
-To match this proposed functionality in matplotlib v1.5.3 and v2.0.0b4,
-one would do the following:
+From the examples above, Option Two seems to have only marginal benifit,
+but in the context of downstream libraries like seaborn, its advantage
+is more apparent as the following would be possible without any patches
+to seaborn:
 
 .. python:
-   fig, ax = plt.subplots()
-   log_data = [np.log(d) for d in data]
-   stats = cbook.boxplot_stats(log_data)
-   for s in stats:
-       for key, value in s.items():
-           if key != 'label':
-               s[key] = np.exp(value)
-
-   ax.bxp(stats, ...)
+   import seaborn
+   tips = seaborn.load_data('tips')
+   g = seaborn.factorplot(x="day", y="total_bill", hue="sex", data=tips,
+                          kind='box', palette="PRGn", shownotches=True,
+                          statfxn=my_box_stats, bootstrap_method='BCA',
+                          whisker_method='dynamic')
 
 This type of flexibility was the intention behind splitting the overall
 boxplot API in the current three functions. In practice however, downstream
diff --git a/doc/devel/MEP/index.rst b/doc/devel/MEP/index.rst
@@ -29,3 +29,4 @@ Matplotlib Enhancement Proposals
    MEP25
    MEP26
    MEP27
+   MEP28

-Original file line number
+Diff line change
    MEP25
    MEP26
    MEP27
 +   MEP28