Add an example using CategoricalColorMapper and Legend

[birdsarah]

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)

[bryevdv]

@birdsarah where should this go? Styling Visual Attributes ?

[bryevdv]

This example is already in

http://bokeh.pydata.org/en/latest/docs/user_guide/annotations.html#legends

[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

[mrocklin]

I agree with the @mficek 's assessment here. This is a useful example of a topic that doesn't seem well covered in docs.

[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]

[flutefreak7]

For those who end up here from using old examples or by some mistake of Google - go see the docs: https://bokeh.pydata.org/en/latest/docs/user_guide/categorical.html. This stuff has gotten much easier to use now.

[atrabattoni]

Still not finding an example in the documentation that explain how to get categorical coloring without specifing a color field. From the documentation it's impossible to guess how to use CategoricalColorMapper.

[bryevdv]

@atrabattoni narrative documentation on client side color mapping is here:

https://docs.bokeh.org/en/latest/docs/user_guide/basic/data.html#client-side-color-mapping

Generally speaking, these days you'd probably use the higher level factor_cmap (shown in a few examples in that section) rather then the CategorticalColorMapper directly.

There are also lots of examples that use factor_cmap in the examples directory that you can refer to:

https://github.com/search?q=repo%3Abokeh%2Fbokeh+factor_cmap+path%3A%2F%5Eexamples%5C%2F%2F&type=code

Many of these are also in the docs, e.g. especially in the "Bars" section:

https://docs.bokeh.org/en/latest/docs/user_guide/basic/bars.html

Or if you are asking about legend grouping (it's not really clear at all), then that is documented in two subsections here:

https://docs.bokeh.org/en/latest/docs/user_guide/basic/annotations.html#legends

Unfortunately, I am not at all sure what "how to get categorical coloring without specifing a color field" means? color mappers are generally always applied to a glyph's various color properties, that is their intended purpose. It's not really clear what it is you are expecting to be able to do. However, I would ask that you migrate that usage question to the Discourse:

https://discourse.bokeh.org/

rather than continuing here. The Discourse is a better place to sort out your usage questions. Please provide more details, e.g. a more thorough description of what you are trying to accomplish and especially a (minimal) complete example code for what you are trying, that is not working the way you expect.

[atrabattoni]

Thank you for this detailed answer.

Indeed I completely misunderstood that CategorticalColorMapper but also LinearColorMapper, LogColorMapper, etc. are low-level class that the user should not use directly.

In particular, I think that the Annotations section is quite misleading. This example does not seem best practice (creating a color field that is just a mapping of another one). Also LogColorMapper is used here.

I was expecting finding some information in the Categorical plots section. Now that I read it again the solution was hidden in the Heatmaps subsection but this later is partially up to date. Indeed LinearColorMapper is mentionned in the body text whereas linear_cmap and factor_cmap are used in the source code.

So after I saw several examples of usage of LinearColorMapper and LogColorMapper (in the docs and on StackOverflow), I landed in the mappers section and discovered this CategoricalColorMapper which is poorly documented (now I understand why). Also keyword search with "Categorical" "Mapper" "Plot" did not lead me to the Data sources section that indeed contain a lot of useful information.

I'll use more the Discourse next time.