Move appendix content into primary notebooks

notebooks/01_introduction.ipynb

@@ -104,7 +104,7 @@
     "[\"T-100 Domestic Market\"](https://transtats.bts.gov/DL_SelectFields.aspx?gnoyr_VQ=FIL&QO_fu146_anzr=Nv4%20Pn44vr45)\n",
     "dataset of airline routes within the United States for the year 2021.\n",
     "\n",
-    "<p style=\"background-color: #f74531; padding: 10px;\">\n",
+    "<p style=\"background-color: #FFCCCC; padding: 10px;\">\n",
     "👇 Run the code cell below to see the dashboard you'll be building:\n",
     "</p>"
    ]
@@ -301,7 +301,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.0"
+   "version": "3.12.4"
   },
   "vscode": {
    "interpreter": {

notebooks/07_annotations.ipynb

@@ -491,6 +491,122 @@
     "By default, the ScaleBar uses metric length units, but you can define custom units of measurement using the `CustomDimensional` model. This allows you to create scale bars with units such as angular measurements or any other custom units you might need. To learn more about customizing units and other advanced features of the ScaleBar, refer to the [Bokeh User Guide on Annotations](https://docs.bokeh.org/en/latest/docs/user_guide/basic/annotations.html#scale-bars)."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### LaTeX"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Bokeh supports LaTeX equations in a number of different elements.\n",
+    "\n",
+    "This is based on the [Bessel equation example](https://docs.bokeh.org/en/latest/docs/examples/styling/mathtext/latex_bessel.html) in the Bokeh documentation:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# from bokeh.io import output_notebook\n",
+    "# from bokeh.models import ColorBar, CustomJS, Div, FixedTicker, Label, LinearColorMapper, Paragraph, Slider\n",
+    "from bokeh.palettes import TolPRGn, PiYG\n",
+    "# from bokeh.plotting import column, figure, show\n",
+    "import numpy as np\n",
+    "from scipy.special import jv"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "p = figure(\n",
+    "    width=700, height=450,\n",
+    "    title=r\"$$\\text{Bessel functions of the first kind: } J_\\alpha(x) = \\sum_{m=0}^{\\infty}\"\n",
+    "          r\"\\frac{(-1)^m}{m!\\:\\Gamma(m+\\alpha+1)} \\left(\\frac{x}{2}\\right)^{2m+\\alpha}$$\",\n",
+    ")\n",
+    "p.x_range.range_padding = 0\n",
+    "p.xaxis.axis_label = r\"$$x$$\"\n",
+    "p.yaxis.axis_label = r\"$$J_\\alpha(x)$$\"\n",
+    "p.title.text_font_size = \"14px\"\n",
+    "\n",
+    "x = np.linspace(0.0, 14.0, 100)\n",
+    "\n",
+    "for i, (xlabel, ylabel) in enumerate(zip([0.5, 1.6, 2.8, 4.2], [0.95, 0.6, 0.5, 0.45])):\n",
+    "    p.line(x, jv(i, x), line_width=3, color=PiYG[4][i])\n",
+    "    p.add_layout(Label(text=r\"$$J_\" + str(i) + \"(x)$$\", x=xlabel, y=ylabel))\n",
+    "\n",
+    "show(p)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Note:\n",
+    "\n",
+    "- Use of standard LaTeX delimeters of ``$$``. Other options are available.\n",
+    "- Use raw Python strings e.g. ``r\"$$\\alpha$$\"`` so that backslashes are interpreted as normal characters rather than control sequences. \n",
+    "- ``Div`` and ``Paragraph`` accept LaTeX for just part of their contents, but for all other elements the whole contents must be LaTeX.\n",
+    "    - To put normal text in a LaTeX string use ``\\text{...}``.\n",
+    "    - We are actively working on improvements in this area.\n",
+    "\n",
+    "\n",
+    "#### Where can LaTeX be used?"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from bokeh.models import ColorBar, Div, FixedTicker, LinearColorMapper, Paragraph, Slider\n",
+    "from bokeh.plotting import column"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "p = figure(width=500, height=400)\n",
+    "p.scatter(1, 1, size=0)\n",
+    "\n",
+    "p.title = r\"$$\\LaTeX \\text{ figure title}$$\"\n",
+    "p.axis.axis_label = r\"$$\\LaTeX \\text{ axis label}$$\"\n",
+    "p.axis.ticker = FixedTicker(ticks=[1])\n",
+    "p.axis.major_label_overrides = {1: r\"$$\\LaTeX \\text{ tick label}$$\"}\n",
+    "p.yaxis.major_label_orientation = \"vertical\"\n",
+    "p.add_layout(Label(text=r\"$$\\LaTeX \\text{ label}$$\", text_font_size=\"26px\",\n",
+    "                   angle=0.4, text_baseline=\"middle\", text_align=\"center\", x=1, y=1))\n",
+    "\n",
+    "slider = Slider(start=0, end=100, value=50, step=1, title=r\"$$\\LaTeX \\text{ slider}$$\")\n",
+    "div = Div(text=r\"$$\\LaTeX$$ div\")\n",
+    "paragraph = Paragraph(text=r\"$$\\LaTeX$$ paragraph\")\n",
+    "\n",
+    "color_mapper = LinearColorMapper(palette=PiYG[8])\n",
+    "colorbar = ColorBar(color_mapper=color_mapper, title=r\"$$\\LaTeX \\text{ colorbar title}$$\")\n",
+    "p.add_layout(colorbar, \"right\")\n",
+    "\n",
+    "show(column(p, slider, div, paragraph))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "For further information see the [LaTeX section](https://docs.bokeh.org/en/latest/docs/user_guide/styling/mathtext.html#latex) in the User Guide."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

notebooks/08_plot_tools.ipynb

@@ -453,6 +453,96 @@
     "- `use_handles`: Set to `True` to add customizable interaction handles for moving (middle) and resizing (edges) the selection box."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Aside: WebGL"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Bokeh draws graphics on web pages using HTML Canvas by default. For larger datasets there is another option which is to use WebGL. This provides hardware acceleration of graphics if you have a processor or graphics cards that supports it.\n",
+    "\n",
+    "Let's look at an example that compares Canvas and WebGL side-by-side, using a ``hex_tile`` plot which is 2D histogram using hexagons."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from bokeh.layouts import row\n",
+    "from bokeh.plotting import figure, show\n",
+    "from bokeh.transform import linear_cmap\n",
+    "from bokeh.util.hex import hexbin\n",
+    "import numpy as np"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "n = 5_000_000\n",
+    "x = np.random.standard_normal(n)\n",
+    "y = np.random.standard_normal(n)\n",
+    "\n",
+    "bins = hexbin(x, y, 0.01)\n",
+    "print(f\"Number of hexagons: {len(bins):,}\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ps = []\n",
+    "for backend in ([\"canvas\", \"webgl\"]):\n",
+    "    p = figure(title=backend, tools=\"pan, wheel_zoom, box_select, reset\",\n",
+    "               output_backend=backend, width=450, height=450, lod_threshold=None)\n",
+    "    p.grid.visible = False\n",
+    "    p.hex_tile(q=\"q\", r=\"r\", size=1, line_color=None, source=bins,\n",
+    "               fill_color=linear_cmap('counts', 'Plasma256', 0, max(bins.counts)))\n",
+    "    ps.append(p)\n",
+    "show(row(ps))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Interact with the plots to see how much faster WebGL is in your browser. Things to try:\n",
+    "\n",
+    "* Pan using the mouse\n",
+    "* Zoom using the mouse wheel\n",
+    "* Select a region of the plot such as one quarter of it, and repeat the pan and zoom"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### How much faster is WebGL?\n",
+    "\n",
+    "It is difficult to generalize, it depends on the graphics processing hardware you have available. Try it out to see.\n",
+    "\n",
+    "### How do you enable WebGL?\n",
+    "\n",
+    "By using the ``output_backend=\"webgl\"`` keyword argument when creating a ``figure``.\n",
+    "\n",
+    "### What glyphs are supported by WebGL?\n",
+    "\n",
+    "Not all Bokeh glyphs have WebGL support yet, but we are adding more all the time. If you have chosen to use WebGL then Bokeh will use WebGL for the glyphs that it can, and drop back to using Canvas for those not yet supported.\n",
+    "\n",
+    "For a full list of glyphs supported using WebGL see the [latest Bokeh documentation](https://docs.bokeh.org/en/latest/docs/user_guide/output/webgl.html#supported-glyphs)"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

notebooks/09_more_plot_types.ipynb

@@ -52,7 +52,8 @@
     "This chapter introduces **specialized plot types**:\n",
     "- [Map plots](#Map-plots)\n",
     "- [Wedge plots](#Wedge-plots) (pie and donut charts)\n",
-    "- [Subplots](#Subplots)"
+    "- [Subplots](#Subplots)\n",
+    "- [Contour plots](#Contour-plots)"
    ]
   },
   {
@@ -783,6 +784,68 @@
     "For additional examples of `subplot`, check out [polar_subcoordinates](https://docs.bokeh.org/en/latest/docs/examples/plotting/polar_subcoordinates.html) and [ridgeplot_subcoordinates](https://docs.bokeh.org/en/latest/docs/examples/plotting/ridgeplot_subcoordinates.html)."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Contour plots"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Bokeh includes contour plots. You can plot both contour lines and filled regions between contour lines with a single ``contour`` call."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from bokeh.palettes import Sunset"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Data to contour is the sum of two Gaussian functions.\n",
+    "x, y = np.meshgrid(np.linspace(0, 3, 40), np.linspace(0, 2, 30))\n",
+    "z = 1.3*np.exp(-2.5*((x-1.3)**2 + (y-0.8)**2)) - 1.2*np.exp(-2*((x-1.8)**2 + (y-1.3)**2))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "p = figure(width=700, height=400, x_range=(0, 3), y_range=(0, 2))\n",
+    "\n",
+    "levels = np.linspace(-1, 1, 9)\n",
+    "contour_renderer = p.contour(x, y, z, levels, fill_color=Sunset, line_color=\"black\")\n",
+    "\n",
+    "colorbar = contour_renderer.construct_color_bar()\n",
+    "p.add_layout(colorbar, \"right\")\n",
+    "\n",
+    "show(p)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Contour lines are calculated and displayed if ``line_color`` is something other than ``None``, and filled contour regions are calculated and displayed if ``fill_color`` is something other than ``None``.\n",
+    "\n",
+    "Visual properties (``line``, ``fill`` and ``hatch``) can be specified as scalar or vector properties as usual, such as ``line_width`` and ``hatch_pattern``.\n",
+    "\n",
+    "For more information see the Contour plots [topic guide](https://docs.bokeh.org/en/latest/docs/user_guide/topics/contour.html) in the latest Bokeh documentation."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

notebooks/11_widgets_interactivity.ipynb

@@ -497,7 +497,7 @@
     "\n",
     "div = Div(\n",
     "    text=r\"\"\"\n",
-    "<div style=\"background-color: darkolivegreen; padding:10px;\">\n",
+    "<div style=\"background-color: lightgreen; padding:10px;\">\n",
     "    <h2>Bokeh's Div widget</h2>\n",
     "    <p> Bokeh's Div widget uses <a href=\"https://en.wikipedia.org/wiki/HTML\">HTML</a> to display text and other information.</p target=\"_blank\">\n",
     "    <p> It is one of the elements that support <a href=\"https://docs.bokeh.org/en/latest/docs/user_guide/styling/mathtext.html\">LaTeX and MathML math expressions</a>. For example:</p target=\"_blank\">\n",

notebooks/13_exporting_embedding.ipynb

@@ -87,6 +87,15 @@
     "save(p)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "<p style=\"background-color: #dddddd; padding: 10px;\">\n",
+    " ✨ The HTML output file of the complete dashboard is hosted at: <a href=\"https://bokeh.github.io/tutorial/\">bokeh.github.io/tutorial ↗️</a>\n",
+    "</p>"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -350,7 +359,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.0"
+   "version": "3.12.4"
   },
   "vscode": {
    "interpreter": {