Tutorial 10 is awkward now that bkcharts has spun off
eldobbins opened this issue · comments
Working my way through Tutorial 10, I got a warning message saying that bkcharts is a separate API now, and "from bokeh.charts import Scatter" will be deprecated in Bokeh 1.0. Also, all the documentation for Charts seems to have been removed from the current Users Guide and References, which makes the Exercises awkward. And 2 of the links at the bottom are broken.
If appropriate, I'm willing to make a PR to transition this to the new API. Should it wait till Bokeh 1.0 is released? Is there new documentation for bkcharts?
A minor point: in the Stacked Bar example, I expected the order of the bars (colors) to be the same for every year, but they were not, even after I sorted the Dataframe. Sometimes the red bar was at the bottom, sometimes in the middle, and once on the top (screenshot attached). Is this a longstanding issue with Bar charts?
@eldobbins The new API is Holoviews. There is already a notebook for that, tho it could probably be updated and also add links more extensive HV docs and tutorials. In the short term it would be great to just remove ch10 and all references to bokeh.charts If you'd like to submit a PR to do that it would be very helpful!
HoloViews has a different philosophy than the Bokeh Charts; HoloView's structure is unfamiliar to me coming from a MATLAB background. For that reason, I don't think that Chapter 13 can be a straight-up replacement for Chapter 10. Reading Chapter 13, I got real distracted by references to "grating" and "repr", and at the end still have no idea how to do something simple like a Box plot in HoloView.
Perhaps, for the short term, I could move Chapter 10 to an Appendix, and explore examples like http://holoviews.org/gallery/demos/bokeh/bars_economic.html#bokeh-gallery-bars-economic to get a feel for the HoloView way of doing things.
@eldobbins To be clear, bkcharts is now unmaintained and unsupported. (There are only 24 hours in a day, and there is just is not anyone one to do the work, it is what it is). It has a number of problems already that may never get fixed. I explicitly don't want to steer anyone in the direction of using it and I intend to remove it from the tutorial completely of this reason. So, I would not support a PR that merely moves the bkcharts material rather than removes it entirely.
Regarding the HV materials in this tutorial: it's definitely the case that the official HV project tutorials are far more comprehensive and also start off more gently
https://github.com/ioam/scipy-2017-holoviews-tutorial
Perhaps it would be better to just link directly to those rather than trying to summarize them here.
OK. I will review that link.
Would you accept a PR that replaces the bkcharts examples in Tutorial 10 with Holoviews code? I like the idea of linking to better developed HV tutorials, but maybe there needs to be an intermediate step.
@eldobbins actually, the overhaul of categoricals was just merged, as well as the network graph work:
http://bokeh.pydata.org/en/dev/docs/user_guide/categorical.html
http://bokeh.pydata.org/en/dev/docs/user_guide/graph.html
These expose some very long-awaited features, make it much easier to create some common kinds of charts, and will certainly eventually make some things easier for the HV devs. They deserve their own treatment in a Bokeh-centric tutoriaI would say new tutorial chapters to cover these features that actually in Bokeh are what I would consider the highest priority, so I would propose:
- a detailed chapter on categoricals
- an appendix that gives a teaser overview of some great HV plots (including some code) that links to HV materials
- remove every mention of
bkcharts/bokeh.charts
What do you think?
Well, those are links to features under development, so it seems it isn't settled whether higher order charts will be routed through HoloViews or exposed through new features. I can't really help with how to document that. Whatever you guys decide is fine with me, as long as a simpler HoloViews tutorial is included if development goes that direction.
The linked dev docs are for features that will be on the next release in about two weeks. As for Bokeh or Bokeh+HV the answer is surely "both" depending on user and use case. But the Bokeh tutorial absolutely needs to cover Bokeh features like the new categorical support in the link
I guess a first useful and hopefully u controversial step would be to excise all mention of bokeh.charts everywhere. I'd suggest that would make a good separate PR to start then we could plan more next week (Im just starting a very short vacation)
As an update: I am working on a top-to-bottom revamp of the tutorial. I've deleted the current Charts chapter and will close this issue when the PR is merged
Actually I am just going to close this now so I don't have to remember to do it later. The new materials will be merged slightly before the next release
For reference this will be the outline
