Skip to content

Cleanup colors.py docstrings. #17151

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 2 commits into from
May 8, 2020
Merged

Cleanup colors.py docstrings. #17151

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
77ea20f
Cleanup colors.py docstrings.
anntzer Apr 15, 2020
60e4d16
DOC: include "special" methods in built docs
tacaswell Apr 15, 2020
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
1 change: 1 addition & 0 deletions doc/_templates/autosummary.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
{% if objtype in ['class'] %}
.. auto{{ objtype }}:: {{ objname }}
:show-inheritance:
:special-members:

{% else %}
.. auto{{ objtype }}:: {{ objname }}
Expand Down
75 changes: 36 additions & 39 deletions lib/matplotlib/colors.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,17 +4,15 @@
*RGB* and *RGBA* are sequences of, respectively, 3 or 4 floats in the
range 0-1.

This module includes functions and classes for color specification
conversions, and for mapping numbers to colors in a 1-D array of colors called
a colormap.

Mapping data onto colors using a colormap typically involves two steps:
a data array is first mapped onto the range 0-1 using a subclass of
:class:`Normalize`, then this number is mapped to a color using
a subclass of :class:`Colormap`. Two are provided here:
:class:`LinearSegmentedColormap`, which uses piecewise-linear interpolation
to define colormaps, and :class:`ListedColormap`, which makes a colormap
from a list of colors.
This module includes functions and classes for color specification conversions,
and for mapping numbers to colors in a 1-D array of colors called a colormap.

Mapping data onto colors using a colormap typically involves two steps: a data
array is first mapped onto the range 0-1 using a subclass of `Normalize`,
then this number is mapped to a color using a subclass of `Colormap`. Two
sublasses of `Colormap` provided here: `LinearSegmentedColormap`, which uses
piecewise-linear interpolation to define colormaps, and `ListedColormap`, which
makes a colormap from a list of colors.

.. seealso::

Expand All @@ -29,10 +27,10 @@
More colormaps are available at palettable_.

The module also provides functions for checking whether an object can be
interpreted as a color (:func:`is_color_like`), for converting such an object
to an RGBA tuple (:func:`to_rgba`) or to an HTML-like hex string in the
"#rrggbb" format (:func:`to_hex`), and a sequence of colors to an (n, 4)
RGBA array (:func:`to_rgba_array`). Caching is used for efficiency.
interpreted as a color (`is_color_like`), for converting such an object
to an RGBA tuple (`to_rgba`) or to an HTML-like hex string in the
"#rrggbb" format (`to_hex`), and a sequence of colors to an (n, 4)
RGBA array (`to_rgba_array`). Caching is used for efficiency.

Matplotlib recognizes the following formats to specify a color:

Expand Down Expand Up @@ -393,8 +391,8 @@ def _create_lookup_table(N, data, gamma=1.0):
Parameters
----------
N : int
The number of elements of the created lookup table.
This must be N >= 1.
The number of elements of the created lookup table; at least 1.

data : Mx3 array-like or callable
Defines the mapping :math:`f`.

Expand All @@ -420,6 +418,7 @@ def _create_lookup_table(N, data, gamma=1.0):
data(x : ndarray) -> ndarray

and map values between 0 - 1 to 0 - 1.

gamma : float
Gamma correction factor for input distribution x of the mapping.

Expand Down Expand Up @@ -488,14 +487,14 @@ class Colormap:
"""
Baseclass for all scalar to RGBA mappings.

Typically Colormap instances are used to convert data values (floats) from
the interval ``[0, 1]`` to the RGBA color that the respective Colormap
represents. For scaling of data into the ``[0, 1]`` interval see
:class:`matplotlib.colors.Normalize`. It is worth noting that
:class:`matplotlib.cm.ScalarMappable` subclasses make heavy use of this
``data->normalize->map-to-color`` processing chain.

Typically, Colormap instances are used to convert data values (floats)
from the interval ``[0, 1]`` to the RGBA color that the respective
Colormap represents. For scaling of data into the ``[0, 1]`` interval see
`matplotlib.colors.Normalize`. Subclasses of `matplotlib.cm.ScalarMappable`
make heavy use of this ``data -> normalize -> map-to-color`` processing
chain.
"""

def __init__(self, name, N=256):
"""
Parameters
Expand All @@ -504,7 +503,6 @@ def __init__(self, name, N=256):
The name of the colormap.
N : int
The number of rgb quantization levels.

"""
self.name = name
self.N = int(N) # ensure that N is always int
Expand All @@ -515,11 +513,10 @@ def __init__(self, name, N=256):
self._i_over = self.N + 1
self._i_bad = self.N + 2
self._isinit = False

#: When this colormap exists on a scalar mappable and colorbar_extend
#: is not False, colorbar creation will pick up ``colorbar_extend`` as
#: the default value for the ``extend`` keyword in the
#: :class:`matplotlib.colorbar.Colorbar` constructor.
#: `matplotlib.colorbar.Colorbar` constructor.
self.colorbar_extend = False

def __call__(self, X, alpha=None, bytes=False):
Expand Down Expand Up @@ -1411,13 +1408,13 @@ def __init__(self, boundaries, ncolors, clip=False):
Number of colors in the colormap to be used
clip : bool, optional
If clip is ``True``, out of range values are mapped to 0 if they
are below ``boundaries[0]`` or mapped to ncolors - 1 if they are
above ``boundaries[-1]``.
are below ``boundaries[0]`` or mapped to ``ncolors - 1`` if they
are above ``boundaries[-1]``.

If clip is ``False``, out of range values are mapped to -1 if
they are below ``boundaries[0]`` or mapped to ncolors if they are
they are below ``boundaries[0]`` or mapped to *ncolors* if they are
above ``boundaries[-1]``. These are then converted to valid indices
by :meth:`Colormap.__call__`.
by `Colormap.__call__`.

Notes
-----
Expand Down Expand Up @@ -1636,11 +1633,11 @@ class LightSource:
Angles are in degrees, with the azimuth measured
clockwise from north and elevation up from the zero plane of the surface.

The :meth:`shade` is used to produce "shaded" rgb values for a data array.
:meth:`shade_rgb` can be used to combine an rgb image with
The :meth:`shade_rgb`
The :meth:`hillshade` produces an illumination map of a surface.
`shade` is used to produce "shaded" rgb values for a data array.
`shade_rgb` can be used to combine an rgb image with an elevation map.
`hillshade` produces an illumination map of a surface.
"""

def __init__(self, azdeg=315, altdeg=45, hsv_min_val=0, hsv_max_val=1,
hsv_min_sat=1, hsv_max_sat=0):
"""
Expand All @@ -1662,8 +1659,8 @@ def __init__(self, azdeg=315, altdeg=45, hsv_min_val=0, hsv_max_val=1,
For backwards compatibility, the parameters *hsv_min_val*,
*hsv_max_val*, *hsv_min_sat*, and *hsv_max_sat* may be supplied at
initialization as well. However, these parameters will only be used if
"blend_mode='hsv'" is passed into :meth:`shade` or :meth:`shade_rgb`.
See the documentation for :meth:`blend_hsv` for more details.
"blend_mode='hsv'" is passed into `shade` or `shade_rgb`.
See the documentation for `blend_hsv` for more details.
"""
self.azdeg = azdeg
self.altdeg = altdeg
Expand Down Expand Up @@ -2054,15 +2051,15 @@ def from_levels_and_colors(levels, colors, extend='neither'):
Parameters
----------
levels : sequence of numbers
The quantization levels used to construct the :class:`BoundaryNorm`.
The quantization levels used to construct the `BoundaryNorm`.
Value ``v`` is quantized to level ``i`` if ``lev[i] <= v < lev[i+1]``.
colors : sequence of colors
The fill color to use for each level. If *extend* is "neither" there
must be ``n_level - 1`` colors. For an *extend* of "min" or "max" add
one extra color, and for an *extend* of "both" add two colors.
extend : {'neither', 'min', 'max', 'both'}, optional
The behaviour when a value falls out of range of the given levels.
See :func:`~matplotlib.pyplot.contourf` for details.
See `~.Axes.contourf` for details.

Returns
-------
Expand Down