DOC: colormap-manipulation tutorial #11905

jklymak · 2018-08-21T19:35:33Z

PR Summary

closes #11903

Shows how to manipulate colormaps.

rendered version 24 Aug: https://12782-1385122-gh.circle-artifacts.com/0/home/circleci/project/doc/build/html/tutorials/colors/colormap-manipulation.html#sphx-glr-tutorials-colors-colormap-manipulation-py

PR Checklist

Needs links in API docs...
Code is PEP 8 compliant
Documentation is sphinx and numpydoc compliant

jklymak · 2018-08-21T22:46:54Z

This is ready for suggestion (but not formal review, as I've not linked everything, nor squashed all flake8 complaints)

https://12679-1385122-gh.circle-artifacts.com/0/home/circleci/project/doc/build/html/tutorials/colors/colormap-manipulation.html#sphx-glr-tutorials-colors-colormap-manipulation-py

jklymak · 2018-08-22T18:28:34Z

https://circleci.com/gh/matplotlib/matplotlib/12711/artifacts/0//home/circleci/project/doc/build/html/index.html

Removing work in progress, though one could argue that some of this should end up in examples/color as well...

tacaswell · 2018-08-23T01:28:22Z

tutorials/colors/colormap-manipulation.py

+# 0.5 of the colormap.
+
+viridis = cm.get_cmap('viridis', 256)
+newcmp = ListedColormap(viridis(np.linspace(0.25, 0.75, 256)))


Will this have over-sampling issues?

Ooops, yes it will. Not really noticeable at 256 resolution, but would certainly be a problem for small colormaps. Changed to

# We can easily reduce the dynamic range of a colormap; here we choose the middle # 0.5 of the colormap. However, we need to interpolate from a larger # colormap, otherwise the new colormap will have repeated values. viridisBig = cm.get_cmap('viridis', 512) newcmp = ListedColormap(viridisBig(np.linspace(0.25, 0.75, 256))) plot_examples([viridis, newcmp])

tacaswell · 2018-08-23T01:34:38Z

Overall I like this!

I might tone down selling how hard this is in the top of the tutorial a bit.

jklymak · 2018-08-23T02:58:24Z

I might tone down selling how hard this is in the top of the tutorial a bit.

Fair enough - I shouldn't point out my own confusion in tutorials. First two paragraphs now just one:


Creating and manipulating colormaps in Matplotlib is quite straight-forward
using the class `.ListedColormap` and a Nx4 numpy array of values
between 0 and 1 to represent the RGBA values of the colormap.  There
is also a `.LinearSegmentedColormap` class that allows colormaps to be
specified with far fewer anchor points defining segments, and linearly
interpolating between the anchor points.

tacaswell · 2018-08-23T03:07:12Z

I added a one word commit (removed 'quite' as I think it falls into the same category as 'just' as a word that can be read by people who don't already know the next part of the sentence as "only dumb people do not know ..." ).

timhoffm · 2018-08-24T08:09:18Z

lib/matplotlib/cm.py

@@ -1,8 +1,13 @@
 """
 Builtin colormaps, colormap handling utilities, and the `ScalarMappable` mixin.

-See :doc:`/gallery/color/colormap_reference` for a list of builtin colormaps.
-See :doc:`/tutorials/colors/colormaps` for an in-depth discussion of colormaps.
+  - See :doc:`/gallery/color/colormap_reference` for a list of builtin


Don't indent bullet points. RestructuredText interprets this as a blockquote. This leads to over-indented bullet points in the HTML.

No problem - shoudl this be a seealso::?

Yeah, you could make this a seealso::.

If you switch to seealso:: the following is just for information: Make sure to write bullet lists exactly like this:

Some paragraph: - Some long text that is continued on the next line. - Some other text. Normal paragraph again.

No indent of the bullets with respect to the surronding paragraphs (that's fixed now).

Continued bulleted lines have to have the text alinged with the text after the bullet (you had extra indentation here.

There needs to be an empty line before and after the bullet list.

I know this is a bit picky, but that's how restructered text wants it.

timhoffm · 2018-08-24T08:42:14Z

tutorials/colors/colormap-manipulation.py

+plot_examples([viridis, newcmp])
+
+##############################################################################
+# LinearSegmented colormaps


Would call this "Creating a new LinearSegmentedColormap" in resemblence to "Creating a new ListedColormap".

Not sure if we need the "new" in the title.

timhoffm · 2018-08-24T08:43:08Z

tutorials/colors/colormap-manipulation.py

+# LinearSegmented colormaps
+# =========================
+#
+# `.LinearSegmentedColormap` have an alternate way to specify colormaps that


Alternative wording:

LinearSegmentedColormap specifies the colors using anchor points. The RGB(A) color values for positions in between the anchor points are linearly interpolated from the anchor point RGB(A) values.

rewritten...

timhoffm · 2018-08-24T08:52:03Z

tutorials/colors/colormap-manipulation.py

+# (RGBA).
+#
+# The format to specify these colormaps is a bit complicated to allow
+# discontinuities at the anchor points.  First, with no discontinuities:


I think the format needs a description here, or at least a "See LinearSegmentedColormap for a description of the format."

new version describes the format.

jklymak · 2018-08-24T21:22:33Z

Thanks @timhoffm https://12778-1385122-gh.circle-artifacts.com/0/home/circleci/project/doc/build/html/tutorials/colors/colormap-manipulation.html#sphx-glr-tutorials-colors-colormap-manipulation-py has some reworked stuff, particularly in the LinearSegmentedColormap section.

timhoffm

The LinearSegmented color map is much cleaner now.

Good to go after the bullet list/seealso in cm.py is fixed.

timhoffm · 2018-08-24T22:11:38Z

tutorials/colors/colormap-manipulation.py

+plot_examples([viridis, newcmp])
+
+##############################################################################
+# Creating LinearSegmented colormaps


I would either use the class name "Creating LinearSegmentedColormaps" or a textual description "Creating linear segmented colormaps" (or maybe "Creating linear-segmented colormaps" I'm never sure when to use a hyphen). In any case no mixture.

Same with "Creating listed colormaps".

Now

Creating listed colormaps

Creating linear segmented colormaps

jklymak · 2018-08-24T23:09:09Z

Thanks again @timhoffm: https://12782-1385122-gh.circle-artifacts.com/0/home/circleci/project/doc/build/html/tutorials/colors/colormap-manipulation.html#sphx-glr-tutorials-colors-colormap-manipulation-py

lumberbot-app · 2018-08-25T13:28:02Z

Owee, I'm MrMeeseeks, Look at me.

There seem to be a conflict, please backport manually. Here are approximate instructions:

Checkout backport branch and update it.

$ git checkout v2.2.3-doc
$ git pull

Cherry pick the first parent branch of the this PR on top of the older branch:

$ git cherry-pick -m1 b02c22dcdcda8931f00b14da2ad8a3d7356c55d8

You will likely have some merge/cherry-pick conflict here, fix them and commit:

$ git commit -am 'Backport PR #11905: DOC: colormap-manipulation tutorial'

Push to a named branch :

git push YOURFORK v2.2.3-doc:auto-backport-of-pr-11905-on-v2.2.3-doc

Create a PR against branch v2.2.3-doc, I would have named this PR:

"Backport PR #11905 on branch v2.2.3-doc"

And apply the correct labels and milestones.

Congratulation you did some good work ! Hopefully your backport PR will be tested by the continuous integration and merged soon!

If these instruction are inaccurate, feel free to suggest an improvement.

timhoffm · 2018-08-25T13:28:12Z

Thanks! This is a significant improvement on the documentation of colormaps.

…ipulation DOC: colormap-manipulation tutorial

DOC: Backport colormap documentation Includes #11905, #11799, #11881, and #12084

DOC: colormap-manipulation tutorial

daa9c59

jklymak added Documentation status: work in progress labels Aug 21, 2018

DOC: colormap-manipulation tutorial

6d2a7bc

lkilcher mentioned this pull request Aug 21, 2018

[NF] Add 'truncate' and 'join' methods to colormaps. #7716

Closed

jklymak mentioned this pull request Aug 22, 2018

DOC: Colormap tutorial needs info on manipulating colormaps #11903

Closed

jklymak force-pushed the doc-add-colormap-manipulation branch 5 times, most recently from a0582fc to 2d51a38 Compare August 22, 2018 17:08

DOC: move custom_colormap

f58f5f3

jklymak force-pushed the doc-add-colormap-manipulation branch from 2d51a38 to f58f5f3 Compare August 22, 2018 17:57

jklymak removed the status: work in progress label Aug 22, 2018

jklymak changed the title ~~[WIP] DOC: colormap-manipulation tutorial~~ DOC: colormap-manipulation tutorial Aug 22, 2018

jklymak requested a review from afvincent August 22, 2018 18:29

tacaswell reviewed Aug 23, 2018

View reviewed changes

tacaswell added this to the v2.2-doc milestone Aug 23, 2018

jklymak and others added 2 commits August 22, 2018 19:58

DOC: fix overinterp issue and modify intro para

d6a5179

DOC: minor wording change

c6544d8

tacaswell approved these changes Aug 23, 2018

View reviewed changes

timhoffm reviewed Aug 24, 2018

View reviewed changes

jklymak mentioned this pull request Aug 24, 2018

ColorbarBase fails to show if the first two values map to the same result #11923

Closed

jklymak force-pushed the doc-add-colormap-manipulation branch 2 times, most recently from 76b263c to 04e096f Compare August 24, 2018 17:42

jklymak force-pushed the doc-add-colormap-manipulation branch 7 times, most recently from 4302477 to e76b41b Compare August 24, 2018 20:53

timhoffm approved these changes Aug 24, 2018

View reviewed changes

timhoffm reviewed Aug 24, 2018

View reviewed changes

jklymak force-pushed the doc-add-colormap-manipulation branch from e76b41b to 84e9f62 Compare August 24, 2018 22:23

DOC: try better math

e9cda7f

jklymak force-pushed the doc-add-colormap-manipulation branch from 84e9f62 to e9cda7f Compare August 24, 2018 22:32

jklymak removed the request for review from afvincent August 24, 2018 23:28

timhoffm merged commit b02c22d into matplotlib:master Aug 25, 2018

lumberbot-app bot added the status: needs manual backport label Aug 25, 2018

tacaswell modified the milestones: v2.2-doc, v3.0.2 Nov 10, 2018

tacaswell pushed a commit to tacaswell/matplotlib that referenced this pull request Nov 10, 2018

Merge pull request matplotlib#11905 from jklymak/doc-add-colormap-man…

c9a71f0

…ipulation DOC: colormap-manipulation tutorial

tacaswell mentioned this pull request Nov 10, 2018

Backports colormap #12789

Merged

tacaswell added a commit that referenced this pull request Nov 10, 2018

Merge pull request #12789 from tacaswell/backports_colormap

906f6ea

DOC: Backport colormap documentation Includes #11905, #11799, #11881, and #12084

dstansby removed the status: needs manual backport label Jun 7, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: colormap-manipulation tutorial #11905

DOC: colormap-manipulation tutorial #11905

jklymak commented Aug 21, 2018 •

edited

Loading

jklymak commented Aug 21, 2018

jklymak commented Aug 22, 2018

tacaswell Aug 23, 2018

jklymak Aug 23, 2018

tacaswell commented Aug 23, 2018

jklymak commented Aug 23, 2018

tacaswell commented Aug 23, 2018

timhoffm Aug 24, 2018

jklymak Aug 24, 2018

timhoffm Aug 24, 2018

timhoffm Aug 24, 2018

jklymak Aug 24, 2018

timhoffm Aug 24, 2018

jklymak Aug 24, 2018

timhoffm Aug 24, 2018

jklymak Aug 24, 2018

jklymak commented Aug 24, 2018

timhoffm left a comment

timhoffm Aug 24, 2018

jklymak Aug 24, 2018

jklymak commented Aug 24, 2018

lumberbot-app bot commented Aug 25, 2018

timhoffm commented Aug 25, 2018

DOC: colormap-manipulation tutorial #11905

DOC: colormap-manipulation tutorial #11905

Conversation

jklymak commented Aug 21, 2018 • edited Loading

PR Summary

PR Checklist

jklymak commented Aug 21, 2018

jklymak commented Aug 22, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tacaswell commented Aug 23, 2018

jklymak commented Aug 23, 2018

tacaswell commented Aug 23, 2018

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

jklymak commented Aug 24, 2018

timhoffm left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jklymak commented Aug 24, 2018

lumberbot-app bot commented Aug 25, 2018

timhoffm commented Aug 25, 2018

jklymak commented Aug 21, 2018 •

edited

Loading