bokeh.charts Interface

Chart Functions

Area(values, index=None, **kws)

Create an area chart using the AreaBuilder to render the geometry from values.

Parameters:
  • values (iterable) – iterable 2d representing the data series values matrix.
  • index (str|1d iterable, optional) – can be used to specify a common custom index for all data series as an 1d iterable of any sort that will be used as series common index or a string that corresponds to the key of the mapping to be used as index (and not as data series) if area.values is a mapping (like a dict, an OrderedDict or a pandas DataFrame)
In addition the the parameters specific to this chart,
Generic arguments are also accepted as keyword parameters.
Returns:a new Chart

Examples

from bokeh.charts import Area, output_file, show

# (dict, OrderedDict, lists, arrays and DataFrames are valid inputs)
xyvalues = dict(
    python=[2, 3, 7, 5, 26, 221, 44, 233, 254, 265, 266, 267, 120],
    pypy=[12, 33, 47, 15, 126, 121, 144, 233, 254, 225, 226, 267, 110],
    jython=[22, 43, 10, 25, 26, 101, 114, 203, 194, 215, 201, 227, 139],
)

area = Area(
    xyvalues, title="Area Chart", xlabel='time', legend=True,
    ylabel='memory', stacked=True,
)

output_file('area.html')
show(area)
Bar(values, cat=None, stacked=False, xscale='categorical', yscale='linear', xgrid=False, ygrid=True, continuous_range=None, **kw)

Create a Bar chart using BarBuilder render the geometry from values, cat and stacked.

Parameters:
  • values (iterable) – iterable 2d representing the data series values matrix.
  • cat (list or bool, optional) – list of string representing the categories. (Defaults to None)
  • stacked (bool, optional) – to see the bars stacked or grouped. (Defaults to False, so grouping is assumed)
  • continuous_range (Range1d, optional) – Custom continuous_range to be used. (Defaults to None)

In addition the the parameters specific to this chart, Generic arguments are also accepted as keyword parameters.

Returns:a new Chart

Examples

from collections import OrderedDict
from bokeh.charts import Bar, output_file, show

# (dict, OrderedDict, lists, arrays and DataFrames are valid inputs)
xyvalues = OrderedDict()
xyvalues['python']=[-2, 5]
xyvalues['pypy']=[12, 40]
xyvalues['jython']=[22, 30]

cat = ['1st', '2nd']

bar = Bar(xyvalues, cat, title="Stacked bars",
        xlabel="category", ylabel="language")

output_file("stacked_bar.html")
show(bar)
BoxPlot(values, marker='circle', outliers=True, xscale='categorical', yscale='linear', xgrid=False, ygrid=True, **kw)

Create a BoxPlot chart using BoxPlotBuilder to render the geometry from values, marker and outliers arguments.

Parameters:
  • values (iterable) – iterable 2d representing the data series values matrix.
  • marker (int or string, optional) – if outliers=True, the marker type to use e.g., circle.
  • outliers (bool, optional) – Whether or not to plot outliers.

In addition the the parameters specific to this chart, Generic arguments are also accepted as keyword parameters.

Returns:a new Chart

Examples:

import numpy as np
from bokeh.charts import BoxPlot, output_file, show

# (dict, OrderedDict, lists, arrays and DataFrames of arrays are valid inputs)
medals = dict([
    ('bronze', np.array([7.0, 10.0, 8.0, 7.0, 4.0, 4.0, 1.0, 5.0, 2.0, 1.0,
                4.0, 2.0, 1.0, 2.0, 4.0, 1.0, 0.0, 1.0, 1.0, 2.0,
                0.0, 1.0, 0.0, 0.0, 1.0, 1.0])),
    ('silver', np.array([8., 4., 6., 4., 8., 3., 3., 2., 5., 6.,
                1., 4., 2., 3., 2., 0., 0., 1., 2., 1.,
                3.,  0.,  0.,  1.,  0.,  0.])),
    ('gold', np.array([6., 6., 6., 8., 4., 8., 6., 3., 2., 2.,  2.,  1.,
              3., 1., 0., 5., 4., 2., 0., 0., 0., 1., 1., 0., 0.,
              0.]))
])

boxplot = BoxPlot(medals, marker="circle", outliers=True, title="boxplot",
    xlabel="medal type", ylabel="medal count")

output_file('boxplot.html')
show(boxplot)
Donut(values, cat=None, width=800, height=800, xgrid=False, ygrid=False, **kws)

Creates a Donut chart using DonutBuilder to render the geometry from values and cat.

Parameters:
  • values (iterable) – iterable 2d representing the data series values matrix.
  • cat (list or bool, optional) – list of string representing the categories. Defaults to None.

In addition the the parameters specific to this chart, Generic arguments are also accepted as keyword parameters.

Returns:a new Chart

Examples:

from bokeh.charts import Donut, output_file, show

# dict, OrderedDict, lists, arrays and DataFrames are valid inputs
xyvalues = [[2., 5., 3.], [4., 1., 4.], [6., 4., 3.]]

donut = Donut(xyvalues, ['cpu1', 'cpu2', 'cpu3'])

output_file('donut.html')
show(donut)
Dot(values, cat=None, stem=True, xscale='categorical', yscale='linear', xgrid=False, ygrid=True, **kws)

Create a dot chart using DotBuilder to render the geometry from values and cat.

Parameters:
  • values (iterable) – iterable 2d representing the data series values matrix.
  • cat (list or bool, optional) – list of string representing the categories. Defaults to None.

In addition the the parameters specific to this chart, Generic arguments are also accepted as keyword parameters.

Returns:a new Chart

Examples:

from collections import OrderedDict
from bokeh.charts import Dot, output_file, show

# dict, OrderedDict, lists, arrays and DataFrames are valid inputs
xyvalues = OrderedDict()
xyvalues['python']=[2, 5]
xyvalues['pypy']=[12, 40]
xyvalues['jython']=[22, 30]

dot = Dot(xyvalues, ['cpu1', 'cpu2'], title='dots')

output_file('dot.html')
show(dot)
HeatMap(values, xscale='categorical', yscale='categorical', xgrid=False, ygrid=False, **kw)

Create a HeatMap chart using HeatMapBuilder to render the geometry from values.

Parameters:values (iterable) – iterable 2d representing the data series values matrix.

In addition the the parameters specific to this chart, Generic arguments are also accepted as keyword parameters.

Returns:a new Chart

Examples:

from collections import OrderedDict
from bokeh.charts import HeatMap, output_file, show

# (dict, OrderedDict, lists, arrays and DataFrames are valid inputs)
xyvalues = OrderedDict()
xyvalues['apples'] = [4,5,8]
xyvalues['bananas'] = [1,2,4]
xyvalues['pears'] = [6,5,4]

hm = HeatMap(xyvalues, title='Fruits')

output_file('heatmap.html')
show(hm)
Histogram(values, bins, mu=None, sigma=None, density=True, **kws)

Create a histogram chart using HistogramBuilder to render the geometry from values, bins, sigma and density.

Parameters:
  • values (iterable) – iterable 2d representing the data series values matrix.
  • bins (int) – number of bins to use in the Histogram building.
  • mu (float, optional) – theoretical mean value for the normal distribution. (default: None)
  • sigma (float, optional) – theoretical sigma value for the normal distribution. (default: None)
  • density (bool, optional) – If False, the result will contain the number of samples in each bin. If True, the result is the value of the probability density function at the bin, normalized such that the integral over the range is 1. For more info check numpy.histogram function documentation. (default: True)

In addition the the parameters specific to this chart, Generic arguments are also accepted as keyword parameters.

Returns:a new Chart

Examples:

import pandas as pd
from bokeh.charts import Histogram, output_file, show

# (dict, OrderedDict, lists, arrays and DataFrames are valid inputs)
xyvalues = pd.DataFrame(dict(normal=[1, 2, 3, 1], lognormal=[5, 4, 4, 1]))

hm = Histogram(xyvalues, bins=5, title='Histogram')

output_file('histogram.html')
show(hm)
Horizon(values, index=None, num_folds=3, pos_color='#006400', neg_color='#6495ed', xscale='datetime', xgrid=False, ygrid=False, **kws)

Create a Horizon chart using HorizonBuilder render the geometry from values, index and num_folds.

Parameters:
  • values (iterable) – iterable 2d representing the data series values matrix.
  • index (str|1d iterable, optional) – can be used to specify a common custom index for all data series as an 1d iterable of any sort that will be used as series common index or a string that corresponds to the key of the mapping to be used as index (and not as data series) if area.values is a mapping (like a dict, an OrderedDict or a pandas DataFrame)
  • num_folds (int, optional) – The number of folds stacked on top of each other. (default: 3)
  • pos_color (color, optional) – The color of the positive folds. (default: “#006400”)
  • neg_color (color, optional) – The color of the negative folds. (default: “#6495ed”)

In addition the the parameters specific to this chart, Generic arguments are also accepted as keyword parameters.

Returns:a new Chart

Examples:

import datetime
from collections import OrderedDict
from bokeh.charts import Horizon, output_file, show

now = datetime.datetime.now()
dts = [now+datetime.timedelta(seconds=i) for i in range(10)]

xyvalues = OrderedDict({'Date': dts})
y_python = xyvalues['python'] = [2, 3, 7, 5, 26, 27, 27, 28, 26, 20]
y_pypy = xyvalues['pypy'] = [12, 33, 47, 15, 126, 122, 95, 90, 110, 112]
y_jython = xyvalues['jython'] = [22, 43, 10, 25, 26, 25, 26, 45, 26, 30]

hz = Horizon(xyvalues, index='Date', title="Horizon Example", ylabel='Sample Data', xlabel='')

output_file('horizon.html')
show(hz)
Line(values, index=None, **kws)

Create a line chart using LineBuilder to render the geometry from values and index.

Parameters:
  • values (iterable) – iterable 2d representing the data series values matrix.
  • index (str|1d iterable, optional) – can be used to specify a common custom index for all data series as an 1d iterable of any sort that will be used as series common index or a string that corresponds to the key of the mapping to be used as index (and not as data series) if area.values is a mapping (like a dict, an OrderedDict or a pandas DataFrame)

In addition the the parameters specific to this chart, Generic arguments are also accepted as keyword parameters.

Returns:a new Chart

Examples:

import numpy as np
from bokeh.charts import Line, output_file, show

# (dict, OrderedDict, lists, arrays and DataFrames are valid inputs)
xyvalues = np.array([[2, 3, 7, 5, 26], [12, 33, 47, 15, 126], [22, 43, 10, 25, 26]])

line = Line(xyvalues, title="line", legend="top_left", ylabel='Languages')

output_file('line.html')
show(line)
Scatter(values, **kws)

Create a scatter chart using ScatterBuilder to render the geometry from values.

Parameters:values (iterable) – iterable 2d representing the data series values matrix.

In addition the the parameters specific to this chart, Generic arguments are also accepted as keyword parameters.

Returns:a new Chart

Examples:

from collections import OrderedDict
from bokeh.charts import Scatter, output_file, show

# (dict, OrderedDict, lists, arrays and DataFrames of (x, y) tuples are valid inputs)
xyvalues = OrderedDict()
xyvalues['python'] = [(1, 2), (3, 3), (4, 7), (5, 5), (8, 26)]
xyvalues['pypy'] = [(1, 12), (2, 23), (4, 47), (5, 15), (8, 46)]
xyvalues['jython'] = [(1, 22), (2, 43), (4, 10), (6, 25), (8, 26)]

scatter = Scatter(xyvalues, title="Scatter", legend="top_left", ylabel='Languages')

output_file('scatter.html')
show(scatter)
Step(values, index=None, **kws)

Create a step chart using StepBuilder render the geometry from values and index.

Parameters:
  • values (iterable) – iterable 2d representing the data series values matrix.
  • index (str|1d iterable, optional) – can be used to specify a common custom index for all data series as an 1d iterable of any sort that will be used as series common index or a string that corresponds to the key of the mapping to be used as index (and not as data series) if area.values is a mapping (like a dict, an OrderedDict or a pandas DataFrame)

In addition the the parameters specific to this chart, Generic arguments are also accepted as keyword parameters.

Returns:a new Chart

Examples:

from collections import OrderedDict
from bokeh.charts import Step, output_file, show

# (dict, OrderedDict, lists, arrays and DataFrames are valid inputs)
xyvalues = [[2, 3, 7, 5, 26], [12, 33, 47, 15, 126], [22, 43, 10, 25, 26]]

step = Step(xyvalues, title="Steps", legend="top_left", ylabel='Languages')

output_file('step.html')
show(step)
TimeSeries(values, index=None, xscale='datetime', **kws)

Create a timeseries chart using TimeSeriesBuilder to render the lines from values and index.

Parameters:
  • values (iterable) – iterable 2d representing the data series values matrix.
  • index (str|1d iterable, optional) – can be used to specify a common custom index for all data series as an 1d iterable of any sort that will be used as series common index or a string that corresponds to the key of the mapping to be used as index (and not as data series) if area.values is a mapping (like a dict, an OrderedDict or a pandas DataFrame)

In addition the the parameters specific to this chart, Generic arguments are also accepted as keyword parameters.

Returns:a new Chart

Examples:

from collections import OrderedDict
import datetime
from bokeh.charts import TimeSeries, output_file, show

# (dict, OrderedDict, lists, arrays and DataFrames are valid inputs)
now = datetime.datetime.now()
delta = datetime.timedelta(minutes=1)
dts = [now + delta*i for i in range(5)]

xyvalues = OrderedDict({'Date': dts})
y_python = xyvalues['python'] = [2, 3, 7, 5, 26]
y_pypy = xyvalues['pypy'] = [12, 33, 47, 15, 126]
y_jython = xyvalues['jython'] = [22, 43, 10, 25, 26]

ts = TimeSeries(xyvalues, index='Date', title="TimeSeries", legend="top_left",
        ylabel='Languages')

output_file('timeseries.html')
show(ts)

Helper Classes

class Chart(*args, **kwargs)

The main Chart class, the core of the Bokeh.charts interface.

add_builder(builder)
add_legend(legends)

Add the legend to your plot, and the plot to a new Document.

It also add the Document to a new Session in the case of server output.

Parameters:legends (List(Tuple(String, List(GlyphRenderer)) – A list of tuples that maps text labels to the legend to corresponding renderers that should draw sample representations for those labels.
add_renderers(builder, renderers)
create_axes()
create_grids(xgrid=True, ygrid=True)
create_tools(tools)
filename(value)

Chained method for filename option.

get_class(view_model_name)

Given a __view_model__ name, returns the corresponding class object

height(value)

Chained method for height option.

id(value)

Chained method for id option.

legend(value)

Chained method for legend option.

make_axis(location, scale, label)

Create linear, date or categorical axis depending on the location, scale and with the proper labels.

Parameters:
  • location (str) – the space localization of the axis. It can be left, right, above or below.
  • scale (str) – the scale on the axis. It can be linear, datetime or categorical.
  • label (str) – the label on the axis.
Returns:

Axis instance
Return type:

axis
make_grid(dimension, ticker)

Create the grid just passing the axis and dimension.

Parameters:
  • dimension (int) – the dimension of the axis, ie. xaxis=0, yaxis=1.
  • ticker (obj) – the axis.ticker object
Returns:

Grid instance
Return type:

grid
notebook(value)

Chained method for notebook option.

server(value)

Chained method for server option.

show()

Main show function.

It shows the plot in file, server and notebook outputs.

start_plot()

Add the axis, grids and tools

width(value)

Chained method for width option.

xgrid(value)

Chained method for xgrid option.

xlabel(value)

Chained method for xlabel option.

xscale(value)

Chained method for xscale option.

ygrid(value)

Chained method for ygrid option.

ylabel(value)

Chained method for ylabel option.

yscale(value)

Chained method for yscale option.

class DataAdapter(data, index=None, columns=None, force_alias=True)

Adapter object used to normalize Charts inputs to a common interface. Supported inputs are dict, list, tuple, np.ndarray and pd.DataFrame.

static get_index_and_data(values, index=None)

Parse values (that must be one of the DataAdapter supported input types) and create an separate/create index and data depending on values type and index.

Parameters:values (iterable) – container that holds data to be plotted using on the Chart classes
Returns:iterable that represents the data index values: iterable containing the values to be plotted
Return type:xs
index_converter(x)
static is_datetime(value)
static is_number(value)
items()
iteritems()
iterkeys()
itervalues()
keys()
static normalize_values(values)
static validate_values(values)
values()
columns
index

Builders

class AreaBuilder(values=None, **kws)

This is the Area class and it is in charge of plotting Area chart in an easy and intuitive way.

Essentially, it provides a way to ingest the data, make the proper calculations and push the references into a source object. We additionally make calculations for the ranges. And finally add the needed glyphs (patch) taking the references from the source.

index

property type: Any

An index to be used for all data series as follows:

  • A 1d iterable of any sort that will be used as

    series common index

  • As a string that corresponds to the key of the

    mapping to be used as index (and not as data series) if area.values is a mapping (like a dict, an OrderedDict or a pandas DataFrame)

stacked

property type: Bool

Whether to stack the areas. (Defaults to False)

If True, areas are draw as a stack, to show the relationship of parts to a whole. Otherwise, areas are layered above one another.

class BarBuilder(values=None, **kws)

This is the Bar class and it is in charge of plotting Bar chart (grouped and stacked) in an easy and intuitive way.

Essentially, it provides a way to ingest the data, make the proper calculations and push the references into a source object. We additionally make calculations for the ranges. And finally add the needed glyphs (rects) taking the references from the source.

The x_range is categorical, and is made either from the cat argument or from the indexes of the passed values if no cat is supplied. The y_range can be supplied as the parameter continuous_range, or will be calculated as a linear range (Range1d) based on the supplied values using the following rules:

  • with all positive data: start = 0, end = 1.1 * max
  • with all negative data: start = 1.1 * min, end = 0
  • with mixed sign data: start = 1.1 * min, end = 1.1 * max
cat

property type: Either(Bool, List(Any))

List of string representing the categories. (Defaults to None.)

stacked

property type: Bool

Whether to stack the bars. (Defaults to False)

If True, bars are draw as a stack, to show the relationship of parts to a whole. Otherwise, bars are grouped on the same chart.

class BoxPlotBuilder(values=None, **kws)

This is the BoxPlot class and it is in charge of plotting scatter plots in an easy and intuitive way.

Essentially, we provide a way to ingest the data, make the proper calculations and push the references into a source object. We additionally make calculations for the ranges. And finally add the needed glyphs (rects, lines and markers) taking the references from the source.

set_and_get(data, attr, val, content)

Set a new attr and then get it to fill the self._data dict.

Keep track of the attributes created.

Parameters:
  • data (dict) – where to store the new attribute content
  • attr (list) – where to store the new attribute names
  • val (string) – name of the new attribute
  • content (obj) – content of the new attribute
marker

property type: String

The marker type to use (e.g., circle) if outliers=True.

outliers

property type: Bool

Whether to display markers for any outliers.

class DonutBuilder(values=None, **kws)

This is the Donut class and it is in charge of plotting Donut chart in an easy and intuitive way.

Essentially, it provides a way to ingest the data, make the proper calculations and push the references into a source object. We additionally make calculations for the donut slices and angles. And finally add the needed glyphs (Wedges and AnnularWedges) taking the references from the source.

draw_central_descriptions()

Draw the descriptions to be placed on the central part of the donut wedge

draw_central_wedge()

Draw the central part of the donut wedge from donut.source and its calculated start and end angles.

draw_external_ring(colors=None)

Draw the external part of the donut wedge from donut.source and its related descriptions

cat

property type: Either(Bool, List(Any))

List of string representing the categories. (Defaults to None.)

class DotBuilder(values=None, **kws)
This is the Dot class and it is in charge of plotting Dot chart
in an easy and intuitive way.

Essentially, it provides a way to ingest the data, make the proper calculations and push the references into a source object. We additionally make calculations for the ranges. And finally add the needed glyphs (segments and circles) taking the references from the source.

cat

property type: Either(Bool, List(Any))

List of string representing the categories. (Defaults to None.)

stem

property type: Bool

Whether to draw a stem from each do to the axis.

class HeatMapBuilder(values=None, **kws)

This is the HeatMap class and it is in charge of plotting HeatMap chart in an easy and intuitive way.

Essentially, it provides a way to ingest the data, make the proper calculations and push the references into a source object. We additionally make calculations for the ranges. And finally add the needed glyphs (rects) taking the references from the source.

class HistogramBuilder(values=None, **kws)

This is the Histogram class and it is in charge of plotting histograms in an easy and intuitive way.

Essentially, we provide a way to ingest the data, make the proper calculations and push the references into a source object. We additionally make calculations for the ranges. And finally add the needed glyphs (quads and lines) taking the references from the source.

bins

property type: Int

Number of bins to use for the histogram. (default: 10)

density

property type: Bool

Whether to normalize the histogram. (default: True)

If True, the result is the value of the probability density function at the bin, normalized such that the integral over the range is 1. If False, the result will contain the number of samples in each bin.

For more info check numpy.histogram function documentation.

mu

property type: Float

Theoretical mean value for the normal distribution. (default: None)

sigma

property type: Float

Theoretical standard deviation value for the normal distribution. (default: None)

class HorizonBuilder(values, **kws)

This is the Horizon class and it is in charge of plotting Horizon charts in an easy and intuitive way.

Essentially, we provide a way to ingest the data, separate the data into a number of folds which stack on top of each others. We additionally make calculations for the ranges. And finally add the needed lines taking the references from the source.

class LineBuilder(values=None, **kws)

This is the Line class and it is in charge of plotting Line charts in an easy and intuitive way. Essentially, we provide a way to ingest the data, make the proper calculations and push the references into a source object. We additionally make calculations for the ranges. And finally add the needed lines taking the references from the source.

index

property type: Any

An index to be used for all data series as follows:

  • A 1d iterable of any sort that will be used as

    series common index

  • As a string that corresponds to the key of the

    mapping to be used as index (and not as data series) if area.values is a mapping (like a dict, an OrderedDict or a pandas DataFrame)

class ScatterBuilder(values=None, **kws)

This is the Scatter class and it is in charge of plotting Scatter charts in an easy and intuitive way.

Essentially, we provide a way to ingest the data, make the proper calculations and push the references into a source object. We additionally make calculations for the ranges. And finally add the needed glyphs (markers) taking the references from the source.

marker

property type: String

The marker type to use (default: circle).

parse_data

Parse data received from self._values and create correct x, y series values checking if input is a pandas DataFrameGroupBy object or one of the stardard supported types (that can be converted to a DataAdapter)

class StepBuilder(values=None, **kws)

This is the Step class and it is in charge of plotting Step charts in an easy and intuitive way.

Essentially, we provide a way to ingest the data, make the proper calculations and push the references into a source object. We additionally make calculations for the ranges. And finally add the needed lines taking the references from the source.

index

property type: Any

An index to be used for all data series as follows:

  • A 1d iterable of any sort that will be used as

    series common index

  • As a string that corresponds to the key of the

    mapping to be used as index (and not as data series) if area.values is a mapping (like a dict, an OrderedDict or a pandas DataFrame)

class TimeSeriesBuilder(values=None, **kws)

This is the TimeSeries class and it is in charge of plotting TimeSeries charts in an easy and intuitive way.

Essentially, we provide a way to ingest the data, make the proper calculations and push the references into a source object. We additionally make calculations for the ranges. And finally add the needed lines taking the references from the source.

index

property type: Any

An index to be used for all data series as follows:

  • A 1d iterable of any sort that will be used as

    series common index

  • As a string that corresponds to the key of the

    mapping to be used as index (and not as data series) if area.values is a mapping (like a dict, an OrderedDict or a pandas DataFrame)