bokeh.charts¶

Area¶

Area(data=None, x=None, y=None, **kws)¶

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

Parameters:	data (Accepted Charts Data Formats) – table-like data x (str or list(str) – the column label to use for the x dimension y (str or list(str) – the column label to use for the y dimension

In addition the the parameters specific to this chart, Chart Defaults are also accepted as keyword parameters.

Returns:	includes glyph renderers that generate the area glyphs
Return type:	Chart

Examples:

from bokeh.charts import Area, show, vplot, output_file

# create some example data
data = dict(
    python=[2, 3, 7, 5, 26, 221, 44, 233, 254, 265, 266, 267, 120, 111],
    pypy=[12, 33, 47, 15, 126, 121, 144, 233, 254, 225, 226, 267, 110, 130],
    jython=[22, 43, 10, 25, 26, 101, 114, 203, 194, 215, 201, 227, 139, 160],
)

area = Area(data, title="Area Chart", legend="top_left",
            xlabel='time', ylabel='memory')

output_file('area.html')
show(area)

Bar¶

Bar(data, label=None, values=None, color=None, stack=None, group=None, agg='sum', 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:

data (Accepted Charts Data Formats) – the data source for the chart. label (list(str) – list of string representing the categories. (Defaults to None) values (str, optional) – iterable 2d representing the data series values matrix. color (str or list(str) – string color, string column name, list of string columns or a custom ColorAttr, which replaces the default ColorAttr for the builder. stack (list(str) – columns to use for stacking. (Defaults to False, so grouping is assumed) group (list(str) – columns to use for grouping. agg (str) – how to aggregate the values. (Defaults to ‘sum’, or only label is provided, then performs a count) continuous_range (Range1d, optional) – Custom continuous_range to be used. (Defaults to None)

In addition to the parameters specific to this chart, Chart Defaults are also accepted as keyword parameters.

Returns:	includes glyph renderers that generate bars
Return type:	Chart

Examples

from bokeh.charts import Bar, output_file, show, hplot

# best support is with data in a format that is table-like
data = {
    'sample': ['1st', '2nd', '1st', '2nd', '1st', '2nd'],
    'interpreter': ['python', 'python', 'pypy', 'pypy', 'jython', 'jython'],
    'timing': [-2, 5, 12, 40, 22, 30]
}

# x-axis labels pulled from the interpreter column, stacking labels from sample column
bar = Bar(data, values='timing', label='interpreter', stack='sample', agg='mean',
          title="Python Interpreter Sampling", legend='top_right', plot_width=400)

# table-like data results in reconfiguration of the chart with no data manipulation
bar2 = Bar(data, values='timing', label=['interpreter', 'sample'],
           agg='mean', title="Python Interpreters", plot_width=400)

output_file("stacked_bar.html")
show(hplot(bar, bar2))

BoxPlot¶

BoxPlot(data, label=None, values=None, color=None, group=None, xscale='categorical', yscale='linear', xgrid=False, ygrid=True, continuous_range=None, **kw)¶

Create a BoxPlot chart containing one or more boxes from table-like data.

Create a boxplot chart using BoxPlotBuilder to render the glyphs from input data and specification. This primary use case for the boxplot is to depict the distribution of a variable by providing summary statistics for it. This boxplot is particularly useful at comparing distributions between categorical variables.

This chart implements functionality for segmenting and comparing the values of a variable by an associated categorical variable.

Reference: BoxPlot on Wikipedia

Parameters:

data (Accepted Charts Data Formats) – the data source for the chart values (str, optional) – the values to use for producing the boxplot using table-like input data label (str or list(str) – the categorical variable to use for creating separate boxes color (str or list(str) – the categorical variable or color attribute specification to use for coloring the boxes. whisker_color (str or list(str) – the color of the “whiskers” that show the spread of values outside the .25 and .75 quartiles. marker (str or list(str) – the marker glyph to use for the outliers outliers (bool, optional) – whether to show outliers. Defaults to True. **kw –

In addition to the parameters specific to this chart, Chart Defaults are also accepted as keyword parameters.

Returns:	includes glyph renderers that generate Boxes and Whiskers
Return type:	Chart

Examples:

from bokeh.sampledata.autompg import autompg as df
from bokeh.charts import BoxPlot, output_file, show, hplot

box = BoxPlot(df, values='mpg', label='cyl', title="Auto MPG Box Plot", plot_width=400)
box2 = BoxPlot(df, values='mpg', label='cyl', color='cyl',
               title="MPG Box Plot by Cylinder Count", plot_width=400)

output_file('box.html')
show(hplot(box, box2))

Donut¶

Donut(data, label='index', values=None, color=None, agg=None, hover_tool=True, hover_text=None, plot_height=400, plot_width=400, xgrid=False, ygrid=False, **kw)¶

Create a Donut chart containing one or more layers from table-like data.

Create a donut chart using DonutBuilder to render the glyphs from input data and specification. The primary use case for the donut chart is to show relative amount each category, within a categorical array or multiple categorical arrays, makes up of the whole for some array of values.

Parameters:

data (Accepted Charts Data Formats) – the data source for the chart label (str or list(str), optional): the categorical variable to use for creating separate boxes values (str, optional) – the values to use for producing the boxplot using table-like input data color (str or list(str) – the categorical variable or color attribute specification to use for coloring the wedges agg (str, optional) – how the values associated with a wedge should be aggregated hover_tool (bool, optional): whether to show the value of the wedge when hovering hover_text (str, optional) – provide an alternative string to use label the value shown with the hover tool **kw –

In addition to the parameters specific to this chart, Chart Defaults are also accepted as keyword parameters.

Returns:	includes glyph renderers that generate the wedges the make up the donut(s)
Return type:	Chart

Examples:

from bokeh.charts import Donut, show, output_file
from bokeh.charts.utils import df_from_json
from bokeh.sampledata.olympics2014 import data

import pandas as pd

# utilize utility to make it easy to get json/dict data converted to a dataframe
df = df_from_json(data)

# filter by countries with at least one medal and sort by total medals
df = df[df['total'] > 8]
df = df.sort("total", ascending=False)
df = pd.melt(df, id_vars=['abbr'],
             value_vars=['bronze', 'silver', 'gold'],
             value_name='medal_count', var_name='medal')

# original example
d = Donut(df, label=['abbr', 'medal'], values='medal_count',
          text_font_size='8pt', hover_text='medal_count')

output_file("donut.html")

show(d)

HeatMap¶

HeatMap(data, x=None, y=None, values=None, stat='count', xgrid=False, ygrid=False, hover_tool=True, hover_text=None, **kw)¶

Represent 3 dimensions in a HeatMap chart using x, y, and values.

Uses the HeatMapBuilder to render the geometry from values.

A HeatMap is a 3 Dimensional chart that crosses two dimensions, then aggregates values that correspond to the intersection of the horizontal and vertical dimensions. The value that falls at the intersection is then mapped to a color in a palette by default. All values that map to the positions on the chart are binned by the number of discrete colors in the palette.

Parameters:

data (Accepted Charts Data Formats) – the data source for the chart x (str or list(str) – specifies variable(s) to use for x axis y (str or list(str) – specifies variable(s) to use for y axis values (str, optional) – the values to use for producing the histogram using table-like input data stat (str, optional) – the aggregation to use. Defaults to count. If provided None, then no aggregation will be attempted. This is useful for cases when the values have already been aggregated. hover_tool (bool, optional) – whether to show the hover tool. Defaults to True hover_text (str, optional) – a string to place beside the value in the hover tooltip. Defaults to None. When None, a hover_text will be derived from the aggregation and the values column.

In addition to the parameters specific to this chart, Chart Defaults are also accepted as keyword parameters.

Returns:	a new Chart

Examples:

from bokeh.charts import HeatMap, output_file, show

# (dict, OrderedDict, lists, arrays and DataFrames are valid inputs)
data = {'fruit': ['apples']*3 + ['bananas']*3 + ['pears']*3,
        'fruit_count': [4, 5, 8, 1, 2, 4, 6, 5, 4],
        'sample': [1, 2, 3]*3}

hm = HeatMap(data, x='fruit', y='sample', values='fruit_count',
             title='Fruits', stat=None)

output_file('heatmap.html')
show(hm)

Histogram¶

Histogram(data, values=None, label=None, color=None, agg='count', bins=None, yscale='linear', xgrid=False, ygrid=True, continuous_range=None, **kw)¶

Create a histogram chart with one or more histograms.

Create a histogram chart using HistogramBuilder to render the glyphs from input data and specification. This primary use case for the histogram is to depict the distribution of a variable by binning and aggregating the values in each bin.

This chart implements functionality to provide convenience in optimal selection of bin count, but also for segmenting and comparing segments of the variable by a categorical variable.

Parameters:

data (Accepted Charts Data Formats) – the data source for the chart values (str, optional) – the values to use for producing the histogram using table-like input data label (str or list(str) – the categorical variable to use for creating separate histograms color (str or list(str) – the categorical variable or color attribute specification to use for coloring the histogram, or explicit color as a string. agg (str, optional) – how to aggregate the bins. Defaults to “count”. bins (int, optional) – the number of bins to use. Defaults to None to auto select. **kw –

In addition to the parameters specific to this chart, Chart Defaults are also accepted as keyword parameters.

Returns:	includes glyph renderers that generate the histograms
Return type:	Chart

Examples:

from bokeh.sampledata.autompg import autompg as df
from bokeh.charts import Histogram, output_file, show, hplot

hist = Histogram(df, values='mpg', title="Auto MPG Histogram", plot_width=400)
hist2 = Histogram(df, values='mpg', label='cyl', color='cyl', legend='top_right',
                  title="MPG Histogram by Cylinder Count", plot_width=400)

output_file('hist.html')
show(hplot(hist, hist2))

Horizon¶

Horizon(data=None, x=None, y=None, series=None, **kws)¶

Create a horizon chart using HorizonBuilder to render the geometry from values.

Parameters:	data (Accepted Charts Data Formats) – table-like data x (str or list(str) – the column label to use for the x dimension y (str or list(str) – the column label to use for the y dimension

In addition to the parameters specific to this chart, Chart Defaults are also accepted as keyword parameters.

Returns:	includes glyph renderers that generate the scatter points
Return type:	Chart

Examples:

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

# read in some stock data from the Yahoo Finance API
AAPL = pd.read_csv(
    "http://ichart.yahoo.com/table.csv?s=AAPL&a=0&b=1&c=2000&d=0&e=1&f=2010",
    parse_dates=['Date'])

MSFT = pd.read_csv(
    "http://ichart.yahoo.com/table.csv?s=MSFT&a=0&b=1&c=2000&d=0&e=1&f=2010",
    parse_dates=['Date'])

IBM = pd.read_csv(
    "http://ichart.yahoo.com/table.csv?s=IBM&a=0&b=1&c=2000&d=0&e=1&f=2010",
    parse_dates=['Date'])

data = dict([
    ('AAPL', AAPL['Adj Close']),
    ('Date', AAPL['Date']),
    ('MSFT', MSFT['Adj Close']),
    ('IBM', IBM['Adj Close'])]
)

hp = Horizon(data, x='Date', plot_width=800, plot_height=300,
             title="horizon plot using stock inputs")

output_file("horizon.html")

show(hp)

Line¶

Line(data=None, x=None, y=None, **kws)¶

Create a line chart using LineBuilder to render the glyphs.

The line chart is typically is used with column oriented data, where each column contains comparable measurements and the column names are treated as a categorical variable for differentiating the measurement values. One of the columns can be used as an index for either the x or y axis.

Note

Only the x or y axis can display multiple variables, while the other is used as an index.

Parameters:	data (list(list) – a 2d data source with columns of data for each line. x (str or list(str) – specifies variable(s) to use for x axis y (str or list(str) – specifies variable(s) to use for y axis

In addition to the parameters specific to this chart, Chart Defaults are also accepted as keyword parameters.

Note

This chart type differs on input types as compared to other charts, due to the way that line charts typically are plotting labeled series. For example, a column for AAPL stock prices over time. Another way this could be plotted is to have a DataFrame with a column of stock_label and columns of price, which is the stacked format. Both should be supported, but the former is the expected one. Internally, the latter format is being derived.

Returns:	includes glyph renderers that generate the lines
Return type:	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¶

Scatter(data=None, x=None, y=None, **kws)¶

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

Parameters:	data (Accepted Charts Data Formats) – table-like data x (str or list(str) – the column label to use for the x dimension y (str or list(str) – the column label to use for the y dimension

In addition to the parameters specific to this chart, Chart Defaults are also accepted as keyword parameters.

Returns:	includes glyph renderers that generate the scatter points
Return type:	Chart

Examples:

from bokeh.sampledata.autompg import autompg as df
from bokeh.charts import Scatter, output_file, show

scatter = Scatter(df, x='mpg', y='hp', color='cyl', marker='origin',
                  title="Auto MPG", xlabel="Miles Per Gallon",
                  ylabel="Horsepower")

output_file('scatter.html')
show(scatter)

Step¶

Step(data=None, x=None, y=None, **kws)¶

Create a step chart using StepBuilder to render the geometry from the inputs.

Note

Only the x or y axis can display multiple variables, while the other is used as an index.

Parameters:	data (list(list) – a 2d data source with columns of data for each stepped line. x (str or list(str) – specifies variable(s) to use for x axis y (str or list(str) – specifies variable(s) to use for y axis

In addition to the parameters specific to this chart, Chart Defaults are also accepted as keyword parameters.

Note

This chart type differs on input types as compared to other charts, due to the way that series-type charts typically are plotting labeled series. For example, a column for AAPL stock prices over time. Another way this could be plotted is to have a DataFrame with a column of stock_label and columns of price, which is the stacked format. Both should be supported, but the former is the expected one. Internally, the latter format is being derived.

Returns:	includes glyph renderers that generate the stepped lines
Return type:	Chart

Examples:

from bokeh.charts import Step, show, output_file

# build a dataset where multiple columns measure the same thing
data = dict(
           stamp=[.33, .33, .34, .37, .37, .37, .37, .39, .41, .42,
                  .44, .44, .44, .45, .46, .49, .49],
           postcard=[.20, .20, .21, .23, .23, .23, .23, .24, .26, .27,
                     .28, .28, .29, .32, .33, .34, .35]
       )

# create a step chart where each column of measures receives a unique color and dash style
step = Step(data, y=['stamp', 'postcard'],
            dash=['stamp', 'postcard'],
            color=['stamp', 'postcard'],
            title="U.S. Postage Rates (1999-2015)",
            ylabel='Rate per ounce', legend=True)

output_file("steps.html")

show(step)

TimeSeries¶

TimeSeries(data=None, x=None, y=None, builder_type=<class 'bokeh.charts.builders.line_builder.LineBuilder'>, **kws)¶

Create a timeseries chart using LineBuilder to produce the renderers from the inputs. The timeseries chart acts as a switchboard to produce charts for timeseries data with different glyph representations.

Parameters:	data (list(list) – a 2d data source with columns of data for each stepped line. x (str or list(str) – specifies variable(s) to use for x axis y (str or list(str) – specifies variable(s) to use for y axis builder_type (str or Builder, optional) – the type of builder to use to produce the renderers. Supported options are ‘line’, ‘step’, or ‘point’.

In addition to the parameters specific to this chart, Chart Defaults are also accepted as keyword parameters.

Returns:	a new Chart

Examples:

import pandas as pd
from bokeh.charts import TimeSeries, show, output_file, vplot

# read in some stock data from the Yahoo Finance API
AAPL = pd.read_csv(
    "http://ichart.yahoo.com/table.csv?s=AAPL&a=0&b=1&c=2000&d=0&e=1&f=2010",
    parse_dates=['Date'])
MSFT = pd.read_csv(
    "http://ichart.yahoo.com/table.csv?s=MSFT&a=0&b=1&c=2000&d=0&e=1&f=2010",
    parse_dates=['Date'])
IBM = pd.read_csv(
    "http://ichart.yahoo.com/table.csv?s=IBM&a=0&b=1&c=2000&d=0&e=1&f=2010",
    parse_dates=['Date'])

data = dict(
    AAPL=AAPL['Adj Close'],
    Date=AAPL['Date'],
    MSFT=MSFT['Adj Close'],
    IBM=IBM['Adj Close'],
)

tsline = TimeSeries(data,
    x='Date', y=['IBM', 'MSFT', 'AAPL'],
    color=['IBM', 'MSFT', 'AAPL'], dash=['IBM', 'MSFT', 'AAPL'],
    title="Timeseries", ylabel='Stock Prices', legend=True)

tspoint = TimeSeries(data,
    x='Date', y=['IBM', 'MSFT', 'AAPL'],
    color=['IBM', 'MSFT', 'AAPL'], dash=['IBM', 'MSFT', 'AAPL'],
    builder_type='point', title="Timeseries Points",
    ylabel='Stock Prices', legend=True)

output_file("timeseries.html")

show(vplot(tsline, tspoint))

Data Operations¶

blend(*cols, **kwargs)¶

Provides a simple function for specifying a Blend data operation.

Parameters:	cols (str) – each column to use for blending by name **kwargs – the keyword args supported by Blend name (str): name of the column to contain the blended values labels_name (str): name of the column to contain the name of the columns used for blending

See Blend

bins(data, values=None, column=None, bin_count=None, labels=None, **kwargs)¶

Specify binning or bins to be used for column or values.

Attribute Generators¶

color(columns=None, palette=None, bin=False, **kwargs)¶

Produces a ColorAttr specification for coloring groups of data based on columns.

Parameters:	columns (str or list(str) – a column or list of columns for coloring palette (list(str) – a list of colors to use for assigning to unique values in columns. **kwargs – any keyword, arg supported by AttrSpec
Returns:	a ColorAttr object

marker(columns=None, markers=None, **kwargs)¶

Specifies detailed configuration for a marker attribute.

Parameters:	columns (list or str) – markers (list(str) – a custom list of markers. Must exist within marker_types. **kwargs – any keyword, arg supported by AttrSpec
Returns:	a MarkerAttr object

cat(columns=None, cats=None, sort=True, ascending=True, **kwargs)¶

Specifies detailed configuration for a chart attribute that uses categoricals.

Parameters:	columns (list or str) – the columns used to generate the categorical variable cats (list, optional) – overrides the values derived from columns sort (bool, optional) – whether to sort the categorical values (default=True) ascending (bool, optional) – whether to sort the categorical values (default=True) **kwargs – any keyword, arg supported by AttrSpec
Returns:	a CatAttr object

Core Classes¶

class Chart(*args, **kwargs)¶

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

__init__(*args, **kwargs)¶

add_builder(builder)¶

add_labels(dim, label)¶

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_ranges(dim, range)¶

add_renderers(builder, renderers)¶

add_scales(dim, scale)¶

add_tooltips(tooltips)¶

create_axes()¶

create_grids(xgrid=True, ygrid=True)¶

create_tools(tools)¶

Create tools if given tools=True input.

Only adds tools if given boolean and does not already have tools added to self.

get_class(view_model_name)¶

Given a __view_model__ name, returns the corresponding class object

make_axis(dim, 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

show(*args, **kwargs)¶

Deprecated in Bokeh 0.11; please use bokeh.io.show instead.

start_plot()¶

Add the axis, grids and tools

filename¶

height¶

legend¶

property type: legend:Either(Bool, Enum(‘top_left’, ‘top_center’, ‘top_right’, ‘right_center’, ‘bottom_right’, ‘bottom_center’, ‘bottom_left’, ‘left_center’, ‘center’), Tuple(Float, Float))

A location where the legend should draw itself.

notebook¶

server¶

width¶

xgrid¶

property type: xgrid:Bool

Whether to draw an x-grid.

xlabel¶

property type: xlabel:String

A label for the x-axis. (default: None)

xscale¶

property type: xscale:Either(Auto, Enum(‘linear’, ‘categorical’, ‘datetime’))

What kind of scale to use for the x-axis.

ygrid¶

property type: ygrid:Bool

Whether to draw an y-grid.

ylabel¶

property type: ylabel:String

A label for the y-axis. (default: None)

yscale¶

property type: yscale:Either(Auto, Enum(‘linear’, ‘categorical’, ‘datetime’))

What kind of scale to use for the y-axis.

class Builder(*args, **kws)¶

A prototype class to inherit each new chart Builder type.

It provides useful methods to be used by the inherited builder classes, in order to automate most of the charts creation tasks and leave the core customization to specialized builder classes. In that pattern inherited builders just need to provide the following methods:

Required:

• yield_renderers(): yields the glyphs to be rendered into the plot. Here you should call the add_glyph() method so that the builder can setup the legend for you.
• set_ranges(): setup the ranges for the glyphs. This is called after glyph creation, so you are able to inspect the comp_glyphs for their minimum and maximum values. See the create() method for more information on when this is called and how the builder provides the ranges to the containing Chart using the Chart.add_ranges() method.

Optional:

• setup(): provides an area where subclasses of builder can introspect properties, setup attributes, or change property values. This is called before process_data().
• process_data(): provides an area where subclasses of builder can manipulate the source data before renderers are created.

__init__(*args, **kws)¶

Common arguments to be used by all the inherited classes.

Parameters:	data (Accepted Charts Data Formats) – source data for the chart legend (str, bool) – the legend of your plot. The legend content is inferred from incoming input.It can be top_left, top_right, bottom_left, bottom_right. It is top_right is you set it as True.

source¶

obj

datasource object for your plot, initialized as a dummy None.

x_range¶

obj

x-associated datarange object for you plot, initialized as a dummy None.

y_range¶

obj

y-associated datarange object for you plot, initialized as a dummy None.

groups¶

list

to be filled with the incoming groups of data. Useful for legend construction.

data¶

dict

to be filled with the incoming data and be passed to the ChartDataSource for each Builder class.

attr¶

list(AttrSpec

to be filled with the new attributes created after loading the data dict.

column_selector¶

alias of OrderedAssigner

add_glyph(group, glyph)¶

Add a composite glyph.

Manages the legend, since the builder might not want all attribute types used for the legend.

Parameters:	group (DataGroup) – the data the glyph is associated with glyph (CompositeGlyph) – the glyph associated with the group
Returns:	None

collect_attr_kwargs()¶

create(chart=None)¶

Builds the renderers, adding them and other components to the chart.

Parameters:	chart (Chart, optional) – the chart that will contain the glyph renderers that the Builder produces.
Returns:	Chart

classmethod generate_help()¶

get_dim_extents()¶

Helper method to retrieve maximum extents of all the renderers.

Returns:	a dict mapping between dimension and value for x_max, y_max, x_min, y_min

get_group_kwargs(group, attrs)¶

process_data()¶

Make any global data manipulations before grouping.

It has to be implemented by any of the inherited class representing each different chart type. It is the place where we make specific calculations for each chart.

Returns:	None

set_ranges()¶

Calculate and set the x and y ranges.

It has to be implemented by any of the subclasses of builder representing each different chart type, and is called after yield_renderers().

Returns:	None

setup()¶

Perform any initial pre-processing, attribute config.

Returns:	None

yield_renderers()¶

Generator that yields the glyphs to be draw on the plot

It has to be implemented by any of the inherited class representing each different chart type.

Yields:	GlyphRenderer

attribute_columns¶

property type: attribute_columns:List(Column Name or Column String)

All columns used for specifying attributes for the Chart. The Builder will set this value on creation so that the subclasses can know the distinct set of columns that are being used to assign attributes.

attributes¶

property type: attributes:Dict(String, Instance(AttrSpec))

The attribute specs used to group data. This is a mapping between the role of the attribute spec (e.g. ‘color’) and the AttrSpec class (e.g., ColorAttr). The Builder will use this attributes property during runtime, which will consist of any attribute specs that are passed into the chart creation function (e.g., Bar), ones that are created for the user from simple input types (e.g. Bar(..., color=’red’) or Bar(..., color=<column_name>)), or lastly, the attribute spec found in the default_attributes configured for the subclass of Builder.

comp_glyph_types¶

property type: comp_glyph_types:List(Instance(CompositeGlyph))

comp_glyphs¶

property type: comp_glyphs:List(Instance(CompositeGlyph))

A list of composite glyphs, where each represents a unique subset of data. The composite glyph is a helper class that encapsulates all low level Glyph, that represent a higher level group of data. For example, the BoxGlyph is a single class that yields each GlyphRenderer needed to produce a Box on a BoxPlot. The single Box represents a full array of values that are aggregated, and is made up of multiple Rect and Segment glyphs.

default_attributes = None¶

dimensions = None¶

The dimension labels that must exist to produce the glyphs. This specifies what are the valid configurations for the chart, with the option of specifying the type of the columns. The ChartDataSource will inspect this property of your subclass of Builder and use this to fill in any required dimensions if no keyword arguments are used.

label_attributes = []¶

Used to assign columns to dimensions when no selections have been provided. The default behavior is provided by the OrderedAssigner, which assigns a single column to each dimension available in the Builder‘s dims property.

labels¶

property type: labels:List(String)

Represents the unique labels to be used for legends.

palette¶

property type: palette:List(Color)

Optional input to override the default palette used

by any color attribute.

req_dimensions = []¶

sort_dim¶

property type: sort_dim:Dict(String, Bool)

sort_legend¶

property type: sort_legend:List(Tuple(String, Bool))

List of tuples to use for sorting the legend, in order that they should be used for sorting. This sorting can be different than the sorting used for the rest of the chart. For example, you might want to sort only on the column assigned to the color attribute, or sort it descending. The order of each tuple is (Column, Ascending).

source¶

property type: source:Instance(ColumnDataSource)

tooltips¶

property type: tooltips:Either(List(Tuple(String, String)), List(String), Bool)

Tells the builder to add tooltips to the chart by either using the columns specified to the chart attributes (True), or by generating tooltips for each column specified (list(str)), or by explicit specification of the tooltips using the valid input for the HoverTool tooltips kwarg.

x_range¶

property type: x_range:Instance(Range)

xlabel¶

property type: xlabel:String

xscale¶

property type: xscale:String

y_range¶

property type: y_range:Instance(Range)

ylabel¶

property type: ylabel:String

yscale¶

property type: yscale:String

class ChartDataSource(df, dims=None, required_dims=None, selections=None, column_assigner=<class 'bokeh.charts.data_source.OrderedAssigner'>, attrs=None, **kwargs)¶

Validates, normalizes, groups, and assigns Chart attributes to groups.

Supported inputs are:

• Array-like: list, tuple, numpy.ndarray, pandas.Series

• Table-like:

  • records: list(dict)
  • columns: dict(list), pandas.DataFrame, or blaze resource

Converts inputs that could be treated as table-like data to pandas DataFrame, which is used for assigning attributes to data groups.

__init__(df, dims=None, required_dims=None, selections=None, column_assigner=<class 'bokeh.charts.data_source.OrderedAssigner'>, attrs=None, **kwargs)¶

Create a ChartDataSource.

Parameters:

df (pandas.DataFrame) – the original data source for the chart dims (List(Str) – list of valid dimensions for the chart. required_dims (List(List(Str) – list of list of valid dimensional selections for the chart. selections (Dict(dimension, List(Column) – mapping between a dimension and the column name(s) associated with it. This represents what the user selected for the current chart. column_assigner (ColumnAssigner, optional) – a reference to a ColumnAssigner class, which is used to collect dimension column assignment when keyword arguments aren’t provided. The default value is OrderedAssigner, which assumes you want to assign each column or array to each dimension of the chart in order that they are received. attrs (list(str) – list of attribute names the chart uses

__getitem__(dim)¶

Get the columns selected for the given dimension name.

e.g. dim=’x’

Returns:	the columns selected as a str or list(str). If the dimension is not in _selections, None is returned.

apply_operations()¶

Applies each data operation.

static collect_metadata(data)¶

Introspect which columns match to which types of data.

classmethod from_arrays(arrays, column_names=None, **kwargs)¶

Produce ColumnDataSource from array-like data.

Returns:	ColumnDataSource

classmethod from_data(*args, **kwargs)¶

Automatically handle all valid inputs.

Attempts to use any data that can be represented in a Table-like format, along with any generated requirements, to produce a ChartDataSource. Internally, these data types are generated, so that a pandas.DataFrame can be generated.

Identifies inputs that are array vs table like, handling them accordingly. If possible, existing column names are used, otherwise column names are generated.

Returns:	ColumnDataSource

classmethod from_dict(data, **kwargs)¶

Produce ColumnDataSource from table-like dict.

Returns:	ColumnDataSource

get_selections(selections, **kwargs)¶

Maps chart dimensions to selections and checks input requirements.

Returns:	mapping between each dimension and the selected columns. If no selection is made for a dimension, then the dimension will be associated with None.

groupby(**specs)¶

Iterable of chart attribute specifications, associated with columns.

Iterates over DataGroup, which represent the lowest level of data that is assigned to the attributes for plotting.

Yields:	a DataGroup, which contains metadata and attributes assigned to the group of data

static is_array(data)¶

Verify if data is array-like.

Returns:	bool

static is_computed(column)¶

Verify if the column provided matches to known computed columns.

Returns:	bool

static is_datetime(value)¶

Verifies that value is a valid Datetime type, or can be converted to it.

Returns:	bool

static is_list_arrays(data)¶

Verify if input data is a list of array-like data.

Returns:	bool

static is_list_dicts(data)¶

Verify if data is row-oriented, table-like data.

Returns:	bool

static is_number(value)¶

Verifies that value is a numerical type.

Returns:	bool

static is_table(data)¶

Verify if data is table-like.

Inspects the types and structure of data.

Returns:	bool

join_attrs(**attr_specs)¶

Produce new DataFrame from source data and AttrSpec provided.

Parameters:	**attr_specs (str, AttrSpec, optional) – pairs of names and attribute spec objects. This is optional and not required only if the ChartDataSource already contains references to the attribute specs.
Returns:	a new dataframe that includes a column for each of the attribute specs joined in, plus one special column called chart_index, which contains the unique items between the different attribute specs.
Return type:	pd.DataFrame

setup_derived_columns()¶

Attempt to add special case columns to the DataFrame for the builder.

stack_measures(measures, ids=None, var_name='variable', value_name='value')¶

De-pivots _data from a ‘wide’ to ‘tall’ layout.

A wide table is one where the column names represent a categorical variable and each contains only the values associated with each unique value of the categorical variable.

This method uses the pandas.melt() function with additional logic to make sure that the same data source can have multiple operations applied, and so all other columns are maintained through the stacking process.

Example

Note

This example is fairly low level and is not something the typical user should worry about. The interface for data transformations from the user perspective are the Chart Functions.

>>> data = {'a': [1, 2, 3, 4],
...         'b': [2, 3, 4, 5],
...         'month': ['jan', 'jan', 'feb', 'feb']
...         }

>>> ds = ChartDataSource.from_data(data)
>>> ds['x'] =['a', 'b'] # say we selected a and b for dimension x

We may want to combine ‘a’ and ‘b’ together. The final data would look like the following:

>>> ds.stack_measures(['c', 'd'], var_name='c_d_variable',
...                   value_name='c_d_value')
>>> ds.df
Out[35]:
      month a_b_variable  a_b_value
    0   jan            a          1
    1   jan            a          2
    2   feb            a          3
    3   feb            a          4
    4   jan            b          2
    5   jan            b          3
    6   feb            b          4
    7   feb            b          5

The transformed data will use the var_name and value_name inputs to name the columns. These derived columns can then be used as a single column to reference the values and the labels of the data. In the example, I could plot a_b_value vs month, and color by a_b_variable.

What this does for you over the pandas.melt() method is that it will apply the DataOperator for a dimension if it exists (e.g. Blend, generated by blend()), and it will try to handle the id columns for you so you don’t lose other columns with the melt transformation.

Returns:	None

attr_specs¶

columns¶

All column names associated with the data.

Returns:	List(Str)

df¶

index¶

The index for the pandas.DataFrame data source.

source¶

values¶

class DataGroup(label, data, attr_specs)¶

Contains subset of data and metadata about it.

The DataGroup contains a map from the labels of each attribute associated with an AttrSpec to the value of the attribute assigned to the DataGroup.

Note

resets the index on the input data

__init__(label, data, attr_specs)¶

Create a DataGroup for the data, with a label and associated attributes.

Parameters:	label (str) – the label for the group based on unique values of each column data (pandas.DataFrame) – the subset of data associated with the group dict (attr_specs) – mapping between attribute name and

:param the associated AttrSpec.:

__getitem__(spec_name)¶

Get the value of the AttrSpec associated with spec_name.

get_values(selection)¶

Get the data associated with the selection of columns.

Parameters:	selection (List(Str) – the column or columns selected
Returns:	pandas.DataFrame

to_dict()¶

attributes¶

source¶

The ColumnDataSource representation of the DataFrame.

class CompositeGlyph(**properties)¶

Represents a subset of data.

A collection of hetero or homogeneous glyph renderers which represent a subset of data. The purpose of the composite glyph is to abstract away the details of constructing glyphs, based on the details of a subset of data, from the grouping operations that a generalized builders must implement.

In general, the Builder operates at the full column oriented data source level, segmenting and assigning attributes from a large selection, while the composite glyphs will typically be passed an array-like structures with one or more singular attributes to apply.

Another way to explain the concept is that the Builder operates as the groupby, as in pandas, while the CompositeGlyph operates as the function used in the apply.

What is the responsibility of the Composite Glyph?

• Produce GlyphRenderers

• Apply any aggregations

• Tag the GlyphRenderers with the group label

• Apply transforms due to chart operations

  • Note: Operations require implementation of special methods

__init__(**properties)¶

__dodge__(glyphs)¶

A special method the dodge function applies to composite glyphs.

__jitter__(glyphs)¶

A special method the jitter function applies to composite glyphs.

__overlay__(glyphs)¶

A special method the overlay function applies to composite glyphs.

__stack__(glyphs)¶

A special method the stack function applies to composite glyphs.

add_chart_index(data)¶

Add identifier of the data group as a column for each row.

Parameters:	data (dict or ColumnDataSource) – can be the type of data used internally to ColumnDataSource, or a ColumnDataSource.
Returns:	returns the same type of data provided
Return type:	dict or ColumnDataSource

apply_operations()¶

build_renderers()¶

build_source()¶

classmethod glyph_properties()¶

refresh()¶

Update the GlyphRenderers.

setup()¶

Build renderers and data source and set sources on renderers.

bottom_buffer¶

property type: bottom_buffer:Float

color¶

property type: color:Color

A high level color. Some glyphs will

implement more specific color attributes for parts or specific glyphs.

data¶

df¶

fill_alpha¶

property type: fill_alpha:Float

fill_color¶

property type: fill_color:Color

glyphs¶

property type: glyphs:Dict(String, Any)

label¶

property type: label:Either(String, Dict(String, Any))

Identifies the subset of data.

left_buffer¶

property type: left_buffer:Float

line_alpha¶

property type: line_alpha:Float

line_color¶

property type: line_color:Color

A default outline color for contained

glyphs.

operations¶

property type: operations:List(Any)

A list of chart operations that can be applied to

manipulate their visual depiction.

renderers¶

property type: renderers:List(Instance(GlyphRenderer))

right_buffer¶

property type: right_buffer:Float

source¶

property type: source:Instance(ColumnDataSource)

The data source used for the contained

glyph renderers. Simple glyphs part of the composite glyph might not use the column data source.

top_buffer¶

property type: top_buffer:Float

values¶

property type: values:Either(Column(Float), Column(String))

Array-like values, which are used as the input to the composite glyph.

Most composite glyphs add their own representation of one or more values-like columns/arrays that they receive as inputs. These are compiled together for generating source, data, and df by the individual composite glyphs.

Attribute Specs¶

class AttrSpec(columns=None, df=None, iterable=None, default=None, items=None, **properties)¶

A container for assigning attributes to values and retrieving them as needed.

A special function this provides is automatically handling cases where the provided iterator is too short compared to the distinct values provided.

Once created as attr_spec, you can do attr_spec[data_label], where data_label must be a one dimensional tuple of values, representing the unique group in the data.

See the AttrSpec.setup() method for the primary way to provide an existing AttrSpec with data and column values and update all derived property values.

__init__(columns=None, df=None, iterable=None, default=None, items=None, **properties)¶

Create a lazy evaluated attribute specification.

Parameters:

columns – a list of column labels df (DataFrame) – the data source for the attribute spec. iterable – an iterable of distinct attribute values default – a value to use as the default attribute when no columns are passed items – the distinct values in columns. If items is provided as input, then the values provided are used instead of being calculated. This can be used to force a specific order for assignment. **properties – other properties to pass to parent HasProps

__getitem__(item)¶

Lookup the attribute to use for the given unique group label.

set_columns(columns)¶

Set columns property and update derived properties as needed.

setup(data=None, columns=None)¶

Set the data and update derived properties as needed.

update_data(data)¶

ascending¶

property type: ascending:Bool

A boolean flag to tell the attribute specification how to sort items if the sort property is set to True. The default setting for ascending is True.

attr_map¶

property type: attr_map:Dict(Any, Any)

Created by the attribute specification when iterable and data are available. The attr_map will include a mapping between the distinct value(s) found in columns and the attribute value that has been assigned.

attrname¶

property type: attrname:String

Name of the attribute the spec provides.

bins¶

property type: bins:Instance(Bins)

If an attribute spec is binning data, so that we can map one value in the iterable to one value in items, then this attribute will contain an instance of the Bins stat. This is used to create unique labels for each bin, which is then used for items instead of the actual unique values in columns.

columns¶

property type: columns:Either(Column Name or Column String, List(Column Name or Column String))

The label or list of column labels that correspond to the columns that will be used to find all distinct values (single column) or combination of values ( multiple columns) to then assign a unique attribute to. If not enough unique attribute values are found, then the attribute values will be cycled.

data¶

property type: data:Instance(ColumnDataSource)

default¶

property type: default:Any

The default value for the attribute, which is used if no column is assigned to the attribute for plotting. If the default value is not provided, the first value in the iterable property is used.

items¶

property type: items:Any

The attribute specification calculates this list of distinct values that are found in columns of data.

iterable¶

property type: iterable:List(Any)

series¶

sort¶

property type: sort:Bool

A boolean flag to tell the attribute specification to sort items, when it is calculated. This affects which value of iterable is assigned to each distinct value in items.

class ColorAttr(**kwargs)¶

An attribute specification for mapping unique data values to colors.

Note

Should be expanded to support more complex coloring options.

add_bin_labels(data)¶

bin¶

property type: bin:Bool

class MarkerAttr(**kwargs)¶

An attribute specification for mapping unique data values to markers.

class DashAttr(**kwargs)¶

An attribute specification for mapping unique data values to line dashes.

class CatAttr(**kwargs)¶

An attribute specification for mapping unique data values to labels.

Note

this is a special attribute specification, which is used for defining which labels are used for one aspect of a chart (grouping) vs another (stacking or legend)

get_levels(columns)¶

Provides a list of levels the attribute represents.