Implement cnorm option

examples/user_guide/04-Style_Mapping.ipynb

@@ -386,7 +386,7 @@
    "source": [
     "### Explicit color mapping\n",
     "\n",
-    "Some elements work through implicit colormapping the prime example being the ``Image`` type, however other elements can be colormapped using style mapping instead, by setting the color to an existing dimension."
+    "Some elements work through implicit colormapping, the prime example being the ``Image`` type. However, other elements can be colormapped using style mapping instead, by setting the color to an existing dimension."
    ]
   },
   {
@@ -521,12 +521,66 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "By default (left plot above), the min and max values in the array map to the first color (white) and last color (dark blue) in the colormap, and NaNs are ``'transparent'`` (an RGBA tuple of (0, 0, 0, 0)), revealing the underlying plot background.  When the specified `clipping_colors` are supplied (middle plot above), NaN values are now colored gray, but the plot is otherwise the same because the autoranging still ensures that no value is mapped outside the available color range.  Finally, when the `z` range is reduced (right plot above), the color range is mapped from a different range of numerical `z` values, and some values now fall outside the range and are thus clipped to red or green as specified.\n",
-    " \n",
-    "#### Other options\n",
+    "By default (left plot above), the min and max values in the array map to the first color (white) and last color (dark blue) in the colormap, and NaNs are ``'transparent'`` (an RGBA tuple of (0, 0, 0, 0)), revealing the underlying plot background.  When the specified `clipping_colors` are supplied (middle plot above), NaN values are now colored gray, but the plot is otherwise the same because the autoranging still ensures that no value is mapped outside the available color range.  Finally, when the `z` range is reduced (right plot above), the color range is mapped from a different range of numerical `z` values, and some values now fall outside the range and are thus clipped to red or green as specified.\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### Normalization modes\n",
+    "\n",
+    "When using a colormap, there are three available color normalization or `cnorm` options to determine how numerical values are mapped to the range of colors in the colorbar:\n",
+    "\n",
+    "* `linear`: Simple linear mapping (used by default)\n",
+    "* `log`: Logarithmic mapping\n",
+    "* `eq_hist`: Histogram-equalized mapping\n",
+    "\n",
+    "The following cell defines an `Image` containing random samples drawn from a normal distribution (mean of 3) with a square of constant value 100 in the middle, shown with the three `cnorm` modes:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "np.random.seed(42)\n",
+    "data = np.random.normal(loc=3, scale=0.3, size=(100,100))\n",
+    "print(\"Mean value of random samples is {mean:.3f}, \".format(mean=np.mean(data))\n",
+    "     + \"which is much lower\\nthan the black square in the center (value 100).\")\n",
+    "data[45:55,45:55] = 100\n",
+    "\n",
+    "opts=dict(colorbar=True, xaxis='bare', yaxis='bare', height=160, width=200)\n",
+    "pattern = hv.Image(data)\n",
+    "\n",
+    "(  pattern.options(cnorm='linear',  title='linear',  **opts) \n",
+    " + pattern.options(cnorm='log',     title='log',     **opts)\n",
+    " + pattern.options(cnorm='eq_hist', title='eq_hist', **opts))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The `'linear'` mode is very easy to interpret numerically, with colors mapped to numerical values linearly as indicated. However, as you can see in this case, high-value outliers like the square here can make it difficult to see any structure in the remaining values. The Gaussian noise values all map to the first few colors at the bottom of the colormap, resulting in a background that is almost uniformly yellow even though we know the data includes a variety of different values in the background area.\n",
+    "\n",
+    "In the `'log'` mode, the random values are a little easier to see but these samples still use a small portion of the colormap. Logarithmic colormaps are most useful when you know that you are plotting data with an approximately logarithmic distribution.\n",
+    "\n",
+    "In the `'eq_hist'` mode, colors are nonlinearly mapped according to the actual distribution of values in the plot, such that each color in the colormap represents an approximately equal number of values in the plot (here with few or no colors reserved for the nearly empty range between 10 and 100). In this mode both the outliers and the overall low-amplitude noise can be seen clearly, but the non-linear distortion can make the colors more difficult to interpret as numerical values.\n",
+    "\n",
+    "When working with unknown data distributions, it is often a good idea to try all three of these modes, using `eq_hist` to be sure that you are seeing all of the patterns in the data, then either `log` or `linear` (depending on which one is a better match to your distribution) with the values clipped to the range of values you want to show."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Other colormapping options\n",
     "\n",
-    "* ``clim_percentile``: Percentile value to compute colorscale robust to outliers. If `True` uses 2nd and 98th percentile, otherwise uses the specified percentile value. \n",
-    "* ``cnorm``: Color normalization to be applied during colormapping. Allows switching between 'linear', 'log' and 'eqhist'.\n",
+    "* ``clim_percentile``: Percentile value to compute colorscale robust to outliers. If `True`, uses 2nd and 98th percentile; otherwise uses the specified percentile value. \n",
+    "* ``cnorm``: Color normalization to be applied during colormapping. Allows switching between 'linear', 'log', and 'eq_hist'.\n",
+    "* ``logz``: Enable logarithmic color scale (same as `cnorm='log'`; to be deprecated at some point)\n",
     "* ``symmetric``: Ensures that the color scale is centered on zero (e.g. ``symmetric=True``)"
    ]
   },