Various small updates and fixes (#7)

* Set Bokeh lower bound to v3.2

* Small updates and fixes

* Update chapter 9

* Add pre-commit info

* Update chapters 7 and 8

Author: tcmetzger

README.md

@@ -71,6 +71,22 @@ is expected to follow the
 [Code of Conduct](https://github.com/bokeh/bokeh/blob/main/docs/CODE_OF_CONDUCT.md).
 This includes working on these tutorials!
 
+## Preparing your environment
+
+The ``bk-tutorial`` environment includes the necessary dependencies to contribute to
+this repository. The only exception if [pre-commit](https://pre-commit.com/), which
+you can install with the following command (after activating the ``bk-tutorial``
+environment):
+
+```bash
+pre-commit install
+```
+
+This way, some basic linting and formatting checks will be run on your code before
+you commit it.
+
+## Making changes
+
 Contributing to this tutorial repository works similarly to
 [contributing to Bokeh itself](https://docs.bokeh.org/en/latest/docs/dev_guide.html):
 

environment.yml

@@ -3,7 +3,7 @@ channels:
   - conda-forge
 dependencies:
   - black
-  - bokeh>=3.0.0
+  - bokeh>=3.2.0
   - firefox
   - flake8
   - geckodriver

notebooks/05_styling.ipynb

@@ -741,9 +741,9 @@
     "\n",
     "# 🔁 uncomment different lines to see different themes\n",
     "# curdoc().theme = \"caliber\"\n",
-    "curdoc().theme = \"dark_minimal\"\n",
+    "# curdoc().theme = \"dark_minimal\"\n",
     "# curdoc().theme = \"light_minimal\"\n",
-    "# curdoc().theme = \"night_sky\"\n",
+    "curdoc().theme = \"night_sky\"\n",
     "# curdoc().theme = \"contrast\"\n",
     "\n",
     "# create a plot\n",

notebooks/06_data_sources.ipynb

@@ -58,7 +58,8 @@
     "inputs for your data.\n",
     "\n",
     "Behind the scenes, Bokeh converts all these inputs to a Bokeh **ColumnDataSource**.\n",
-    "This is **Bokeh's internal data structure**. It is used in all plots.\n",
+    "This is **Bokeh's primary internal data structure**. It is used in almost all plots\n",
+    "(with the exception of [map plots](#Map-plots)).\n",
     "\n",
     "In most cases, Bokeh can just handle the ColumnDataSource automatically. However,\n",
     "there are many cases where it is useful to create and use a ColumnDataSource\n",
@@ -107,7 +108,7 @@
     "source = ColumnDataSource(\n",
     "    data={\n",
     "        \"x\": [1, 2, 3, 4, 5],  # first dictionary creates a column named \"x\"\n",
-    "        \"y\": [3, 7, 8, 5, 1],  # second dictionary creates a column named \"x\"\n",
+    "        \"y\": [3, 7, 8, 5, 1],  # second dictionary creates a column named \"y\"\n",
     "    }\n",
     ")"
    ]
@@ -326,7 +327,7 @@
     "p.line(\n",
     "    x=\"month_name\",  # use the sequence of strings from the \"month_name\" column as categories\n",
     "    y=\"freight\",  # use the sequence of values from the \"freight\" column as values\n",
-    "    # y=\"mail\",       # use this line instead of the one above to use data from the \"mail\" column\n",
+    "    # y=\"mail\",       # 🔁 use this line instead of the one above to use data from the \"mail\" column\n",
     "    source=source,\n",
     ")\n",
     "\n",
@@ -352,7 +353,7 @@
     "Using ColumnDataSource objects also allows you to use Bokeh's built-in transforms.\n",
     "Transforms are useful for performing computations on the data before the data is\n",
     "displayed.\n",
-    "These transforms are run by BokehJS, in the browser.\n",
+    "These transforms are performed by BokehJS, in the browser.\n",
     "This means the underlying data is not modified and is always available for other plots\n",
     "in the same document.\n",
     "\n",
@@ -392,7 +393,7 @@
     "# create a bar chart with cumulative data from the \"mail\" column\n",
     "p.vbar(\n",
     "    x=\"month_name\",\n",
-    "    top=cumsum(\"mail\", include_zero=True),  # use the cumulative sums of the \"mail\" column as values\n",
+    "    top=cumsum(\"passengers\", include_zero=True),  # use the cumulative sums of the \"passengers\" column as values\n",
     "    width=0.9,\n",
     "    source=source,\n",
     ")\n",
@@ -409,7 +410,10 @@
     "#### The linear_cmap transform\n",
     "\n",
     "The ``linear_cmap`` transform generates a new sequence of colors by **applying a linear\n",
-    "color map** to a ColumnDataSource column.\n"
+    "color map** to a ColumnDataSource column.\n",
+    "\n",
+    "See [05 Styling plots](05_styling.ipynb#Color-mappers-and-palettes) for more information\n",
+    "about color mappers."
    ]
   },
   {

notebooks/07_annotations.ipynb

@@ -197,7 +197,9 @@
     "By default, these coordinates are in **data-space units**. This means they use the same\n",
     "units as the x- and y-axes of your plot. This is helpful if you want to place a label\n",
     "relative to a specific data point. To define the position of a label in pixels, set the\n",
-    "``x_units`` and ``y_units`` parameters to **screen units**. See\n",
+    "``x_units`` and ``y_units`` parameters to **screen units**. \n",
+    "Screen and data-space units is a concept that you can use in many places in Bokeh\n",
+    "(including with Spans). See\n",
     "[Screen units and data-space units](https://docs.bokeh.org/en/latest/docs/user_guide/styling/visuals.html#screen-units-and-data-space-units)\n",
     "in the Bokeh user guide for more information.\n",
     "\n",

notebooks/08_plot_tools.ipynb

@@ -53,6 +53,8 @@
    "source": [
     "This chapter provides an overview of the tools that are available in the Bokeh toolbar.\n",
     "\n",
+    "![Example of Bokeh toolbar](assets/bokeh_toolbar.png)\n",
+    "\n",
     "The Bokeh toolbar is a collection of tools that are displayed together with a plot.\n",
     "You have seen the toolbar in all previous examples. This chapter is about configuring\n",
     "the toolbar and its tools."
@@ -112,7 +114,7 @@
     "When you configure the toolbar with the ``figure()`` method, you can specify **which\n",
     "tools to include**.\n",
     "\n",
-    "You can pass a list of tool names to the `tools` argument. The following list contains\n",
+    "You can pass a sequence of tool names to the `tools` argument. The following list contains\n",
     "some of the most commonly used tools for viewing data:\n",
     "\n",
     "* `pan` - pan the plot\n",
@@ -139,7 +141,7 @@
     "# set up a figure with a toolbar\n",
     "p = figure(\n",
     "    height=300,\n",
-    "    tools=[\"box_zoom\", \"wheel_zoom\", \"save\"],  # 🔁 swap out tools from the list above\n",
+    "    tools=(\"box_zoom\", \"wheel_zoom\", \"save\"),  # 🔁 swap out tools from the list above\n",
     ")\n",
     "\n",
     "p.line(x=list(range(10)), y=list(range(10)))\n",
@@ -167,16 +169,15 @@
    "source": [
     "### Defining active tools\n",
     "\n",
-    "By default, Bokeh will activate the first tool in the list of tools. You can **change\n",
-    "which tools are active** by setting the ``active_drag``, ``active_inspect``,`\n",
+    "You can **change which tools are active** by setting the ``active_drag``, ``active_inspect``,\n",
     "``active_scroll``, and ``active_tap`` properties of a toolbar.\n",
     "\n",
     "The reason why Bokeh has separate properties for different types of tools is that\n",
     "you can have several tools of different types active at the same time. For example,\n",
     "you can have an active scroll tool and an active inspect tool at the same time.\n",
     "\n",
-    "The following code cell uses the ``xwenel_zoom`` tool as its active scroll tool.\n",
-    "Update the code in line 7 to make the ``ywheel_zoom`` tool active by default instead:"
+    "The following code cell uses the ``xpan`` tool as its active drag tool.\n",
+    "Update the code in line 7 to make the ``ypan`` tool active by default instead:"
    ]
   },
   {
@@ -190,8 +191,8 @@
     "# set up a figure with a toolbar\n",
     "p = figure(\n",
     "    height=300,\n",
-    "    tools=[\"reset\", \"wheel_zoom\", \"xwheel_zoom\", \"save\"],\n",
-    "    active_scroll=\"xwheel_zoom\",  # 🔁 update this line to make \"xwheel_zoom\" the active scroll tool\n",
+    "    tools=(\"reset\", \"pan\", \"ypan\", \"xpan\", \"save\"),\n",
+    "    active_drag=\"xpan\",  # 🔁 update this line to make \"ypan\" the active drag tool\n",
     ")\n",
     "\n",
     "p.line(x=list(range(10)), y=list(range(10)))\n",
@@ -208,7 +209,7 @@
     "The `HoverTool` is a special tool that **displays a tooltip when the user hovers the\n",
     "mouse over a data point or taps on a data point**.\n",
     "\n",
-    "To enable tooltips, you need to add a `HoverTool` to the list of tools. You can then\n",
+    "To enable tooltips, you need to add a `hover` tool to the list of tools. You can then\n",
     "use the `tooltips` argument to specify which data fields to display in the tooltip.\n",
     "\n",
     "Run the cell below and hover over the data points:"
@@ -225,20 +226,20 @@
     "\n",
     "source = ColumnDataSource(\n",
     "    data={\n",
-    "        \"x\": [1, 2, 3, 4, 5],\n",
-    "        \"y\": [3, 7, 8, 5, 1],\n",
+    "        \"x\": [1, 2, 3, 6, 9],\n",
+    "        \"y\": [3, 7, 8, 2, 1],\n",
     "    }\n",
     ")\n",
     "\n",
     "p = figure(\n",
     "    toolbar_location=None,\n",
-    "    tools=[HoverTool()],  # add the HoverTool to the figure\n",
-    "    tooltips=\"Data point @x has the value @y\",  # define a tooltip using data from the x and y columns\n",
+    "    tools=\"hover\",  # add the hover tool to the figure (the hover tool will work even if the toolbar is hidden)\n",
+    "    tooltips=\"Data point is at @x, @y\",  # define a tooltip using data from the x and y columns\n",
     "    height=300,\n",
     ")\n",
     "\n",
     "# add renderers\n",
-    "p.circle(\"x\", \"y\", size=10, source=source)\n",
+    "p.circle(\"x\", \"y\", size=25, source=source)\n",
     "p.line(\"x\", \"y\", line_width=2, source=source)\n",
     "\n",
     "# show the results\n",
@@ -253,7 +254,7 @@
     "The text that is displayed in the tooltip uses **special syntax to refer to data from\n",
     "the ColumnDataSource**.\n",
     "\n",
-    "In the example above, the tooltip text is `\"Data point @x has the value @y\"`. The `@x`\n",
+    "In the example above, the tooltip text is `\"Data point is at @x, @y`. The `@x`\n",
     "and `@y` are replaced with the actual value of the `x` and `y` columns in the\n",
     "ColumnDataSource at that point.\n",
     "\n",

notebooks/09_more_plot_types.ipynb

@@ -368,7 +368,7 @@
     "The next code cell contains the code to create this visualization.\n",
     "\n",
     "You'll recognize several elements from the previous chapters. For example:\n",
-    "* Tooltips,\n",
+    "* Tooltips\n",
     "* Configuring plot tools\n",
     "* Configuring visual elements of the plot\n",
     "* Using a ColorMapper to map values to colors from a palette\n",
@@ -471,7 +471,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Next, calculate the angle for each wedge:"
+    "Next, calculate the angle for each wedge (in radians):"
    ]
   },
   {
@@ -679,7 +679,7 @@
     "# configure tooltips\n",
     "TOOLTIPS = [\n",
     "    (\"Carrier\", \"@unique_carrier_name\"),\n",
-    "    (\"Passengers\", \"@passengers{{(0,0)}}\"),\n",
+    "    (\"Passengers\", \"@passengers{(0,0)}\"),\n",
     "]\n",
     "\n",
     "# create a ColumnDataSource from the DataFrame\n",