Regrid doc elaboration for image data (#3911)

examples/user_guide/15-Large_Data.ipynb

@@ -159,7 +159,42 @@
    "source": [
     "In all three of the above plots, `rasterize()` is being called to aggregate the data (a large set of x,y locations) into a rectangular grid, with each grid cell counting up the number of points that fall into it.  In the plot on the left, only `rasterize()` is done, and the resulting numeric array of counts is passed to Bokeh for colormapping.  Bokeh can then use dynamic (client-side, browser-based) operations in JavaScript, allowing users to have dynamic control over  even static HTML plots.  For instance, in this case, users can use the Box Select tool and select a range of the histogram shown, dynamically remapping the colors used in the plot to cover the selected range.\n",
     "\n",
-    "The other two plots should be identical.  In both cases, the numerical array output of `rasterize()` is mapped into RGB colors by Datashader itself, in Python (\"server-side\"), which allows special Datashader computations like the histogram-equalization in the above plots and the \"spreading\" discussed below.  The `shade()` and `datashade()` operations accept a `cmap` argument that lets you control the colormap used, which can be selected to match the HoloViews/Bokeh `cmap` option but is strictly independent of it.  See ``hv.help(rasterize)``,  ``hv.help(shade)``, and ``hv.help(datashade)`` for options that can be selected, and the [Datashader web site](http://datashader.org) for all the details. You can also try the lower-level ``hv.aggregate()`` (for points and lines) and ``hv.regrid()` (for image/raster data) operations, which may provide more control."
+    "The other two plots should be identical.  In both cases, the numerical array output of `rasterize()` is mapped into RGB colors by Datashader itself, in Python (\"server-side\"), which allows special Datashader computations like the histogram-equalization in the above plots and the \"spreading\" discussed below.  The `shade()` and `datashade()` operations accept a `cmap` argument that lets you control the colormap used, which can be selected to match the HoloViews/Bokeh `cmap` option but is strictly independent of it.  See ``hv.help(rasterize)``,  ``hv.help(shade)``, and ``hv.help(datashade)`` for options that can be selected, and the [Datashader web site](http://datashader.org) for all the details. The lower-level `aggregate()` and `regrid()` give more control over how the data is aggregated.\n",
+    "\n",
+    "Since datashader only sends the data currently in view to the plotting backend, the default behavior is to rescale colormap to the range of the visible data as the zoom level changes. This behavior may not be desirable when working with images; to instead use a fixed colormap range, the `clim` parameter can be passed to the `bokeh` backend via the `opts()` method. Note that this approach works with `rasterize()` where the colormapping is done by the `bokeh` backend. With `datashade()`, the colormapping is done with the `shade()` function which takes a `clims` parameter directly instead of passing additional parameters to the backend via `opts()`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "n = 10_000\n",
+    "\n",
+    "# Strong signal on top\n",
+    "rs = np.random.RandomState(101010)\n",
+    "x = rs.pareto(n, n)\n",
+    "y = x + rs.standard_normal(n)\n",
+    "img1, *_ = np.histogram2d(x, y, bins=60)\n",
+    "\n",
+    "# Weak signal in the middle\n",
+    "x2 = rs.standard_normal(n)\n",
+    "y2 = 5 * x + 10 * rs.standard_normal(n)\n",
+    "img2, *_ = np.histogram2d(x2, y2, bins=60)\n",
+    "\n",
+    "img = img1 + img2\n",
+    "hv_img = hv.Image(img).opts(active_tools=['wheel_zoom'])\n",
+    "auto_scale_grid = rasterize(hv_img).opts(title='Automatic color range rescaling')\n",
+    "fixed_scale_grid = rasterize(hv_img).opts(title='Fixed color range', clim=(img.min(), img.max()))\n",
+    "auto_scale_grid + fixed_scale_grid; # Output supressed and gif shown below instead"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "![](http://assets.holoviews.org/gifs/guides/user_guide/Large_Data/rasterize_color_range.gif)"
    ]
   },
   {