Plotting with basic glyphs

Creating figures

Bokeh plots you create with the bokeh.plotting interface come with a default set of tools and visual styles. For information on how to customize the visual style of plots, see Styling visual attributes. For information about changing or specifying tools, see Configuring plot tools.

Scatter markers

Bokeh includes a large variety of markers for creating scatter plots. For example, to render circle scatter markers on a plot, use the circle() method of Figure:

from bokeh.plotting import figure, output_file, show

# output to static HTML file
output_file("line.html")

p = figure(width=400, height=400)

# add a circle renderer with a size, color, and alpha
p.circle([1, 2, 3, 4, 5], [6, 7, 2, 4, 5], size=20, color="navy", alpha=0.5)

# show the results
show(p)

Similarly, use the square() method of Figure to scatter square markers on a plot:

from bokeh.plotting import figure, output_file, show

# output to static HTML file
output_file("square.html")

p = figure(width=400, height=400)

# add a square renderer with a size, color, and alpha
p.square([1, 2, 3, 4, 5], [6, 7, 2, 4, 5], size=20, color="olive", alpha=0.5)

# show the results
show(p)

Bokeh’s built-in scatter markers consist of a set of base markers, most of which can be combined with different kinds of additional visual features. This is an overview of all available scatter markers:

To see details and example plots for any of the available scatter markers, click on the corresponding glyph method in the following list:

asterisk() circle() circle_cross() circle_dot() circle_x() circle_y() cross() dash() dot() diamond()

diamond_cross() diamond_dot() hex() hex_dot() inverted_triangle() plus() square() square_cross() square_dot()

square_pin() square_x() star() star_dot() triangle() triangle_dot() triangle_pin() x() y()

All the markers have the same set of properties: x, y, size (in screen units), and angle (in radians by default). The circle() marker is an exception: this method accepts an additional radius property that you can use with data units.

Line glyphs

Single lines

The example below shows how to generate a single line glyph from one-dimensional sequences of x and y points using the line() glyph method:

from bokeh.plotting import figure, output_file, show

output_file("line.html")

p = figure(width=400, height=400)

# add a line renderer
p.line([1, 2, 3, 4, 5], [6, 7, 2, 4, 5], line_width=2)

show(p)

Step lines

For some kinds of data, discrete steps between data points may work better than linear segments. To produce this type of data representation, use the step() glyph method.

from bokeh.plotting import figure, output_file, show

output_file("line.html")

p = figure(width=400, height=400)

# add a steps renderer
p.step([1, 2, 3, 4, 5], [6, 7, 2, 4, 5], line_width=2, mode="center")

show(p)

Adjust the mode parameter to draw step levels with the x-coordinates before, after, or in the middle of each step.

Multiple lines

If you want to draw multiple lines in one go, use the multi_line() glyph method as follows:

from bokeh.plotting import figure, output_file, show

output_file("patch.html")

p = figure(width=400, height=400)

p.multi_line([[1, 3, 2], [3, 4, 6, 6]], [[2, 1, 4], [4, 7, 8, 5]],
             color=["firebrick", "navy"], alpha=[0.8, 0.3], line_width=4)

show(p)

Note

Unlike many other glyph methods, multi_line() accepts a list of lists of x and y positions for each line. The multi_line() method also expects a scalar value or a list of scalars for each line for parameters such as color, alpha, and line width. You can similarly use a ColumnDataSource consisting of a list of lists of point coordinates and a list of scalar values of matching length.

Missing points

You can pass NaN values to line() and multi_line() glyphs. This produces disjointed lines with gaps for NaN values.

from bokeh.plotting import figure, output_file, show

output_file("line.html")

p = figure(width=400, height=400)

# add a line renderer with a NaN
nan = float('nan')
p.line([1, 2, 3, nan, 4, 5], [6, 7, 2, 4, 4, 5], line_width=2)

show(p)

Stacked lines

You may wish to stack lines with a common index when working with time series of percentages and other similar data. To do so, you can use the vline_stack() and hline_stack() convenience methods.

from bokeh.models import ColumnDataSource
from bokeh.plotting import figure, output_file, show

output_file("vline_stack.html")

source = ColumnDataSource(data=dict(
    x=[1, 2, 3, 4, 5],
    y1=[1, 2, 4, 3, 4],
    y2=[1, 4, 2, 2, 3],
))
p = figure(width=400, height=400)

p.vline_stack(['y1', 'y2'], x='x', source=source)

show(p)

Note

This and other examples in this chapter rely on `ColumnDataSource for data structuring. For information on how to work with this data structure, see Providing data.

Bars and rectangles

Bars

To make drawing rectangular bars more convenient, Bokeh provides hbar() and vbar() glyph functions that combine the coordinate systems above.

To draw vertical bars by specifying a center x-coordinate, width, and top and bottom endpoints, use the vbar() glyph function:

from bokeh.plotting import figure, output_file, show

output_file('vbar.html')

p = figure(width=400, height=400)
p.vbar(x=[1, 2, 3], width=0.5, bottom=0,
       top=[1.2, 2.5, 3.7], color="firebrick")

show(p)

To draw horizontal bars by specifying a center y-coordinate, height, and left and right endpoints, use the hbar() glyph function:

from bokeh.plotting import figure, output_file, show

output_file('hbar.html')

p = figure(width=400, height=400)
p.hbar(y=[1, 2, 3], height=0.5, left=0,
       right=[1.2, 2.5, 3.7], color="navy")

show(p)

Stacked bars

To stack the bars, you can use the vbar_stack() and hbar_stack() convenience methods.

from bokeh.models import ColumnDataSource
from bokeh.plotting import figure, output_file, show

output_file("hbar_stack.html")

source = ColumnDataSource(data=dict(
    y=[1, 2, 3, 4, 5],
    x1=[1, 2, 4, 3, 4],
    x2=[1, 4, 2, 2, 3],
))
p = figure(width=400, height=400)

p.hbar_stack(['x1', 'x2'], y='y', height=0.8, color=("grey", "lightgrey"), source=source)

show(p)

For more examples of stacked bars, see Handling categorical data.

Rectangles

To draw axis aligned rectangles by specifying the left, right, top, and bottom positions, use the quad() glyph function:

from bokeh.plotting import figure, output_file, show

output_file('rectangles.html')

p = figure(width=400, height=400)
p.quad(top=[2, 3, 4], bottom=[1, 2, 3], left=[1, 2, 3],
       right=[1.2, 2.5, 3.7], color="#B3DE69")

show(p)

To draw arbitrary rectangles by specifying center coordinates, width, height, and angle, use the rect() glyph function:

from math import pi

from bokeh.plotting import figure, output_file, show

output_file('rectangles_rotated.html')

p = figure(width=400, height=400)
p.rect(x=[1, 2, 3], y=[1, 2, 3], width=0.2, height=40, color="#CAB2D6",
       angle=pi/3, height_units="screen")

show(p)

Hex tiles

Bokeh can plot hexagonal tiles, which you can use to show binned aggregations and more. The hex_tile() method takes a size parameter to define the size of the hex grid and axial coordinates to specify the tiles.

import numpy as np

from bokeh.io import output_file, show
from bokeh.plotting import figure
from bokeh.util.hex import axial_to_cartesian

output_file("hex_coords.html")

q = np.array([0,  0, 0, -1, -1,  1, 1])
r = np.array([0, -1, 1,  0,  1, -1, 0])

p = figure(width=400, height=400, toolbar_location=None)
p.grid.visible = False

p.hex_tile(q, r, size=1, fill_color=["firebrick"]*3 + ["navy"]*4,
           line_color="white", alpha=0.5)

x, y = axial_to_cartesian(q, r, 1, "pointytop")

p.text(x, y, text=["(%d, %d)" % (q,r) for (q, r) in zip(q, r)],
       text_baseline="middle", text_align="center")

show(p)

A more practical example below computes counts per bin using the hexbin() function and plots the color mapped counts.

import numpy as np

from bokeh.io import output_file, show
from bokeh.plotting import figure
from bokeh.transform import linear_cmap
from bokeh.util.hex import hexbin

n = 50000
x = np.random.standard_normal(n)
y = np.random.standard_normal(n)

bins = hexbin(x, y, 0.1)

p = figure(tools="wheel_zoom,reset", match_aspect=True, background_fill_color='#440154')
p.grid.visible = False

p.hex_tile(q="q", r="r", size=0.1, line_color=None, source=bins,
           fill_color=linear_cmap('counts', 'Viridis256', 0, max(bins.counts)))

output_file("hex_tile.html")

show(p)

You can simplify this code by calling the hexbin() method of Figure.

Directed areas

Directed areas are filled regions between two series that share a common index. For instance, a vertical directed area has one x coordinate array and two y coordinate arrays, y1 and y2, defining the space for Bokeh to fill.

Single areas

To fill an area in vertical direction, use the varea() method. You can do the same in horizontal direction with harea().

from bokeh.plotting import figure, output_file, show

output_file("varea.html")

p = figure(width=400, height=400)

p.varea(x=[1, 2, 3, 4, 5],
        y1=[2, 6, 4, 3, 5],
        y2=[1, 4, 2, 2, 3])

show(p)

Stacked areas

To stack directed areas, use the varea_stack() and harea_stack() convenience methods.

from bokeh.models import ColumnDataSource
from bokeh.plotting import figure, output_file, show

output_file("varea_stack.html")

source = ColumnDataSource(data=dict(
    x=[1, 2, 3, 4, 5],
    y1=[1, 2, 4, 3, 4],
    y2=[1, 4, 2, 2, 3],
))
p = figure(width=400, height=400)

p.varea_stack(['y1', 'y2'], x='x', color=("grey", "lightgrey"), source=source)

show(p)

Patches and polygons

Single patches

The following example generates a single polygonal patch from one-dimensional sequences of x and y points using the patch() glyph method:

from bokeh.plotting import figure, output_file, show

output_file("patch.html")

p = figure(width=400, height=400)

# add a patch renderer with an alpha and line width
p.patch([1, 2, 3, 4, 5], [6, 7, 8, 7, 3], alpha=0.5, line_width=2)

show(p)

Multiple patches

To plot several polygonal patches, use the patches() glyph method:

from bokeh.plotting import figure, output_file, show

output_file("patch.html")

p = figure(width=400, height=400)

p.patches([[1, 3, 2], [3, 4, 6, 6]], [[2, 1, 4], [4, 7, 8, 5]],
          color=["firebrick", "navy"], alpha=[0.8, 0.3], line_width=2)

show(p)

Note

Unlike many other glyph methods, patches() accepts a list of lists of x and y positions for each line. The patches() method also expects a scalar value or a list of scalars for each patch for parameters such as color, alpha, and line width. You can similarly use a ColumnDataSource consisting of a list of lists of point coordinates and a list of scalar values of matching length.

Missing points

Just as with the line() and multi_line() methods, you can pass NaN values to patch() and patches() glyphs. This produces disjointed patches with gaps for NaN values.

from bokeh.plotting import figure, output_file, show

output_file("patch.html")

p = figure(width=400, height=400)

# add a patch renderer with a NaN value
nan = float('nan')
p.patch([1, 2, 3, nan, 4, 5, 6], [6, 7, 5, nan, 7, 3, 6], alpha=0.5, line_width=2)

show(p)

Warning

Bokeh doesn’t currently support hit testing on patch objects with NaN values.

Polygons

The multi_polygons() glyph uses nesting to accept a variety of information relevant to polygons. The method duplicates the functionality of patches() but you can also use it to render holes inside polygons.

Note

Unlike many other glyph methods, multi_polygons() accepts a triple-nested lists of x and y positions for the exterior and holes composing each polygon. The multi_polygons() method also expects a scalar value or a list of scalars for each item for parameters such as color, alpha, and line width. You can similarly use a ColumnDataSource consisting of a triple- nested list of point coordinates and a list of scalars, with the top-level list of point coordinates being of equal length with the list of scalars.

Simple polygon

The following example generates a single polygon from a triple-nested list of one-dimensional sequences of x and y points using the multi_polygons() glyph method.

from bokeh.plotting import figure, output_file, show

output_file('multipolygon_simple.html')

p = figure(width=400, height=400)
p.multi_polygons(xs=[[[[1, 1, 2, 2]]]],
                 ys=[[[[3, 4, 4, 3]]]])

show(p)

Polygon with holes

The following example generates a single polygon with holes from three sequences of x and y points. The first sequence represents the exterior of the polygon and the following sequences represent the holes.

from bokeh.plotting import figure, output_file, show

output_file('multipolygon_with_holes.html')

p = figure(width=400, height=400)
p.multi_polygons(xs=[[[ [1, 2, 2, 1], [1.2, 1.6, 1.6], [1.8, 1.8, 1.6] ]]],
                 ys=[[[ [3, 3, 4, 4], [3.2, 3.6, 3.2], [3.4, 3.8, 3.8] ]]])

show(p)

Multi-polygon with separate parts

A single polygon concept can comprise multiple polygon geometries. The following example generates a multi-polygon glyph from several sequences of x and y points. Each item in the sequence represents a part of the glyph.

from bokeh.plotting import figure, output_file, show

output_file('multipolygon_with_separate_parts.html')

p = figure(width=400, height=400)
p.multi_polygons(xs=[[[ [1, 1, 2, 2], [1.2, 1.6, 1.6], [1.8, 1.8, 1.6] ], [ [3, 4, 3] ]]],
                 ys=[[[ [4, 3, 3, 4], [3.2, 3.2, 3.6], [3.4, 3.8, 3.8] ], [ [1, 1, 3] ]]])

show(p)

Multiple multi-polygons

The top-level of nesting separates each multi-polygon from the rest. You can think of each multi-polygon as a row in the data source, potentially with a corresponding label or color.

from bokeh.plotting import figure, output_file, show

output_file('multipolygons.html')

p = figure(width=400, height=400)
p.multi_polygons(
    xs=[
        [[ [1, 1, 2, 2], [1.2, 1.6, 1.6], [1.8, 1.8, 1.6] ], [ [3, 3, 4] ]],
        [[ [1, 2, 2, 1], [1.3, 1.3, 1.7, 1.7] ]]],
    ys=[
        [[ [4, 3, 3, 4], [3.2, 3.2, 3.6], [3.4, 3.8, 3.8] ], [ [1, 3, 1] ]],
        [[ [1, 1, 2, 2], [1.3, 1.7, 1.7, 1.3] ]]],
    color=['blue', 'red'])

show(p)

Ellipses

The ellipse() glyph method accepts the same properties as rect(), but renders ellipse shapes.

from math import pi

from bokeh.plotting import figure, output_file, show

output_file('ellipses.html')

p = figure(width=400, height=400)
p.ellipse(x=[1, 2, 3], y=[1, 2, 3], width=[0.2, 0.3, 0.1], height=0.3,
          angle=pi/3, color="#CAB2D6")

show(p)

Images

You can display images on Bokeh plots using the image(), image_rgba(), and image_url() glyph methods. You can use hovering tooltips with image glyphs to let the user see the values of each pixel. For more information on how to enable hovering tooltips for images, see Image hover.

Raw RGBA data

The following example shows how to display images using raw RGBA data with the image_rgba() method.

import numpy as np

from bokeh.plotting import figure, output_file, show

# create an array of RGBA data
N = 20
img = np.empty((N, N), dtype=np.uint32)
view = img.view(dtype=np.uint8).reshape((N, N, 4))
for i in range(N):
    for j in range(N):
        view[i, j, 0] = int(255 * i / N)
        view[i, j, 1] = 158
        view[i, j, 2] = int(255 * j / N)
        view[i, j, 3] = 255

output_file("image_rgba.html")

p = figure(width=400, height=400, x_range=(0, 10), y_range=(0, 10))

p.image_rgba(image=[img], x=[0], y=[0], dw=[10], dh=[10])

show(p)

Color mapped images

The following example shows how to supply an array of scalar values and have Bokeh automatically color map the data in the browser with the image() glyph method.

import numpy as np

from bokeh.plotting import figure, output_file, show

output_file("image.html", title="image.py example")

x = np.linspace(0, 10, 250)
y = np.linspace(0, 10, 250)
xx, yy = np.meshgrid(x, y)
d = np.sin(xx)*np.cos(yy)

p = figure(width=400, height=400)
p.x_range.range_padding = p.y_range.range_padding = 0

p.image(image=[d], x=0, y=0, dw=10, dh=10, palette="Spectral11", level="image")
p.grid.grid_line_width = 0.5

show(p)

Note that this example sets the render level to "image". Normally, Bokeh draws all glyphs above grid lines, but with this render level they appear below the grid lines.

Segments and rays

To draw multiple individual line segments use the segment() and ray() glyph methods.

The segment() method accepts the starting points x0 and y0 and end points x1 and y1. It renders segments between those points.

from bokeh.plotting import figure, show

p = figure(width=400, height=400)
p.segment(x0=[1, 2, 3], y0=[1, 2, 3], x1=[1.2, 2.4, 3.1],
          y1=[1.2, 2.5, 3.7], color="#F4A582", line_width=3)

show(p)

The ray() method accepts the starting points x and y with a length (in screen units) and an angle. The angle_units parameter defaults to "rad" but you can also set it to "deg" to have the angle measured in degrees instead of radians. To have an “infinite” ray that always extends to the edge of the plot, set length to 0.

from bokeh.plotting import figure, show

p = figure(width=400, height=400)
p.ray(x=[1, 2, 3], y=[1, 2, 3], length=45, angle=[30, 45, 60],
      angle_units="deg", color="#FB8072", line_width=2)

show(p)

Wedges and arcs

To draw a simple line arc, use the arc() glyph method, which accepts radius, start_angle, and end_angle to determine position. Additionally, the direction property determines whether to render clockwise ("clock") or anti-clockwise ("anticlock") between the start and end angles.

from bokeh.plotting import figure, show

p = figure(width=400, height=400)
p.arc(x=[1, 2, 3], y=[1, 2, 3], radius=0.1, start_angle=0.4, end_angle=4.8, color="navy")

show(p)

The wedge() glyph method accepts the same properties as arc() but renders a filled wedge instead:

from bokeh.plotting import figure, show

p = figure(width=400, height=400)
p.wedge(x=[1, 2, 3], y=[1, 2, 3], radius=0.2, start_angle=0.4, end_angle=4.8,
        color="firebrick", alpha=0.6, direction="clock")

show(p)

The annular_wedge() glyph method is similar to wedge() but leaves an inner portion of the wedge hollow. It accepts an inner_radius and outer_radius instead of just radius.

from bokeh.plotting import figure, show

p = figure(width=400, height=400)
p.annular_wedge(x=[1, 2, 3], y=[1, 2, 3], inner_radius=0.1, outer_radius=0.25,
                start_angle=0.4, end_angle=4.8, color="green", alpha=0.6)

show(p)

Finally, the annulus() glyph method also accepts inner_radius and outer_radius to produce hollow circles.

from bokeh.plotting import figure, show

p = figure(width=400, height=400)
p.annulus(x=[1, 2, 3], y=[1, 2, 3], inner_radius=0.1, outer_radius=0.25,
          color="orange", alpha=0.6)

show(p)

Specialized curves

To draw parameterized quadratic and cubic curves, use the quadratic() and bezier() glyph methods. For more detail on these curves, see reference documentation.

Combining multiple glyphs

You can combine multiple glyphs on a single plot by calling their methods on a single Figure.

from bokeh.plotting import figure, output_file, show

x = [1, 2, 3, 4, 5]
y = [6, 7, 8, 7, 3]

output_file("multiple.html")

p = figure(width=400, height=400)

# add both a line and circles on the same plot
p.line(x, y, line_width=2)
p.circle(x, y, fill_color="white", size=8)

show(p)

This principle applies to all bokeh.plotting glyph methods. You can add as many glyphs to a Bokeh plot as you want.

Setting ranges

By default, Bokeh attempts to automatically set the data bounds of plots to fit snugly around the data. You may, however, need to set a plot’s range explicitly. To do so, set the x_range and/or y_range properties using a Range1d object that lets you set the start and end points of the range you want.

p.x_range = Range1d(0, 100)

For convenience, the figure() function can also accept (start, end) tuples as values for the x_range or y_range parameters. Here’s how you can use both methods to set a range:

from bokeh.models import Range1d
from bokeh.plotting import figure, output_file, show

output_file("title.html")

# create a new plot with a range set with a tuple
p = figure(width=400, height=400, x_range=(0, 20))

# set a range using a Range1d
p.y_range = Range1d(0, 15)

p.circle([1, 2, 3, 4, 5], [2, 5, 8, 2, 7], size=10)

show(p)

Ranges also have a bounds property that lets you specify the limits of the plot beyond which the user cannot pan or zoom.

# set a range using a Range1d
p.y_range = Range1d(0, 15, bounds=(0, None))

Specifying axis types

All the examples above use the default linear axis. This axis is suitable for plots that need to show numerical data on a linear scale. However, you may have categorical data or need to display numerical data on a datetime or log scale. This section shows you how to specify the axis type when using the bokeh.plotting interface.

Categorical axes

To create a categorical axis, specify a FactorRange for one of the plot’s ranges or a list of factors to be converted to one. Here’s an example:

from bokeh.plotting import figure, output_file, show

factors = ["a", "b", "c", "d", "e", "f", "g", "h"]
x = [50, 40, 65, 10, 25, 37, 80, 60]

output_file("categorical.html")

p = figure(y_range=factors)

p.circle(x, factors, size=15, fill_color="orange", line_color="green", line_width=3)

show(p)

For complete details, see Handling categorical data.

Datetime axes

Note

The example in this section requires a network connection and depends on the open source Pandas library to present realistic time series data.

For time series, or any data that involves dates or time, you may want to use axes with labels suitable for different date and time scales.

The figure() function accepts x_axis_type and y_axis_type as arguments. To specify a datetime axis, pass "datetime" for the value of either of these parameters.

import pandas as pd

from bokeh.plotting import figure, output_file, show
from bokeh.sampledata.stocks import AAPL

df = pd.DataFrame(AAPL)
df['date'] = pd.to_datetime(df['date'])

output_file("datetime.html")

# create a new plot with a datetime axis type
p = figure(width=800, height=250, x_axis_type="datetime")

p.line(df['date'], df['close'], color='navy', alpha=0.5)

show(p)

Note

Future versions of Bokeh will attempt to auto-detect situations when datetime axes are appropriate and add them automatically.

Log scale axes

Data that grows exponentially or covers many orders of magnitude often requires one axis to be on a log scale. For data that has a power law relationship, you may want to use log scales on both axes.

You can use the same figure() arguments, x_axis_type and y_axis_type, to set one or both of the axes to "log".

By default, Bokeh calculates log axis ranges to fit around positive value data. For information on how to set your own ranges, see Setting ranges.

from bokeh.plotting import figure, output_file, show

x = [0.1, 0.5, 1.0, 1.5, 2.0, 2.5, 3.0]
y = [10**xx for xx in x]

output_file("log.html")

# create a new plot with a log axis type
p = figure(width=400, height=400, y_axis_type="log")

p.line(x, y, line_width=2)
p.circle(x, y, fill_color="white", size=8)

show(p)

Twin axes

You can add multiple axes representing different ranges to a single plot. To do this, configure the plot with “extra” named ranges in the extra_x_range and extra_y_range properties. You can then refer to these named ranges when adding new glyph methods as well as when adding new axis objects with the add_layout method of the Plot. Here’s an example:

from numpy import arange, linspace, pi, sin

from bokeh.models import LinearAxis, Range1d
from bokeh.plotting import figure, output_file, show

x = arange(-2*pi, 2*pi, 0.1)
y = sin(x)
y2 = linspace(0, 100, len(y))

output_file("twin_axis.html")

p = figure(x_range=(-6.5, 6.5), y_range=(-1.1, 1.1))

p.circle(x, y, color="red")

p.extra_y_ranges = {"foo": Range1d(start=0, end=100)}
p.circle(x, y2, color="blue", y_range_name="foo")
p.add_layout(LinearAxis(y_range_name="foo"), 'left')

show(p)

previous

Defining key concepts

next

Providing data