Join GitHub today
GitHub is home to over 20 million developers working together to host and review code, manage projects, and build software together.
Clean up BoundaryNorm docstring #8007
Conversation
dstansby
added the
Documentation
label
Feb 1, 2017
| - then v is mapped to color j; | ||
| + Notes | ||
| + ----- | ||
| + If :code:`b[i] <= v < b[i+1]` then v is mapped to color j; |
| + ncolors : int | ||
| + 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 |
dstansby
Feb 2, 2017
Contributor
But http://matplotlib.org/devdocs/devel/documenting_mpl.html#formatting says to explicitly not do that! (at least for arguments to functions)
anntzer
Feb 2, 2017
Contributor
Indeed, that simply means I've been doing things wrong :-)
https://docs.python.org/devguide/documenting.html#id3 (the mpl docs refer to consistency with python itself) says to use emphasis specifically for local variables (i.e. arguments) only.
|
I think this obscures the most common case where both are of equal length. I would say something like (could be enhanced) "Boundaries define bins, that are each mapped to the color with the same index (or linearly interpolating the index if the sizes don't match)." |
| + Notes | ||
| + ----- | ||
| + If :code:`b[i] <= v < b[i+1]` then v is mapped to | ||
| + floor( :math:`\frac{n_{colors}- 1}{n_{bins} - 1} * i`), where nbins is |
dstansby
Feb 2, 2017
Contributor
I thought it looked better visually outside, but I can put it inside.
| - above *boundaries[-1]*. | ||
| + 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]``. | ||
| If clip is *False*, out of range values are mapped to *-1* if they |
dstansby
added the
needs_review
label
Feb 10, 2017
dstansby
added
to Needs review in Reviewing pull requests.
Feb 18, 2017
NelleV
approved these changes
Feb 24, 2017
LGTM
| - b[i] <= v < b[i+1] | ||
| + Parameters | ||
| + ---------- | ||
| + boundaries : sequence |
| + ncolors : int | ||
| + 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 |
NelleV
Feb 24, 2017
Contributor
Can you please remove the *? They make docstrings hard to read in the terminal
| + Raises | ||
| + ------ | ||
| + ValueError | ||
| + BoundaryNorm is not invertible, so calling this method will always |
NelleV
changed the title from
Clean up BoundaryNorm docstring to [MRG+1] Clean up BoundaryNorm docstring
Feb 24, 2017
|
Those should be fixed now |
| - If clip == True, out-of-range values | ||
| - are mapped to 0 if low and ncolors-1 if high. | ||
| + If the number of bins doesn't equal *ncolors*, the color is chosen | ||
| + by linear inpolation of the bin number onto color numbers. |
|
Thanks! |
dstansby commentedFeb 1, 2017
invertwill always raise aValueError