8000 DOC updated hexbin documentation to numpydoc format. by dcmarcu · Pull Request #7170 · matplotlib/matplotlib · GitHub
[go: up one dir, main page]
Skip to content

DOC updated hexbin documentation to numpydoc format. #7170

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 6 commits into from
Sep 28, 2016
Merged

DOC updated hexbin documentation to numpydoc format. #7170

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
e93286d
DOC updated hexbin documentation to numpydoc format.
dcmarcu Sep 23, 2016
dfa9f6f
DOC fixed pep8 compliance, added parameter defaults, fixed parsing is…
dcmarcu Sep 25, 2016
22acb50
DOC fixed pep8 conformance issue on line 4183 (line too long), made i…
dcmarcu Sep 25, 2016
d0aa9ae
DOC Reduced repetitions, made corrections on linewidths and edgecolors
dcmarcu Sep 26, 2016
d43caec
Fixed line 4173 for pep8 conformance
dcmarcu Sep 26, 2016
465f7b2
DOC Updated gridsize description, language consistency where multiple…
dcmarcu Sep 27, 2016
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
Prev Previous commit
Next Next commit
DOC fixed pep8 compliance, added parameter defaults, fixed parsing is… 
…sues
  • Loading branch information
@dcmarcu
dcmarcu committed Sep 25, 2016
commit dfa9f6fe1f6344757bedd098106e5a49e6bbeb92
61 changes: 28 additions & 33 deletions lib/matplotlib/axes/_axes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4094,30 +4094,30 @@ def hexbin(self, x, y, C=None, gridsize=100, bins=None,
defaults to numpy's mean function (np.mean). (If *C* is
specified, it must also be a 1-D sequence of the same length
as *x* and *y*.)

Parameters
----------
x : array
may be masked array, in which case only unmasked points
will be plotted
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would like to see a reduction of the repetition here. I think that for x, y, C you can just say "array or masked array" on the top line. No need to spell out that masked points will be ignored. Or, a note like the original single sentence about masked arrays can be put somewhere.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@QuLogic has the right suggestion below, applicable here also: group x, y : array or masked array. C needs its own line because it is optional.


y : array
may be masked array, in which case only unmasked points
will be plotted
C : array

C : array, default is *None*
may be masked array, in which case only unmasked points
will be plotted

gridsize : int, optional
gridsize : int, optional, default is 100
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should say something like "int, (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.

bins : {'log'} or int or sequence, optional
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.

Expand All @@ -4131,69 +4131,64 @@ def hexbin(self, x, y, C=None, gridsize=100, bins=None,
If a sequence of values, the values of the lower bound of
the bins to be used.

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

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

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

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

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

If *xscale* or *yscale* is set to 'log', the limits are
expected to be the exponent for a power of 10. E.g. for
x-limits of 1 and 50 in 'linear' scale and y-limits
of 10 and 1000 in 'log' scale, enter (1, 50, 1, 3).

Order of scalars is (left, right, bottom, top).

Other parameters
----------------
Other keyword arguments controlling color mapping and normalization
arguments.

cmap : object, optional
cmap : object, optional, default is *None*
a :class:`matplotlib.colors.Colormap` instance. If *None*,
defaults to rc ``image.cmap``.
norm : object, optional

norm : object, optional, default is *None*
:class:`matplotlib.colors.Normalize` instance is used to
scale luminance data to 0,1.

vmin : scalar, optional
*vmin* is used in conjunction with *norm* to normalize
vmin : scalar, optional, default is *None*
*vmin* is used in conjunction with *norm* to normalize
luminance data. If *None*, the min of the color array *C*
is used. Note if you pass a norm instance, your settings
for *vmin* will be ignored.
vmax : scalar, optional

vmax : scalar, optional, default is *None*
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can consolidate: Under vmin, say "see vmax". Under vmax, concisely describe what they do; it is mostly the same, so you can minimize repetition.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They can be put together as the same entry with vmin, vmax : scalar, ...

*vmax* is used in conjunction with *norm* to normalize
luminance data. If *None*, the max of the color array *C*
is used. Note if you pass a norm instance, your settings
for *vmax* will be ignored.

alpha : scalar between 0 and 1, optional
alpha : scalar between 0 and 1, optional, default is *None*
the alpha value for the patches

linewidths : scalar, optional
linewidths : scalar, optional, default is *None*
If *None*, defaults to 1.0. Note that this is a tuple, and
if you set the linewidths argument you must set it as a
sequence of floats, as required by
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is repeating the original incorrect description. In fact, only a scalar makes sense here, although a sequence can be accepted if it is not too long. I can't see any reasonable use case for a sequence of length other than 1, for which one might as well use a scalar. So, please delete the sentence starting with "Note".

:class:`~matplotlib.collections.RegularPolyCollection`.

Other keyword arguments controlling the Collection properties.

edgecolors : {'none'}, mpl color, color sequence, optional
edgecolors : {'none'}, mpl color, color sequence, optional, default is 'none'
If 'none', draws the edges in the same color as the fill color.
This is the default, as it avoids unsightly unpainted pixels
between the hexagons.
Expand All @@ -4202,24 +4197,24 @@ def hexbin(self, x, y, C=None, gridsize=100, bins=None,

If a matplotlib color arg or sequence of rgba tuples, draws the
outlines in the specified color.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again, for hexbin, specifying anything other than a single color makes no sense: first, because one doesn't know at this point where the hexagon getting that edge color will be, and second, because even if one did, it would be nonsensical from a plotting standpoint. So please omit everything having to do with the color sequence.


Returns
-------
object
a :class:`~matplotlib.collections.PolyCollection` instance; use
:meth:`~matplotlib.collections.PolyCollection.get_array` on
this :class:`~matplotlib.collections.PolyCollection` to get
the counts in each hexagon.

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

Examples
--------
.. plot:: mpl_examples/pylab_examples/hexbin_demo.py
See also

Notes
--------
The standard descriptions of all the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "See Also" section is meant for other functions, methods or modules. This format will not be understood properly by numpdoc.
I think you should be using the "Notes" section instead of the "See Also" section.
It is also possible that the %(Collection)s needs tweaking, but I need to build the documentation to check this.

:class:`~matplotlib.collections.Collection` parameters:
Expand Down
0