Creating and updating figures section #26

jonmmease · 2019-06-21T17:21:23Z

The new section on representing, creating, and updating figures. Closes https://github.com/plotly/plotly.py-docs/issues/6.

Let me know what you think @nicolaskruchten @emmanuelle

Doc upgrade checklist:

Every example is independently runnable and is optimized for short line count
graph_objs has been renamed to graph_objects
fig = <something> call is high up in each example
minimal creation of intermediate trace objects
liberal use of add_trace and update_layout
fig.show() at the end of each example
v4upgrade: true metadata added
minimize usage of hex codes for colors in favour of those in https://github.com/plotly/plotly.py-docs/issues/14

notebooks/creating-updating-figures.md

nicolaskruchten · 2019-06-21T18:46:12Z

notebooks/creating-updating-figures.md

+
+```python
+import plotly.graph_objects as go
+fig = go.Figure({


basically I would use this example as the first one :)

I think I would use the go.Scatter constructor in the first example. We want the first example to look like a typical doc page.

nicolaskruchten · 2019-06-21T18:47:31Z

notebooks/creating-updating-figures.md

+```python
+import plotly.graph_objects as go
+fig = go.Figure(data=go.Bar(x=[1, 2, 3], y=[1, 3, 2]))
+fig.update_layout(title={"text": "A Bar Chart",


I would use magic underscores here :)

nicolaskruchten · 2019-06-21T18:49:17Z

notebooks/creating-updating-figures.md

+import plotly.express as px
+iris = px.data.iris()
+(px.scatter(iris, x="sepal_width", y="sepal_length", color="species", facet_col="species", trendline='ols')
+ .update_layout(title_text='Iris Dataset')


so there's a px kwarg for title... I like showing how to turn the legend horizontal with update_layout as something that's not doable with existing kwargs :)

I tried the horizontal legend, but it didn't look so great by default in this case (is gets squashed pretty close to the x-axis labels). So I set the title with px and used update_layout to increase the title font size.

nicolaskruchten · 2019-06-21T18:54:35Z

notebooks/creating-updating-figures.md

+fig.data[0].marker.line.width = 4
+fig.data[0].marker.line.color = 'black'
+fig.show()
+```


Here I would consider a little example that shows the N ways of updating the same pair of attributes (one nested, one not) with an explanation saying "the following are equivalent": dict (in dict(x= and in literal {"x": forms plus in nested and magic-flat forms) and go

I added an example of 6 equivalent update_layout operations at the end of the update layout section. How's that?

love this example

if we moved property-assignment back up, we could add that kind of example here too.

nicolaskruchten · 2019-06-21T18:55:13Z

This is really great: just what's needed IMO. @emmanuelle I would love your thoughts

…pdate_layout

emmanuelle · 2019-06-21T20:14:44Z

This is great. It's exactly what I would have needed when I started using the library :-). A few remarks:

as @nicolaskruchten suggests, I would also start with a short example with the preferred syntax, ie with go objects. A paragraph like "your first plotly figure" which will the only one that 90% of readers see because they are in a hurry and go somewhere else. So, something like an executive summary.
I think most Python users don't care much about what happens in the javascript library, so I would postpone the first paragraph to a "behind the scene" paragraph which comes after the first example with go.
In the doc I have written most chart type examples with dictionaries defined as dict(key1=val1, key2=val2) because there are less quotes and it's easier to use the magic underscore. Would it be possible to use this syntax also here, at least in the update methods?

notebooks/creating-updating-figures.md

emmanuelle · 2019-06-21T20:17:48Z

notebooks/creating-updating-figures.md

+ 2. Graph objects contain descriptions of each property as Python docstrings.  You can use these docstrings to learn about the available properties as an alternative to consulting the *Full Reference*.
+ 3. Graph objects support higher-level convenience functions for making updates to already constructed figures.
+
+Graph objects are stored in a hierarchy of modules under the `plotly.graph_objects` package.  Here is an example of one way that the figure above could be constructed using graph objects.


is it important for users (as opposed to devs) to mention the "hierarchy of modules"? How about "stored under the ... package"?

Only insofar as it's important that people look for go.layout.title.Font() and don't expect to find go.Font().

emmanuelle · 2019-06-21T20:18:43Z

notebooks/creating-updating-figures.md

+
+```python
+import plotly.graph_objects as go
+fig = go.Figure({


I think I would use the go.Scatter constructor in the first example. We want the first example to look like a typical doc page.

emmanuelle · 2019-06-21T20:20:24Z

notebooks/creating-updating-figures.md

+```
+
+### Plotly express
+Plotly express (included in plotly.py as the `plotly.express` module) is a high-level data exploration API that produces graph object figures.


"included as the plotly.express module", I think most users only know "plotly" and mentioning "plotly.py" can be confusing.

Also mention that px only works with tidy Pandas dataframes.

emmanuelle · 2019-06-21T20:33:31Z

notebooks/creating-updating-figures.md

+v1 = np.sin(x1)*y1
+
+fig = ff.create_quiver(x1, y1, u1, v1)
+fig.show()


Here I tried to explore the fig object to know what was specific in the figure factory so that the resulting trace looks like a quiver but it was quite difficult (I finally found out that it's thanks to None and not connecting gaps, but it was not straightforward). Would it be possible to add something about properties introspection? Like, how can you use tab completion?

Tab completion with getattr access? I don't really want to get into the process of reverse engineering what the figure factories and plotly express do in this section. We could change which figure factory is demonstrated here if another example seems better.

emmanuelle · 2019-06-21T20:37:05Z

notebooks/creating-updating-figures.md

+
+### Magic underscore notation
+To make it easier to work with nested properties graph object constructors, and many graph object methods, support magic underscore notation. This allows you to reference nested properties by joining together multiple nested property names with underscores.  For example, specifying the figure title in the figure constructor *without* magic underscore notation requires setting the `layout` argument to `{"title": {"text": "A Chart"}}`.
+


"As a rule of thumb most names with underscores denote a magic underscore syntax." (Is it true? Not all names with underscores, since there is "error_x" etc., but ideally it should be the case since it would be clearer).

Yeah, it's a little messy.

i think there are only 3 or 4 properties that break this rule, so we could just call it out here. like:

By “most” we mean all properties except error_x, error_y, paper_bg, ... Those properties were added back in the early days of the library (2012 & 2013!) before we standardized on “no underscores in property names.”

i like using the markdown blocquotes (>) for little sidenotes like these.

👍 I added a block quote explanation in 9d14e21

emmanuelle · 2019-06-21T20:39:12Z

notebooks/creating-updating-figures.md

+
+Magic underscore notation is supported throughout the graph objects API, and it can often significantly simplify operations involving deeply nested properties.
+
+### Property assignment


I would put update_traces and update_layout before property assignment, because this is what we use in the docs. Or have them mentioned in the first "excutive summary" example.

Good point, moving this to the end

…aries

jonmmease · 2019-06-21T21:44:51Z

Thanks for the quick feedback @nicolaskruchten and @emmanuelle.

I've made all of the updates for the suggestions that I immediately agreed with.

For what's left, it's probably better if one of you take a stab at the restructuring you have in mind. I definitely don't mind more changes being made, but the structure/order I have still makes sense to me, so I'm finding it difficult make the changes myself. I'm going to move on to the other new pages now (templates and renderers).

nicolaskruchten · 2019-06-21T22:42:56Z

Thanks Jon! I have an idea of how to preserve the structure and meet my goals as well, let me propose something in a bit when the kids are down

notebooks/creating-updating-figures.md

nicolaskruchten · 2019-06-22T00:33:13Z

notebooks/creating-updating-figures.md

+fig.show()
+```
+
+Once you have a figure as a graph object, you can retrieve the dictionary representation using the `fig.to_dict()` method.  You can also retrieve the JSON string representation using the `fig.to_json()` method.


I would point out that you can also read attributes directly with fig.layout.title.text as this is a big advantage over dicts !

👍 I added another item to the advantages list above in c0f6c8c

chriddyp · 2019-06-21T22:54:59Z

notebooks/creating-updating-figures.md

+
+The value of the top-level `"data"` key is a list of trace specifications.  Each trace specification has a special `"type"` key that indicates the trace type that is being defined (e.g. a `"bar"`, `"scatter"`, `"contour"`, etc.).  The rest of the keys in the trace specification are used to configure the properties of the trace of this type.
+
+The value of the top-level `"layout"` key is a dictionary that specifies the properties of the figure's layout.  In contrast to trace configuration options that apply to individual traces, the layout configuration options apply to the figure as a whole.


“like the axes, annotations, shapes, legend, and more.”

👍 28f1d8f

chriddyp · 2019-06-21T22:55:35Z

notebooks/creating-updating-figures.md

+
+The [*Full Reference*](https://plot.ly/python/reference/) page contains descriptions of all of the supported trace and layout options.
+
+If working from the *Full Reference* to build figures as Python dictionaries suites your needs, go for it! This is a perfectly valid way to use use plotly.py to build figures.  On the other hand, if you would like an API that offers a bit more assistance, read on to learn about graph objects.


“and lists”

also maybe “as you become more comfortable with the graph reference, you may find yourself using this “shorthand” instead of the objects below.”?

"and lists"

👍 in ff64f59

also maybe “as you become more comfortable with the graph reference, you may find yourself using this “shorthand” instead of the objects below.”?

This didn't quite fit the flow I was going for, so I didn't put it in yet. Does it feel like an important clarification to you?

notebooks/creating-updating-figures.md

chriddyp · 2019-06-21T23:02:28Z

notebooks/creating-updating-figures.md

+```python
+import plotly.express as px
+iris = px.data.iris()
+fig = px.scatter(iris, x="sepal_width", y="sepal_length", color="species")


what if we added like a # print(fig.to_dict()). # if you inspect the fig, you’ll see it’s just a regular figure with data and layout

👍 cacbc37

chriddyp · 2019-06-21T23:04:16Z

notebooks/creating-updating-figures.md

+```
+
+### Figure factories
+Figure factories (included in plotly.py in the `plotly.figure_factory` module) are functions that produce graph object figures, often to satisfy the needs of specialized domains.  Here's an example of using the `create_quiver` figure factory to construct a graph object figure that displays a 2D quiver plot.


should we add a “Note - some of these functions are better served by px now, like ff.dist_plot and ff.facet_plot (or w/e)?

I definitely think this info belongs somewhere, but in my mind it's a level below what this section is trying to communicate. At this level, I think we just want people to understand that the things produced by plotly express and the figure factories are just normal figures.

chriddyp · 2019-06-21T23:06:25Z

notebooks/creating-updating-figures.md

+```python
+import plotly.graph_objects as go
+fig = go.Figure(
+    data=[go.Bar(x=[1, 2, 3], y=[1, 3, 2])],


what about having two bar traces, one that uses go.bar.Marker and one that uses just marker={colour: ...} to demonstrate the two ways then nested objects can be defined? could even have go.marker.Line too

The first example in the "Constructor" section below calls out the fact that you can mix graph objects and dicts in the constructor. Is that sufficient? I think I'd rather add another example to that section if we want to be more explicit about it.

We certainly could add more traces here, but I would want to add them to he prior dict-only example above so that we're working with the same underlying figure. And that would make the first dict-only figure a bit more complicated.

chriddyp · 2019-06-21T23:07:57Z

notebooks/creating-updating-figures.md

+                            showlegend=False)
+fig.add_trace(reference_line, row=1, col=1)
+fig.add_trace(reference_line, row=1, col=2)
+fig.add_trace(reference_line, row=1, col=3)


nice example!

chriddyp · 2019-06-21T23:11:41Z

notebooks/creating-updating-figures.md

+
+### Magic underscore notation
+To make it easier to work with nested properties graph object constructors, and many graph object methods, support magic underscore notation. This allows you to reference nested properties by joining together multiple nested property names with underscores.  For example, specifying the figure title in the figure constructor *without* magic underscore notation requires setting the `layout` argument to `{"title": {"text": "A Chart"}}`.
+


i think there are only 3 or 4 properties that break this rule, so we could just call it out here. like:

By “most” we mean all properties except error_x, error_y, paper_bg, ... Those properties were added back in the early days of the library (2012 & 2013!) before we standardized on “no underscores in property names.”

i like using the markdown blocquotes (>) for little sidenotes like these.

chriddyp · 2019-06-21T23:16:42Z

notebooks/creating-updating-figures.md

+
+```python
+import plotly.graph_objects as go
+fig = go.Figure(layout=dict(title=dict(text="A Chart")))


could we just add a simple trace here too to really enforce the point? with eg marker_color

👍 d7d6a51

chriddyp · 2019-06-21T23:17:19Z

notebooks/creating-updating-figures.md

+fig.data[0].marker.line.width = 4
+fig.data[0].marker.line.color = 'black'
+fig.show()
+```


love this example

jonmmease · 2019-06-22T23:02:57Z

Alright, I made another round of updates. Thanks for the feedback @nicolaskruchten @emmanuelle and @chriddyp . I'm really excited about having this page in our docs soon!

nicolaskruchten · 2019-06-23T00:49:55Z

I could keep workshopping this but it's certainly good to go as is from where I sit :)

💃

…etadata

# Conflicts: # notebooks/user-guide.md

nicolaskruchten · 2019-06-27T01:38:15Z

Let's merge this one in!

jonmmease added 2 commits June 21, 2019 13:16

Initial draft of the creating and updating figures section

a7c9d5a

Added v4upgrade metadata

22d394f

nicolaskruchten reviewed Jun 21, 2019

View reviewed changes

notebooks/creating-updating-figures.md Outdated Show resolved Hide resolved

nicolaskruchten reviewed Jun 21, 2019

View reviewed changes

jonmmease added 3 commits June 21, 2019 16:02

Use magic underscore notation

cda3d67

Add example of 6 equivalent update_layout operations

1a9fe7b

Update chaining example to specify title with px and font size with u…

61000ba

…pdate_layout

emmanuelle reviewed Jun 21, 2019

View reviewed changes

jonmmease added 4 commits June 21, 2019 17:19

Standardize on double quotes and dict constructor for small diction…

51ed6f4

…aries

as described below

8bd1f53

included as the plotly.express module

9147f27

Move property assignment to the end

58a9154

nicolaskruchten reviewed Jun 22, 2019

View reviewed changes

notebooks/creating-updating-figures.md Outdated Show resolved Hide resolved

nicolaskruchten reviewed Jun 22, 2019

View reviewed changes

chriddyp reviewed Jun 22, 2019

View reviewed changes

jonmmease added 7 commits June 22, 2019 18:47

Push down pio import in first dictionary example

4825440

axes, annotations, shapes, legend, and more

28f1d8f

and lists

ff64f59

class-style property access

c0f6c8c

If you print fig

cacbc37

add trace to magic underscore example

d7d6a51

almost always

9d14e21

jonmmease added 3 commits June 25, 2019 10:41

Delete old user guide

6e47754

Move creating-and-updating-figures to user-guide and add user-guide m…

a82dd4c

…etadata

Merge branch 'master' into create_updating_figures

89b03a1

# Conflicts: # notebooks/user-guide.md

jonmmease merged commit 27badef into master Jun 27, 2019


		### Magic underscore notation
		To make it easier to work with nested properties graph object constructors, and many graph object methods, support magic underscore notation. This allows you to reference nested properties by joining together multiple nested property names with underscores. For example, specifying the figure title in the figure constructor without magic underscore notation requires setting the `layout` argument to `{"title": {"text": "A Chart"}}`.


		Magic underscore notation is supported throughout the graph objects API, and it can often significantly simplify operations involving deeply nested properties.

		### Property assignment


		The value of the top-level `"data"` key is a list of trace specifications. Each trace specification has a special `"type"` key that indicates the trace type that is being defined (e.g. a `"bar"`, `"scatter"`, `"contour"`, etc.). The rest of the keys in the trace specification are used to configure the properties of the trace of this type.

		The value of the top-level `"layout"` key is a dictionary that specifies the properties of the figure's layout. In contrast to trace configuration options that apply to individual traces, the layout configuration options apply to the figure as a whole.


		The [Full Reference](https://plot.ly/python/reference/) page contains descriptions of all of the supported trace and layout options.

		If working from the Full Reference to build figures as Python dictionaries suites your needs, go for it! This is a perfectly valid way to use use plotly.py to build figures. On the other hand, if you would like an API that offers a bit more assistance, read on to learn about graph objects.

Creating and updating figures section #26

Creating and updating figures section #26

Conversation

jonmmease commented Jun 21, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nicolaskruchten commented Jun 21, 2019 • edited Loading

emmanuelle commented Jun 21, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jonmmease commented Jun 21, 2019

nicolaskruchten commented Jun 21, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jonmmease commented Jun 22, 2019

nicolaskruchten commented Jun 23, 2019

nicolaskruchten commented Jun 27, 2019

nicolaskruchten commented Jun 21, 2019 •

edited

Loading