Tidying up some docs

python/3d-bubble-charts.md

@@ -37,7 +37,7 @@ jupyter:
     title: Python 3D Bubble Charts | plotly
 ---
 
-### 3d Bubble chart with plotly express
+### 3d Bubble chart with Plotly Express
 
 ```python
 import plotly.express as px

python/3d-line-plots.md

@@ -36,7 +36,7 @@ jupyter:
     title: 3D Line Plots in Python | plotly
 ---
 
-### 3D Line plot with plotly express
+### 3D Line plot with Plotly Express
 
 ```python
 import plotly.express as px

python/3d-scatter-plots.md

@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.6.7
+    version: 3.6.8
   plotly:
     description: How to make 3D scatter plots in Python with Plotly.
     display_as: 3d_charts
@@ -37,9 +37,11 @@ jupyter:
     v4upgrade: true
 ---
 
-## 3D scatter plot with plotly express
+## 3D scatter plot with Plotly Express
 
-Like the [2D scatter plot](https://plot.ly/python/line-and-scatter/) `px.scatter`, the 3D function `px.scatter_3d` plots individual data in three-dimensional space. 
+[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/).
+
+Like the [2D scatter plot](https://plot.ly/python/line-and-scatter/) `px.scatter`, the 3D function `px.scatter_3d` plots individual data in three-dimensional space.
 
 ```python
 import plotly.express as px
@@ -78,7 +80,7 @@ fig.update_layout(margin=dict(l=0, r=0, b=0, t=0))
 
 #### Basic 3D Scatter Plot
 
-When data are not available as tidy dataframes, it is also possible to use the more generic `go.Scatter3D` from `plotly.graph_objs`.
+If Plotly Express does not provide a good starting point, it is also possible to use the more generic `go.Scatter3D` from `plotly.graph_objs`.
 Like the [2D scatter plot](https://plot.ly/python/line-and-scatter/) `go.Scatter`, `go.Scatter3d` plots individual data in three-dimensional space.
 
 ```python

python/animations.md

@@ -27,10 +27,10 @@ jupyter:
     v4upgrade: true
 ---
 
-#### Animated figures with plotly express
-Several plotly express functions support the creation of animated figures through the `animation_frame` and `animation_group` arguments.
+#### Animated figures with Plotly Express
+Several Plotly Express functions support the creation of animated figures through the `animation_frame` and `animation_group` arguments.
 
-Here is an example of an animated scatter plot creating using plotly express
+Here is an example of an animated scatter plot creating using Plotly Express
 
 ```python
 import plotly.express as px

python/axes.md

@@ -94,12 +94,12 @@ fig.update_yaxes(showgrid=False, zeroline=False)
 fig.show()
 ```
 
-##### Toggle grid and zerolines for figure created with plotly express
+##### Toggle grid and zerolines for figure created with Plotly Express
 
 
-An advantage of using the `update_xaxis` and `update_yaxis` methods is that these updates will (by default) apply to all axes in the figure.  This is especially useful when customizing figures created using plotly express, figure factories, or `make_subplots`.
+An advantage of using the `update_xaxis` and `update_yaxis` methods is that these updates will (by default) apply to all axes in the figure.  This is especially useful when customizing figures created using Plotly Express, figure factories, or `make_subplots`.
 
-Here is an example of disabling all grid and zero lines in a faceted figure created by plotly express.
+Here is an example of disabling all grid and zero lines in a faceted figure created by Plotly Express.
 
 ```python
 import plotly.express as px
@@ -115,7 +115,7 @@ fig.show()
 ##### Toggling axis tick marks
 Axis tick marks are disabled by default for the default `plotly` theme, but they can easily be turned on by setting the `ticks` axis property to `"inside"` (to place ticks inside plotting area) or `"outside"` (to place ticks outside the plotting area).
 
-Here is an example of turning on inside x-axis and y-axis ticks in a faceted figure created using plotly express. Note how the `col` argument to `update_yaxes` is used to only turn on the y-axis ticks for the left-most subplot.
+Here is an example of turning on inside x-axis and y-axis ticks in a faceted figure created using Plotly Express. Note how the `col` argument to `update_yaxes` is used to only turn on the y-axis ticks for the left-most subplot.
 
 ```python
 import plotly.express as px
@@ -131,7 +131,7 @@ fig.show()
 ##### Toggling axis labels
 The axis tick mark labels can be disabled by setting the `showticklabels` axis property to `False`.
 
-Here is an example of disabling tick labels in all subplots for a faceted figure created using plotly express.
+Here is an example of disabling tick labels in all subplots for a faceted figure created using Plotly Express.
 
 ```python
 import plotly.express as px
@@ -149,7 +149,7 @@ fig.show()
 ##### Set number of tick marks
 The approximate number of ticks displayed for an axis can be specified using the `nticks` axis property.
 
-Here is an example of updating the y-axes of a figure created using plotly express to display approximately 20 ticks.
+Here is an example of updating the y-axes of a figure created using Plotly Express to display approximately 20 ticks.
 
 ```python
 import plotly.express as px
@@ -164,7 +164,7 @@ fig.show()
 ##### Set start position and distance between ticks
 The `tick0` and `dtick` axis properties can be used to control to placement of axis ticks as follows:  If specified, a tick will fall exactly on the location of `tick0` and additional ticks will be added in both directions at intervals of `dtick`.
 
-Here is an example of updating the y axis of a figure created using plotly express to position the ticks at intervals of 0.5, starting at 0.25.
+Here is an example of updating the y axis of a figure created using Plotly Express to position the ticks at intervals of 0.5, starting at 0.25.
 
 ```python
 import plotly.express as px
@@ -179,7 +179,7 @@ fig.show()
 ##### Set exact location of axis ticks
 It is possible to configure an axis to display ticks at a set of predefined locations by setting the `tickvals` property to an array of positions.
 
-Here is an example of setting the exact location of ticks on the y axes of a figure created using plotly express.
+Here is an example of setting the exact location of ticks on the y axes of a figure created using Plotly Express.
 
 ```python
 import plotly.express as px
@@ -196,7 +196,7 @@ As discussed above, tick marks are disabled by default in the default `plotly` t
 
 The appearance of these tick marks can be customized by setting their length (`ticklen`), width (`tickwidth`), and color (`tickcolor`).
 
-Here is an example of enabling and styling the tick marks of a faceted figure created using plotly express.  Note how the `col` argument to `update_yaxes` is used to only turn on and style the y-axis ticks for the left-most subplot.
+Here is an example of enabling and styling the tick marks of a faceted figure created using Plotly Express.  Note how the `col` argument to `update_yaxes` is used to only turn on and style the y-axis ticks for the left-most subplot.
 
 ```python
 import plotly.express as px
@@ -227,7 +227,7 @@ fig.show()
 ```
 
 ##### Set axis title font
-Here is an example that configures the font family, size, and color for the axis titles in a figure created using plotly express.
+Here is an example that configures the font family, size, and color for the axis titles in a figure created using Plotly Express.
 
 ```python
 import plotly.express as px
@@ -243,7 +243,7 @@ fig.show()
 ##### Set axis label rotation and font
 The orientation of the axis tick mark labels is configured using the `tickangle` axis property. The value of `tickangle` is the angle of rotation, in the clockwise direction, of the labels from vertical in units of degrees.  The font family, size, and color for the tick labels are stored under the `tickfont` axis property.
 
-Here is an example of rotating the x-axis tick labels by 45 degrees, and customizing their font properties, in a faceted histogram figure created using plotly express.
+Here is an example of rotating the x-axis tick labels by 45 degrees, and customizing their font properties, in a faceted histogram figure created using Plotly Express.
 
 ```python
 import plotly.express as px
@@ -261,7 +261,7 @@ fig.show()
 ##### Styling axis lines
 The `showline` axis property controls the visibility of the axis line, and the `linecolor` and `linewidth` axis properties control the color and width of the axis line.
 
-Here is an example of enabling the x and y axis lines, and customizing their width and color, for a faceted histogram created with plotly express.
+Here is an example of enabling the x and y axis lines, and customizing their width and color, for a faceted histogram created with Plotly Express.
 
 ```python
 import plotly.express as px
@@ -277,7 +277,7 @@ fig.show()
 ##### Mirroring axis lines
 Axis lines can be mirrored to the opposite side of the plotting area by setting the `mirror` axis property to `True`.
 
-Here is an example of mirroring the x and y axis lines in a faceted histogram created using plotly express.
+Here is an example of mirroring the x and y axis lines in a faceted histogram created using Plotly Express.
 
 ```python
 import plotly.express as px
@@ -293,7 +293,7 @@ fig.show()
 ##### Styling grid lines
 The width and color of axis grid lines are controlled by the `gridwidth` and `gridcolor` axis properties.
 
-Here is an example of customizing the grid line width and color for a faceted scatter plot created with plotly express
+Here is an example of customizing the grid line width and color for a faceted scatter plot created with Plotly Express
 
 ```python
 import plotly.express as px
@@ -327,7 +327,7 @@ fig.show()
 #### Setting the Range of Axes Manually
 The visible x and y axis range can be configured manually by setting the `range` axis property  to a list of two values, the lower and upper boundary.
 
-Here's an example of manually specifying the x and y axis range for a faceted scatter plot created with plotly express.
+Here's an example of manually specifying the x and y axis range for a faceted scatter plot created with Plotly Express.
 
 ```python
 import plotly.express as px
@@ -444,7 +444,7 @@ fig.show()
 #### Reversed Axes
 You can tell plotly's automatic axis range calculation logic to reverse the direction of an axis by setting the `autorange` axis property to `"reversed"`.
 
-Here is an example of reversing the direction of the y axes for a faceted scatter plot created using plotly express.
+Here is an example of reversing the direction of the y axes for a faceted scatter plot created using Plotly Express.
 
 ```python
 import plotly.express as px
@@ -459,7 +459,7 @@ fig.show()
 #### Reversed Axes with Range ( Min/Max ) Specified
 The direction of an axis can be reversed when manually setting the range extents by specifying a list containing the upper bound followed by the lower bound (rather that the lower followed by the upper) as the `range` axis property.
 
-Here is an example of manually setting the reversed range of the y axes in a faceted scatter plot figure created using plotly express.
+Here is an example of manually setting the reversed range of the y axes in a faceted scatter plot figure created using Plotly Express.
 
 ```python
 import plotly.express as px
@@ -477,7 +477,7 @@ The axis auto-range calculation logic can be configured using the `rangemode` ax
 
 If `rangemode` is `"normal"` (the default), the range is computed based on the min and max values of the input data. If `"tozero"`, the the range will always include zero.  If `"nonnegative"`, the range will not extend below zero, regardless of the input data.
 
-Here is an example of configuring a faceted scatter plot created using plotly express to always include zero for both the x and y axes.
+Here is an example of configuring a faceted scatter plot created using Plotly Express to always include zero for both the x and y axes.
 
 ```python
 import plotly.express as px

python/bar-charts.md

@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.1'
-      jupytext_version: 1.2.1
+      jupytext_version: 1.1.1
   kernelspec:
     display_name: Python 3
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.7.3
+    version: 3.6.8
   plotly:
     description: How to make Bar Charts in Python with Plotly.
     display_as: basic
@@ -37,10 +37,12 @@ jupyter:
     v4upgrade: true
 ---
 
-### Bar chart with plotly express
+### Bar chart with Plotly Express
 
 
-In a bar plot, each row of the DataFrame is represented as a rectangular mark.
+[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/).
+
+With `px.bar`, each row of the DataFrame is represented as a rectangular mark.
 
 ```python
 import plotly.express as px
@@ -53,7 +55,7 @@ fig.show()
 data_canada
 ```
 
-### Customize bar chart with plotly express
+### Customize bar chart with Plotly Express
 
 The bar plot can be customized using keyword arguments.
 
@@ -103,7 +105,7 @@ To learn more, see the *link to px.bar reference page*.
 
 #### Basic Bar Chart with plotly.graph_objects
 
-When data are not available as tidy dataframes, it is also possible to use the more generic `go.Bar` function from `plotly.graph_objects`.
+If Plotly Express does not provide a good starting point, it is also possible to use the more generic `go.Bar` function from `plotly.graph_objects`.
 
 ```python
 import plotly.graph_objects as go
@@ -327,7 +329,7 @@ fig.show()
 
 ### Bar Chart with Sorted or Ordered Categories
 
-Set `categoryorder` to "category ascending/descending" for the alphanumerical order of the category names or "total ascending/descending" for numerical order of values. [categoryorder](https://plot.ly/python/reference/#layout-xaxis-categoryorder) for more information. 
+Set `categoryorder` to "category ascending/descending" for the alphanumerical order of the category names or "total ascending/descending" for numerical order of values. [categoryorder](https://plot.ly/python/reference/#layout-xaxis-categoryorder) for more information.
 
 ```python
 import plotly.graph_objects as go

python/box-plots.md

@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.6.7
+    version: 3.6.8
   plotly:
     description: How to make Box Plots in Python with Plotly.
     display_as: statistical
@@ -40,7 +40,9 @@ jupyter:
 A [box plot](https://en.wikipedia.org/wiki/Box_plot) is a statistical representation of numerical data through their quartiles. The ends of the box represent the lower and upper quartiles, while the median (second quartile) is marked by a line inside the box. For other statistical representations of numerical data, see [other statistical charts](https://plot.ly/python/statistical-charts/).
 
 
-## Box Plot with plotly express
+## Box Plot with Plotly Express
+
+[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/).
 
 In a box plot created by `px.box`, the distribution of the column given as `y` argument is represented.
 
@@ -89,7 +91,7 @@ fig.show()
 
 ## Box plot with go.Box
 
-When data are not available as tidy dataframes, it is also possible to use the more generic `go.Box` function from `plotly.graph_objects`. All available options for `go.Box` are described in the reference page https://plot.ly/python/reference/#box.
+If Plotly Express does not provide a good starting point, it is also possible to use the more generic `go.Box` function from `plotly.graph_objects`. All available options for `go.Box` are described in the reference page https://plot.ly/python/reference/#box.
 
 ### Basic Box Plot ###
 

python/bubble-charts.md

@@ -42,7 +42,7 @@ jupyter:
 
 A [bubble chart](https://en.wikipedia.org/wiki/Bubble_chart) is a scatter plot in which a third dimension of the data is shown through the size of markers. For other types of scatter plot, see the [line and scatter page](https://plot.ly/python/line-and-scatter/).
 
-We first show a bubble chart example using plotly express. [Plotly Express](../plotly-express/) functions take as a first argument a [tidy `pandas.DataFrame`](https://www.jeannicholashould.com/tidy-data-in-python.html). The size of markers is set from the dataframe column given as the `size` parameter.
+We first show a bubble chart example using Plotly Express. [Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/). The size of markers is set from the dataframe column given as the `size` parameter.
 
 ```python
 import plotly.express as px
@@ -56,7 +56,7 @@ fig.show()
 
 ## Bubble Chart with plotly.graph_objects
 
-When data are not available as tidy dataframes, it is also possible to use the more generic `go.Scatter` from `plotly.graph_objects`, and define the size of markers to create a bubble chart. All of the available options are described in the scatter section of the reference page: https://plot.ly/python/reference#scatter.
+If Plotly Express does not provide a good starting point, it is also possible to use the more generic `go.Scatter` from `plotly.graph_objects`, and define the size of markers to create a bubble chart. All of the available options are described in the scatter section of the reference page: https://plot.ly/python/reference#scatter.
 
 ### Simple Bubble Chart
 

python/bubble-maps.md

@@ -36,9 +36,9 @@ jupyter:
     v4upgrade: true
 ---
 
-### Bubble map with plotly express
+### Bubble map with Plotly Express
 
-[Plotly Express](../plotly-express/) functions take as a first argument a [tidy `pandas.DataFrame`](https://www.jeannicholashould.com/tidy-data-in-python.html). With ``px.scatter_geo``, each line of the dataframe is represented as a marker point. The column set as the `size` argument gives the size of markers.
+[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/). With ``px.scatter_geo``, each line of the dataframe is represented as a marker point. The column set as the `size` argument gives the size of markers.
 
 ```python
 import plotly.express as px

python/choropleth-maps.md

@@ -29,10 +29,12 @@ jupyter:
 
 A [Choropleth Map](https://en.wikipedia.org/wiki/Choropleth_map) is a heatmap using geographical boundaries. It is used to represent spatial variations of a quantity. See also the [index of other geographical charts](../maps/).
 
-Below we show how to create Choropleth Maps using either `px.choropleth` (one-liner function call for data as tidy pandas DataFrame) or for the more generic case `go.Choropleth`.
+Below we show how to create Choropleth Maps using either Plotly Express' `px.choropleth` or the lower-level `go.Choropleth`.
 
 ### Choropleth Map with plotly.express
 
+[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/).
+
 ```python
 import plotly.express as px
 

python/colorscales.md

@@ -37,10 +37,10 @@ jupyter:
     v4upgrade: true
 ---
 
-### Predefined colorscales in plotly express
+### Predefined colorscales in Plotly Express
 A collection of predefined sequential colorscales is provided in the `plotly.express.colors.sequential` module.
 
-Here is an example that creates a scatter plot using plotly express, with points colored using the Viridis colorscale.
+Here is an example that creates a scatter plot using Plotly Express, with points colored using the Viridis colorscale.
 
 ```python
 import plotly.express as px