Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Improve docstring of Axes.hexbin #14839

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
Jul 18, 2019
Merged

Improve docstring of Axes.hexbin #14839

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
148 changes: 79 additions & 69 deletions lib/matplotlib/axes/_axes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4496,63 +4496,60 @@ def hexbin(self, x, y, C=None, gridsize=100, bins=None,
reduce_C_function=np.mean, mincnt=None, marginals=False,
**kwargs):
"""
Make a hexagonal binning plot.
Make a 2D hexagonal binning plot of points *x*, *y*.

Make a hexagonal binning plot of *x* versus *y*, where *x*,
*y* are 1-D sequences of the same length, *N*. If *C* is *None*
(the default), this is a histogram of the number of occurrences
of the observations at (x[i],y[i]).

If *C* is specified, it specifies values at the coordinate
(x[i], y[i]). These values are accumulated for each hexagonal
bin and then reduced according to *reduce_C_function*, which
defaults to `numpy.mean`. (If *C* is specified, it must also
be a 1-D sequence of the same length as *x* and *y*.)
If *C* is *None*, the value of the hexagon is determined by the number
of points in the hexagon. Otherwise, *C* specifies values at the
coordinate (x[i], y[i]). For each hexagon, these values are reduced
using *reduce_C_function*.

Parameters
----------
x, y : array or masked array

C : array or masked array, optional, default is *None*
x, y : array-like
The data positions. *x* and *y* must be of the same length.

gridsize : int or (int, int), optional, default is 100
The number of hexagons in the *x*-direction, default is
100. The corresponding number of hexagons in the
*y*-direction is chosen such that the hexagons are
approximately regular. Alternatively, gridsize can be a
tuple with two elements specifying the number of hexagons
in the *x*-direction and the *y*-direction.
C : array-like, optional
If given, these values are accumulated in the bins. Otherwise,
every point has a value of 1. Must be of the same length as *x*
and *y*.

bins : 'log' or int or sequence, optional, default is *None*
If *None*, no binning is applied; the color of each hexagon
directly corresponds to its count value.
gridsize : int or (int, int), default: 100
If a single int, the number of hexagons in the *x*-direction.
The number of hexagons in the *y*-direction is chosen such that
the hexagons are approximately regular.

If 'log', use a logarithmic scale for the color
map. Internally, :math:`log_{10}(i+1)` is used to
determine the hexagon color.
Alternatively, if a tuple (*nx*, *ny*), the number of hexagons
in the *x*-direction and the *y*-direction.

If an integer, divide the counts in the specified number
of bins, and color the hexagons accordingly.
bins : 'log' or int or sequence, default: *None*
Discretization of the hexagon values.

If a sequence of values, the values of the lower bound of
the bins to be used.
- If *None*, no binning is applied; the color of each hexagon
directly corresponds to its count value.
- If 'log', use a logarithmic scale for the color map.
Internally, :math:`log_{10}(i+1)` is used to determine the
hexagon color. This is equivalent to ``norm=LogNorm()``.
- If an integer, divide the counts in the specified number
of bins, and color the hexagons accordingly.
- If a sequence of values, the values of the lower bound of
the bins to be used.

xscale : {'linear', 'log'}, optional, default is 'linear'
xscale : {'linear', 'log'}, default: 'linear'
Use a linear or log10 scale on the horizontal axis.

yscale : {'linear', 'log'}, optional, default is 'linear'
yscale : {'linear', 'log'}, default: 'linear'
Use a linear or log10 scale on the vertical axis.

mincnt : int > 0, optional, default is *None*
mincnt : int > 0, default: *None*
If not *None*, only display cells with more than *mincnt*
number of points in the cell
number of points in the cell.

marginals : bool, optional, default is *False*
if marginals is *True*, plot the marginal density as
marginals : bool, default: *False*
If marginals is *True*, plot the marginal density as
colormapped rectangles along the bottom of the x-axis and
left of the y-axis
left of the y-axis.

extent : scalar, optional, default is *None*
extent : float, default: *None*
The limits of the bins. The default assigns the limits
based on *gridsize*, *x*, *y*, *xscale* and *yscale*.

Expand All @@ -4565,54 +4562,67 @@ def hexbin(self, x, y, C=None, gridsize=100, bins=None,

Other Parameters
----------------
cmap : object, optional, default is *None*
a :class:`matplotlib.colors.Colormap` instance. If *None*,
defaults to rc ``image.cmap``.
cmap : str or `~matplotlib.colors.Colormap`, optional
The Colormap instance or registered colormap name used to map
the bin values to colors. Defaults to :rc:`image.cmap`.

norm : object, optional, default is *None*
:class:`matplotlib.colors.Normalize` instance is used to
scale luminance data to (0, 1).
norm : `~matplotlib.colors.Normalize`, optional
The Normalize instance scales the bin values to the canonical
colormap range [0, 1] for mapping to colors. By default, the data
range is mapped to the colorbar range using linear scaling.

vmin, vmax : scalar, optional, default is *None*
*vmin* and *vmax* are used in conjunction with *norm* to
normalize luminance data. If *None*, the min and max of the
color array *C* are used. Note if you pass a norm instance
your settings for *vmin* and *vmax* will be ignored.
vmin, vmax : float, optional, default: None
The colorbar range. If *None*, suitable min/max values are
automatically chosen by the `~.Normalize` instance (defaults to
the respective min/max values of the bins in case of the default
linear scaling). This is ignored if *norm* is given.

alpha : scalar between 0 and 1, optional, default is *None*
the alpha value for the patches
alpha : float between 0 and 1, optional
The alpha blending value, between 0 (transparent) and 1 (opaque).

linewidths : scalar, optional, default is *None*
linewidths : float, default: *None*
If *None*, defaults to 1.0.

edgecolors : {'face', 'none', *None*} or color, optional
edgecolors : {'face', 'none', *None*} or color, default: 'face'
The color of the hexagon edges. Possible values are:

If 'face' (the default), draws the edges in the same color as the
fill color.
- 'face': Draw the edges in the same color as the fill color.
- 'none': No edges are drawn. This can sometimes lead to unsightly
unpainted pixels between the hexagons.
- *None*: Draw outlines in the default color.
- An explicit matplotlib color.

If 'none', no edge is drawn; this can sometimes lead to unsightly
unpainted pixels between the hexagons.
reduce_C_function : callable, default is `numpy.mean`
The function to aggregate *C* within the bins. It is ignored if
*C* is not given. This must have the signature::

If *None*, draws outlines in the default color.
def reduce_C_function(C: array) -> float

If a matplotlib color arg, draws outlines in the specified color.
Commonly used functions are:

- `numpy.mean`: average of the points
- `numpy.sum`: integral of the point values
- `numpy.max`: value taken from the largest point

**kwargs : `~matplotlib.collections.PolyCollection` properties
All other keyword arguments are passed on to `.PolyCollection`:

%(PolyCollection)s

Returns
-------
polycollection
A `.PolyCollection` instance; use `.PolyCollection.get_array` on
this to get the counts in each hexagon.
polycollection : `~matplotlib.collections.PolyCollection`
A `.PolyCollection` defining the hexagonal bins.

- `.PolyCollection.get_offset` contains a Mx2 array containing
the x, y positions of the M hexagon centers.
- `.PolyCollection.get_array` contains the values of the M
hexagons.

If *marginals* is *True*, horizontal
bar and vertical bar (both PolyCollections) will be attached
to the return collection as attributes *hbar* and *vbar*.

Notes
-----
The standard descriptions of all the
:class:`~matplotlib.collections.Collection` parameters:

%(Collection)s
"""
self._process_unit_info(xdata=x, ydata=y, kwargs=kwargs)

Expand Down