Colorbar only tut #8600

patniharshit · 2017-05-09T21:02:41Z

PR Summary

Trying to convert colorbar_only example to tutorial.

cc @choldgraf

#8561

PR Checklist

Has Pytest style unit tests
Code is PEP 8 compliant
New features are documented, with examples if plot related
Documentation is sphinx and numpydoc compliant
Added an entry to doc/users/whats_new.rst if major new feature
Documented in doc/api/api_changes.rst if API changed in a backward-incompatible way

story645

also cc @choldgraf since he's been kinda lead on documentation lately.

story645 · 2017-05-10T21:18:59Z

tutorials/colors/colorbar_only.py

+Customized Colorbars Tutorial
+=============================
+
+This tutorial shows how to build colorbars without an attached mappable.


Since this is a tutorial, use something less jargony than mappable. Without an attached plot maybe?

Mappable replaced by plot.

story645 · 2017-05-10T22:17:27Z

tutorials/colors/colorbar_only.py

+import matplotlib.pyplot as plt
+import matplotlib as mpl
+
+fig = plt.figure(figsize=(8, 3))


I wonder if you can get away with this since axes stuff isn't the point of this tutorial:
fig, (ax1, ax2, ax3) = plt.subplots(nrows=3, figsize=(8,3))

Even figsize is not necessary so removed that too.

story645 · 2017-05-10T22:18:24Z

tutorials/colors/colorbar_only.py

+# ---------------------------
+#
+# The second example illustrates the use of a ListedColormap which generates
+# colormap from a set of listed colors, a BoundaryNorm which generates a


generates a

story645 · 2017-05-10T22:18:38Z

tutorials/colors/colorbar_only.py

+#
+# The second example illustrates the use of a ListedColormap which generates
+# colormap from a set of listed colors, a BoundaryNorm which generates a
+# colormap index based on discrete interval and extended ends to show the


discrete intervals

story645 · 2017-05-10T22:55:13Z

tutorials/colors/colorbar_only.py

+# Colorbar with custom extension lengths
+# --------------------------------------
+#
+# Now in the third example we illustrate the use of custom length colorbar


Here we illustrate the use of custom length colorbar extensions. (They're used on both discrete and continuous colorbars.)

I am guessing here that 'Now in the third example' is needed to be replaced by 'Here'. Correct me if I am wrong.

story645 · 2017-05-10T22:55:51Z

tutorials/colors/colorbar_only.py

+# Now in the third example we illustrate the use of custom length colorbar
+# extensions, used on a colorbar with discrete intervals. Here we pass colors
+# as RGB triplet. To make the length of each extension the same as the length
+# of the interior colors pass extendfrac argument as auto


pass the extendfrac argument

story645 · 2017-05-10T22:58:17Z

tutorials/colors/colorbar_only.py

+# ====================
+#
+# `matplotlib.colorbar.ColorbarBase` derives from `ScalarMappable` and puts a
+# colorbar in specified axes, it is the base class with standalone colorbar


I think the original is clearer:

ColorbarBase derives from ScalarMappable and puts a colorbar in a specified axes, so it has everything needed for a standalone colorbar.

story645 · 2017-05-10T22:58:34Z

tutorials/colors/colorbar_only.py

+#
+# `matplotlib.colorbar.ColorbarBase` derives from `ScalarMappable` and puts a
+# colorbar in specified axes, it is the base class with standalone colorbar
+# drawing functionality. It can be used as-is to make a colorbar for a given


no dash in as is

Dash removed.

patniharshit · 2017-05-11T05:47:13Z

tutorials/colors/colorbar_only.py

+# the length of each extension the same as the length of the interior colors
+# pass the extendfrac argument as auto.
+
+cmap = mpl.colors.ListedColormap([[0., .4, 1.], [0., .8, 1.],


Instead of passing color in RGB format, I feel it will be more clear if colors are referenced by name?

Totally agree.

What is the name of the color with RGB = (0, 0.4, 1)?

choldgraf · 2017-05-11T16:32:03Z

tutorials/colors/colorbar_only.py

+
+"""
+
+###############################################################################


not a big deal but you technically don't need to be commenting out lines here, just extend the """ up until the first bit of code

Changed so as to have uniform format in all tutorials.

choldgraf · 2017-05-11T16:32:39Z

tutorials/colors/colorbar_only.py

+# object like an image. In this tutorial we will explore what can be done with
+# standalone colorbar.
+#
+# We will start by making a figure of desired size and adding thress axes.


three axes

Is ScalarMappable something we can link to via :mod:? If so we should do it, it's going to be unclear to most people what this is (if it's important)

choldgraf · 2017-05-11T16:34:19Z

tutorials/colors/colorbar_only.py

+# will be used. Then create the colorbar by calling `ColorbarBase` and
+# specify axis, colormap, norm and orientation as parameters. Here we create
+# a basic continuous colorbar with ticks and labels. There are many more kwargs
+# which can be used to further modify the colorbar.


In these kinds of sentences I like to say something like "for more examples, see ". Something worth thinking of inserting where reasonable!

I wasn't sure where could it point to so gave a link to colorbar api.

choldgraf · 2017-05-11T16:34:40Z

tutorials/colors/colorbar_only.py

+# outside of the normalized [0,1] range. Here we pass colors as gray shades as
+# a string encoding a float in the 0-1 range.
+#
+# If a ListedColormap is used, the length of the bounds array must be


":class:matplotlib.colors.ListedColormap"

(and elsewhere in any point that we refer to a specific class / function / module in MPL)

choldgraf · 2017-05-11T16:36:37Z

tutorials/colors/colorbar_only.py

+cb3.set_label('Custom extension lengths, some other units')
+
+plt.tight_layout()
+plt.show()


stupid question but is there an extra line at the bottom? I think that's best practices but not sure what MPL does as a standard.

Thanks for pointing it out. My text editor was inserting a new line on save, fixed now.

There should be a newline at the end. If GitHub has that little red symbol on the last line, it means there isn't one.

oops - yes I meant we wanted the new line, sorry about the confusion

choldgraf · 2017-05-11T16:37:10Z

@patniharshit looking really nice! thanks for putting this together. I've got a couple quick points in there but I think it's looking great.

choldgraf · 2017-05-12T15:33:52Z

tutorials/colors/colorbar_only.py

-# the length of each extension the same as the length of the interior colors
-# pass the extendfrac argument as auto.
+# colorbar with discrete intervals. To make the length of each extension the
+# same as the length of the interior colors pass the *extendfrac* argument as


"...length of the interior colors, use extendfrac='auto'"

choldgraf · 2017-05-12T15:34:57Z

small point in there about using double backticks for the kwarg but other than that LGTM

choldgraf · 2017-05-12T16:08:41Z

tutorials/colors/colorbar_only.py

-# same as the length of the interior colors pass the *extendfrac* argument as
-# *auto*.
+# colorbar with discrete intervals. To make the length of each extension same
+# as the length of the interior colors, use extendfrac='auto'.


sorry to be picky, but I meant adding in double backticks around it, so:

``extendfrac='auto'``

so that it will render like: extendfrac='auto' instead of "extendfrac='auto'"

I'd edit the branch if I could but I don't have commit rights :-/

choldgraf · 2017-05-12T16:58:54Z

tutorials/colors/colorbar_only.py

@@ -85,7 +85,7 @@
 #
 # Here we illustrate the use of custom length colorbar extensions, used on a
 # colorbar with discrete intervals. To make the length of each extension same
-# as the length of the interior colors, use extendfrac='auto'.
+# as the length of the interior colors, use ``extendfrac='auto'``.


actually do you think you could make this triple backticks?

...JK, this PR looks good to me :)

patniharshit · 2017-05-14T18:44:10Z

Whats the issue here? Why check is failing?

choldgraf · 2017-05-14T18:53:41Z

Check out the logs in travis: https://travis-ci.org/matplotlib/matplotlib/jobs/231794760

One drawback of sphinx-gallery is that it collects the figure each time it hits another RST block, so you need to re-do fig, ax = plt.subplots each time you want a new figure to show up in the rST. It's one of those annoying errors that works fine when you run the example on your own, but breaks with sphinx-gallery.

choldgraf · 2017-05-15T15:48:16Z

Looks like tests are passing. @story645 do you know if there's a build that generates the website for us? E.g., MNE uses circle.ci to generate the documentation as a part of the tests, which is a really nice sanity check to make sure it looks correct at the end of documentation PRs.

patniharshit · 2017-05-15T16:07:55Z

Just removed a line in comments which read like draw a figure and three axes. It lost its value after we switched to making seperate fig and axis in each rst block instead of making three axes initially.

story645 · 2017-05-15T21:20:17Z

Sorry @choldgraf dunno. I know at least one of the tests builds docs, but dunno which one it renders. Maybe @tacaswell can answer this question?

QuLogic · 2017-05-15T21:38:15Z

There are two builds that run the docs, but unfortunately do not upload them anywhere. Travis doesn't hold artifacts though it can go to S3, but I think no-one remembers the key for it...

choldgraf · 2017-05-15T23:18:54Z

@QuLogic I've found it really useful for building docs, particularly when building them locally is non-trivial (as it is with MPL). I can ask the MNE dev that set it up for us if they can explain how tough it was, in case it'd be useful for MPL...lemme know!

Otherwise, this PR looks good to me

dstansby

👍 Thanks!

patniharshit added 2 commits May 10, 2017 02:23

Convert colorbar_only example to tutorial

f8d96be

Move to tutorial directory

d6b49b9

story645 reviewed May 10, 2017

View reviewed changes

Changes in colorbar_only tutorial documentation

1a2b58a

patniharshit commented May 11, 2017

View reviewed changes

choldgraf reviewed May 11, 2017

View reviewed changes

Changes to colorbar_only tutorial

a875825

dstansby added the Documentation label May 12, 2017

dstansby added this to the 2.1 (next point release) milestone May 12, 2017

choldgraf reviewed May 12, 2017

View reviewed changes

Change how kwarg extendfrac is presented in colorbar_only tutorial

c7f582c

choldgraf reviewed May 12, 2017

View reviewed changes

Add double backticks to extendfrac in colorbar_only tutorial

00e7d0f

choldgraf reviewed May 12, 2017

View reviewed changes

Add new line at the end of the file

3c19954

Call for new figure in each rst block

6ae3c6f

Remove a line asking to create three axes in colorbar_only tutorial

2996c49

dstansby approved these changes May 29, 2017

View reviewed changes

dstansby merged commit 8d40dce into matplotlib:master May 29, 2017

dstansby mentioned this pull request May 29, 2017

Convert colorbar_only to tutorial #8561

Closed


		"""

		###############################################################################

Colorbar only tut #8600

Colorbar only tut #8600

Conversation

patniharshit commented May 9, 2017 • edited Loading

PR Summary

PR Checklist

story645 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

choldgraf May 11, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

choldgraf commented May 11, 2017

Choose a reason for hiding this comment

choldgraf commented May 12, 2017

choldgraf May 12, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

patniharshit commented May 14, 2017

choldgraf commented May 14, 2017

choldgraf commented May 15, 2017

patniharshit commented May 15, 2017 • edited Loading

story645 commented May 15, 2017 • edited Loading

QuLogic commented May 15, 2017

choldgraf commented May 15, 2017

dstansby left a comment

Choose a reason for hiding this comment

patniharshit commented May 9, 2017 •

edited

Loading

choldgraf May 11, 2017 •

edited

Loading

choldgraf May 12, 2017 •

edited

Loading

patniharshit commented May 15, 2017 •

edited

Loading

story645 commented May 15, 2017 •

edited

Loading