8000 Update docstrings and allow infinite counts for plot_{surface,wirefra… · matplotlib/matplotlib@f66875c · GitHub
[go: up one dir, main page]
Skip to content

Commit f66875c

Browse files
anntzeranntzer
committed
Update docstrings and allow infinite counts for plot_{surface,wireframe}.
Docstrings: Emphasize the downsampling. Clarify when the defaults for rstride and cstride apply. Passing an infinite rcount and ccount is the easiest way to ensure the data does not get downsampled (which I still think is a misfeature, but that's a battle for another day), but would result in a stride of zero; instead, ensure that the stride is at least 1.
1 parent 9986196 commit f66875c

File tree

1 file changed

+91
-80
lines changed

1 file changed

+91
-80
lines changed

‎lib/mpl_toolkits/mplot3d/axes3d.py

Lines changed: 91 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -1560,49 +1560,60 @@ def plot(self, xs, ys, *args, **kwargs):
15601560
plot3D = plot
15611561

15621562
def plot_surface(self, X, Y, Z, *args, **kwargs):
1563-
'''
1563+
"""
15641564
Create a surface plot.
15651565
1566-
By default it will be colored in shades of a solid color,
1567-
but it also supports color mapping by supplying the *cmap*
1568-
argument.
1569-
1570-
The `rstride` and `cstride` kwargs set the stride used to
1571-
sample the input data to generate the graph. If 1k by 1k
1572-
arrays are passed in, the default values for the strides will
1573-
result in a 100x100 grid being plotted. Defaults to 10.
1574-
Raises a ValueError if both stride and count kwargs
1575-
(see next section) are provided.
1576-
1577-
The `rcount` and `ccount` kwargs supersedes `rstride` and
1578-
`cstride` for default sampling method for surface plotting.
1579-
These arguments will determine at most how many evenly spaced
1580-
samples will be taken from the input data to generate the graph.
1581-
This is the default sampling method unless using the 'classic'
1582-
style. Will raise ValueError if both stride and count are
1583-
specified.
1584-
Added in v2.0.0.
1566+
By default it will be colored in shades of a solid color, but it also
1567+
supports color mapping by supplying the *cmap* argument.
15851568
1586-
============= ================================================
1587-
Argument Description
1588-
============= ================================================
1589-
*X*, *Y*, *Z* Data values as 2D arrays
1590-
*rstride* Array row stride (step size)
1591-
*cstride* Array column stride (step size)
1592-
*rcount* Use at most this many rows, defaults to 50
1593-
*ccount* Use at most this many columns, defaults to 50
1594-
*color* Color of the surface patches
1595-
*cmap* A colormap for the surface patches.
1596-
*facecolors* Face colors for the individual patches
1597-
*norm* An instance of Normalize to map values to colors
1598-
*vmin* Minimum value to map
1599-
*vmax* Maximum value to map
1600-
*shade* Whether to shade the facecolors
1601-
============= ================================================
1569+
.. note::
16021570
1603-
Other arguments are passed on to
1604-
:class:`~mpl_toolkits.mplot3d.art3d.Poly3DCollection`
1605-
'''
1571+
The *rcount* and *ccount* kwargs, which both default to 50,
1572+
determine the maximum number of samples used in each direction. If
1573+
the input data is larger, it will be downsampled (by slicing) to
1574+
these numbers of points.
1575+
1576+
Parameters
1577+
----------
1578+
X, Y, Z : 2d arrays
1579+
Data values.
1580+
1581+
rcount, ccount : int
1582+
Maximum number of samples used in each direction. If the input
1583+
data is larger, it will be downsampled (by slicing) to these
1584+
numbers of points. Defaults to 50.
1585+
1586+
.. versionadded:: 2.0
1587+
1588+
rstride, cstride : int
1589+
Downsampling stride in each direction. These arguments are
1590+
mutually exclusive with *rcount* and *ccount*. If only one of
1591+
*rcount* or *ccount* is set, the other defaults to 10.
1592+
1593+
'classic' mode uses a default of ``rstride = cstride = 10`` instead
1594+
of the new default of ``rcount = ccount = 50``.
1595+
1596+
color : color-like
1597+
Color of the surface patches.
1598+
1599+
cmap : Colormap
1600+
Colormap of the surface patches.
1601+
1602+
facecolors : array-like of colors.
1603+
Colors of each individual patch.
1604+
1605+
norm : Normalize
1606+
Normalization for the colormap.
1607+
1608+
vmin, vmax : float
1609+
Bounds for the normalization.
1610+
1611+
shade : bool
1612+
Whether to shade the face colors.
1613+
1614+
**kwargs :
1615+
Other arguments are forwarded to `~.Poly3DCollection`.
1616+
"""
16061617

16071618
had_data = self.has_data()
16081619

@@ -1628,14 +1639,14 @@ def plot_surface(self, X, Y, Z, *args, **kwargs):
16281639
# So, only compute strides from counts
16291640
# if counts were explicitly given
16301641
if has_count:
1631-
rstride = int(np.ceil(rows / rcount))
1632-
cstride = int(np.ceil(cols / ccount))
1642+
rstride = int(max(np.ceil(rows / rcount), 1))
1643+
cstride = int(max(np.ceil(cols / ccount), 1))
16331644
else:
16341645
# If the strides are provided then it has priority.
16351646
# Otherwise, compute the strides from the counts.
16361647
if not has_stride:
1637-
rstride = int(np.ceil(rows / rcount))
1638-
cstride = int(np.ceil(cols / ccount))
1648+
rstride = int(max(np.ceil(rows / rcount), 1))
1649+
cstride = int(max(np.ceil(cols / ccount), 1))
16391650

16401651
if 'facecolors' in kwargs:
16411652
fcolors = kwargs.pop('facecolors')
@@ -1779,44 +1790,44 @@ def _shade_colors_lightsource(self, data, cmap, lightsource):
17791790
return lightsource.shade(data, cmap)
17801791

17811792
def plot_wireframe(self, X, Y, Z, *args, **kwargs):
1782-
'''
1793+
"""
17831794
Plot a 3D wireframe.
17841795
1785-
The `rstride` and `cstride` kwargs set the stride used to
1786-
sample the input data to generate the graph. If either is 0
1787-
the input data in not sampled along this direction producing a
1788-
3D line plot rather than a wireframe plot. The stride arguments
1789-
are only used by default if in the 'classic' mode. They are
1790-
now superseded by `rcount` and `ccount`. Will raise ValueError
1791-
if both stride and count are used.
1792-
1793-
` The `rcount` and `ccount` kwargs supersedes `rstride` and
1794-
`cstride` for default sampling method for wireframe plotting.
1795-
These arguments will determine at most how many evenly spaced
1796-
samples will be taken from the input data to generate the graph.
1797-
This is the default sampling method unless using the 'classic'
1798-
style. Will raise ValueError if both stride and count are
1799-
specified. If either is zero, then the input data is not sampled
1800-
along this direction, producing a 3D line plot rather than a
1801-
wireframe plot.
1802-
Added in v2.0.0.
1796+
.. note::
18031797
1804-
========== ================================================
1805-
Argument Description
1806-
========== ================================================
1807-
*X*, *Y*, Data values as 2D arrays
1808-
*Z*
1809-
*rstride* Array row stride (step size), defaults to 1
1810-
*cstride* Array column stride (step size), defaults to 1
1811-
*rcount* Use at most this many rows, defaults to 50
1812-
*ccount* Use at most this many columns, defaults to 50
1813-
========== ================================================
1798+
The *rcount* and *ccount* kwargs, which both default to 50,
1799+
determine the maximum number of samples used in each direction. If
1800+
the input data is larger, it will be downsampled (by slicing) to
1801+
these numbers of points.
18141802
1815-
Keyword arguments are passed on to
1816-
:class:`~matplotlib.collections.LineCollection`.
1803+
Parameters
1804+
----------
1805+
X, Y, Z : 2d arrays
1806+
Data values.
18171807
1818-
Returns a :class:`~mpl_toolkits.mplot3d.art3d.Line3DCollection`
1819-
'''
1808+
rcount, ccount : int
1809+
Maximum number of samples used in each direction. If the input
1810+
data is larger, it will be downsampled (by slicing) to these
1811+
numbers of points. Setting a count to zero causes the data to be
1812+
not sampled in the corresponding direction, producing a 3D line
1813+
plot rather than a wireframe plot. Defaults to 50.
1814+
1815+
.. versionadded:: 2.0
1816+
1817+
rstride, cstride : int
1818+
Downsampling stride in each direction. These arguments are
1819+
mutually exclusive with *rcount* and *ccount*. If only one of
1820+
*rcount* or *ccount* is set, the other defaults to 1. Setting a
1821+
stride to zero causes the data to be not sampled in the
1822+
corresponding direction, producing a 3D line plot rather than a
1823+
wireframe plot.
1824+
1825+
'classic' mode uses a default of ``rstride = cstride = 1`` instead
1826+
of the new default of ``rcount = ccount = 50``.
1827+
1828+
**kwargs :
1829+
Other arguments are forwarded to `~.Line3DCollection`.
1830+
"""
18201831

18211832
had_data = self.has_data()
18221833
if Z.ndim != 2:
@@ -1841,14 +1852,14 @@ def plot_wireframe(self, X, Y, Z, *args, **kwargs):
18411852
# So, only compute strides from counts
18421853
# if counts were explicitly given
18431854
if has_count:
1844-
rstride = int(np.ceil(rows / rcount)) if rcount else 0
1845-
cstride = int(np.ceil(cols / ccount)) if ccount else 0
1855+
rstride = int(max(np.ceil(rows / rcount), 1)) if rcount else 0
1856+
cstride = int(max(np.ceil(cols / ccount), 1)) if ccount else 0
18461857
else:
18471858
# If the strides are provided then it has priority.
18481859
# Otherwise, compute the strides from the counts.
18491860
if not has_stride:
1850-
rstride = int(np.ceil(rows / rcount)) if rcount else 0
1851-
cstride = int(np.ceil(cols / ccount)) if ccount else 0
1861+
rstride = int(max(np.ceil(rows / rcount), 1)) if rcount else 0
1862+
cstride = int(max(np.ceil(cols / ccount), 1)) if ccount else 0
18521863

18531864
# We want two sets of lines, one running along the "rows" of
18541865
# Z and another set of lines running along the "columns" of Z.

0 commit comments

Comments
 (0)
0