Longer chapter(s) on interactive graphs

[emmanuelle]

We've already mentioned a few times that the part on plotly graphs in Dash applications should be expanded. I'm trying here to summarize what could go into a new version:

• [x] the different ways to set dcc.Graph.figure: dict or plotly figure, which can be created with plotly.graph_objects or plotly.express (possibly using fig.update_traces and fig.update_layout). provide a link to plot.ly/python/creating-and-updating-figures/ -[ ] existing example capturing user interaction (clickData etc.)

• [ ] existing example Update Graphs on Hover

• [ ] example of editable (`config={'editable":True}) figure triggering a callback when edited

• [ ] explain the shape of selectedData and how to access the components of it

• [ ] explain how we recommend selectedData with clicking instead of clickData

• [ ] explain how the user interface for selectedData works: clicking, shift clicking, double clicking to unselect, and more.

• [ ] explain what selected data looks like for other chart types including sunbursts

• [ ] datashader examples

• [ ] rasterly examples

• [ ] mention clientside callbacks for graphs (see #754 )

• [ ] subplots vs multiple dcc.Graph components

• [ ] real world examples of restyleData (responding to legend events, like keeping two graphs in sync)

• [ ] real world examples of hoverData, including:

  • [ ] using hover data to update the graph itself. For example:

  You can thicken a trace when hovering over it in Dash without needing to use javascript by creating a callback with the input hoverData. The hoverData includes the index of the trace that's being hovered on so you would be able to use that info to generate a thicker version of the trace in that callback (I would simply append this thicker trace to the list of existing traces because that is easier than deleting the thin trace first).

  Then if you set clear_on_unhover=True in the dcc.Graph, hoverData will change to None when a trace is unhovered so your callback would look something like this:

  @app.callback(Output('graph', 'figure'), [Input('graph', 'hoverData')], [State('graph', 'figure')])
  update_graph_on_hover(hoverData, fig):
    if not hoverData is None:
      trace = create_thicker_version_of_hovered_over_trace(hoverData)
      fig['data'].append(trace)
      return fig
  
    # delete that last trace if hoverdata is cleared
    else:
      fig['data'].pop()
  

  If you go the above route, you may need to add a dummy trace that'll get popped before any hover action takes place.

  • [ ] using hover data to update something different

• [ ] Examples of the config. For example, how to change the size and resolution of the PNG graph when downloading it

Does that make sense? Anything else missing? It's a lot of work but I think it makes sense to consider this as a whole. A lot of questions on the forum would probably disappear with the above additions.

[chriddyp]

Since https://github.com/plotly/dash-docs/pull/641, each component now has a dedicated page. These pages aren't directly linked to in dash.plot.ly but they are linked to in other environments like Dash Enterprise that have a sidebar:

We'll be adding a sidebar in dash.plot.ly next quarter as well.

So, could we do a quick first pass at this by just adding a preamble to this page with:

1. A link to plot.ly/python
2. A couple examples (it could be syntax only) showing what figure is.
3. A link to https://plot.ly/python/creating-and-updating-figures/ for the exhaustive list
4. A link to the interactive-graphing chapter
5. A link to whatever community posts we have uirevision & transitions

5 is optional, but 1-4 should be pretty quick and would add some intermediate value.

[emmanuelle]

ok; so I should add this to the docstring of dcc.Graph, ie here https://github.com/plotly/dash-core-components/blob/dev/src/components/Graph.react.js#L15. Correct?

[chriddyp]

You can actually add it in this file, to a variable named Graph https://github.com/plotly/dash-docs/blob/master/dash_docs/tutorial/core_component_examples.py that you "export" in this dictionary: https://github.com/plotly/dash-docs/blob/master/dash_docs/tutorial/core_component_examples.py#L12-L42

It's a little convulted, but that file is imported here: https://github.com/plotly/dash-docs/blob/master/dash_docs/tutorial/init.py#L3, which is then referred to when autogenerating the chapters here: https://github.com/plotly/dash-docs/blob/master/dash_docs/chapter_index.py#L184-L189

For example, these examples at the top of dropdown chapter: https://dash.plot.ly/dash-core-components/dropdown are defined here: https://github.com/plotly/dash-docs/blob/master/dash_docs/tutorial/core_component_examples.py#L45-L175

[chriddyp]

Here's a preamble that I've used when teaching the plotly graphing library, this might be a good one to include at the top of this section in the spirit of providing some helpful info/guidance to our end users:

        1. The **Plotly Graphing Library**, known as the package package `plotly`,
        generates "figures". These are used in `dcc.Graph` 
        with e.g. `dcc.Graph(figure=fig)`
        2. The **best thing you can learn** is how the documentation is organized:
            1. Learn the architecture of the `figure`: https://plot.ly/python/creating-and-updating-figures/
            2. Every chart type has a set of examples at a unique URL.
            Familarize yourself with the structure of these pages. Google is your friend.
            "Plotly Python Histogram Charts" at https://plot.ly/python/histogram
            3. Plotly Express is the recommended high level interface.
            Understand where it fits in by reading 1.
            Once you understand its structure, you can see all of the arguments in the
            "API Reference" page documented here: https://plot.ly/python-api-reference/plotly.express.html
            3. Every aspect of a chart is configurable.
            Read through 1 to understand the low level `figure` interface and how to
            modify the properties of a generated figure.
            Once you understand it, view _all_ of the
            properties by visiting the "Figure Reference" page at https://plot.ly/python/reference.
            4. If you can't generate the graph easily with `px`, then learn the
            `graph_objects` structure by reading 1 and understanding
            the structure of the figure via https://plot.ly/python/reference.
        3. Plotly supports 40-50 different chart types. Learn more by navigating
        https://plot.ly/python/
        4. In development, you can create figures by running Dash apps or
        in other environments like Jupyter, your console, and more.
        If you are using the interface outside of Dash, then calling
        `fig.show()` will always display the graph (either in your browser
        or inline directly in your environment). To see all of these rendering
        environments, see https://plot.ly/python/renderers/

[chriddyp]

@emmanuelle - if we could get something quick up within the next few days, that would be great! This will make it's way into the formal release.

[emmanuelle]

Sure it's on my list for today. Thank you for the clarification above.

[chriddyp]

we might want to make graphing it's own "section" so that we can split out these things into multiple chapters

[chriddyp]

for the R version, instead of datashader we'll document rasterly

[chriddyp]

• [ ] Summary / Details workaround: https://community.plotly.com/t/graph-is-squashed-in-collapsible-details-summary-element/39215/4

[emmanuelle]

extendData often triggers questions in the forum since there is no doc example and some links (including the release notes of dash 0.41) point to https://github.com/plotly/dash-core-components/pull/461, where the example code block is not valid any more (different syntax). See for example https://community.plotly.com/t/what-is-a-correct-usage-of-extenddata-property-to-achieve-adding-data-to-existing-graph-instead-of-constantly-updating-it/39569/4