11.. _colormapnorm-tutorial :
22
3- Colormap Normaliztions
4- ================================
3+ Colormap Normalization
4+ ======================
55
66Objects that use colormaps by default linearly map the colors in the
77colormap from data values *vmin * to *vmax *. For example::
@@ -13,21 +13,19 @@ give a color at the center of the colormap *RdBu_r* (white in this
1313case).
1414
1515Matplotlib does this mapping in two steps, with a normalization from
16- [0,1] occuring first, and then mapping onto the indices in the
17- colormap. Normalizations are defined as part of
18- :func: `matplotlib.colors ` module. The default normalization is
16+ [0,1] occurring first, and then mapping onto the indices in the
17+ colormap. Normalizations are classes defined in the
18+ :func: `matplotlib.colors ` module. The default, linear normalization is
1919:func: `matplotlib.colors.Normalize `.
2020
21- The artists that map data to
22- color pass the arguments *vmin * and *vmax * to
23- :func: `matplotlib.colors.Normalize `. We can substnatiate the
24- normalization and see what it returns. In this case it returns 0.5:
21+ Artists that map data to color pass the arguments *vmin * and *vmax * to
22+ construct a :func: `matplotlib.colors.Normalize ` instance, then call it:
2523
2624.. ipython ::
2725
2826 In [1]: import matplotlib as mpl
2927
30- In [2]: norm= mpl.colors.Normalize(vmin=-1.,vmax=1.)
28+ In [2]: norm = mpl.colors.Normalize(vmin=-1.,vmax=1.)
3129
3230 In [3]: norm(0.)
3331 Out[3]: 0.5
@@ -36,69 +34,69 @@ However, there are sometimes cases where it is useful to map data to
3634colormaps in a non-linear fashion.
3735
3836Logarithmic
39- ---------------------------------
37+ -----------
4038
41- One of the most common transformations is to plot data by taking its
42- logarithm (to the base-10). This transformation is useful when there
43- are changes across disparate scales that we still want to be able to
44- see. Using :func: ` colors.LogNorm ` normalizes the data by
45- :math: `log_{ 10 }`. In the example below, there are two bumps, one much
46- smaller than the other. Using :func: `colors.LogNorm `, the shape and
47- location of each bump can clearly be seen:
39+ One of the most common transformations is to plot data by taking
40+ its logarithm (to the base-10). This transformation is useful to
41+ display changes across disparate scales. Using :func: ` colors.LogNorm `
42+ normalizes the data via :math: `log_{ 10 }`. In the example below,
43+ there are two bumps, one much smaller than the other. Using
44+ :func: `colors.LogNorm `, the shape and location of each bump can clearly
45+ be seen:
4846
4947.. plot :: users/plotting/examples/colormap_normalizations_lognorm.py
5048 :include-source:
5149
52- Symetric logarithmic
53- ---------------------------------
50+ Symmetric logarithmic
51+ ---------------------
5452
5553Similarly, it sometimes happens that there is data that is positive
5654and negative, but we would still like a logarithmic scaling applied to
5755both. In this case, the negative numbers are also scaled
58- logarithmically, and mapped to small numbers. i.e. If `vmin=-vmax `,
56+ logarithmically, and mapped to smaller numbers; e.g., if `vmin=-vmax `,
5957then they the negative numbers are mapped from 0 to 0.5 and the
6058positive from 0.5 to 1.
6159
62- Since the values close to zero tend toward infinity, there is a need
63- to have a range around zero that is linear . The parameter * linthresh *
64- allows the user to specify the size of this range (-* linthresh *,
65- *linthresh *). The size of this range in the colormap is set by
66- *linscale *. When *linscale * == 1.0 (the default), the space used for
67- the positive and negative halves of the linear range will be equal to
68- one decade in the logarithmic range.
60+ Since the logarithm of values close to zero tends toward infinity, a
61+ small range around zero needs to be mapped linearly . The parameter
62+ * linthresh * allows the user to specify the size of this range
63+ (- *linthresh *, * linthresh * ). The size of this range in the colormap is
64+ set by *linscale *. When *linscale * == 1.0 (the default), the space used
65+ for the positive and negative halves of the linear range will be equal
66+ to one decade in the logarithmic range.
6967
7068.. plot :: users/plotting/examples/colormap_normalizations_symlognorm.py
7169 :include-source:
7270
7371Power-law
74- ---------------------------------
72+ ---------
7573
7674Sometimes it is useful to remap the colors onto a power-law
7775relationship (i.e. :math: `y=x^{\gamma }`, where :math: `\gamma ` is the
7876power). For this we use the :func: `colors.PowerNorm `. It takes as an
79- argument *gamma * ( *gamma * == 1.0 will just yield the defalut linear
77+ argument *gamma * (*gamma * == 1.0 will just yield the default linear
8078normalization):
8179
8280.. note ::
8381
8482 There should probably be a good reason for plotting the data using
8583 this type of transformation. Technical viewers are used to linear
8684 and logarithmic axes and data transformations. Power laws are less
87- common, and viewers should explictly be made aware that they have
85+ common, and viewers should explicitly be made aware that they have
8886 been used.
8987
9088
9189.. plot :: users/plotting/examples/colormap_normalizations_power.py
9290 :include-source:
9391
9492Discrete bounds
95- ---------------------------------
93+ ---------------
9694
9795Another normaization that comes with matplolib is
9896:func: `colors.BoundaryNorm `. In addition to *vmin * and *vmax *, this
9997takes as arguments boundaries between which data is to be mapped. The
10098colors are then linearly distributed between these "bounds". For
101- instance, if :
99+ instance:
102100
103101.. ipython ::
104102
@@ -118,20 +116,19 @@ Note unlike the other norms, this norm returns values from 0 to *ncolors*-1.
118116
119117
120118Custom normalization: Two linear ranges
121- -----------------------------------------
119+ ---------------------------------------
122120
123- It is possible to define your own normalization. This example
124- plots the same data as the :func: `colors:SymLogNorm ` example, but
125- a different linear map is used for the negative data values than
126- the positive. (Note that this example is simple, and does not account
127- for the edge cases like masked data or invalid values of *vmin * and
128- *vmax *)
121+ It is possible to define your own normalization. In the following
122+ example, we modify :func: `colors:SymLogNorm ` to use different linear
123+ maps for the negative data values and the positive. (Note that this
124+ example is simple, and does not validate inputs or account for complex
125+ cases such as masked data)
129126
130127.. note ::
131- This may appear soon as :func: `colors.OffsetNorm `
128+ This may appear soon as :func: `colors.OffsetNorm `.
132129
133- As above, non-symetric mapping of data to color is non-standard
134- practice for quantitative data, and should only be used advisedly. A
130+ As above, non-symmetric mapping of data to color is non-standard
131+ practice for quantitative data, and should only be used advisedly. A
135132 practical example is having an ocean/land colormap where the land and
136133 ocean data span different ranges.
137134
0 commit comments