From 83ad8564353e4ac307c2f0a006272e10a6e660ff Mon Sep 17 00:00:00 2001 From: Silviu Draghici Date: Sun, 13 May 2018 16:31:03 -0400 Subject: [PATCH] added documentation for new mult_bar function --- lib/matplotlib/axes/_axes.py | 107 +++++++++++++++++++++++++++++++++++ lib/matplotlib/pyplot.py | 71 +++++++++++++++++------ tools/boilerplate.py | 1 + 3 files changed, 161 insertions(+), 18 deletions(-) diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py index d6e4f50a2d7e..047ba659654f 100644 --- a/lib/matplotlib/axes/_axes.py +++ b/lib/matplotlib/axes/_axes.py @@ -2201,6 +2201,113 @@ def barh(self, y, width, height=0.8, left=None, *, align="center", align=align, **kwargs) return patches + @docstring.dedent_interpd + def multi_bar(self, pos, length, thickness=0.8, *, + style='grouped', orientation='vertical', **kwargs): + r""" + Make a bar plot from two dimensional data. + + Call signatures:: + + multi_bar(pos, length, *, style='grouped', **kwargs) + multi_bar(pos, length, thickness, *, style='grouped', **kwargs) + multi_bar(pos, length, thickness, *, + style='stacked', orientation='vertical', **kwargs) + + The bars are positioned at *pos* with the given style and orientation. + Their dimensions are given by *length* and *thickness*. + + *length* is a 2-dimensional array (N,M) where N is the numer of + positions a M is the number of bars per position. + + Parameters + ---------- + pos : sequence of scalars + The x or y coordinates of the bars, depending on orientation. + + length : array-like of shape(N,M). The lengths of the bars. + N is the number of bar positions (same as the length of pos) + and M the number of bars per pos. + + thickness : scalar or array-like, optional + The thickness(') of the bars (default: 0.8). + + style : {'grouped', 'stacked'}, optional, default: 'grouped' + How of the bars at a pos are placed with respect to each other: + + - 'grouped': Bars are placed next to eachother with *pos* being + the midpoint. + - 'stacked': Bars are placed on on top of another. + + orientation : {'vertical', 'horizontal'}, optional + How the bars are to be oriented. + + Returns + ------- + `List of .BarContainer` + There are M containers in the list. + Each container has the bars created from a column of *length* + and optionally errorbars. + + Other Parameters + ---------------- + color : scalar or array-like, optional + The colors of the bar faces. + + edgecolor : scalar or array-like, optional + The colors of the bar edges. + + linewidth : scalar or array-like, optional + Width of the bar edge(s). If 0, don't draw edges. + + tick_label : string or array-like, optional + The tick labels of the bars. + Default: None (Use default numeric labels.) + + xerr, yerr : scalar or array-like of shape(N,) or shape(2,N), optional + If not *None*, add horizontal / vertical errorbars to the bar tips. + The values are +/- sizes relative to the data: + + - scalar: symmetric +/- values for all bars + - shape(N,): symmetric +/- values for each bar + - shape(2,N): separate + and - values for each bar + + Default: None + + ecolor : scalar or array-like, optional, default: 'black' + The line color of the errorbars. + + capsize : scalar, optional + The length of the error bar caps in points. + Default: None, which will take the value from + :rc:`errorbar.capsize`. + + error_kw : dict, optional + Dictionary of kwargs to be passed to the `~.Axes.errorbar` + method. Values of *ecolor* or *capsize* defined here take + precedence over the independent kwargs. + + log : bool, optional, default: False + If *True*, set the y-axis to be log scale. + + Notes + ----- + The optional arguments *color*, *edgecolor*, *linewidth*, + *xerr*, and *yerr* can be either scalars or an array-like of shape(N,M) + matching the shape of *length*. + Detail: *xerr* and *yerr* are passed directly to + :meth:`errorbar`, so they can also have shape 2xN for + independent specification of lower and upper errors. + + The optional argument *label* should be an array-like of length M. + + Other optional kwargs: + + %(Rectangle)s + + """ + pass + @_preprocess_data(label_namer=None) @docstring.dedent_interpd def broken_barh(self, xranges, yrange, **kwargs): diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py index 6fe1d3296772..c797a43ffcca 100644 --- a/lib/matplotlib/pyplot.py +++ b/lib/matplotlib/pyplot.py @@ -2259,8 +2259,21 @@ def axvspan(xmin, xmax, ymin=0, ymax=1, **kwargs): # Autogenerated by boilerplate.py. Do not edit as changes will be lost. @docstring.copy_dedent(Axes.bar) -def bar(*args, data=None, **kwargs): - return gca().bar(*args, data=data, **kwargs) +def bar( + x, height, width=0.8, bottom=None, *, align='center', + data=None, **kwargs): + return gca().bar( + x=x, height=height, width=width, bottom=bottom, align=align, + data=data, **kwargs) + +# Autogenerated by boilerplate.py. Do not edit as changes will be lost. +@docstring.copy_dedent(Axes.multi_bar) +def multi_bar( + pos, length, thickness=0.8, *, style='grouped', + orientation='vertical', **kwargs): + return gca().multi_bar( + pos=pos, length=length, thickness=thickness, style=style, + orientation=orientation, **kwargs) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. @docstring.copy_dedent(Axes.barbs) @@ -2269,8 +2282,10 @@ def barbs(*args, data=None, **kw): # Autogenerated by boilerplate.py. Do not edit as changes will be lost. @docstring.copy_dedent(Axes.barh) -def barh(*args, **kwargs): - return gca().barh(*args, **kwargs) +def barh(y, width, height=0.8, left=None, *, align='center', **kwargs): + return gca().barh( + y=y, width=width, height=height, left=left, align=align, + **kwargs) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. @docstring.copy_dedent(Axes.boxplot) @@ -2496,8 +2511,8 @@ def magnitude_spectrum( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. @docstring.copy_dedent(Axes.margins) -def margins(*args, **kw): - return gca().margins(*args, **kw) +def margins(*margins, x=None, y=None, tight=True): + return gca().margins(*margins, x=x, y=y, tight=tight) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. @docstring.copy_dedent(Axes.minorticks_off) @@ -2511,15 +2526,25 @@ def minorticks_on(): # Autogenerated by boilerplate.py. Do not edit as changes will be lost. @_autogen_docstring(Axes.pcolor) -def pcolor(*args, data=None, **kwargs): - __ret = gca().pcolor(*args, data=data, **kwargs) +def pcolor( + *args, alpha=None, norm=None, cmap=None, vmin=None, + vmax=None, data=None, **kwargs): + __ret = gca().pcolor( + *args, alpha=alpha, norm=norm, cmap=cmap, vmin=vmin, + vmax=vmax, data=data, **kwargs) sci(__ret) return __ret # Autogenerated by boilerplate.py. Do not edit as changes will be lost. @_autogen_docstring(Axes.pcolormesh) -def pcolormesh(*args, data=None, **kwargs): - __ret = gca().pcolormesh(*args, data=data, **kwargs) +def pcolormesh( + *args, alpha=None, norm=None, cmap=None, vmin=None, + vmax=None, shading='flat', antialiased=False, data=None, + **kwargs): + __ret = gca().pcolormesh( + *args, alpha=alpha, norm=norm, cmap=cmap, vmin=vmin, + vmax=vmax, shading=shading, antialiased=antialiased, + data=data, **kwargs) sci(__ret) return __ret @@ -2550,8 +2575,9 @@ def pie( # Autogenerated by boilerplate.py. Do not edit as changes will be lost. @docstring.copy_dedent(Axes.plot) -def plot(*args, data=None, **kwargs): - return gca().plot(*args, data=data, **kwargs) +def plot(*args, scalex=True, scaley=True, data=None, **kwargs): + return gca().plot( + *args, scalex=scalex, scaley=scaley, data=data, **kwargs) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. @docstring.copy_dedent(Axes.plot_date) @@ -2642,13 +2668,17 @@ def stackplot(x, *args, data=None, **kwargs): # Autogenerated by boilerplate.py. Do not edit as changes will be lost. @docstring.copy_dedent(Axes.stem) -def stem(*args, data=None, **kwargs): - return gca().stem(*args, data=data, **kwargs) +def stem( + *args, linefmt=None, markerfmt=None, basefmt=None, bottom=0, + label=None, data=None): + return gca().stem( + *args, linefmt=linefmt, markerfmt=markerfmt, basefmt=basefmt, + bottom=bottom, label=label, data=data) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. @docstring.copy_dedent(Axes.step) -def step(x, y, *args, data=None, **kwargs): - return gca().step(x=x, y=y, *args, data=data, **kwargs) +def step(x, y, *args, where='pre', data=None, **kwargs): + return gca().step(x=x, y=y, *args, where=where, data=data, **kwargs) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. @_autogen_docstring(Axes.streamplot) @@ -2685,8 +2715,13 @@ def tick_params(axis='both', **kwargs): # Autogenerated by boilerplate.py. Do not edit as changes will be lost. @docstring.copy_dedent(Axes.ticklabel_format) -def ticklabel_format(**kwargs): - return gca().ticklabel_format(**kwargs) +def ticklabel_format( + *, axis='both', style='', scilimits=None, useOffset=None, + useLocale=None, useMathText=None): + return gca().ticklabel_format( + axis=axis, style=style, scilimits=scilimits, + useOffset=useOffset, useLocale=useLocale, + useMathText=useMathText) # Autogenerated by boilerplate.py. Do not edit as changes will be lost. @_autogen_docstring(Axes.tricontour) diff --git a/tools/boilerplate.py b/tools/boilerplate.py index 682fe3b2cef4..ad13f79fd952 100644 --- a/tools/boilerplate.py +++ b/tools/boilerplate.py @@ -84,6 +84,7 @@ def boilerplate_gen(): 'axvline', 'axvspan', 'bar', + 'multi_bar', 'barbs', 'barh', 'boxplot',