Additional userguide fixes (#693)

* Updated ROADMAP.md, geo.py, and various notebooks

ROADMAP.md

@@ -30,7 +30,6 @@ If you need any of the functionality listed below and want to help make it a pri
   -  [#92](../../issues/92)  Box select support
   -  [#61](../../issues/61)  Add information on requirements for osm example
   - [#242](../../issues/242) Spatiotemporal data animation
-  - [Bokeh 7651](https://github.com/bokeh/bokeh/pull/7651) Image hover using Bokeh
 
 
 Also see the [PyViz.org roadmap](http://pyviz.org/roadmap.html).

datashader/geo.py

@@ -322,8 +322,8 @@ def _gen_heights(bumps):
             x = b[0]
             y = b[1]
             val = agg.data[y, x]
-            if val >= .33 and val <= 3:
-                out[i] = .1
+            if val >= 0.33 and val <= 3:
+                out[i] = 0.1
         return out
 
     def _scale(value, old_range, new_range):
@@ -355,7 +355,7 @@ def _scale(value, old_range, new_range):
                         x_range=x_range_scaled, y_range=y_range_scaled)
 
     data = (data - np.min(data))/np.ptp(data)
-    data[data < .3] = 0  # create water
+    data[data < 0.3] = 0  # create water
     data *= zfactor
 
     xs = np.linspace(canvas.x_range[0], canvas.x_range[1], canvas.plot_width, endpoint=False)

examples/user_guide/1_Plotting_Pitfalls.ipynb

@@ -90,7 +90,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Plots **C** and **D** shown the same distribution of points, yet they give a very different impression of which category is more common, which can lead to incorrect decisions based on this data.  Of course, both are equally common in this case.  The cause for this problem is simply occlusion:"
+    "Plots **C** and **D** shown the same distribution of points, yet they give a very different impression of which category is more common, which can lead to incorrect decisions based on this data.  Of course, both are equally common in this case, so neither **C** nor **D** accurately reflects the data.  The cause for this problem is simply occlusion:"
    ]
   },
   {

examples/user_guide/8_Geography.ipynb

@@ -21,9 +21,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {
-    "collapsed": true
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "from datashader.transfer_functions import shade, stack\n",
@@ -36,7 +34,7 @@
    "source": [
     "## Generate Terrain Data\n",
     "\n",
-    "To demonstrate using these functions, Let's generate some fake terrain..."
+    "To demonstrate using these functions, let's generate some fake terrain..."
    ]
   },
   {
@@ -53,7 +51,22 @@
     "H = 750\n",
     "\n",
     "canvas = Canvas(plot_width=W, plot_height=H, x_range=(-20e6, 20e6), y_range=(-20e6, 20e6))\n",
-    "terrain = generate_terrain(canvas)\n",
+    "terrain = generate_terrain(canvas)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The grayscale value above shows the elevation linearly in intensity (with the large black areas indicating low elevation), but it will look more like a landscape if we map the lowest values to colors representing water, and the highest to colors representing mountaintops:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
     "shade(terrain, cmap=Elevation, how='linear')"
    ]
   },
@@ -76,10 +89,24 @@
     "\n",
     "illuminated = hillshade(terrain)\n",
     "\n",
-    "stack(\n",
-    "    shade(illuminated, cmap=['gray', 'white'], alpha=255, how='linear'),\n",
-    "    #shade(terrain, cmap=Elevation, how='linear', alpha=128)\n",
-    ")"
+    "shade(illuminated, cmap=['gray', 'white'], alpha=255, how='linear')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You can combine hillshading with elevation colormapping to indicate terrain types:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "stack(shade(illuminated, cmap=['gray', 'white'], alpha=255, how='linear'),\n",
+    "      shade(terrain, cmap=Elevation, how='linear', alpha=128))"
    ]
   },
   {
@@ -90,7 +117,7 @@
     "[Slope](https://en.wikipedia.org/wiki/Slope) is the inclination of a surface. \n",
     "In geography, *slope* is amount of change in elevation of a terrain regarding its surroundings.\n",
     "\n",
-    "Datashader's slope function returns slope in degrees.  Below we highlight areas at risk for avalanche by looking at slopes with greater than 75 degree incline."
+    "Datashader's slope function returns slope in degrees.  Below we highlight areas at risk for avalanche by looking at [slopes around 38 degrees](http://wenatcheeoutdoors.org/2016/04/07/avalanche-abcs-for-snowshoers/)."
    ]
   },
   {
@@ -102,12 +129,14 @@
     "from datashader.geo import slope\n",
     "\n",
     "avalanche_slope_risk = slope(terrain)\n",
-    "avalanche_slope_risk.data = np.where(avalanche_slope_risk.data > 75, 1, np.nan)\n",
+    "avalanche_slope_risk.data = np.where(np.logical_and(avalanche_slope_risk.data > 25, \n",
+    "                                     avalanche_slope_risk.data < 50),\n",
+    "                                     1, np.nan)\n",
     "\n",
     "stack(\n",
     "    shade(terrain, cmap=['black', 'white'], how='linear'),\n",
     "    shade(illuminated, cmap=['black', 'white'], alpha=128, how='linear'),\n",
-    "    shade(avalanche_slope_risk, cmap='red', alpha=50), \n",
+    "    shade(avalanche_slope_risk, cmap='red', alpha=100), \n",
     ")"
    ]
   },
@@ -131,9 +160,8 @@
     "from datashader.geo import aspect\n",
     "\n",
     "north_faces = aspect(terrain)\n",
-    "north_faces.data = np.where((north_faces.data > 350) | (north_faces.data < 10), \n",
-    "                            1, \n",
-    "                            np.nan)\n",
+    "north_faces.data = np.where(np.logical_or(north_faces.data > 350 ,\n",
+    "                                          north_faces.data < 10), 1, np.nan)\n",
     "stack(\n",
     "    shade(terrain, cmap=['black', 'white'], how='linear'),\n",
     "    shade(illuminated, cmap=['black', 'white'], alpha=128, how='linear'),\n",
@@ -159,7 +187,7 @@
    "source": [
     "The output of *NDVI* ranges from [-1,+1], where `-1` means more \"Red\" radiation while `+1` means more \"NIR\" radiation.\n",
     "\n",
-    "Below, we simulate the red and near-infrared bands using `datashader.perlin` with different seeds and frequencies.  Green areas should area > 0 whose higher NDVI values would indicate vegetation."
+    "Below, we simulate the red and near-infrared bands using `datashader.perlin` random noise with different seeds and frequencies.  Green areas should be those > 0, where higher NDVI values would indicate vegetation."
    ]
   },
   {
@@ -220,11 +248,9 @@
     "tree_colorize = trees.copy()\n",
     "tree_colorize.data[tree_colorize.data == 0] = np.nan\n",
     "\n",
-    "stack(\n",
-    "    shade(terrain + trees, cmap=['black', 'white'], how='linear'),\n",
-    "    shade(hillshade(terrain + trees), cmap=['black', 'white'], alpha=128, how='linear'),\n",
-    "    shade(tree_colorize, cmap='limegreen', how='linear'),\n",
-    ")"
+    "stack(shade(terrain + trees, cmap=['black', 'white'], how='linear'),\n",
+    "      shade(hillshade(terrain + trees), cmap=['black', 'white'], alpha=128, how='linear'),\n",
+    "      shade(tree_colorize, cmap='limegreen', how='linear'))"
    ]
   },
   {
@@ -278,12 +304,10 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "stack(\n",
-    "    shade(terrain + trees, cmap=Elevation, how='linear'),\n",
-    "    shade(water, cmap=['aqua','white']),\n",
-    "    shade(hillshade(terrain + trees), cmap=['black', 'white'], alpha=128, how='linear'),\n",
-    "    shade(tree_colorize, cmap='limegreen', how='linear'),\n",
-    ")"
+    "stack(shade(terrain + trees, cmap=Elevation, how='linear'),\n",
+    "      shade(water, cmap=['aqua','white']),\n",
+    "      shade(hillshade(terrain + trees), cmap=['black', 'white'], alpha=128, how='linear'),\n",
+    "      shade(tree_colorize, cmap='limegreen', how='linear'))"
    ]
   },
   {

examples/user_guide/index.ipynb

@@ -36,8 +36,8 @@
     "-   [7. Networks](7_Networks.ipynb)  \n",
     "    Plotting large network graphs.\n",
     "\n",
-    "-   [8. Geography](http://geoviews.org)  \n",
-    "    (Under construction; meanwhile points to the [GeoViews.org](http://geoviews.org) website.)\n",
+    "-   [8. Geography](8_Geography.ipynb)  \n",
+    "    Using Datashader for geographic applications\n",
     "\n",
     "-   [9. Extending](9_Extending.ipynb)  \n",
     "    Extending datashader with new components and functionality.\n",