From 7d83aa076312f2ded1e91273b2db4169ac7110cc Mon Sep 17 00:00:00 2001 From: Antony Lee Date: Tue, 20 Nov 2018 16:48:51 +0100 Subject: [PATCH] Cleanup collections docs. --- .../2018-11-20-AL-removals.rst | 4 + lib/matplotlib/collections.py | 121 +++++++----------- 2 files changed, 50 insertions(+), 75 deletions(-) create mode 100644 doc/api/next_api_changes/2018-11-20-AL-removals.rst diff --git a/doc/api/next_api_changes/2018-11-20-AL-removals.rst b/doc/api/next_api_changes/2018-11-20-AL-removals.rst new file mode 100644 index 000000000000..db36efb8c146 --- /dev/null +++ b/doc/api/next_api_changes/2018-11-20-AL-removals.rst @@ -0,0 +1,4 @@ +Removals +```````` + +The ``collections.CIRCLE_AREA_FACTOR`` constant has been removed. diff --git a/lib/matplotlib/collections.py b/lib/matplotlib/collections.py index 5b6c7cbd8304..d77df3660db1 100644 --- a/lib/matplotlib/collections.py +++ b/lib/matplotlib/collections.py @@ -17,8 +17,6 @@ from . import (_path, artist, cbook, cm, colors as mcolors, docstring, lines as mlines, path as mpath, transforms) -CIRCLE_AREA_FACTOR = 1.0 / np.sqrt(np.pi) - @cbook._define_aliases({ "antialiased": ["antialiaseds"], @@ -58,7 +56,6 @@ class Collection(artist.Artist, cm.ScalarMappable): * *hatch*: None * *zorder*: 1 - *offsets* and *transOffset* are used to translate the patch after rendering (default no offsets). If offset_position is 'screen' (default) the offset is applied after the master transform has @@ -207,12 +204,12 @@ def get_datalim(self, transData): return result def get_window_extent(self, renderer): - # TODO:check to ensure that this does not fail for + # TODO: check to ensure that this does not fail for # cases other than scatter plot legend return self.get_datalim(transforms.IdentityTransform()) def _prepare_points(self): - """Point prep for drawing and hit testing""" + # Helper for drawing and hit testing. transform = self.get_transform() transOffset = self.get_offset_transform() @@ -227,8 +224,7 @@ def _prepare_points(self): xs = self.convert_xunits(xs) ys = self.convert_yunits(ys) paths.append(mpath.Path(np.column_stack([xs, ys]), path.codes)) - - if offsets.size > 0: + if offsets.size: xs = self.convert_xunits(offsets[:, 0]) ys = self.convert_yunits(offsets[:, 1]) offsets = np.column_stack([xs, ys]) @@ -336,7 +332,8 @@ def draw(self, renderer): self.stale = False def set_pickradius(self, pr): - """Set the pick radius used for containment tests. + """ + Set the pick radius used for containment tests. Parameters ---------- @@ -352,8 +349,8 @@ def contains(self, mouseevent): """ Test whether the mouse event occurred in the collection. - Returns True | False, ``dict(ind=itemlist)``, where every - item in itemlist contains the event. + Returns ``bool, dict(ind=itemlist)``, where every item in itemlist + contains the event. """ if callable(self._contains): return self._contains(self, mouseevent) @@ -430,8 +427,7 @@ def get_hatch(self): def set_offsets(self, offsets): """ - Set the offsets for the collection. *offsets* can be a scalar - or a sequence. + Set the offsets for the collection. Parameters ---------- @@ -552,8 +548,7 @@ def set_linestyle(self, ls): def set_capstyle(self, cs): """ - Set the capstyle for the collection. The capstyle can - only be set globally for all elements in the collection + Set the capstyle for the collection (for all its elements). Parameters ---------- @@ -570,8 +565,7 @@ def get_capstyle(self): def set_joinstyle(self, js): """ - Set the joinstyle for the collection. The joinstyle can only be - set globally for all elements in the collection. + Set the joinstyle for the collection (for all its elements). Parameters ---------- @@ -588,19 +582,18 @@ def get_joinstyle(self): @staticmethod def _bcast_lwls(linewidths, dashes): - '''Internal helper function to broadcast + scale ls/lw + """ + Internal helper function to broadcast + scale ls/lw - In the collection drawing code the linewidth and linestyle are - cycled through as circular buffers (via v[i % len(v)]). Thus, - if we are going to scale the dash pattern at set time (not - draw time) we need to do the broadcasting now and expand both - lists to be the same length. + In the collection drawing code, the linewidth and linestyle are cycled + through as circular buffers (via ``v[i % len(v)]``). Thus, if we are + going to scale the dash pattern at set time (not draw time) we need to + do the broadcasting now and expand both lists to be the same length. Parameters ---------- linewidths : list line widths of collection - dashes : list dash specification (offset, (dash pattern tuple)) @@ -608,8 +601,7 @@ def _bcast_lwls(linewidths, dashes): ------- linewidths, dashes : list Will be the same length, dashes are scaled by paired linewidth - - ''' + """ if mpl.rcParams['_internal.classic_mode']: return linewidths, dashes # make sure they are the same length so we can zip them @@ -723,26 +715,20 @@ def _set_edgecolor(self, c): def set_edgecolor(self, c): """ - Set the edgecolor(s) of the collection. *c* can be a - matplotlib color spec (all patches have same color), or a - sequence of specs; if it is a sequence the patches will - cycle through the sequence. - - If *c* is 'face', the edge color will always be the same as - the face color. If it is 'none', the patch boundary will not - be drawn. + Set the edgecolor(s) of the collection. Parameters ---------- - c : color or sequence of colors + c : color or sequence of colors or 'face' + The collection edgecolor(s). If a sequence, the patches cycle + through it. If 'face', match the facecolor. """ self._original_edgecolor = c self._set_edgecolor(c) def set_alpha(self, alpha): """ - Set the alpha tranparencies of the collection. *alpha* must be - a float or *None*. + Set the alpha tranparencies of the collection. Parameters ---------- @@ -765,10 +751,7 @@ def get_linestyle(self): return self._linestyles def update_scalarmappable(self): - """ - If the scalar mappable array is not none, update colors - from scalar data - """ + """Update colors from the scalar mappable array, if it is not None.""" if self._A is None: return if self._A.ndim > 1: @@ -861,7 +844,6 @@ def set_sizes(self, sizes, dpi=72.0): sizes : ndarray or None The size to set for each element of the collection. The value is the 'area' of the element. - dpi : float The dpi of the canvas. Defaults to 72.0. """ @@ -963,7 +945,7 @@ def set_verts(self, verts, closed=True): set_paths = set_verts def set_verts_and_codes(self, verts, codes): - '''This allows one to initialize vertices with path codes.''' + """This allows one to initialize vertices with path codes.""" if len(verts) != len(codes): raise ValueError("'codes' must be a 1D list or array " "with the same length of 'verts'") @@ -1025,9 +1007,9 @@ def span_where(x, ymin, ymax, where, **kwargs): class RegularPolyCollection(_CollectionWithSizes): """Draw a collection of regular polygons with *numsides*.""" - _path_generator = mpath.Path.unit_regular_polygon - _factor = CIRCLE_AREA_FACTOR + _path_generator = mpath.Path.unit_regular_polygon + _factor = np.pi ** (-1/2) @docstring.dedent_interpd def __init__(self, @@ -1089,16 +1071,12 @@ def draw(self, renderer): class StarPolygonCollection(RegularPolyCollection): - """ - Draw a collection of regular stars with *numsides* points.""" - + """Draw a collection of regular stars with *numsides* points.""" _path_generator = mpath.Path.unit_regular_star class AsteriskPolygonCollection(RegularPolyCollection): - """ - Draw a collection of regular asterisks with *numsides* points.""" - + """Draw a collection of regular asterisks with *numsides* points.""" _path_generator = mpath.Path.unit_regular_asterisk @@ -1295,13 +1273,13 @@ def get_color(self): class EventCollection(LineCollection): - ''' + """ A collection of discrete events. The events are given by a 1-dimensional array, usually the position of something along an axis, such as time or length. They do not have an amplitude and are displayed as vertical or horizontal parallel bars. - ''' + """ _edge_default = True @@ -1542,10 +1520,9 @@ def get_color(self): class CircleCollection(_CollectionWithSizes): - """ - A collection of circles, drawn using splines. - """ - _factor = CIRCLE_AREA_FACTOR + """A collection of circles, drawn using splines.""" + + _factor = np.pi ** (-1/2) @docstring.dedent_interpd def __init__(self, sizes, **kwargs): @@ -1562,9 +1539,8 @@ def __init__(self, sizes, **kwargs): class EllipseCollection(Collection): - """ - A collection of ellipses, drawn using splines. - """ + """A collection of ellipses, drawn using splines.""" + @docstring.dedent_interpd def __init__(self, widths, heights, angles, units='points', **kwargs): """ @@ -1607,9 +1583,8 @@ def __init__(self, widths, heights, angles, units='points', **kwargs): self._paths = [mpath.Path.unit_circle()] def _set_transforms(self): - """ - Calculate transforms immediately before drawing. - """ + """Calculate transforms immediately before drawing.""" + ax = self.axes fig = self.figure @@ -1712,11 +1687,9 @@ def set_paths(self, patches): class TriMesh(Collection): """ - Class for the efficient drawing of a triangular mesh using - Gouraud shading. + Class for the efficient drawing of a triangular mesh using Gouraud shading. - A triangular mesh is a :class:`~matplotlib.tri.Triangulation` - object. + A triangular mesh is a `~matplotlib.tri.Triangulation` object. """ def __init__(self, triangulation, **kwargs): Collection.__init__(self, **kwargs) @@ -1743,11 +1716,10 @@ def set_paths(self): @staticmethod def convert_mesh_to_paths(tri): """ - Converts a given mesh into a sequence of - :class:`matplotlib.path.Path` objects for easier rendering by - backends that do not directly support meshes. + Converts a given mesh into a sequence of `~.Path` objects. - This function is primarily of use to backend implementers. + This function is primarily of use to implementers of backends that do + not directly support meshes. """ triangles = tri.get_masked_triangles() verts = np.stack((tri.x[triangles], tri.y[triangles]), axis=-1) @@ -1839,11 +1811,10 @@ def get_datalim(self, transData): @staticmethod def convert_mesh_to_paths(meshWidth, meshHeight, coordinates): """ - Converts a given mesh into a sequence of - :class:`matplotlib.path.Path` objects for easier rendering by - backends that do not directly support quadmeshes. + Converts a given mesh into a sequence of `~.Path` objects. - This function is primarily of use to backend implementers. + This function is primarily of use to implementers of backends that do + not directly support quadmeshes. """ if isinstance(coordinates, np.ma.MaskedArray): c = coordinates.data @@ -1863,7 +1834,7 @@ def convert_mesh_to_triangles(self, meshWidth, meshHeight, coordinates): """ Converts a given mesh into a sequence of triangles, each point with its own color. This is useful for experiments using - `draw_qouraud_triangle`. + `draw_gouraud_triangle`. """ if isinstance(coordinates, np.ma.MaskedArray): p = coordinates.data