From b2600c9797e5e3d46b827cc2defa8f72529b39da Mon Sep 17 00:00:00 2001 From: Antony Lee Date: Tue, 27 Nov 2018 14:13:38 +0100 Subject: [PATCH] Reword a bit the contour docs. --- lib/matplotlib/contour.py | 45 ++++++++++++++------------------ lib/matplotlib/tri/tricontour.py | 43 ++++++++++++------------------ 2 files changed, 36 insertions(+), 52 deletions(-) diff --git a/lib/matplotlib/contour.py b/lib/matplotlib/contour.py index e411bd60338c..57dc5ba0cd41 100644 --- a/lib/matplotlib/contour.py +++ b/lib/matplotlib/contour.py @@ -1661,11 +1661,9 @@ def _initialize_x_y(self, z): contour([X, Y,] Z, [levels], **kwargs) - :func:`~matplotlib.pyplot.contour` and - :func:`~matplotlib.pyplot.contourf` draw contour lines and - filled contours, respectively. Except as noted, function - signatures and return values are the same for both versions. - + `.contour` and `.contourf` draw contour lines and filled contours, + respectively. Except as noted, function signatures and return values + are the same for both versions. Parameters ---------- @@ -1673,7 +1671,7 @@ def _initialize_x_y(self, z): The coordinates of the values in *Z*. *X* and *Y* must both be 2-D with the same shape as *Z* (e.g. - created via :func:`numpy.meshgrid`), or they must both be 1-D such + created via `numpy.meshgrid`), or they must both be 1-D such that ``len(X) == M`` is the number of columns in *Z* and ``len(Y) == N`` is the number of rows in *Z*. @@ -1705,8 +1703,7 @@ def _initialize_x_y(self, z): nearest those points are always masked out, other triangular corners comprising three unmasked points are contoured as usual. - Defaults to ``rcParams['contour.corner_mask']``, which defaults to - ``True``. + Defaults to :rc:`contour.corner_mask`, which defaults to ``True``. colors : color string or sequence of colors, optional The colors of the levels, i.e. the lines for `.contour` and the @@ -1756,15 +1753,14 @@ def _initialize_x_y(self, z): *None* in the rcParam is currently handled as 'lower'. extent : (x0, x1, y0, y1), optional - 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 *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]. - This keyword is not active if *X* and *Y* are specified in - the call to contour. + This argument is ignored if *X* and *Y* are specified in the call + to contour. locator : ticker.Locator subclass, optional The locator is used to determine the contour levels if they @@ -1830,20 +1826,17 @@ def _initialize_x_y(self, z): Hatching is supported in the PostScript, PDF, SVG and Agg backends only. - Notes ----- - 1. :func:`~matplotlib.pyplot.contourf` differs from the MATLAB - version in that it does not draw the polygon edges. - To draw edges, add line contours with - calls to :func:`~matplotlib.pyplot.contour`. + 1. `.contourf` differs from the MATLAB version in that it does not draw + the polygon edges. To draw edges, add line contours with calls to + `.contour`. - 2. contourf fills intervals that are closed at the top; that - is, for boundaries *z1* and *z2*, the filled region is:: + 2. `.contourf` fills intervals that are closed at the top; that is, for + boundaries *z1* and *z2*, the filled region is:: z1 < Z <= z2 - There is one exception: if the lowest boundary coincides with - the minimum value of the *Z* array, then that minimum value - will be included in the lowest interval. + except for the lowest interval, which is closed on both sides (i.e. + it includes the lowest value). """ diff --git a/lib/matplotlib/tri/tricontour.py b/lib/matplotlib/tri/tricontour.py index ac9d198bd78f..e1394a28b0a8 100644 --- a/lib/matplotlib/tri/tricontour.py +++ b/lib/matplotlib/tri/tricontour.py @@ -94,19 +94,16 @@ def _contour_args(self, args, kwargs): def tricontour(ax, *args, **kwargs): """ Draw contours on an unstructured triangular grid. - :func:`~matplotlib.pyplot.tricontour` and - :func:`~matplotlib.pyplot.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:: + `.tricontour` and `.tricontourf` draw contour lines and filled contours, + respectively. Except as noted, function signatures and return values are + the same for both versions. - tricontour(triangulation, ...) + The triangulation can be specified in one of two ways; either :: - where triangulation is a :class:`matplotlib.tri.Triangulation` - object, or + tricontour(triangulation, ...) - :: + where *triangulation* is a `matplotlib.tri.Triangulation` object, or :: tricontour(x, y, ...) tricontour(x, y, triangles, ...) @@ -114,24 +111,21 @@ def tricontour(ax, *args, **kwargs): tricontour(x, y, mask=mask, ...) tricontour(x, y, triangles, mask=mask, ...) - in which case a Triangulation object will be created. See - :class:`~matplotlib.tri.Triangulation` for a explanation of - these possibilities. + in which case a `.Triangulation` object will be created. See that class' + docstring for an explanation of these cases. The remaining arguments may be:: 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. :: tricontour(..., Z, N) - contour up to *N+1* automatically chosen contour levels - (*N* intervals). + contour up to *N+1* automatically chosen contour levels (*N* intervals). :: @@ -154,8 +148,7 @@ def tricontour(ax, *args, **kwargs): Use keyword args to control colors, linewidth, origin, cmap ... see below for more details. - ``C = tricontour(...)`` returns a - :class:`~matplotlib.contour.TriContourSet` object. + `.tricontour(...)` returns a `~matplotlib.contour.TriContourSet` object. Optional keyword arguments: @@ -226,7 +219,6 @@ def tricontour(ax, *args, **kwargs): Override axis units by specifying an instance of a :class:`matplotlib.units.ConversionInterface`. - tricontour-only keyword arguments: *linewidths*: [ *None* | number | tuple of numbers ] @@ -254,14 +246,13 @@ def tricontour(ax, *args, **kwargs): *antialiased*: bool enable antialiasing - Note: tricontourf fills intervals that are closed at the top; that - is, for boundaries *z1* and *z2*, the filled region is:: + Note: `.tricontourf` fills intervals that are closed at the top; that is, + for boundaries *z1* and *z2*, the filled region is:: - z1 < z <= z2 + z1 < Z <= z2 - There is one exception: if the lowest boundary coincides with - the minimum value of the *z* array, then that minimum value - will be included in the lowest interval. + except for the lowest interval, which is closed on both sides (i.e. it + includes the lowest value). """ kwargs['filled'] = False return TriContourSet(ax, *args, **kwargs)