8000 Cleanup collections docs. by anntzer · Pull Request #12852 · matplotlib/matplotlib · GitHub
[go: up one dir, main page]
Skip to content

Cleanup collections docs. #12852

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 29, 2018
Merged

Cleanup collections docs. #12852

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions doc/api/next_api_changes/2018-11-20-AL-removals.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
Removals
````````

The ``collections.CIRCLE_AREA_FACTOR`` constant has been removed.
121 changes: 46 additions & 75 deletions lib/matplotlib/collections.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"],
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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()
Expand All @@ -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])
Expand Down Expand Up @@ -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
----------
Expand All @@ -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)
Expand Down Expand Up @@ -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
----------
Expand Down Expand Up @@ -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
----------
Expand All @@ -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
----------
Expand All @@ -588,28 +582,26 @@ 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))

Returns
-------
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
Expand Down Expand Up @@ -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
----------
Expand All @@ -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:
Expand Down Expand Up @@ -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.
"""
Expand Down Expand Up @@ -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'")
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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


Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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):
Expand All @@ -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):
"""
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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)
Expand All @@ -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)
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down
0