Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 11243ff

Browse files
kthyngkthyng
committed
finished up draft
1 parent 1354f36 commit 11243ff

1 file changed

Lines changed: 12 additions & 281 deletions

File tree

‎doc/users/colormaps.rst‎

Lines changed: 12 additions & 281 deletions
Original file line numberDiff line numberDiff line change
@@ -19,11 +19,13 @@ For many applications, a perceptual colormap is the best choice --- one in which
1919

2020
Color can be represented in 3D space in various ways. One way to represent color is using CIELAB. In CIELAB, color space is represented by lightness, :math:`L^*`; red-green, :math:`a^*`; and yellow-blue, :math:`b^*`. The lightness parameter :math:`L^*` can then be used to learn more about how the matplotlib colormaps will be perceived by viewers.
2121

22+
An excellent starting resource for learning about human perception of colormaps is from [IBM]_.
23+
2224

2325
Classes of colormaps
2426
====================
2527

26-
Colormaps are often split into several categories based on function (see, *e.g.*, [Moreland]_):
28+
Colormaps are often split into several categories based on their function (see, *e.g.*, [Moreland]_):
2729

2830
1. Sequential: change in lightness and often saturation of color incrementally, often using a single hue; should be used for representing information that has ordering.
2931
2. Diverging: change in lightness and possibly saturation of two different colors that meet in the middle at an unsaturated color; should be used when the information being plotted has a critical middle value, such as topography or when the data deviates around zero.
@@ -78,15 +80,19 @@ Grayscale conversion
7880

7981
Conversion to grayscale is important to pay attention to for printing publications that have color plots. If this is not paid attention to ahead of time, your readers may end up with indecipherable plots because the grayscale changes unpredictably through the colormap.
8082

81-
Conversion to grayscale is done in many different ways [bw]_. Some of the better ones use a linear combination of the rgb values of a pixel, but weighted according to how we perceive color intensity. A nonlinear method of conversion to grayscale is to use the :math:`L^*` values of the pixels. In general, similar principles apply for this question as they do for presenting one's information perceptually; that is, if a colormap is chosen that has monotonically increasing in :math:`L^*` values, it will print in a reasonable manner to grayscale.
83+
Conversion to grayscale is done in many different ways [bw]_. Some of the better ones use a linear combination of the rgb values of a pixel, but weighted according to how we perceive color intensity. A nonlinear method of conversion to grayscale is to use the :math:`L^*` values of the pixels. In general, similar principles apply for this question as they do for presenting one's information perceptually; that is, if a colormap is chosen that has monotonically increasing in :math:`L^*` values, it will print in a reasonable manner to grayscale.
84+
85+
With this in mind, we see that the Sequential colormaps have reasonable representations in grayscale. Some of the Sequential2 colormaps have decent enough grayscale representations, though some (autumn, spring, summer, winter) have very little grayscale change. If a colormap like this was used in a plot and then the plot was printed to grayscale, a lot of the information may map to the same gray values. The Diverging colormaps mostly vary from darker gray on the outer edges to white in the middle. Some (PuOr and seismic) have noticably darker gray on one side than the other and therefore are not very symmetric. coolwarm has little range of gray scale and would print to a more uniform plot, losing a lot of detail. Note that overlaid, labeled contours could help differentiate between one side of the colormap vs. the other since color cannot be used once a plot is printed to grayscale. Many of the Qualitative and Miscellaneous colormaps, such as Accent, hsv, and jet, change from darker to lighter and back to darker gray throughout the colormap. This would make it impossible for a viewer to interpret the information in a plot once it is printed in grayscale.
8286

8387
.. plot:: users/plotting/colormaps/grayscale.py
8488

8589

8690
Color vision deficiencies
8791
=========================
8892

89-
MORE
93+
There is a lot of information available about color blindness available (*e.g.*, [colorblindness]_). Additionally, there are tools available to convert images to how they look for different types of color vision deficiencies (*e.g.*, [asp]_).
94+
95+
The most common form of color vision deficiency involves differentiating between red and green. Thus, avoiding colormaps with both red and green will avoid many problems in general.
9096

9197

9298
References
@@ -100,282 +106,7 @@ References
100106
.. [mycarta_lablinear] http://mycarta.wordpress.com/2012/12/06/the-rainbow-is-deadlong-live-the-rainbow-part-5-cie-lab-linear-l-rainbow/
101107
.. [mycarta_cubelaw] http://mycarta.wordpress.com/2013/02/21/perceptual-rainbow-palette-the-method/
102108
.. [bw] http://www.tannerhelland.com/3643/grayscale-image-algorithm-vb6/
103-
IBM paper
104-
More
105-
106-
.. :mod:`matplotlib.pyplot` is a collection of command style functions
107-
.. that make matplotlib work like MATLAB.
108-
.. Each ``pyplot`` function makes
109-
.. some change to a figure: eg, create a figure, create a plotting area
110-
.. in a figure, plot some lines in a plotting area, decorate the plot
111-
.. with labels, etc.... :mod:`matplotlib.pyplot` is stateful, in that it
112-
.. keeps track of the current figure and plotting area, and the plotting
113-
.. functions are directed to the current axes
114-
115-
.. .. plot:: pyplots/pyplot_simple.py
116-
.. :include-source:
117-
118-
.. You may be wondering why the x-axis ranges from 0-3 and the y-axis
119-
.. from 1-4. If you provide a single list or array to the
120-
.. :func:`~matplotlib.pyplot.plot` command, matplotlib assumes it is a
121-
.. sequence of y values, and automatically generates the x values for
122-
.. you. Since python ranges start with 0, the default x vector has the
123-
.. same length as y but starts with 0. Hence the x data are
124-
.. ``[0,1,2,3]``.
125-
126-
.. :func:`~matplotlib.pyplot.plot` is a versatile command, and will take
127-
.. an arbitrary number of arguments. For example, to plot x versus y,
128-
.. you can issue the command::
129-
130-
.. plt.plot([1,2,3,4], [1,4,9,16])
131-
132-
.. For every x, y pair of arguments, there is an optional third argument
133-
.. which is the format string that indicates the color and line type of
134-
.. the plot. The letters and symbols of the format string are from
135-
.. MATLAB, and you concatenate a color string with a line style string.
136-
.. The default format string is 'b-', which is a solid blue line. For
137-
.. example, to plot the above with red circles, you would issue
138-
139-
.. .. plot:: pyplots/pyplot_formatstr.py
140-
.. :include-source:
141-
142-
.. See the :func:`~matplotlib.pyplot.plot` documentation for a complete
143-
.. list of line styles and format strings. The
144-
.. :func:`~matplotlib.pyplot.axis` command in the example above takes a
145-
.. list of ``[xmin, xmax, ymin, ymax]`` and specifies the viewport of the
146-
.. axes.
147-
148-
.. If matplotlib were limited to working with lists, it would be fairly
149-
.. useless for numeric processing. Generally, you will use `numpy
150-
.. <http://numpy.scipy.org>`_ arrays. In fact, all sequences are
151-
.. converted to numpy arrays internally. The example below illustrates a
152-
.. plotting several lines with different format styles in one command
153-
.. using arrays.
154-
155-
.. .. plot:: pyplots/pyplot_three.py
156-
.. :include-source:
157-
158-
.. .. _controlling-line-properties:
159-
160-
.. Controlling line properties
161-
.. ===========================
162-
163-
.. Lines have many attributes that you can set: linewidth, dash style,
164-
.. antialiased, etc; see :class:`matplotlib.lines.Line2D`. There are
165-
.. several ways to set line properties
166-
167-
.. * Use keyword args::
168-
169-
.. plt.plot(x, y, linewidth=2.0)
170-
171-
172-
.. * Use the setter methods of the ``Line2D`` instance. ``plot`` returns a list
173-
.. of lines; eg ``line1, line2 = plot(x1,y1,x2,y2)``. Below I have only
174-
.. one line so it is a list of length 1. I use tuple unpacking in the
175-
.. ``line, = plot(x, y, 'o')`` to get the first element of the list::
176-
177-
.. line, = plt.plot(x, y, '-')
178-
.. line.set_antialiased(False) # turn off antialising
179-
180-
.. * Use the :func:`~matplotlib.pyplot.setp` command. The example below
181-
.. uses a MATLAB-style command to set multiple properties
182-
.. on a list of lines. ``setp`` works transparently with a list of objects
183-
.. or a single object. You can either use python keyword arguments or
184-
.. MATLAB-style string/value pairs::
185-
186-
.. lines = plt.plot(x1, y1, x2, y2)
187-
.. # use keyword args
188-
.. plt.setp(lines, color='r', linewidth=2.0)
189-
.. # or MATLAB style string value pairs
190-
.. plt.setp(lines, 'color', 'r', 'linewidth', 2.0)
191-
192-
193-
.. Here are the available :class:`~matplotlib.lines.Line2D` properties.
194-
195-
.. ====================== ==================================================
196-
.. Property Value Type
197-
.. ====================== ==================================================
198-
.. alpha float
199-
.. animated [True | False]
200-
.. antialiased or aa [True | False]
201-
.. clip_box a matplotlib.transform.Bbox instance
202-
.. clip_on [True | False]
203-
.. clip_path a Path instance and a Transform instance, a Patch
204-
.. color or c any matplotlib color
205-
.. contains the hit testing function
206-
.. dash_capstyle [``'butt'`` | ``'round'`` | ``'projecting'``]
207-
.. dash_joinstyle [``'miter'`` | ``'round'`` | ``'bevel'``]
208-
.. dashes sequence of on/off ink in points
209-
.. data (np.array xdata, np.array ydata)
210-
.. figure a matplotlib.figure.Figure instance
211-
.. label any string
212-
.. linestyle or ls [ ``'-'`` | ``'--'`` | ``'-.'`` | ``':'`` | ``'steps'`` | ...]
213-
.. linewidth or lw float value in points
214-
.. lod [True | False]
215-
.. marker [ ``'+'`` | ``','`` | ``'.'`` | ``'1'`` | ``'2'`` | ``'3'`` | ``'4'`` ]
216-
.. markeredgecolor or mec any matplotlib color
217-
.. markeredgewidth or mew float value in points
218-
.. markerfacecolor or mfc any matplotlib color
219-
.. markersize or ms float
220-
.. markevery [ None | integer | (startind, stride) ]
221-
.. picker used in interactive line selection
222-
.. pickradius the line pick selection radius
223-
.. solid_capstyle [``'butt'`` | ``'round'`` | ``'projecting'``]
224-
.. solid_joinstyle [``'miter'`` | ``'round'`` | ``'bevel'``]
225-
.. transform a matplotlib.transforms.Transform instance
226-
.. visible [True | False]
227-
.. xdata np.array
228-
.. ydata np.array
229-
.. zorder any number
230-
.. ====================== ==================================================
231-
232-
.. To get a list of settable line properties, call the
233-
.. :func:`~matplotlib.pyplot.setp` function with a line or lines
234-
.. as argument
235-
236-
.. .. sourcecode:: ipython
237-
238-
.. In [69]: lines = plt.plot([1,2,3])
239-
240-
.. In [70]: plt.setp(lines)
241-
.. alpha: float
242-
.. animated: [True | False]
243-
.. antialiased or aa: [True | False]
244-
.. ...snip
245-
246-
.. .. _multiple-figs-axes:
247-
248-
.. Working with multiple figures and axes
249-
.. ======================================
250-
251-
252-
.. MATLAB, and :mod:`~matplotlib.pyplot`, have the concept of the current
253-
.. figure and the current axes. All plotting commands apply to the
254-
.. current axes. The function :func:`~matplotlib.pyplot.gca` returns the
255-
.. current axes (a :class:`matplotlib.axes.Axes` instance), and
256-
.. :func:`~matplotlib.pyplot.gcf` returns the current figure
257-
.. (:class:`matplotlib.figure.Figure` instance). Normally, you don't have
258-
.. to worry about this, because it is all taken care of behind the
259-
.. scenes. Below is a script to create two subplots.
260-
261-
.. .. plot:: pyplots/pyplot_two_subplots.py
262-
.. :include-source:
263-
264-
.. The :func:`~matplotlib.pyplot.figure` command here is optional because
265-
.. ``figure(1)`` will be created by default, just as a ``subplot(111)``
266-
.. will be created by default if you don't manually specify an axes. The
267-
.. :func:`~matplotlib.pyplot.subplot` command specifies ``numrows,
268-
.. numcols, fignum`` where ``fignum`` ranges from 1 to
269-
.. ``numrows*numcols``. The commas in the ``subplot`` command are
270-
.. optional if ``numrows*numcols<10``. So ``subplot(211)`` is identical
271-
.. to ``subplot(2,1,1)``. You can create an arbitrary number of subplots
272-
.. and axes. If you want to place an axes manually, ie, not on a
273-
.. rectangular grid, use the :func:`~matplotlib.pyplot.axes` command,
274-
.. which allows you to specify the location as ``axes([left, bottom,
275-
.. width, height])`` where all values are in fractional (0 to 1)
276-
.. coordinates. See :ref:`pylab_examples-axes_demo` for an example of
277-
.. placing axes manually and :ref:`pylab_examples-subplots_demo` for an
278-
.. example with lots-o-subplots.
279-
280-
281-
.. You can create multiple figures by using multiple
282-
.. :func:`~matplotlib.pyplot.figure` calls with an increasing figure
283-
.. number. Of course, each figure can contain as many axes and subplots
284-
.. as your heart desires::
285-
286-
.. import matplotlib.pyplot as plt
287-
.. plt.figure(1) # the first figure
288-
.. plt.subplot(211) # the first subplot in the first figure
289-
.. plt.plot([1,2,3])
290-
.. plt.subplot(212) # the second subplot in the first figure
291-
.. plt.plot([4,5,6])
292-
293-
294-
.. plt.figure(2) # a second figure
295-
.. plt.plot([4,5,6]) # creates a subplot(111) by default
296-
297-
.. plt.figure(1) # figure 1 current; subplot(212) still current
298-
.. plt.subplot(211) # make subplot(211) in figure1 current
299-
.. plt.title('Easy as 1,2,3') # subplot 211 title
300-
301-
.. You can clear the current figure with :func:`~matplotlib.pyplot.clf`
302-
.. and the current axes with :func:`~matplotlib.pyplot.cla`. If you find
303-
.. this statefulness, annoying, don't despair, this is just a thin
304-
.. stateful wrapper around an object oriented API, which you can use
305-
.. instead (see :ref:`artist-tutorial`)
306-
307-
.. If you are making a long sequence of figures, you need to be aware of one
308-
.. more thing: the memory required for a figure is not completely
309-
.. released until the figure is explicitly closed with
310-
.. :func:`~matplotlib.pyplot.close`. Deleting all references to the
311-
.. figure, and/or using the window manager to kill the window in which
312-
.. the figure appears on the screen, is not enough, because pyplot
313-
.. maintains internal references until :func:`~matplotlib.pyplot.close`
314-
.. is called.
315-
316-
.. .. _working-with-text:
317-
318-
.. Working with text
319-
.. =================
320-
321-
.. The :func:`~matplotlib.pyplot.text` command can be used to add text in
322-
.. an arbitrary location, and the :func:`~matplotlib.pyplot.xlabel`,
323-
.. :func:`~matplotlib.pyplot.ylabel` and :func:`~matplotlib.pyplot.title`
324-
.. are used to add text in the indicated locations (see :ref:`text-intro`
325-
.. for a more detailed example)
326-
327-
.. .. plot:: pyplots/pyplot_text.py
328-
.. :include-source:
329-
330-
331-
.. All of the :func:`~matplotlib.pyplot.text` commands return an
332-
.. :class:`matplotlib.text.Text` instance. Just as with with lines
333-
.. above, you can customize the properties by passing keyword arguments
334-
.. into the text functions or using :func:`~matplotlib.pyplot.setp`::
335-
336-
.. t = plt.xlabel('my data', fontsize=14, color='red')
337-
338-
.. These properties are covered in more detail in :ref:`text-properties`.
339-
340-
341-
.. Using mathematical expressions in text
342-
.. --------------------------------------
343-
344-
.. matplotlib accepts TeX equation expressions in any text expression.
345-
.. For example to write the expression :math:`\sigma_i=15` in the title,
346-
.. you can write a TeX expression surrounded by dollar signs::
347-
348-
.. plt.title(r'$\sigma_i=15$')
349-
350-
.. The ``r`` preceding the title string is important -- it signifies
351-
.. that the string is a *raw* string and not to treat backslashes as
352-
.. python escapes. matplotlib has a built-in TeX expression parser and
353-
.. layout engine, and ships its own math fonts -- for details see
354-
.. :ref:`mathtext-tutorial`. Thus you can use mathematical text across platforms
355-
.. without requiring a TeX installation. For those who have LaTeX and
356-
.. dvipng installed, you can also use LaTeX to format your text and
357-
.. incorporate the output directly into your display figures or saved
358-
.. postscript -- see :ref:`usetex-tutorial`.
359-
360-
361-
.. Annotating text
362-
.. ---------------
363-
364-
.. The uses of the basic :func:`~matplotlib.pyplot.text` command above
365-
.. place text at an arbitrary position on the Axes. A common use case of
366-
.. text is to annotate some feature of the plot, and the
367-
.. :func:`~matplotlib.pyplot.annotate` method provides helper
368-
.. functionality to make annotations easy. In an annotation, there are
369-
.. two points to consider: the location being annotated represented by
370-
.. the argument ``xy`` and the location of the text ``xytext``. Both of
371-
.. these arguments are ``(x,y)`` tuples.
372-
373-
.. .. plot:: pyplots/pyplot_annotate.py
374-
.. :include-source:
109+
.. [colorblindness] http://aspnetresources.com/tools/colorBlindness
110+
.. [asp] http://aspnetresources.com/tools/colorBlindness
111+
.. [IBM] http://www.research.ibm.com/people/l/lloydt/color/color.HTM
375112
376-
.. In this basic example, both the ``xy`` (arrow tip) and ``xytext``
377-
.. locations (text location) are in data coordinates. There are a
378-
.. variety of other coordinate systems one can choose -- see
379-
.. :ref:`annotations-tutorial` and :ref:`plotting-guide-annotation` for
380-
.. details. More examples can be found in
381-
.. :ref:`pylab_examples-annotation_demo`.

0 commit comments

Comments
 (0)