Bokeh 'User Research' Feedback

Hi All!
I’m a (python data stack) data scientist with a predilection towards data viz. I’ve recently taken a bit of a sojourn into Bokeh-land. I’ve found Bokeh to be an incredibly powerful library with a ton of cool features, but I also ran in to a number of pain points which ultimately led me to elect not to use Bokeh for my work at this time (though I’m still tinkering with it on the side). I just wanted to document some of the issues I encountered at a high level to provide some ‘user research’, if you will, that may be instructive for the team as you move towards v1.0. I’m mostly documenting pain points here, but I really do think Bokeh is an awesome library with great potential – I don’t mean at all to be critical, I just want to provide feedback in case it proves useful (caveating all this with: I know you are short-handed and doing the best you can with limited resources!).
At a super high level, the main problems I ran into were:
(1) Documentation
(2) Interactivity
(1) Documentation:
To me this is really the only thing that is a must-fix before v1.0, and really the only thing that would prevent extremely widespread adoption of Bokeh. The current state of the documentation is a serious blocker for non-engineers trying to work with Bokeh. The single biggest problem is the **KWARGS! problem. Put simply, while using a jupyter notebook attempts to quickly view documentation using the shift-tab notebook feature (or %psource, ‘?’, etc) are futile. Most functions and class instances merely note that they take args and kwargs, and don’t provide relevant options and customizations that a user would be looking for.
The ‘give a list of valid options when user enters an invalid option’ feature is genuinely brilliant, but it is not a substitute for quick, easy, access to full-bodied readme docs. Unfortunately the API reference on the site often falls prey to the same issue, and even when it doesn’t the available options are often undocumented, or sparsely documented. Compared to the docs for, say, seaborn, which provide full options, extensive details, and extensive examples right on the same page, Bokeh lags. This is critical for quick iteration in the data analytics world. In seaborn I can fix a syntax problem very quickly by consulting the site or shift-tabbing. In Bokeh often times I had to abandon such efforts after 30 minutes of searching with no answer. Improving the API references and the, related, readme references, are from a user experience side the highest priority open tasks for Bokeh. I honestly feel documentation improvements are more valuable than any plausible feature that could be added before v1.
The user guide is a valuable supplement, but it is much harder to diagnose a problem with command XYZ by going to the user guide than by knowing which command to look up for examples in the API reference or, even better, with a simple shift-tab (or %psource, etc) in notebook. The demos are likewise awesome, but have a similar concern. Also, many things are available in github examples only and not online, which is a minor annoyance. The user guide and examples also fall short in the area I would say is by far Bokehs core competency, interactivity.
(2) Interactivity

I was drawn to Bokeh by the powerful (and hopefully simple!) interactive elements. In particular, ability to use widgets to control plots in an interactive manner in static html. Jupyter widgets already make it super easy to get chart interactivity, but this is harder to port to static webpage contexts. I don’t really have any background in JS, and I found it very difficult to navigate the docs for adding interactivity in a static html context. The from_pyfunc() function proved too limited, which is understandable, but richer docs (with explanations) for CustomJS would be helpful.

Bokeh server certainly has a ton of value for certain solutions, but most of the time a light weight solution is vastly preferable. Where the server really shines is in the potential to have the extremely elusive ‘shiny for python’ type dashboard experience. This experience includes Bokeh server but would also include pre-built infrastructure to easily add ready-made sidebars, filters, formatting options, etc. as Shiny provides. These are all doable with Bokeh, certainly, but a dashboarding solution would make them simple and painless. At least in the data science part of the world this is where Bokeh server shines, and I’d love to see Bokeh server target this use case, which is a HUGE open need in the #pydata stack. For someone with absolutely no background in software engineering setting up an internal-network-facing dashboard application served by Bokeh server is currently a dream, contrasted with Shiny.

To this one user’s eyes Bokeh has a clear fit in the #pydata stack, and that fit is in (1) making it easy to publish interactive, widget driven visualizations that function in static html, and (2) providing the first genuinely viable counterpart to shiny for python. Libraries like seaborn will always be better for exploratory, quick visualizations, and that is totally ok. Bokeh has a huge opportunity space, and I feel it is well poised to fill that space. I think focusing in those areas will provide the easiest wins, compared to trying to reinvent the billion things one can already do in matplotlib. Focusing on interactivity and dashboarding solutions will, to my eyes, facilitate the broadest Bokeh adoption.

I really love what I’ve seen out of Bokeh so far, and I hope this user research proves somewhat helpful. I know there are many limitations on the time of all Bokeh developers and I stress again that none of this is intended to be critical in any way. I would be happy to follow up and discuss my experiences more insofar as that would be valuable.

Best,
Stu

Hi Stu,

Thanks so much for tak ing
the time to write this down. I know Bryan and I, at
least, appreciate tha t you took the time to
caveat your critique and highlight it as a good faith attempt to provide
constructive feedback.

Documentation. I think your
critique is
valid and
suggestions great. W hether we
can achieve it is a nother
matter, but I think the se are
good thoughts and I ,
for one, will be kee ping
them in mind as we
plan toward s 1.0. Just to
highlight your point.
I’m a core bokeh developer and have been for 18 month s and
just last week
I asked
my team mates
about an
undocumented kwarg
that I needed but had forgotten about…so it’s definitely not just you , and I appreciate
you explaining
your work
patterns and how you want to look things up.

Interactivity. My reading of
your feedback is that ~80% of it could be
solved if we
had great docs , more examples,
and a r ich
online
examples/gallery
set. I have had many ideas along
these lines
and, again,
it’s great to
hear you articulatin g this
all
specifically.
I also hear
you on the
dashboard stuff, although I
think it’s probably a lower priority than great documentation.

Thanks again for taking the time.

                                                      It's

much
appreciated.

Sincerely,

S arah
Bird

···

On 11/2/16 1:13 PM,
wrote:

[email protected]

Hi All!

    I'm a (python data stack) data scientist with a predilection

towards data viz. I’ve recently taken a bit of a sojourn into
Bokeh-land. I’ve found Bokeh to be an incredibly powerful
library with a ton of cool features, but I also ran in to a
number of pain points which ultimately led me to elect not to
use Bokeh for my work at this time (though I’m still tinkering
with it on the side). I just wanted to document some of the
issues I encountered at a high level to provide some ‘user
research’, if you will, that may be instructive for the team as
you move towards v1.0. I’m mostly documenting pain points here,
but I really do think Bokeh is an awesome library with great
potential – I don’t mean at all to be critical, I just want to
provide feedback in case it proves useful (caveating all this
with: I know you are short-handed and doing the best you can
with limited resources!).

    At a super high level, the main problems I ran into were:
    (1) Documentation
    (2) Interactivity

    **(1) Documentation:**

    To me this is really the only thing that is a must-fix before

v1.0, and really the only thing that would prevent extremely
widespread adoption of Bokeh. The current state of the
documentation is a serious blocker for non-engineers trying to
work with Bokeh. The single biggest problem is the **KWARGS!
problem. Put simply, while using a jupyter notebook attempts to
quickly view documentation using the shift-tab notebook feature
(or %psource, ‘?’, etc) are futile. Most functions and class
instances merely note that they take args and kwargs, and don’t
provide relevant options and customizations that a user would be
looking for.

    The 'give a list of valid options when user enters an invalid

option’ feature is genuinely brilliant, but it is not a
substitute for quick, easy, access to full-bodied readme docs.
Unfortunately the API reference on the site often falls prey to
the same issue, and even when it doesn’t the available options
are often undocumented, or sparsely documented. Compared to the
docs for, say, seaborn, which provide full options, extensive
details, and extensive examples right on the same page, Bokeh
lags. This is critical for quick iteration in the data analytics
world. In seaborn I can fix a syntax problem very quickly by
consulting the site or shift-tabbing. In Bokeh often times I had
to abandon such efforts after 30 minutes of searching with no
answer. Improving the API references and the, related, readme
references, are from a user experience side the highest priority
open tasks for Bokeh. I honestly feel documentation improvements
are more valuable than any plausible feature that could be added
before v1.

    The user guide is a valuable supplement, but it is much harder

to diagnose a problem with command XYZ by going to the user
guide than by knowing which command to look up for examples in
the API reference or, even better, with a simple shift-tab (or
%psource, etc) in notebook. The demos are likewise awesome, but
have a similar concern. Also, many things are available in
github examples only and not online, which is a minor annoyance.
The user guide and examples also fall short in the area I would
say is by far Bokehs core competency, interactivity.

    **(2) Interactivity**



    I was drawn to Bokeh by the powerful (and hopefully simple!)

interactive elements. In particular, ability to use widgets to
control plots in an interactive manner in static html. Jupyter
widgets already make it super easy to get chart interactivity,
but this is harder to port to static webpage contexts. I don’t
really have any background in JS, and I found it very difficult
to navigate the docs for adding interactivity in a static html
context. The from_pyfunc() function proved too limited, which is
understandable, but richer docs (with explanations) for CustomJS
would be helpful.

    Bokeh server certainly has a ton of value for certain solutions,

but most of the time a light weight solution is vastly
preferable. Where the server really shines is in the potential
to have the extremely elusive ‘shiny for python’ type dashboard
experience. This experience includes Bokeh server but would also
include pre-built infrastructure to easily add ready-made
sidebars, filters, formatting options, etc. as Shiny provides.
These are all doable with Bokeh, certainly, but a dashboarding
solution would make them simple and painless. At least in the
data science part of the world this is where Bokeh server
shines, and I’d love to see Bokeh server target this use case,
which is a HUGE open need in the #pydata stack. For someone with
absolutely no background in software engineering setting up an
internal-network-facing dashboard application served by Bokeh
server is currently a dream, contrasted with Shiny.

    To this one user's eyes Bokeh has a clear fit in the #pydata

stack, and that fit is in (1) making it easy to publish
interactive, widget driven visualizations that function in
static html, and (2) providing the first genuinely viable
counterpart to shiny for python. Libraries like seaborn will
always be better for exploratory, quick visualizations, and that
is totally ok. Bokeh has a huge opportunity space, and I feel it
is well poised to fill that space. I think focusing in those
areas will provide the easiest wins, compared to trying to
reinvent the billion things one can already do in matplotlib.
Focusing on interactivity and dashboarding solutions will, to my
eyes, facilitate the broadest Bokeh adoption.

    I really love what I've seen out of Bokeh so far, and I hope

this user research proves somewhat helpful. I know there are
many limitations on the time of all Bokeh developers and I
stress again that none of this is intended to be critical in any
way. I would be happy to follow up and discuss my experiences
more insofar as that would be valuable.

    Best,

    Stu

  You received this message because you are subscribed to the Google

Groups “Bokeh Discussion - Public” group.

  To unsubscribe from this group and stop receiving emails from it,

send an email to [email protected].

  To post to this group, send email to [email protected]

  To view this discussion on the web visit [https://groups.google.com/a/continuum.io/d/msgid/bokeh/c0c9f871-d6ea-4dbd-9aec-4c96bb5858ff%40continuum.io](https://groups.google.com/a/continuum.io/d/msgid/bokeh/c0c9f871-d6ea-4dbd-9aec-4c96bb5858ff%40continuum.io?utm_medium=email&utm_source=footer).

  For more options, visit [https://groups.google.com/a/continuum.io/d/optout](https://groups.google.com/a/continuum.io/d/optout).


Sarah Bird
Developer, Bokeh

    [
      ![Continuum Analytics](http://docs.continuum.io/_static/img/ContinuumWordmark.png)
    ](http://continuum.io)

Thank you so so much for this feedback, Stu!​ We really appreciate it, and as Sarah said, we’re actively working hard to address some of this pain. Your detailed and thoughtful writeup helps provide additional color on that work and its prioritization.

-Peter

Hi,

As it happens, I just merged a large PR to clean up and extend our automated documentation generation in ways that coincide with these suggestions:

  • all script examples can have a ReST docstring that can exmplain, add context, or add entries in into indicies and cross references

  • fix some problems limiting the kinds of examples that can easily go in the gallery

So, now’s the task of writing all those many ReST docsrings, and adding the remaining GH examples to the gallery…

Regarding the notebook, this kind of feedback is valuable, because to perfectly frank, I am not any sort of regular notebook user at all. Making the Bokeh notebook experience better will definitely require input (and hopefully direct help) from heavy notebook users.

In particular, I am not sure I understand all of your suggestions. Can you expand on them (or possibly even make a screencast of your usual workflow available)? Many Bokeh models have many dozens of properties that can be set. Are you saying you would like to see all of them and their descriptions in a singe (pages long) docstring? It seems like there might be other notebook-specific “help modes” I just don’t know anything about. Again, a screencast of some sort would be a valuable demonstration.

Finally, in case it helps, two pieces of information that perhaps have not been communicated as well as they could:

  • There is basically a 1-1 correspondence between kwargs and a model’s properties. That is

    hover = HoverTool(tooltips=[…])

is really just an alternative way of writing:

hover = HoverTool()

hover.tooltips = []

This is consistent all throughout every Bokeh model. I find and keeping this in mind is always helpful to my mental picture.

The other bit of information is:

  • Notebook tab completion and ? should work for all model’s properties. I’ve attached a few screenshots below.

Hopefully these two bits of information taken together, might offer some immediate relief, if I have understood your concerns. With some more input, we can try to make additional improvements as well.

Thanks,

Bryan

···

On Nov 2, 2016, at 1:13 PM, [email protected] wrote:

Hi All!

I’m a (python data stack) data scientist with a predilection towards data viz. I’ve recently taken a bit of a sojourn into Bokeh-land. I’ve found Bokeh to be an incredibly powerful library with a ton of cool features, but I also ran in to a number of pain points which ultimately led me to elect not to use Bokeh for my work at this time (though I’m still tinkering with it on the side). I just wanted to document some of the issues I encountered at a high level to provide some ‘user research’, if you will, that may be instructive for the team as you move towards v1.0. I’m mostly documenting pain points here, but I really do think Bokeh is an awesome library with great potential – I don’t mean at all to be critical, I just want to provide feedback in case it proves useful (caveating all this with: I know you are short-handed and doing the best you can with limited resources!).

At a super high level, the main problems I ran into were:
(1) Documentation
(2) Interactivity

(1) Documentation:

To me this is really the only thing that is a must-fix before v1.0, and really the only thing that would prevent extremely widespread adoption of Bokeh. The current state of the documentation is a serious blocker for non-engineers trying to work with Bokeh. The single biggest problem is the **KWARGS! problem. Put simply, while using a jupyter notebook attempts to quickly view documentation using the shift-tab notebook feature (or %psource, ‘?’, etc) are futile. Most functions and class instances merely note that they take args and kwargs, and don’t provide relevant options and customizations that a user would be looking for.

The ‘give a list of valid options when user enters an invalid option’ feature is genuinely brilliant, but it is not a substitute for quick, easy, access to full-bodied readme docs. Unfortunately the API reference on the site often falls prey to the same issue, and even when it doesn’t the available options are often undocumented, or sparsely documented. Compared to the docs for, say, seaborn, which provide full options, extensive details, and extensive examples right on the same page, Bokeh lags. This is critical for quick iteration in the data analytics world. In seaborn I can fix a syntax problem very quickly by consulting the site or shift-tabbing. In Bokeh often times I had to abandon such efforts after 30 minutes of searching with no answer. Improving the API references and the, related, readme references, are from a user experience side the highest priority open tasks for Bokeh. I honestly feel documentation improvements are more valuable than any plausible feature that could be added before v1.

The user guide is a valuable supplement, but it is much harder to diagnose a problem with command XYZ by going to the user guide than by knowing which command to look up for examples in the API reference or, even better, with a simple shift-tab (or %psource, etc) in notebook. The demos are likewise awesome, but have a similar concern. Also, many things are available in github examples only and not online, which is a minor annoyance. The user guide and examples also fall short in the area I would say is by far Bokehs core competency, interactivity.

(2) Interactivity

I was drawn to Bokeh by the powerful (and hopefully simple!) interactive elements. In particular, ability to use widgets to control plots in an interactive manner in static html. Jupyter widgets already make it super easy to get chart interactivity, but this is harder to port to static webpage contexts. I don’t really have any background in JS, and I found it very difficult to navigate the docs for adding interactivity in a static html context. The from_pyfunc() function proved too limited, which is understandable, but richer docs (with explanations) for CustomJS would be helpful.

Bokeh server certainly has a ton of value for certain solutions, but most of the time a light weight solution is vastly preferable. Where the server really shines is in the potential to have the extremely elusive ‘shiny for python’ type dashboard experience. This experience includes Bokeh server but would also include pre-built infrastructure to easily add ready-made sidebars, filters, formatting options, etc. as Shiny provides. These are all doable with Bokeh, certainly, but a dashboarding solution would make them simple and painless. At least in the data science part of the world this is where Bokeh server shines, and I’d love to see Bokeh server target this use case, which is a HUGE open need in the #pydata stack. For someone with absolutely no background in software engineering setting up an internal-network-facing dashboard application served by Bokeh server is currently a dream, contrasted with Shiny.

To this one user’s eyes Bokeh has a clear fit in the #pydata stack, and that fit is in (1) making it easy to publish interactive, widget driven visualizations that function in static html, and (2) providing the first genuinely viable counterpart to shiny for python. Libraries like seaborn will always be better for exploratory, quick visualizations, and that is totally ok. Bokeh has a huge opportunity space, and I feel it is well poised to fill that space. I think focusing in those areas will provide the easiest wins, compared to trying to reinvent the billion things one can already do in matplotlib. Focusing on interactivity and dashboarding solutions will, to my eyes, facilitate the broadest Bokeh adoption.

I really love what I’ve seen out of Bokeh so far, and I hope this user research proves somewhat helpful. I know there are many limitations on the time of all Bokeh developers and I stress again that none of this is intended to be critical in any way. I would be happy to follow up and discuss my experiences more insofar as that would be valuable.

Best,
Stu


You received this message because you are subscribed to the Google Groups “Bokeh Discussion - Public” group.
To unsubscribe from this group and stop receiving emails from it, send an email to [email protected].
To post to this group, send email to [email protected].
To view this discussion on the web visit https://groups.google.com/a/continuum.io/d/msgid/bokeh/c0c9f871-d6ea-4dbd-9aec-4c96bb5858ff%40continuum.io.
For more options, visit https://groups.google.com/a/continuum.io/d/optout.

Though, looking now at my own second screenshot, I am not sure where that help string is coming from. That is *NOT* the helpstring associated with the "major_label_orientation" property, so something odd and previously unknown is going on...

Bryan

···

On Nov 2, 2016, at 5:57 PM, Bryan Van de Ven <[email protected]> wrote:

Hi,

As it happens, I just merged a large PR to clean up and extend our automated documentation generation in ways that coincide with these suggestions:

* all script examples can have a ReST docstring that can exmplain, add context, or add entries in into indicies and cross references

* fix some problems limiting the kinds of examples that can easily go in the gallery

So, now's the task of writing all those many ReST docsrings, and adding the remaining GH examples to the gallery....

Regarding the notebook, this kind of feedback is valuable, because to perfectly frank, I am not any sort of regular notebook user at all. Making the Bokeh notebook experience better will definitely require input (and hopefully direct help) from heavy notebook users.

In particular, I am not sure I understand all of your suggestions. Can you expand on them (or possibly even make a screencast of your usual workflow available)? Many Bokeh models have many dozens of properties that can be set. Are you saying you would like to see all of them and their descriptions in a singe (pages long) docstring? It seems like there might be other notebook-specific "help modes" I just don't know anything about. Again, a screencast of some sort would be a valuable demonstration.

Finally, in case it helps, two pieces of information that perhaps have not been communicated as well as they could:

* There is basically a 1-1 correspondence between kwargs and a model's properties. That is

  hover = HoverTool(tooltips=[...])

is really just an alternative way of writing:

   hover = HoverTool()
  hover.tooltips =

This is consistent all throughout every Bokeh model. I find and keeping this in mind is always helpful to my mental picture.

The other bit of information is:

* Notebook tab completion and ? should work for all model's properties. I've attached a few screenshots below.

Hopefully these two bits of information taken together, might offer some immediate relief, if I have understood your concerns. With some more input, we can try to make additional improvements as well.

Thanks,

Bryan

<Screen Shot 2016-11-02 at 5.52.45 PM.png>

<Screen Shot 2016-11-02 at 5.52.58 PM.png>

On Nov 2, 2016, at 1:13 PM, [email protected] wrote:

Hi All!

I'm a (python data stack) data scientist with a predilection towards data viz. I've recently taken a bit of a sojourn into Bokeh-land. I've found Bokeh to be an incredibly powerful library with a ton of cool features, but I also ran in to a number of pain points which ultimately led me to elect not to use Bokeh for my work at this time (though I'm still tinkering with it on the side). I just wanted to document some of the issues I encountered at a high level to provide some 'user research', if you will, that may be instructive for the team as you move towards v1.0. I'm mostly documenting pain points here, but I really do think Bokeh is an awesome library with great potential -- I don't mean at all to be critical, I just want to provide feedback in case it proves useful (caveating all this with: I know you are short-handed and doing the best you can with limited resources!).

At a super high level, the main problems I ran into were:
(1) Documentation
(2) Interactivity

(1) Documentation:

To me this is really the only thing that is a must-fix before v1.0, and really the only thing that would prevent extremely widespread adoption of Bokeh. The current state of the documentation is a serious blocker for non-engineers trying to work with Bokeh. The single biggest problem is the **KWARGS! problem. Put simply, while using a jupyter notebook attempts to quickly view documentation using the shift-tab notebook feature (or %psource, '?', etc) are futile. Most functions and class instances merely note that they take args and kwargs, and don't provide relevant options and customizations that a user would be looking for.

The 'give a list of valid options when user enters an invalid option' feature is genuinely brilliant, but it is not a substitute for quick, easy, access to full-bodied readme docs. Unfortunately the API reference on the site often falls prey to the same issue, and even when it doesn't the available options are often undocumented, or sparsely documented. Compared to the docs for, say, seaborn, which provide full options, extensive details, and extensive examples right on the same page, Bokeh lags. This is critical for quick iteration in the data analytics world. In seaborn I can fix a syntax problem very quickly by consulting the site or shift-tabbing. In Bokeh often times I had to abandon such efforts after 30 minutes of searching with no answer. Improving the API references and the, related, readme references, are from a user experience side the highest priority open tasks for Bokeh. I honestly feel documentation improvements are more valuable than any plausible feature that could be added before v1.

The user guide is a valuable supplement, but it is much harder to diagnose a problem with command XYZ by going to the user guide than by knowing which command to look up for examples in the API reference or, even better, with a simple shift-tab (or %psource, etc) in notebook. The demos are likewise awesome, but have a similar concern. Also, many things are available in github examples only and not online, which is a minor annoyance. The user guide and examples also fall short in the area I would say is by far Bokehs core competency, interactivity.

(2) Interactivity

I was drawn to Bokeh by the powerful (and hopefully simple!) interactive elements. In particular, ability to use widgets to control plots in an interactive manner *in static html*. Jupyter widgets already make it super easy to get chart interactivity, but this is harder to port to static webpage contexts. I don't really have any background in JS, and I found it very difficult to navigate the docs for adding interactivity in a static html context. The from_pyfunc() function proved too limited, which is understandable, but richer docs (with explanations) for CustomJS would be helpful.

Bokeh server certainly has a ton of value for certain solutions, but most of the time a light weight solution is vastly preferable. Where the server really shines is in the potential to have the extremely elusive 'shiny for python' type dashboard experience. This experience includes Bokeh server but would also include pre-built infrastructure to easily add ready-made sidebars, filters, formatting options, etc. as Shiny provides. These are all doable with Bokeh, certainly, but a dashboarding solution would make them simple and painless. At least in the data science part of the world this is where Bokeh server shines, and I'd love to see Bokeh server target this use case, which is a HUGE open need in the #pydata stack. For someone with absolutely no background in software engineering setting up an internal-network-facing dashboard application served by Bokeh server is currently a dream, contrasted with Shiny.

To this one user's eyes Bokeh has a clear fit in the #pydata stack, and that fit is in (1) making it easy to publish interactive, widget driven visualizations that function in static html, and (2) providing the first genuinely viable counterpart to shiny for python. Libraries like seaborn will always be better for exploratory, quick visualizations, and that is totally ok. Bokeh has a huge opportunity space, and I feel it is well poised to fill that space. I think focusing in those areas will provide the easiest wins, compared to trying to reinvent the billion things one can already do in matplotlib. Focusing on interactivity and dashboarding solutions will, to my eyes, facilitate the broadest Bokeh adoption.

I really love what I've seen out of Bokeh so far, and I hope this user research proves somewhat helpful. I know there are many limitations on the time of all Bokeh developers and I stress again that none of this is intended to be critical in any way. I would be happy to follow up and discuss my experiences more insofar as that would be valuable.

Best,
Stu

--
You received this message because you are subscribed to the Google Groups "Bokeh Discussion - Public" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [email protected].
To post to this group, send email to [email protected].
To view this discussion on the web visit https://groups.google.com/a/continuum.io/d/msgid/bokeh/c0c9f871-d6ea-4dbd-9aec-4c96bb5858ff%40continuum.io.
For more options, visit https://groups.google.com/a/continuum.io/d/optout.

Well, a quick update about this particular issue. Unfortunately, I believe there is no technical path to make, e.g.

  axis.major_label_orientation?

work in general. The only hook for customization that Jupyter provides is to look for a .getdoc method on the inspected value. I had thought it possible to create a value-based wrapper subclass on the fly that would supply this .getdoc method, and this seemed to initially be successful (tho I had potential concerns about performance). But quickly ran into a serious problem: many of the property values are None, and python itself absolutely will not allow subclassing NoneType, which means those values cannot be wrapped to provide .getdoc, which means model.property? cannot be made to return anything better than it currently does, in general.

All that said, I think your main interest is actually elsewhere, in better docstrings for the models, and in particular that list all the available properties. That would be easy enough to do in an automated fashion, but then I think you would end up with some docstrings that are hundreds or thousands of lines long. Is that actually an improvement? Maybe short hand-written docstrings, with a link to the corresponding reference guide section (which would have all the individual properties) would be more useful than pages and pages of automatically generated text?

Feedback around these questions is definitely appreciated,

Bryan

···

On Nov 2, 2016, at 5:59 PM, Bryan Van de Ven <[email protected]> wrote:

Though, looking now at my own second screenshot, I am not sure where that help string is coming from. That is *NOT* the helpstring associated with the "major_label_orientation" property, so something odd and previously unknown is going on...

Bryan

On Nov 2, 2016, at 5:57 PM, Bryan Van de Ven <[email protected]> wrote:

Hi,

As it happens, I just merged a large PR to clean up and extend our automated documentation generation in ways that coincide with these suggestions:

* all script examples can have a ReST docstring that can exmplain, add context, or add entries in into indicies and cross references

* fix some problems limiting the kinds of examples that can easily go in the gallery

So, now's the task of writing all those many ReST docsrings, and adding the remaining GH examples to the gallery....

Regarding the notebook, this kind of feedback is valuable, because to perfectly frank, I am not any sort of regular notebook user at all. Making the Bokeh notebook experience better will definitely require input (and hopefully direct help) from heavy notebook users.

In particular, I am not sure I understand all of your suggestions. Can you expand on them (or possibly even make a screencast of your usual workflow available)? Many Bokeh models have many dozens of properties that can be set. Are you saying you would like to see all of them and their descriptions in a singe (pages long) docstring? It seems like there might be other notebook-specific "help modes" I just don't know anything about. Again, a screencast of some sort would be a valuable demonstration.

Finally, in case it helps, two pieces of information that perhaps have not been communicated as well as they could:

* There is basically a 1-1 correspondence between kwargs and a model's properties. That is

  hover = HoverTool(tooltips=[...])

is really just an alternative way of writing:

  hover = HoverTool()
  hover.tooltips =

This is consistent all throughout every Bokeh model. I find and keeping this in mind is always helpful to my mental picture.

The other bit of information is:

* Notebook tab completion and ? should work for all model's properties. I've attached a few screenshots below.

Hopefully these two bits of information taken together, might offer some immediate relief, if I have understood your concerns. With some more input, we can try to make additional improvements as well.

Thanks,

Bryan

<Screen Shot 2016-11-02 at 5.52.45 PM.png>

<Screen Shot 2016-11-02 at 5.52.58 PM.png>

On Nov 2, 2016, at 1:13 PM, [email protected] wrote:

Hi All!

I'm a (python data stack) data scientist with a predilection towards data viz. I've recently taken a bit of a sojourn into Bokeh-land. I've found Bokeh to be an incredibly powerful library with a ton of cool features, but I also ran in to a number of pain points which ultimately led me to elect not to use Bokeh for my work at this time (though I'm still tinkering with it on the side). I just wanted to document some of the issues I encountered at a high level to provide some 'user research', if you will, that may be instructive for the team as you move towards v1.0. I'm mostly documenting pain points here, but I really do think Bokeh is an awesome library with great potential -- I don't mean at all to be critical, I just want to provide feedback in case it proves useful (caveating all this with: I know you are short-handed and doing the best you can with limited resources!).

At a super high level, the main problems I ran into were:
(1) Documentation
(2) Interactivity

(1) Documentation:

To me this is really the only thing that is a must-fix before v1.0, and really the only thing that would prevent extremely widespread adoption of Bokeh. The current state of the documentation is a serious blocker for non-engineers trying to work with Bokeh. The single biggest problem is the **KWARGS! problem. Put simply, while using a jupyter notebook attempts to quickly view documentation using the shift-tab notebook feature (or %psource, '?', etc) are futile. Most functions and class instances merely note that they take args and kwargs, and don't provide relevant options and customizations that a user would be looking for.

The 'give a list of valid options when user enters an invalid option' feature is genuinely brilliant, but it is not a substitute for quick, easy, access to full-bodied readme docs. Unfortunately the API reference on the site often falls prey to the same issue, and even when it doesn't the available options are often undocumented, or sparsely documented. Compared to the docs for, say, seaborn, which provide full options, extensive details, and extensive examples right on the same page, Bokeh lags. This is critical for quick iteration in the data analytics world. In seaborn I can fix a syntax problem very quickly by consulting the site or shift-tabbing. In Bokeh often times I had to abandon such efforts after 30 minutes of searching with no answer. Improving the API references and the, related, readme references, are from a user experience side the highest priority open tasks for Bokeh. I honestly feel documentation improvements are more valuable than any plausible feature that could be added before v1.

The user guide is a valuable supplement, but it is much harder to diagnose a problem with command XYZ by going to the user guide than by knowing which command to look up for examples in the API reference or, even better, with a simple shift-tab (or %psource, etc) in notebook. The demos are likewise awesome, but have a similar concern. Also, many things are available in github examples only and not online, which is a minor annoyance. The user guide and examples also fall short in the area I would say is by far Bokehs core competency, interactivity.

(2) Interactivity

I was drawn to Bokeh by the powerful (and hopefully simple!) interactive elements. In particular, ability to use widgets to control plots in an interactive manner *in static html*. Jupyter widgets already make it super easy to get chart interactivity, but this is harder to port to static webpage contexts. I don't really have any background in JS, and I found it very difficult to navigate the docs for adding interactivity in a static html context. The from_pyfunc() function proved too limited, which is understandable, but richer docs (with explanations) for CustomJS would be helpful.

Bokeh server certainly has a ton of value for certain solutions, but most of the time a light weight solution is vastly preferable. Where the server really shines is in the potential to have the extremely elusive 'shiny for python' type dashboard experience. This experience includes Bokeh server but would also include pre-built infrastructure to easily add ready-made sidebars, filters, formatting options, etc. as Shiny provides. These are all doable with Bokeh, certainly, but a dashboarding solution would make them simple and painless. At least in the data science part of the world this is where Bokeh server shines, and I'd love to see Bokeh server target this use case, which is a HUGE open need in the #pydata stack. For someone with absolutely no background in software engineering setting up an internal-network-facing dashboard application served by Bokeh server is currently a dream, contrasted with Shiny.

To this one user's eyes Bokeh has a clear fit in the #pydata stack, and that fit is in (1) making it easy to publish interactive, widget driven visualizations that function in static html, and (2) providing the first genuinely viable counterpart to shiny for python. Libraries like seaborn will always be better for exploratory, quick visualizations, and that is totally ok. Bokeh has a huge opportunity space, and I feel it is well poised to fill that space. I think focusing in those areas will provide the easiest wins, compared to trying to reinvent the billion things one can already do in matplotlib. Focusing on interactivity and dashboarding solutions will, to my eyes, facilitate the broadest Bokeh adoption.

I really love what I've seen out of Bokeh so far, and I hope this user research proves somewhat helpful. I know there are many limitations on the time of all Bokeh developers and I stress again that none of this is intended to be critical in any way. I would be happy to follow up and discuss my experiences more insofar as that would be valuable.

Best,
Stu

--
You received this message because you are subscribed to the Google Groups "Bokeh Discussion - Public" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [email protected].
To post to this group, send email to [email protected].
To view this discussion on the web visit https://groups.google.com/a/continuum.io/d/msgid/bokeh/c0c9f871-d6ea-4dbd-9aec-4c96bb5858ff%40continuum.io.
For more options, visit https://groups.google.com/a/continuum.io/d/optout.

Hi Bryan and All,
Absolutely. Bryan, notebook has a shift-tab feature where you can hit shift-tab while inside of to parens () as in:

This is distinct from tab completion, but certainly related. However, sometimes it is actually the **kwargs that contain all of the valuable information, which is where difficulty can sometimes arise:

More information is definitely glean-able though:

However, as you noted, this is getting into the realm of ‘text wall’ which can be off-putting to someone trying to quickly find a simple setting. Having shift-tab pull up a curated list of the most valuable settings is a neat trick. It definitely isn’t a must-have, but it is nice for ease of use. What is odd is that, eg for circle, some of the parameters noted here aren’t noted in an easy-to-track-down way in the API ref.
Perhaps the main pain-point on the docs side lies in that, often, the only way to figure out how features surrounding callbacks and server interactions work is via examples, should they exist, or much frustration, if they do not. E.g., as I tried to figure out how to get various callbacks to work, I struggled immediately any time a direct analog wasn’t readily available in the examples (and figuring out where to look between API reference, user guide, gallery, github/examples, could be confusing at times). W.r.t. callbacks I struggled starting at cb_obj, basically. For several things I’ve tried (some successfully!) to implement I knew cb_obj probably had the information I needed, but how to get that information? What exactly is available with regards to selected data, the object, which triggering events exist and how to set such a trigger based on xyz characteristic of the selected data proved difficult to navigate. An (even more) extended hand-holding into the very shallow end of the CustomJS callback pool would be a great addition to the docs. Likewise, shallow-end ‘spin up a bokeh server to serve app on your local network’ could address a pain point for the more data science-y inclined users. Many are drawn to Bokeh for these features in particular.
If there is any other area in which I may provide clarification just let me know. Thanks again to all of the developers for their work on Bokeh – I really like the direction the project is headed!

Kind regards,
Stu

Hi Stu,

First thanks for the continued input. Comments inline below.

Absolutely. Bryan, notebook has a shift-tab feature where you can hit shift-tab while inside of to parens () as in:
<Auto Generated Inline Image 1.png>

This is distinct from tab completion, but certainly related. However, sometimes it is actually the **kwargs that contain all of the valuable information, which is where difficulty can sometimes arise:
<Auto Generated Inline Image 2.png>

I don't think we can make the signature report anything different, unfortunately. We can't change it on our side in any way that wouldn't be a maintenance nightmare, and as I mentioned in the other email the only hook that Jupyter seems to provide is for customizing the reported docstring. But, we can certainly make the docstring portion of that popup list the properties of the underlying glyph in an automated way very easily.

More information is definitely glean-able though:
<Auto Generated Inline Image 3.png>
However, as you noted, this is getting into the realm of 'text wall' which can be off-putting to someone trying to quickly find a simple setting. Having shift-tab pull up a curated list of the most valuable settings is a neat trick.

And then I guess the question is of curation. We can make the above-mentioned docstring shorter in this way, but I'm not entirely sure what constitute the most valuable settings, so input here is welcome.

It definitely isn't a must-have, but it is nice for ease of use. What is odd is that, eg for circle, some of the parameters noted here aren't noted in an easy-to-track-down way in the API ref.

I recently added the notion of Options that can be auto-documented with everything else. The first place was to auto-document the non-property kwargs that can be passed to figure:

  http://bokeh.pydata.org/en/dev/docs/reference/plotting.html#bokeh.plotting.figure.figure

I think this can be used exactly the same on glyph methods like circle to bring all the extra non-property kwargs under automation in the ref guide. Thanks for reminding me of this other place to use Options.

Perhaps the main pain-point on the docs side lies in that, often, the only way to figure out how features surrounding callbacks and server interactions work is via examples, should they exist, or much frustration, if they do not. E.g., as I tried to figure out how to get various callbacks to work, I struggled immediately any time a direct analog wasn't readily available in the examples (and figuring out where to look between API reference, user guide, gallery, github/examples, could be confusing at times). W.r.t. callbacks I struggled starting at cb_obj, basically. For several things I've tried (some successfully!) to implement I knew cb_obj probably had the information I needed, but how to get that information? What exactly is available with regards to selected data, the object, which triggering events exist and

I'm sorry for your frustrations. This is a general principle that is probably something to surface better, that might hold the key to helping wrt to CustomJS callbacks: the public properties on BokehJS and python Bokeh models are always in 1-1 agreement. This is maintained strictly under test. Perhaps this is something that is so ingrained that we have forgotten to mention it enough. This is to say, the python reference API is usually a perfectly good reference for the BokehJS objects as well. Then to note, the value of cb_obj is always the object that the callback was attached to. So if you attach a callback to a data source, the reference API (for python) for the data source will have all the properties that a JS callback might use.

how to set such a trigger based on xyz characteristic of the selected data proved difficult to navigate. An (even more) extended hand-holding into the very shallow end of the CustomJS callback pool would be a great addition to the docs.

There is only one time trigger should ever be required: when updating the internal "guts" of some property value in place. Or by example:

  source.data = { ... } # no trigger needed, .data replaced wholesale

vs

  source.data['foo'][i] = 20 # source.trigger('data') needed, .data modified in-place

Likewise, shallow-end 'spin up a bokeh server to serve app on your local network' could address a pain point for the more data science-y inclined users. Many are drawn to Bokeh for these features in particular.

I think this could use more elaboration, at least for me. Perhaps one point we should try to emphasize better is:

  If you're not afraid of "ipython notebook" (which is a server)

  Then you shouldn't be afraid of "bokeh serve" either.

As for spinning one up on a local network, that entails running "bokeh serve myapp" on a machine and leaving it there. And that is mentioned in the user's guide. I guess I'm sincerely not sure what else there is to add to that, so any suggestions are welcome.

If there is any other area in which I may provide clarification just let me know. Thanks again to all of the developers for their work on Bokeh -- I really like the direction the project is headed!

Kind regards,
Stu

I will make issues to codify some of the immediately actionable ideas from this chain in the next few days.

Thanks again,

Bryan

It turns out the signatures can be improved and in fact that’s maybe the quickest simplest thing that could be done. Please see:

[https://github.com/bokeh/bokeh/pull/5447](https://github.com/bokeh/bokeh/pull/5447)

Which results in, e.g.

I also have some prototype code for marking some options as “advanced” (so that they could be omitted in the interactive docstring, but included in the ref guide) but I don’t think there is getting away from the fact that there just being very many options, even very many “common” or “most useful” options in alot of cases. I still think this is probably worth pursuing but I’m not sure sure it makes a huge dent in the size of things.

Bryan

···

On Nov 4, 2016, at 4:54 PM, Bryan Van de Ven [email protected] wrote:

Hi Stu,

First thanks for the continued input. Comments inline below.

Absolutely. Bryan, notebook has a shift-tab feature where you can hit shift-tab while inside of to parens () as in:
<Auto Generated Inline Image 1.png>

This is distinct from tab completion, but certainly related. However, sometimes it is actually the **kwargs that contain all of the valuable information, which is where difficulty can sometimes arise:
<Auto Generated Inline Image 2.png>

I don’t think we can make the signature report anything different, unfortunately. We can’t change it on our side in any way that wouldn’t be a maintenance nightmare, and as I mentioned in the other email the only hook that Jupyter seems to provide is for customizing the reported docstring. But, we can certainly make the docstring portion of that popup list the properties of the underlying glyph in an automated way very easily.

More information is definitely glean-able though:
<Auto Generated Inline Image 3.png>
However, as you noted, this is getting into the realm of ‘text wall’ which can be off-putting to someone trying to quickly find a simple setting. Having shift-tab pull up a curated list of the most valuable settings is a neat trick.

And then I guess the question is of curation. We can make the above-mentioned docstring shorter in this way, but I’m not entirely sure what constitute the most valuable settings, so input here is welcome.

It definitely isn’t a must-have, but it is nice for ease of use. What is odd is that, eg for circle, some of the parameters noted here aren’t noted in an easy-to-track-down way in the API ref.

I recently added the notion of Options that can be auto-documented with everything else. The first place was to auto-document the non-property kwargs that can be passed to figure:

http://bokeh.pydata.org/en/dev/docs/reference/plotting.html#bokeh.plotting.figure.figure

I think this can be used exactly the same on glyph methods like circle to bring all the extra non-property kwargs under automation in the ref guide. Thanks for reminding me of this other place to use Options.

Perhaps the main pain-point on the docs side lies in that, often, the only way to figure out how features surrounding callbacks and server interactions work is via examples, should they exist, or much frustration, if they do not. E.g., as I tried to figure out how to get various callbacks to work, I struggled immediately any time a direct analog wasn’t readily available in the examples (and figuring out where to look between API reference, user guide, gallery, github/examples, could be confusing at times). W.r.t. callbacks I struggled starting at cb_obj, basically. For several things I’ve tried (some successfully!) to implement I knew cb_obj probably had the information I needed, but how to get that information? What exactly is available with regards to selected data, the object, which triggering events exist and

I’m sorry for your frustrations. This is a general principle that is probably something to surface better, that might hold the key to helping wrt to CustomJS callbacks: the public properties on BokehJS and python Bokeh models are always in 1-1 agreement. This is maintained strictly under test. Perhaps this is something that is so ingrained that we have forgotten to mention it enough. This is to say, the python reference API is usually a perfectly good reference for the BokehJS objects as well. Then to note, the value of cb_obj is always the object that the callback was attached to. So if you attach a callback to a data source, the reference API (for python) for the data source will have all the properties that a JS callback might use.

how to set such a trigger based on xyz characteristic of the selected data proved difficult to navigate. An (even more) extended hand-holding into the very shallow end of the CustomJS callback pool would be a great addition to the docs.

There is only one time trigger should ever be required: when updating the internal “guts” of some property value in place. Or by example:

source.data = { … } # no trigger needed, .data replaced wholesale

vs

source.data[‘foo’][i] = 20 # source.trigger(‘data’) needed, .data modified in-place

Likewise, shallow-end ‘spin up a bokeh server to serve app on your local network’ could address a pain point for the more data science-y inclined users. Many are drawn to Bokeh for these features in particular.

I think this could use more elaboration, at least for me. Perhaps one point we should try to emphasize better is:

If you’re not afraid of “ipython notebook” (which is a server)

Then you shouldn’t be afraid of “bokeh serve” either.

As for spinning one up on a local network, that entails running “bokeh serve myapp” on a machine and leaving it there. And that is mentioned in the user’s guide. I guess I’m sincerely not sure what else there is to add to that, so any suggestions are welcome.

If there is any other area in which I may provide clarification just let me know. Thanks again to all of the developers for their work on Bokeh – I really like the direction the project is headed!

Kind regards,
Stu

I will make issues to codify some of the immediately actionable ideas from this chain in the next few days.

Thanks again,

Bryan

Thanks for looking at this – definitely a very solid step in the right direction!

···

On Monday, November 7, 2016 at 9:44:42 AM UTC-8, Bryan Van de ven wrote:

It turns out the signatures can be improved and in fact that’s maybe the quickest simplest thing that could be done. Please see:

https://github.com/bokeh/bokeh/pull/5447

Which results in, e.g.

I also have some prototype code for marking some options as “advanced” (so that they could be omitted in the interactive docstring, but included in the ref guide) but I don’t think there is getting away from the fact that there just being very many options, even very many “common” or “most useful” options in alot of cases. I still think this is probably worth pursuing but I’m not sure sure it makes a huge dent in the size of things.

Bryan

On Nov 4, 2016, at 4:54 PM, Bryan Van de Ven [email protected] wrote:

Hi Stu,

First thanks for the continued input. Comments inline below.

Absolutely. Bryan, notebook has a shift-tab feature where you can hit shift-tab while inside of to parens () as in:
<Auto Generated Inline Image 1.png>

This is distinct from tab completion, but certainly related. However, sometimes it is actually the **kwargs that contain all of the valuable information, which is where difficulty can sometimes arise:
<Auto Generated Inline Image 2.png>

I don’t think we can make the signature report anything different, unfortunately. We can’t change it on our side in any way that wouldn’t be a maintenance nightmare, and as I mentioned in the other email the only hook that Jupyter seems to provide is for customizing the reported docstring. But, we can certainly make the docstring portion of that popup list the properties of the underlying glyph in an automated way very easily.

More information is definitely glean-able though:
<Auto Generated Inline Image 3.png>
However, as you noted, this is getting into the realm of ‘text wall’ which can be off-putting to someone trying to quickly find a simple setting. Having shift-tab pull up a curated list of the most valuable settings is a neat trick.

And then I guess the question is of curation. We can make the above-mentioned docstring shorter in this way, but I’m not entirely sure what constitute the most valuable settings, so input here is welcome.

It definitely isn’t a must-have, but it is nice for ease of use. What is odd is that, eg for circle, some of the parameters noted here aren’t noted in an easy-to-track-down way in the API ref.

I recently added the notion of Options that can be auto-documented with everything else. The first place was to auto-document the non-property kwargs that can be passed to figure:

[http://bokeh.pydata.org/en/dev/docs/reference/plotting.html#bokeh.plotting.figure.figure](http://bokeh.pydata.org/en/dev/docs/reference/plotting.html#bokeh.plotting.figure.figure)

I think this can be used exactly the same on glyph methods like circle to bring all the extra non-property kwargs under automation in the ref guide. Thanks for reminding me of this other place to use Options.

Perhaps the main pain-point on the docs side lies in that, often, the only way to figure out how features surrounding callbacks and server interactions work is via examples, should they exist, or much frustration, if they do not. E.g., as I tried to figure out how to get various callbacks to work, I struggled immediately any time a direct analog wasn’t readily available in the examples (and figuring out where to look between API reference, user guide, gallery, github/examples, could be confusing at times). W.r.t. callbacks I struggled starting at cb_obj, basically. For several things I’ve tried (some successfully!) to implement I knew cb_obj probably had the information I needed, but how to get that information? What exactly is available with regards to selected data, the object, which triggering events exist and

I’m sorry for your frustrations. This is a general principle that is probably something to surface better, that might hold the key to helping wrt to CustomJS callbacks: the public properties on BokehJS and python Bokeh models are always in 1-1 agreement. This is maintained strictly under test. Perhaps this is something that is so ingrained that we have forgotten to mention it enough. This is to say, the python reference API is usually a perfectly good reference for the BokehJS objects as well. Then to note, the value of cb_obj is always the object that the callback was attached to. So if you attach a callback to a data source, the reference API (for python) for the data source will have all the properties that a JS callback might use.

how to set such a trigger based on xyz characteristic of the selected data proved difficult to navigate. An (even more) extended hand-holding into the very shallow end of the CustomJS callback pool would be a great addition to the docs.

There is only one time trigger should ever be required: when updating the internal “guts” of some property value in place. Or by example:

source.data = { ... }       # no trigger needed, .data replaced wholesale

vs

source.data['foo'][i] = 20  # source.trigger('data') needed, .data modified in-place

Likewise, shallow-end ‘spin up a bokeh server to serve app on your local network’ could address a pain point for the more data science-y inclined users. Many are drawn to Bokeh for these features in particular.

I think this could use more elaboration, at least for me. Perhaps one point we should try to emphasize better is:

If you're not afraid of "ipython notebook" (which is a server)

Then you shouldn't be afraid of "bokeh serve" either.

As for spinning one up on a local network, that entails running “bokeh serve myapp” on a machine and leaving it there. And that is mentioned in the user’s guide. I guess I’m sincerely not sure what else there is to add to that, so any suggestions are welcome.

If there is any other area in which I may provide clarification just let me know. Thanks again to all of the developers for their work on Bokeh – I really like the direction the project is headed!

Kind regards,
Stu

I will make issues to codify some of the immediately actionable ideas from this chain in the next few days.

Thanks again,

Bryan