Skip to content

Clean up BoundaryNorm docstring #8007

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
Mar 5, 2017
Merged

Clean up BoundaryNorm docstring #8007

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
2b6699c
Clean up BoundaryNorm docstring
dstansby Feb 1, 2017
32641c7
Document what happens when ncolors > bins
dstansby Feb 2, 2017
b3b0750
BoundaryNorm docstring clarification
dstansby Feb 3, 2017
da208dd
BoundaryNorm docstring formatting
dstansby Feb 3, 2017
99279b4
Small docstring fixes
dstansby Feb 25, 2017
9dd7110
Fix small spelling mistake
dstansby Feb 27, 2017
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
Next Next commit
Clean up BoundaryNorm docstring
  • Loading branch information
@dstansby
dstansby committed Feb 1, 2017
commit 2b6699c63daef39e9997f59b04ebdc8c480ee43f
41 changes: 25 additions & 16 deletions lib/matplotlib/colors.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1247,25 +1247,27 @@ class BoundaryNorm(Normalize):
"""
def __init__(self, boundaries, ncolors, clip=False):
"""
*boundaries*
a monotonically increasing sequence
*ncolors*
number of colors in the colormap to be used

If::

b[i] <= v < b[i+1]
Parameters
----------
boundaries : sequence
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 be array-like

Monotonically increasing sequence of boundaries
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
Copy link
Contributor

Choose a reason for hiding this comment

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

Use double backquotes here and below.

Copy link
Member Author

@dstansby dstansby Feb 2, 2017 •
edited
Loading

Choose a reason for hiding this comment

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

For clip or for True and 0?

Copy link
Contributor

Choose a reason for hiding this comment

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

I would say for all (they're all "code").

Copy link
Member Author

Choose a reason for hiding this comment

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

But http://matplotlib.org/devdocs/devel/documenting_mpl.html#formatting says to explicitly not do that! (at least for arguments to functions)

Copy link
Contributor

Choose a reason for hiding this comment

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

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.

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
Copy link
Member

Choose a reason for hiding this comment

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

False and boundaries[0] to be consistent with the previous paragrpha

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__`.

then v is mapped to color j;
Notes
-----
If :code:`b[i] <= v < b[i+1]` then v is mapped to color j;
Copy link
Contributor

Choose a reason for hiding this comment

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

What happens if the two lengths don't match?

Copy link
Member Author

Choose a reason for hiding this comment

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

I have no idea, will try and work out and update this later today.

as i varies from 0 to len(boundaries)-2,
j goes from 0 to ncolors-1.

Out-of-range values are mapped
to -1 if low and ncolors if high; these are converted
to valid indices by
:meth:`Colormap.__call__` .
If clip == True, out-of-range values
are mapped to 0 if low and ncolors-1 if high.
"""
self.clip = clip
self.vmin = boundaries[0]
Expand Down Expand Up @@ -1304,6 +1306,13 @@ def __call__(self, value, clip=None):
return ret

def inverse(self, value):
"""
Raises
------
ValueError
BoundaryNorm is not invertible, so calling this method will always
Copy link
Member

Choose a reason for hiding this comment

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

👍

raise an error
"""
return ValueError("BoundaryNorm is not invertible")


Expand Down