Add a variant of ridgeplot example that uses sub-coordinates

[mattpap]

Keeps the original look, but allows to preserve actual data (see data (x, y) in the tooltip).

[bryevdv]

This is great, but there is a little more updating required. This example is also used here:

https://docs.bokeh.org/en/latest/docs/user_guide/categorical.html#categorical-offsets

as a demonstration of categorical offsets. We shouldn't use the same example in two different ways in different places. (If we want to compare/contrast methods it should be explicit and side by side) cc @tcmetzger for thoughts on how to organize. Some comments:

• we still need to document categorical offsets somewhere
• we should probably make sub-coordinates be the default way to do "series of data per category"
• there may be other examples that use offsets for series that could be updated

[tcmetzger]

That's a good point! I agree that we shouldn't use something that looks the same to illustrate two different concepts in two different places. I see basically the following options:

• we create a new and different example to illustrate categorical offsets in https://docs.bokeh.org/en/latest/docs/user_guide/categorical.html#categorical-offsets
• we find a way to make examples/plotting/file/ridgeplot.py use categorical offsets and thus be a valid example again for the 'categorical offsets' section in the user guide.

It sounds to me like using sub-coordinates is now the definitive way to go for ridge plots, so that means we should probably look at option one: creating a new example to serve as an illustration of categorical offsets. Do you have any ideas what that could be? If not, we can also just leave it at one example (the current fruit count example) in the user guide's 'categorical offsets' section and just not have a "more sophisticated example".

[codecov]

Codecov Report

Merging #12068 (143c75b) into branch-3.3 (7cd6b36) will not change coverage.
The diff coverage is n/a.

@@             Coverage Diff             @@
##           branch-3.3   #12068   +/-   ##
===========================================
  Coverage       92.45%   92.45%           
===========================================
  Files             317      317           
  Lines           20268    20268           
===========================================
  Hits            18738    18738           
  Misses           1530     1530           

[mattpap]

I took a different approach with this. I added a new category to examples/topics: subcoordinates, where I added a variant of ridgeplot.py that uses sub-coordinates. Whereas I reverted changes to examples/topics/categorical, while updating descriptions. This allows ridgeplot to be used for showing and comparing both approaches. I will continue in PR #13346, where I will add more examples and add documentation for sub-coordinates and update documentation for categoricals (pointing to sub-coordinates and explaining differences between both).

[bryevdv]

@mattpap There is intended to be a 1-1 correspondence between examples/topics/foo directories, and subchapters under the Topics chapter of the user's guide. Do you actually envision an entire subchapter for this? If there aren't at least 3-4 subheadings and examples to flesh out a sub-chapter then it would be better to find an existing diretory corresponding to and existing chapter to add it to. Or of you don't want it to be in the User's guide, then it can go in one of the "grab bag" examples dirs that don't correspond to the docs hierarchy e.g. examples/models or examples/plotting

Edit: Here is the current chapter/subchapter hierarchy with the top level directories noted:

Basic plotting # examples/basic

• Scatter plots
• Lines and curves
• Data sources
• Ranges and axes
• Bar charts
• Area glyphs
• Grids and layouts
• Annotations

Appearance # examples/styling

• General visual properties
• Styling plot elements
• Mathematical notation
• Themes
• Styling DOM elements

Topic guides # examples/topics

• Images and raster data
• Contour plots
• Hex tiles
• Categorical plots
• Hierarchical data
• Geographical data
• Network graphs
• Timeseries plots
• Pie and donut charts
• Statistical plots

I could imaging Basic Plotting -> Sub-coordinates as making sense, or it could potentially go under Appearance if we wanted to broaden the scope of that chapter (cc @tcmetzger) but if you want to punt on this for now just move it to one of the grab-bag dirs and open an issue to discuss future docs work around it.

[bryevdv]

@mattpap for expediency I think the simplest thing to do is to move the example to examples/plotting for now, to get this merged, and open an issue for future docs work. As you mention this really merits a full discussion/comparison so we'll just need to figure out the best place to land that.

[bryevdv]

Just a couple of wording suggestions