From 1de59f49171f3dbe98085b745b26e609257b4c22 Mon Sep 17 00:00:00 2001 From: Kanchana Ranasinghe Date: Fri, 24 Mar 2017 09:34:06 -0700 Subject: [PATCH 1/4] DOC: convert axes.pie doctring to numpy doc --- lib/matplotlib/axes/_axes.py | 92 ++++++++++++++++++------------------ 1 file changed, 47 insertions(+), 45 deletions(-) diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py index 76dc174e2f53..af4959b42db4 100644 --- a/lib/matplotlib/axes/_axes.py +++ b/lib/matplotlib/axes/_axes.py @@ -2469,14 +2469,13 @@ def stem(self, *args, **kwargs): return stem_container @_preprocess_data(replace_names=['x', 'explode', 'labels', 'colors'], - label_namer=None) + label_namer=None) def pie(self, x, explode=None, labels=None, colors=None, autopct=None, pctdistance=0.6, shadow=False, labeldistance=1.1, startangle=None, radius=None, counterclock=True, wedgeprops=None, textprops=None, center=(0, 0), frame=False, rotatelabels=False): - r""" - Plot a pie chart. + r"""Plot a pie chart. Make a pie chart of array *x*. The fractional area of each wedge is given by x/sum(x). If sum(x) <= 1, then the values @@ -2484,90 +2483,93 @@ def pie(self, x, explode=None, labels=None, colors=None, be normalized. The wedges are plotted counterclockwise, by default starting from the x-axis. - Keyword arguments: + Parameters + ---------- + x : array + The input array used to make the pie chart. - *explode*: [ *None* | len(x) sequence ] + explode : None or array If not *None*, is a ``len(x)`` array which specifies the fraction of the radius with which to offset each wedge. - *colors*: [ *None* | color sequence ] + colors : None or array A sequence of matplotlib color args through which the pie chart will cycle. If `None`, will use the colors in the currently active cycle. - *labels*: [ *None* | len(x) sequence of strings ] + labels : None or list A sequence of strings providing the labels for each wedge - *autopct*: [ *None* | format string | format function ] + autopct : None or string or function If not *None*, is a string or function used to label the wedges with their numeric value. The label will be placed inside the wedge. If it is a format string, the label will be ``fmt%pct``. If it is a function, it will be called. - *pctdistance*: scalar + pctdistance : float The ratio between the center of each pie slice and the start of the text generated by *autopct*. Ignored if *autopct* is *None*; default is 0.6. - *labeldistance*: scalar + labeldistance : float The radial distance at which the pie labels are drawn - *shadow*: [ *False* | *True* ] + shadow : bool Draw a shadow beneath the pie. - *startangle*: [ *None* | Offset angle ] + startangle : None or float If not *None*, rotates the start of the pie chart by *angle* degrees counterclockwise from the x-axis. - *radius*: [ *None* | scalar ] + radius : None or float The radius of the pie, if *radius* is *None* it will be set to 1. - *counterclock*: [ *False* | *True* ] + counterclock : bool Specify fractions direction, clockwise or counterclockwise. - *wedgeprops*: [ *None* | dict of key value pairs ] + wedgeprops : None or dict Dict of arguments passed to the wedge objects making the pie. For example, you can pass in wedgeprops = { 'linewidth' : 3 } to set the width of the wedge border lines equal to 3. For more details, look at the doc/arguments of the wedge object. By default `clip_on=False`. - *textprops*: [ *None* | dict of key value pairs ] + textprops : None or dict Dict of arguments to pass to the text objects. - *center*: [ (0,0) | sequence of 2 scalars ] - Center position of the chart. - - *frame*: [ *False* | *True* ] - Plot axes frame with the chart. + center : list of float + Center position of the chart. Takes value (0,0) or is a sequence + of 2 scalars. - *rotatelabels*: [ *False* | *True* ] - Rotate each label to the angle of the corresponding slice. + frame : bool + Plot axes frame with the chart if true. - The pie chart will probably look best if the figure and axes are - square, or the Axes aspect is equal. e.g.:: + rotatelabels : bool + Rotate each label to the angle of the corresponding slice if true. - figure(figsize=(8,8)) - ax = axes([0.1, 0.1, 0.8, 0.8]) + Returns + ------- + patches : list + A sequence of :class:`matplotlib.patches.Wedge` instances - or:: + texts : list + A is a list of the label :class:`matplotlib.text.Text` instances. - axes(aspect=1) + autotexts : list + A is a list of :class:`~matplotlib.text.Text` instances for the + numeric labels. Is returned only if parameter *autopct* is + not *None*. - Return value: - If *autopct* is *None*, return the tuple (*patches*, *texts*): + Examples + -------- + The pie chart will probably look best if the figure and axes are + square, or the Axes aspect is equal. - - *patches* is a sequence of - :class:`matplotlib.patches.Wedge` instances + >>> figure(figsize=(8,8)) + >>> ax = axes([0.1, 0.1, 0.8, 0.8]) - - *texts* is a list of the label - :class:`matplotlib.text.Text` instances. + >>> axes(aspect=1) - If *autopct* is not *None*, return the tuple (*patches*, - *texts*, *autotexts*), where *patches* and *texts* are as - above, and *autotexts* is a list of - :class:`~matplotlib.text.Text` instances for the numeric - labels. """ x = np.array(x, np.float32) @@ -2623,9 +2625,9 @@ def get_next_color(): y += expl * math.sin(thetam) w = mpatches.Wedge((x, y), radius, 360. * min(theta1, theta2), - 360. * max(theta1, theta2), - facecolor=get_next_color(), - **wedgeprops) + 360. * max(theta1, theta2), + facecolor=get_next_color(), + **wedgeprops) slices.append(w) self.add_patch(w) w.set_label(label) @@ -2682,9 +2684,9 @@ def get_next_color(): self.set_frame_on(False) self.set_xlim((-1.25 + center[0], - 1.25 + center[0])) + 1.25 + center[0])) self.set_ylim((-1.25 + center[1], - 1.25 + center[1])) + 1.25 + center[1])) self.set_xticks([]) self.set_yticks([]) From 6e74e7d0b1f965660eeb34b70c4a701470b6a718 Mon Sep 17 00:00:00 2001 From: Paul Hobson Date: Fri, 24 Mar 2017 09:21:58 -0700 Subject: [PATCH 2/4] DOC: sync order of axes.pie args to call sig --- lib/matplotlib/axes/_axes.py | 62 +++++++++++++++++------------------- 1 file changed, 30 insertions(+), 32 deletions(-) diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py index af4959b42db4..4087299efe74 100644 --- a/lib/matplotlib/axes/_axes.py +++ b/lib/matplotlib/axes/_axes.py @@ -2478,73 +2478,73 @@ def pie(self, x, explode=None, labels=None, colors=None, r"""Plot a pie chart. Make a pie chart of array *x*. The fractional area of each - wedge is given by x/sum(x). If sum(x) <= 1, then the values - of x give the fractional area directly and the array will not - be normalized. The wedges are plotted counterclockwise, - by default starting from the x-axis. + wedge is given by ``x/sum(x)``. If ``sum(x) <= 1``, then the + values of x give the fractional area directly and the array + will not be normalized. The wedges are plotted + counterclockwise, by default starting from the x-axis. Parameters ---------- - x : array + x : array-like The input array used to make the pie chart. - explode : None or array + explode : array-like, optional (default is None) If not *None*, is a ``len(x)`` array which specifies the fraction of the radius with which to offset each wedge. - colors : None or array + labels : list, optional (default is None) + A sequence of strings providing the labels for each wedge + + colors : array-like, optional (default is None) A sequence of matplotlib color args through which the pie chart will cycle. If `None`, will use the colors in the currently active cycle. - labels : None or list - A sequence of strings providing the labels for each wedge - - autopct : None or string or function + autopct : None (default), string, or function, optional If not *None*, is a string or function used to label the wedges with their numeric value. The label will be placed inside the wedge. If it is a format string, the label will be ``fmt%pct``. If it is a function, it will be called. - pctdistance : float + pctdistance : float, optional (default is 0.6) The ratio between the center of each pie slice and the start of the text generated by *autopct*. Ignored if *autopct* is *None*; default is 0.6. - labeldistance : float - The radial distance at which the pie labels are drawn - - shadow : bool + shadow : bool, optional (default is False) Draw a shadow beneath the pie. - startangle : None or float + labeldistance : float, optional (default is 1.1) + The radial distance at which the pie labels are drawn + + startangle : float, optional (default is None) If not *None*, rotates the start of the pie chart by *angle* degrees counterclockwise from the x-axis. - radius : None or float - The radius of the pie, if *radius* is *None* it will be set to 1. + radius : float, optional (default is None) + The radius of the pie, if *radius* is *None* it will be set to 1. - counterclock : bool + counterclock : bool, optional (default is True) Specify fractions direction, clockwise or counterclockwise. - wedgeprops : None or dict + wedgeprops : dict, optional (default is None) Dict of arguments passed to the wedge objects making the pie. - For example, you can pass in wedgeprops = { 'linewidth' : 3 } + For example, you can pass in``wedgeprops = {'linewidth': 3}`` to set the width of the wedge border lines equal to 3. For more details, look at the doc/arguments of the wedge object. - By default `clip_on=False`. + By default ``clip_on=False``. - textprops : None or dict + textprops : dict, optional (default is None) Dict of arguments to pass to the text objects. - center : list of float - Center position of the chart. Takes value (0,0) or is a sequence - of 2 scalars. + center : list of float, optional (default is (0, 0)) + Center position of the chart. Takes value (0, 0) or is a + sequence of 2 scalars. - frame : bool + frame : bool, optional (default is False) Plot axes frame with the chart if true. - rotatelabels : bool + rotatelabels : bool, optional (default is False) Rotate each label to the angle of the corresponding slice if true. Returns @@ -2565,10 +2565,8 @@ def pie(self, x, explode=None, labels=None, colors=None, The pie chart will probably look best if the figure and axes are square, or the Axes aspect is equal. - >>> figure(figsize=(8,8)) - >>> ax = axes([0.1, 0.1, 0.8, 0.8]) + .. plot:: mpl_examples/pie_and_polar_charts/pie_demo_features.py - >>> axes(aspect=1) """ From 21284591fa9b408aa20b8216cbb14eca2221a91d Mon Sep 17 00:00:00 2001 From: Paul Hobson Date: Fri, 24 Mar 2017 10:03:14 -0700 Subject: [PATCH 3/4] DOC: move pie's Axes aspect advice into notes section --- lib/matplotlib/axes/_axes.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py index 4087299efe74..e2a02da3b93e 100644 --- a/lib/matplotlib/axes/_axes.py +++ b/lib/matplotlib/axes/_axes.py @@ -2560,11 +2560,13 @@ def pie(self, x, explode=None, labels=None, colors=None, numeric labels. Is returned only if parameter *autopct* is not *None*. - Examples - -------- + Notes + ----- The pie chart will probably look best if the figure and axes are square, or the Axes aspect is equal. + Examples + -------- .. plot:: mpl_examples/pie_and_polar_charts/pie_demo_features.py From abff9fff55fa94c6b16c5d17de35907f83644ec9 Mon Sep 17 00:00:00 2001 From: Paul Hobson Date: Fri, 24 Mar 2017 13:26:35 -0700 Subject: [PATCH 4/4] DOC: use colons for Axes.pie defaults, etc. --- lib/matplotlib/axes/_axes.py | 39 ++++++++++++++++++------------------ 1 file changed, 20 insertions(+), 19 deletions(-) diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py index e2a02da3b93e..a1c63cf4577e 100644 --- a/lib/matplotlib/axes/_axes.py +++ b/lib/matplotlib/axes/_axes.py @@ -2475,7 +2475,8 @@ def pie(self, x, explode=None, labels=None, colors=None, startangle=None, radius=None, counterclock=True, wedgeprops=None, textprops=None, center=(0, 0), frame=False, rotatelabels=False): - r"""Plot a pie chart. + r""" + Plot a pie chart. Make a pie chart of array *x*. The fractional area of each wedge is given by ``x/sum(x)``. If ``sum(x) <= 1``, then the @@ -2488,14 +2489,14 @@ def pie(self, x, explode=None, labels=None, colors=None, x : array-like The input array used to make the pie chart. - explode : array-like, optional (default is None) + explode : array-like, optional, default: None If not *None*, is a ``len(x)`` array which specifies the fraction of the radius with which to offset each wedge. - labels : list, optional (default is None) + labels : list, optional, default: None A sequence of strings providing the labels for each wedge - colors : array-like, optional (default is None) + colors : array-like, optional, default: None A sequence of matplotlib color args through which the pie chart will cycle. If `None`, will use the colors in the currently active cycle. @@ -2506,45 +2507,45 @@ def pie(self, x, explode=None, labels=None, colors=None, wedge. If it is a format string, the label will be ``fmt%pct``. If it is a function, it will be called. - pctdistance : float, optional (default is 0.6) + pctdistance : float, optional, default: 0.6 The ratio between the center of each pie slice and the start of the text generated by *autopct*. Ignored if - *autopct* is *None*; default is 0.6. + *autopct* is *None*. - shadow : bool, optional (default is False) + shadow : bool, optional, default: False Draw a shadow beneath the pie. - labeldistance : float, optional (default is 1.1) + labeldistance : float, optional, default: 1.1 The radial distance at which the pie labels are drawn - startangle : float, optional (default is None) + startangle : float, optional, default: None If not *None*, rotates the start of the pie chart by *angle* degrees counterclockwise from the x-axis. - radius : float, optional (default is None) + radius : float, optional, default: None The radius of the pie, if *radius* is *None* it will be set to 1. - counterclock : bool, optional (default is True) + counterclock : bool, optional, default: True Specify fractions direction, clockwise or counterclockwise. - wedgeprops : dict, optional (default is None) + wedgeprops : dict, optional, default: None Dict of arguments passed to the wedge objects making the pie. For example, you can pass in``wedgeprops = {'linewidth': 3}`` to set the width of the wedge border lines equal to 3. For more details, look at the doc/arguments of the wedge object. By default ``clip_on=False``. - textprops : dict, optional (default is None) + textprops : dict, optional, default: None Dict of arguments to pass to the text objects. - center : list of float, optional (default is (0, 0)) + center : list of float, optional, default: (0, 0) Center position of the chart. Takes value (0, 0) or is a sequence of 2 scalars. - frame : bool, optional (default is False) + frame : bool, optional, default: False Plot axes frame with the chart if true. - rotatelabels : bool, optional (default is False) + rotatelabels : bool, optional, default: False Rotate each label to the angle of the corresponding slice if true. Returns @@ -2558,7 +2559,7 @@ def pie(self, x, explode=None, labels=None, colors=None, autotexts : list A is a list of :class:`~matplotlib.text.Text` instances for the numeric labels. Is returned only if parameter *autopct* is - not *None*. + not *None*. Notes ----- @@ -2684,9 +2685,9 @@ def get_next_color(): self.set_frame_on(False) self.set_xlim((-1.25 + center[0], - 1.25 + center[0])) + 1.25 + center[0])) self.set_ylim((-1.25 + center[1], - 1.25 + center[1])) + 1.25 + center[1])) self.set_xticks([]) self.set_yticks([])