From 84e2a56bb77b45c877f4f1f29a1192e2bdb2d7f0 Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Fri, 26 Jun 2020 03:39:01 +0200 Subject: [PATCH] Backport PR #17742: Update tricontour[f] docs --- doc/api/tri_api.rst | 3 + doc/missing-references.json | 6 - lib/matplotlib/contour.py | 4 +- lib/matplotlib/tri/tricontour.py | 294 ++++++++++++++++++------------- 4 files changed, 174 insertions(+), 133 deletions(-) diff --git a/doc/api/tri_api.rst b/doc/api/tri_api.rst index 67db3068d46b..9205e34ff93b 100644 --- a/doc/api/tri_api.rst +++ b/doc/api/tri_api.rst @@ -7,6 +7,9 @@ .. autoclass:: matplotlib.tri.Triangulation :members: +.. autoclass:: matplotlib.tri.TriContourSet + :show-inheritance: + .. autoclass:: matplotlib.tri.TriFinder .. autoclass:: matplotlib.tri.TrapezoidMapTriFinder diff --git a/doc/missing-references.json b/doc/missing-references.json index 382d8fe91ed1..77244902b2f1 100644 --- a/doc/missing-references.json +++ b/doc/missing-references.json @@ -1374,12 +1374,6 @@ "matplotlib.colorbar.ColorbarBase.set_norm": [ "doc/api/prev_api_changes/api_changes_3.1.0.rst:290" ], - "matplotlib.contour.TriContourSet": [ - "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.tricontour:57", - "lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.tricontourf:57", - "lib/matplotlib/tri/tricontour.py:docstring of matplotlib.axes.Axes.tricontour:57", - "lib/matplotlib/tri/tricontour.py:docstring of matplotlib.axes.Axes.tricontourf:57" - ], "matplotlib.dates.rrulewrapper": [ "lib/matplotlib/dates.py:docstring of matplotlib.dates:121" ], diff --git a/lib/matplotlib/contour.py b/lib/matplotlib/contour.py index 30581cff0b7a..54bf26d3e1c6 100644 --- a/lib/matplotlib/contour.py +++ b/lib/matplotlib/contour.py @@ -1653,7 +1653,7 @@ def _initialize_x_y(self, z): By default (value *None*), the colormap specified by *cmap* will be used. - alpha : float, optional + alpha : float, default: 1 The alpha blending value, between 0 (transparent) and 1 (opaque). cmap : str or `.Colormap`, default: :rc:`image.cmap` @@ -1707,7 +1707,7 @@ def _initialize_x_y(self, z): and above the *levels* range. Values below ``min(levels)`` and above ``max(levels)`` are mapped - to the under/over values of the `.Colormap`. Note, that most + to the under/over values of the `.Colormap`. Note that most colormaps do not have dedicated colors for these by default, so that the over and under values are the edge values of the colormap. You may want to set these values explicitly using diff --git a/lib/matplotlib/tri/tricontour.py b/lib/matplotlib/tri/tricontour.py index 13641627065f..6eb5332289d8 100644 --- a/lib/matplotlib/tri/tricontour.py +++ b/lib/matplotlib/tri/tricontour.py @@ -1,5 +1,6 @@ import numpy as np +from matplotlib import docstring from matplotlib.contour import ContourSet from matplotlib.tri.triangulation import Triangulation @@ -11,16 +12,20 @@ class TriContourSet(ContourSet): User-callable method: clabel - Useful attributes: - ax: - the axes object in which the contours are drawn - collections: - a silent_list of LineCollections or PolyCollections - levels: - contour levels - layers: - same as levels for line contours; half-way between - levels for filled contours. See _process_colors method. + Attributes + ---------- + ax + The axes object in which the contours are drawn. + + collections + A silent_list of LineCollections or PolyCollections. + + levels + Contour levels. + + layers + Same as levels for line contours; half-way between + levels for filled contours. See :meth:`_process_colors`. """ def __init__(self, ax, *args, **kwargs): """ @@ -30,7 +35,7 @@ def __init__(self, ax, *args, **kwargs): The first argument of the initializer must be an axes object. The remaining arguments and keyword arguments - are described in the docstring of `tricontour`. + are described in the docstring of `~.Axes.tricontour`. """ ContourSet.__init__(self, ax, *args, **kwargs) @@ -103,175 +108,214 @@ def _contour_args(self, args, kwargs): return (tri, z) -def tricontour(ax, *args, **kwargs): - """ - Draw contours on an unstructured triangular grid. +docstring.interpd.update(_tricontour_doc=""" +Draw contour %(type)s on an unstructured triangular grid. - `.tricontour` and `.tricontourf` draw contour lines and filled contours, - respectively. Except as noted, function signatures and return values are - the same for both versions. +The triangulation can be specified in one of two ways; either :: - The triangulation can be specified in one of two ways; either :: + %(func)s(triangulation, ...) - tricontour(triangulation, ...) +where *triangulation* is a `.Triangulation` object, or :: - where *triangulation* is a `.Triangulation` object, or :: + %(func)s(x, y, ...) + %(func)s(x, y, triangles, ...) + %(func)s(x, y, triangles=triangles, ...) + %(func)s(x, y, mask=mask, ...) + %(func)s(x, y, triangles, mask=mask, ...) - tricontour(x, y, ...) - tricontour(x, y, triangles, ...) - tricontour(x, y, triangles=triangles, ...) - tricontour(x, y, mask=mask, ...) - tricontour(x, y, triangles, mask=mask, ...) +in which case a `.Triangulation` object will be created. See that class' +docstring for an explanation of these cases. - in which case a `.Triangulation` object will be created. See that class' - docstring for an explanation of these cases. +The remaining arguments may be:: - The remaining arguments may be:: + %(func)s(..., Z) - tricontour(..., Z) +where *Z* is the array of values to contour, one per point in the +triangulation. The level values are chosen automatically. - where *Z* is the array of values to contour, one per point in the - triangulation. The level values are chosen automatically. +:: - :: + %(func)s(..., Z, levels) - tricontour(..., Z, N) +contour up to *levels+1* automatically chosen contour levels (*levels* +intervals). - contour up to *N+1* automatically chosen contour levels (*N* intervals). +:: - :: + %(func)s(..., Z, levels) - tricontour(..., Z, V) +draw contour %(type)s at the values specified in sequence *levels*, which must +be in increasing order. - draw contour lines at the values specified in sequence *V*, - which must be in increasing order. +:: - :: + %(func)s(Z, **kwargs) - tricontourf(..., Z, V) +Use keyword arguments to control colors, linewidth, origin, cmap ... see below +for more details. - fill the (len(*V*)-1) regions between the values in *V*, - which must be in increasing order. +Parameters +---------- +triangulation : `.Triangulation`, optional + The unstructured triangular grid. - :: + If specified, then *x*, *y*, *triangles*, and *mask* are not accepted. - tricontour(Z, **kwargs) +x, y : array-like, optional + The coordinates of the values in *Z*. - Use keyword args to control colors, linewidth, origin, cmap ... see - below for more details. +triangles : int array-like of shape (ntri, 3), optional + For each triangle, the indices of the three points that make up the + triangle, ordered in an anticlockwise manner. If not specified, the + Delaunay triangulation is calculated. - `~.Axes.tricontour` returns a `~matplotlib.contour.TriContourSet` object. +mask : bool array-like of shape (ntri), optional + Which triangles are masked out. - Optional keyword arguments: +Z : array-like(N, M) + The height values over which the contour is drawn. - *colors*: [ *None* | str | (mpl_colors) ] - If *None*, the colormap specified by cmap will be used. +levels : int or array-like, optional + Determines the number and positions of the contour lines / regions. - If a string, like 'r' or 'red', all levels will be plotted in this - color. + If an int *n*, use `~matplotlib.ticker.MaxNLocator`, which tries to + automatically choose no more than *n+1* "nice" contour levels between + *vmin* and *vmax*. - If a tuple of colors (string, float, rgb, etc), different levels will - be plotted in different colors in the order specified. + If array-like, draw contour lines at the specified levels. The values must + be in increasing order. - *alpha*: float - The alpha blending value +Returns +------- +`~matplotlib.tri.TriContourSet` - *cmap*: [ *None* | Colormap ] - A cm :class:`~matplotlib.colors.Colormap` instance or - *None*. If *cmap* is *None* and *colors* is *None*, a - default Colormap is used. +Other Parameters +---------------- +colors : color string or sequence of colors, optional + The colors of the levels, i.e., the contour %(type)s. - *norm*: [ *None* | Normalize ] - A :class:`matplotlib.colors.Normalize` instance for - scaling data values to colors. If *norm* is *None* and - *colors* is *None*, the default linear scaling is used. + The sequence is cycled for the levels in ascending order. If the sequence + is shorter than the number of levels, it's repeated. - *levels* [level0, level1, ..., leveln] - A list of floating point numbers indicating the level - curves to draw, in increasing order; e.g., to draw just - the zero contour pass ``levels=[0]`` + As a shortcut, single color strings may be used in place of one-element + lists, i.e. ``'red'`` instead of ``['red']`` to color all levels with the + same color. This shortcut does only work for color strings, not for other + ways of specifying colors. - *origin*: [ *None* | 'upper' | 'lower' | 'image' ] - If *None*, the first value of *Z* will correspond to the - lower left corner, location (0, 0). If 'image', the rc - value for ``image.origin`` will be used. + By default (value *None*), the colormap specified by *cmap* will be used. - This keyword is not active if *X* and *Y* are specified in - the call to contour. +alpha : float, default: 1 + The alpha blending value, between 0 (transparent) and 1 (opaque). - *extent*: [ *None* | (x0, x1, y0, y1) ] +cmap : str or `.Colormap`, default: :rc:`image.cmap` + A `.Colormap` instance or registered colormap name. The colormap maps the + level values to colors. - If *origin* is not *None*, then *extent* is interpreted as - in :func:`matplotlib.pyplot.imshow`: it gives the outer - pixel boundaries. In this case, the position of Z[0, 0] - is the center of the pixel, not a corner. If *origin* is - *None*, then (*x0*, *y0*) is the position of Z[0, 0], and - (*x1*, *y1*) is the position of Z[-1, -1]. + If both *colors* and *cmap* are given, an error is raised. - This keyword is not active if *X* and *Y* are specified in - the call to contour. +norm : `~matplotlib.colors.Normalize`, optional + If a colormap is used, the `.Normalize` instance scales the level values to + the canonical colormap range [0, 1] for mapping to colors. If not given, + the default linear scaling is used. - *locator*: [ *None* | ticker.Locator subclass ] - If *locator* is None, the default - :class:`~matplotlib.ticker.MaxNLocator` is used. The - locator is used to determine the contour levels if they - are not given explicitly via the *V* argument. +origin : {*None*, 'upper', 'lower', 'image'}, default: None + Determines the orientation and exact position of *Z* by specifying the + position of ``Z[0, 0]``. This is only relevant, if *X*, *Y* are not given. - *extend*: [ 'neither' | 'both' | 'min' | 'max' ] - Unless this is 'neither', contour levels are automatically - added to one or both ends of the range so that all data - are included. These added ranges are then mapped to the - special colormap values which default to the ends of the - colormap range, but can be set via - :meth:`matplotlib.colors.Colormap.set_under` and - :meth:`matplotlib.colors.Colormap.set_over` methods. + - *None*: ``Z[0, 0]`` is at X=0, Y=0 in the lower left corner. + - 'lower': ``Z[0, 0]`` is at X=0.5, Y=0.5 in the lower left corner. + - 'upper': ``Z[0, 0]`` is at X=N+0.5, Y=0.5 in the upper left corner. + - 'image': Use the value from :rc:`image.origin`. - *xunits*, *yunits*: [ *None* | registered units ] - Override axis units by specifying an instance of a - :class:`matplotlib.units.ConversionInterface`. +extent : (x0, x1, y0, y1), optional + If *origin* is not *None*, then *extent* is interpreted as in `.imshow`: it + gives the outer pixel boundaries. In this case, the position of Z[0, 0] is + the center of the pixel, not a corner. If *origin* is *None*, then + (*x0*, *y0*) is the position of Z[0, 0], and (*x1*, *y1*) is the position + of Z[-1, -1]. - tricontour-only keyword arguments: + This argument is ignored if *X* and *Y* are specified in the call to + contour. - *linewidths*: [ *None* | number | tuple of numbers ] - If *linewidths* is *None*, defaults to :rc:`lines.linewidth`. +locator : ticker.Locator subclass, optional + The locator is used to determine the contour levels if they are not given + explicitly via *levels*. + Defaults to `~.ticker.MaxNLocator`. - If a number, all levels will be plotted with this linewidth. +extend : {'neither', 'both', 'min', 'max'}, default: 'neither' + Determines the ``%(func)s``-coloring of values that are outside the + *levels* range. + + If 'neither', values outside the *levels* range are not colored. If 'min', + 'max' or 'both', color the values below, above or below and above the + *levels* range. - If a tuple, different levels will be plotted with different - linewidths in the order specified + Values below ``min(levels)`` and above ``max(levels)`` are mapped to the + under/over values of the `.Colormap`. Note that most colormaps do not have + dedicated colors for these by default, so that the over and under values + are the edge values of the colormap. You may want to set these values + explicitly using `.Colormap.set_under` and `.Colormap.set_over`. - *linestyles*: [ *None* | 'solid' | 'dashed' | 'dashdot' | 'dotted' ] - If *linestyles* is *None*, the 'solid' is used. + .. note:: - *linestyles* can also be an iterable of the above strings - specifying a set of linestyles to be used. If this - iterable is shorter than the number of contour levels - it will be repeated as necessary. + An existing `.TriContourSet` does not get notified if properties of its + colormap are changed. Therefore, an explicit call to + `.ContourSet.changed()` is needed after modifying the colormap. The + explicit call can be left out, if a colorbar is assigned to the + `.TriContourSet` because it internally calls `.ContourSet.changed()`. - If contour is using a monochrome colormap and the contour - level is less than 0, then the linestyle specified - in :rc:`contour.negative_linestyle` will be used. +xunits, yunits : registered units, optional + Override axis units by specifying an instance of a + :class:`matplotlib.units.ConversionInterface`.""") - tricontourf-only keyword arguments: - *antialiased*: bool - enable antialiasing +@docstring.Substitution(func='tricontour', type='lines') +@docstring.dedent_interpd +def tricontour(ax, *args, **kwargs): + """ + %(_tricontour_doc)s - Note: `.tricontourf` fills intervals that are closed at the top; that is, - for boundaries *z1* and *z2*, the filled region is:: + linewidths : float or array-like, default: :rc:`contour.linewidth` + The line width of the contour lines. - z1 < Z <= z2 + If a number, all levels will be plotted with this linewidth. - except for the lowest interval, which is closed on both sides (i.e. it - includes the lowest value). + If a sequence, the levels in ascending order will be plotted with + the linewidths in the order specified. + + If None, this falls back to :rc:`lines.linewidth`. + + linestyles : {*None*, 'solid', 'dashed', 'dashdot', 'dotted'}, optional + If *linestyles* is *None*, the default is 'solid' unless the lines are + monochrome. In that case, negative contours will take their linestyle + from :rc:`contour.negative_linestyle` setting. + + *linestyles* can also be an iterable of the above strings specifying a + set of linestyles to be used. If this iterable is shorter than the + number of contour levels it will be repeated as necessary. """ kwargs['filled'] = False return TriContourSet(ax, *args, **kwargs) +@docstring.Substitution(func='tricontourf', type='regions') +@docstring.dedent_interpd def tricontourf(ax, *args, **kwargs): - kwargs['filled'] = True - return TriContourSet(ax, *args, **kwargs) + """ + %(_tricontour_doc)s + + antialiased : bool, default: True + Whether to use antialiasing. + Notes + ----- + `.tricontourf` fills intervals that are closed at the top; that is, for + boundaries *z1* and *z2*, the filled region is:: -tricontourf.__doc__ = tricontour.__doc__ + z1 < Z <= z2 + + except for the lowest interval, which is closed on both sides (i.e. it + includes the lowest value). + """ + kwargs['filled'] = True + return TriContourSet(ax, *args, **kwargs)