Importance#

Since the limits of the whiskers are computed arithmetically, thereis an implicit assumption of normality in box and whisker plots.This primarily affects which data points are classified as outliers.

Allowing transformations to the data and the results used to drawboxplots will allow users to opt-out of that assumption if thedata are known to not fit a normal distribution.

Below is an example of howAxes.boxplot classifies outliers of lognormaldata differently depending one these types of transforms.

importnumpyasnpimportmatplotlib.pyplotaspltfrommatplotlibimportcbooknp.random.seed(0)fig,ax=plt.subplots(figsize=(4,6))ax.set_yscale('log')data=np.random.lognormal(-1.75,2.75,size=37)stats=cbook.boxplot_stats(data,labels=['arithmetic'])logstats=cbook.boxplot_stats(np.log(data),labels=['log-transformed'])forlsdictinlogstats:forkey,valueinlsdict.items():ifkey!='label':lsdict[key]=np.exp(value)stats.extend(logstats)ax.bxp(stats)fig.show()

(Sourcecode,2x.png,png)

Passing transform functions tocbook.boxplots_stats#

This MEP proposes that two parameters (e.g.,transform_in andtransform_out be added to the cookbook function that computes thestatistics for the boxplot function. These will be optional keyword-onlyarguments and can easily be set tolambdax:x as a no-op when omittedby the user. Thetransform_in function will be applied to the dataas theboxplot_stats function loops through each subset of the datapassed to it. After the list of statistics dictionaries are computed thetransform_out function is applied to each value in the dictionaries.

These transformations can then be added to the call signature ofAxes.boxplot with little impact to that method's complexity. This isbecause they can be directly passed tocbook.boxplot_stats.Alternatively,Axes.boxplot could be modified to accept an optionalstatistical function kwarg and a dictionary of parameters to be directlypassed to it.

At this point in the implementation users and external libraries likeseaborn would have complete control via theAxes.boxplot method. Moreimportantly, at the very least, seaborn would require no changes to itsAPI to allow users to take advantage of these new options.

Simplifications to theAxes.boxplot API and other functions#

Simplifying the boxplot method consists primarily of deprecating and thenremoving the redundant parameters. Optionally, a next step would includerectifying minor terminological inconsistencies betweenAxes.boxplotandAxes.bxp.

The parameters to be deprecated and removed include:

1. usermedians - processed by 10 SLOC, 3if blocks, afor loop

2. conf_intervals - handled by 15 SLOC, 6if blocks, afor loop

3. sym - processed by 12 SLOC, 4if blocks

Removing thesym option allows all code in handling the remainingstyling parameters to be moved toAxes.bxp. This doesn't removeany complexity, but does reinforce the single responsibility principleamongAxes.bxp,cbook.boxplot_stats, andAxes.boxplot.

Additionally, thenotch parameter could be renamedshownotchesto be consistent withAxes.bxp. This kind of cleanup could be takena step further and thewhis,bootstrap,autorange couldbe rolled into the kwargs passed to the newstatfxn parameter.

Schedule#

An accelerated timeline could look like the following:

1. v2.0.1 add transforms tocbook.boxplots_stats, expose inAxes.boxplot

2. v2.1.0 Initial Deprecations , and using 2D NumPy arrays as input

   1. Using 2D NumPy arrays as input. The semantics around 2D arrays are generally confusing.

   2. usermedians,conf_intervals,sym parameters

3. v2.2.0

   1. removeusermedians,conf_intervals,sym parameters

   2. deprecatenotch in favor ofshownotches to be consistent withother parameters andAxes.bxp

4. v2.3.0

   1. removenotch parameter

   2. move all style and artist toggling logic toAxes.bxp suchAxes.boxplotis little more than a broker betweenAxes.bxp andcbook.boxplots_stats

Anticipated Impacts to Users#

As described above deprecatingusermedians andconf_intervalswill likely impact few users. Those who will be impacted are almostcertainly advanced users who will be able to adapt to the change.

Deprecating thesym option may import more users and effort shouldbe taken to collect community feedback on this.

Anticipated Impacts to Downstream Libraries#

The source code (GitHub master as of 2016-10-17) was inspected forseaborn and python-ggplot to see if these changes would impact theiruse. None of the parameters nominated for removal in this MEP are used byseaborn. The seaborn APIs that use matplotlib's boxplot function allowuser's to pass arbitrary**kwargs through to matplotlib's API. Thusseaborn users with modern matplotlib installations will be able to takefull advantage of any new features added as a result of this MEP.

Python-ggplot has implemented its own function to draw boxplots. Therefore,no impact can come to it as a result of implementing this MEP.

Variations on the theme#

This MEP can be divided into a few loosely coupled components:

1. Allowing pre- and post-computation transformation function incbook.boxplot_stats

2. Exposing that transformation in theAxes.boxplot API

3. Removing redundant statistical options inAxes.boxplot

4. Shifting all styling parameter processing fromAxes.boxplot toAxes.bxp.

With this approach, #2 depends and #1, and #4 depends on #3.

There are two possible approaches to #2. The first and most direct wouldbe to mirror the newtransform_in andtransform_out parameters ofcbook.boxplot_stats inAxes.boxplot and pass them directly.

The second approach would be to addstatfxn andstatfxn_argsparameters toAxes.boxplot. Under this implementation, the defaultvalue ofstatfxn would becbook.boxplot_stats, but users couldpass their own function. Thentransform_in andtransform_out wouldthen be passed as elements of thestatfxn_args parameter.

defboxplot_stats(data,...,transform_in=None,transform_out=None):iftransform_inisNone:transform_in=lambdax:xiftransform_outisNone:transform_out=lambdax:xoutput=[]for_dindata:d=transform_in(_d)stat_dict=do_stats(d)forkey,valueinstat_dict.item():ifkey!='label':stat_dict[key]=transform_out(value)output.append(d)returnoutputclassAxes(...):defboxplot_option1(data,...,transform_in=None,transform_out=None):stats=cbook.boxplot_stats(data,...,transform_in=transform_in,transform_out=transform_out)returnself.bxp(stats,...)defboxplot_option2(data,...,statfxn=None,**statopts):ifstatfxnisNone:statfxn=boxplot_statsstats=statfxn(data,**statopts)returnself.bxp(stats,...)

Both cases would allow users to do the following:

fig,ax1=plt.subplots()artists1=ax1.boxplot_optionX(data,transform_in=np.log,transform_out=np.exp)

But Option Two lets a user write a completely custom stat function(e.g.,my_box_stats) with fancy BCA confidence intervals and thewhiskers set differently depending on some attribute of the data.

This is available under the current API:

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

fig,ax=plt.subplots()statopts=dict(transform_in=np.log,transform_out=np.exp)ax.boxplot(data,...,**statopts)

Users could also pass their own function to compute the stats:

fig,ax1=plt.subplots()ax1.boxplot(data,statfxn=my_box_stats,bootstrap_method='BCA',whisker_method='dynamic')

From the examples above, Option Two seems to have only marginal benefit,but in the context of downstream libraries like seaborn, its advantageis more apparent as the following would be possible without any patchesto seaborn:

importseaborntips=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 overallboxplot API in the current three functions. In practice however, downstreamlibraries like seaborn support versions of matplotlib dating back wellbefore the split. Thus, adding just a bit more flexibility to theAxes.boxplot could expose all the functionality to users of thedownstream libraries with modern matplotlib installation without interventionfrom the downstream library maintainers.

Doing less#

Another obvious alternative would be to omit the added pre- and post-computation transform functionality incbook.boxplot_stats andAxes.boxplot, and simply remove the redundant statistical and styleparameters as described above.

Doing nothing#

As with many things in life, doing nothing is an option here. This meanswe simply advocate for users and downstream libraries to take advantageof the split betweencbook.boxplot_stats andAxes.bxp and letthem decide how to provide an interface to that.