Add an example using CategoricalColorMapper and Legend

e.g.

from bokeh.io import show
from bokeh.models import ColumnDataSource, CategoricalColorMapper
from bokeh.palettes import RdBu3
from bokeh.plotting import figure

source = ColumnDataSource(dict(
    x=[1, 2, 3, 4, 5, 6],
    y=[2, 1, 2, 1, 2, 1],
    label=['hi', 'lo', 'hi', 'lo', 'hi', 'lo']
))
color_mapper = CategoricalColorMapper(factors=['hi', 'lo'], palette=[RdBu3[2], RdBu3[0]])

p = figure(x_range=(0, 7), y_range=(0, 3), height=300, tools='save')
p.circle(
    x='x', y='y', radius=0.5, source=source,
    color={'field': 'label', 'transform': color_mapper},
    legend='label'
)
show(p)

[mficek]

I think this a very nice example, actually. I was looking for CategorialColorMapper and found its usage only here. I think the documentation would benefit from such example. The referenced page (legends) shows only a variant of this and it is not as elegant as the one from @birdsarah

[rsgoodwin]

I also agree with @mficek. The example here uses CategorialColorMapper to bind a categorical variable, instead of explicitly calling out the color in the ColumnDataSource in the user_guide example.

I would also add, that in explorative data analysis, we often don’t know the number of unique levels in a categorical variable “before” we want to plot it.

So an even more powerful example would include 1) Counting the number of unique levels. 2) Picking an appropriate categorical pallet with matching number colors.

If the number of levels is, say, greater then the unique colors in the chosen palette, then recycle the colors starting at [0]