standardizing language around tidy data

nicolaskruchten · nicolaskruchten · commit 173b11c27eaa · 2019-10-27T22:31:09.000-07:00
diff --git a/python/3d-scatter-plots.md b/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
@@ -39,7 +39,9 @@ jupyter:
 
 ## 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
diff --git a/python/bar-charts.md b/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
@@ -40,7 +40,9 @@ jupyter:
 ### 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
@@ -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
diff --git a/python/box-plots.md b/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
@@ -42,6 +42,8 @@ A [box plot](https://en.wikipedia.org/wiki/Box_plot) is a statistical representa
 
 ## 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 ###
 
diff --git a/python/bubble-charts.md b/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
 
diff --git a/python/bubble-maps.md b/python/bubble-maps.md
@@ -38,7 +38,7 @@ jupyter:
 
 ### 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
diff --git a/python/choropleth-maps.md b/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
 
diff --git a/python/distplot.md b/python/distplot.md
@@ -40,7 +40,7 @@ jupyter:
 
 Several representations of statistical distributions are available in plotly, such as [histograms](https://plot.ly/python/histograms/), [violin plots](https://plot.ly/python/violin/), [box plots](https://plot.ly/python/box-plots/) (see [the complete list here](https://plot.ly/python/statistical-charts/)). It is also possible to combine several representations in the same plot.
 
-For example, the `plotly.express` function `px.histogram` can add a subplot with a different statistical representation than the histogram, given by the parameter `marginal`. [Plotly Express](../plotly-express/) functions take as a first argument a [tidy `pandas.DataFrame`](https://www.jeannicholashould.com/tidy-data-in-python.html).
+For example, the `plotly.express` function `px.histogram` can add a subplot with a different statistical representation than the histogram, given by the parameter `marginal`. [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
diff --git a/python/dot-plots.md b/python/dot-plots.md
@@ -39,10 +39,12 @@ jupyter:
 
 #### Basic Dot Plot
 
-Dot plots (also known as [Cleveland dot plots](https://en.wikipedia.org/wiki/Dot_plot_(statistics))) show changes between two (or more) points in time or between two (or more) conditions. Compared to a [bar chart](../bar-charts/), dot plots can be less cluttered and allow for an easier comparison between conditions. 
+Dot plots (also known as [Cleveland dot plots](https://en.wikipedia.org/wiki/Dot_plot_(statistics))) show changes between two (or more) points in time or between two (or more) conditions. Compared to a [bar chart](../bar-charts/), dot plots can be less cluttered and allow for an easier comparison between conditions.
 
 For the same data, we show below how to create a dot plot using either `px.scatter` (for a tidy pandas DataFrame) or `go.Scatter`.
 
+[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
 import pandas as pd
diff --git a/python/error-bars.md b/python/error-bars.md
@@ -39,7 +39,7 @@ jupyter:
 
 ### Error Bars 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). For functions representing 2D data points such as [`px.scatter`](https://plot.ly/python/line-and-scatter/), [`px.line`](https://plot.ly/python/line-charts/), [`px.bar`](https://plot.ly/python/bar-charts/) etc., error bars are given as a column name which is the value of the `error_x` (for the error on x position) and `error_y` (for the error on y position).
+[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/). For functions representing 2D data points such as [`px.scatter`](https://plot.ly/python/line-and-scatter/), [`px.line`](https://plot.ly/python/line-charts/), [`px.bar`](https://plot.ly/python/bar-charts/) etc., error bars are given as a column name which is the value of the `error_x` (for the error on x position) and `error_y` (for the error on y position).
 
 ```python
 import plotly.express as px
diff --git a/python/filled-area-plots.md b/python/filled-area-plots.md
@@ -42,7 +42,7 @@ This example shows how to fill the area enclosed by traces.
 
 ## Filled area plot 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).
+[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/).
 
 `px.area` creates a stacked area plot. Each filled area corresponds to one value of the column given by the `line_group` parameter.
 
diff --git a/python/histograms.md b/python/histograms.md
@@ -42,7 +42,7 @@ jupyter:
 
 In statistics, a [histogram](https://en.wikipedia.org/wiki/Histogram) is representation of the distribution of numerical data, where the data are binned and the count for each bin is represented. More generally, in plotly a histogram is an aggregated bar chart, with several possible aggregation functions (e.g. sum, average, count...). Also, the data to be binned can be numerical data but also categorical or date data.
 
-[Plotly Express](../plotly-express/) functions take as a first argument a [tidy `pandas.DataFrame`](https://www.jeannicholashould.com/tidy-data-in-python.html).
+[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
@@ -130,7 +130,7 @@ fig.show()
 
 ## Histograms with go.Histogram
 
-When data are not available as tidy dataframes, it is also possible to use the more generic `go.Histogram` from `plotly.graph_objects`. All of the available histogram options are described in the histogram section of the reference page: https://plot.ly/python/reference#histogram.
+If Plotly Express does not provide a good starting point, it is also possible to use the more generic `go.Histogram` from `plotly.graph_objects`. All of the available histogram options are described in the histogram section of the reference page: https://plot.ly/python/reference#histogram.
 
 ### Basic Histogram ###
 
diff --git a/python/horizontal-bar-charts.md b/python/horizontal-bar-charts.md
@@ -42,7 +42,7 @@ See more examples of bar charts (including vertical bar charts) and styling opti
 
 ### Horizontal Bar Chart 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). For a horizontal bar char, use the `px.bar` function with `orientation='h'`.
+[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/). For a horizontal bar char, use the `px.bar` function with `orientation='h'`.
 
 
 #### Basic Horizontal Bar Chart with plotly express
diff --git a/python/line-and-scatter.md b/python/line-and-scatter.md
@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.1'
-      jupytext_version: 1.2.3
+      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 scatter plots in Python with Plotly.
     display_as: basic
@@ -40,6 +40,8 @@ jupyter:
 
 ## Scatter 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/).
+
 With ``px.scatter``, each data point is represented as a marker point, which location is given by the `x` and `y` columns.
 
 ```python
@@ -90,7 +92,7 @@ fig.show()
 
 ## Scatter and line plot with go.Scatter
 
-When data are not available as tidy dataframes, it is possible to use the more generic `go.Scatter` function from `plotly.graph_objects`. Whereas `plotly.express` has two functions `scatter` and `line`, `go.Scatter` can be used both for plotting points (makers) or lines, depending on the value of `mode`. The different options of `go.Scatter` are documented in its [reference page](https://plot.ly/python/reference/#scatter ).
+If Plotly Express does not provide a good starting point, it is possible to use the more generic `go.Scatter` function from `plotly.graph_objects`. Whereas `plotly.express` has two functions `scatter` and `line`, `go.Scatter` can be used both for plotting points (makers) or lines, depending on the value of `mode`. The different options of `go.Scatter` are documented in its [reference page](https://plot.ly/python/reference/#scatter ).
 
 
 #### Simple Scatter Plot
diff --git a/python/line-charts.md b/python/line-charts.md
@@ -40,7 +40,7 @@ jupyter:
 
 ### Line Plot 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.line``, each data point is represented as a vertex (which location is given by the `x` and `y` columns) of a **polyline mark** in 2D space.
+[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.line``, each data point is represented as a vertex (which location is given by the `x` and `y` columns) of a **polyline mark** in 2D space.
 
 For more examples of line plots, see the [line and scatter notebook](https://plot.ly/python/line-and-scatter/).
 
@@ -75,7 +75,7 @@ fig.show()
 
 ### Line Plot with go.Scatter
 
-When data are not available as tidy dataframes, it is possible to use the more generic `go.Scatter` function from `plotly.graph_objects`. Whereas `plotly.express` has two functions `scatter` and `line`, `go.Scatter` can be used both for plotting points (makers) or lines, depending on the value of `mode`. The different options of `go.Scatter` are documented in its [reference page](https://plot.ly/python/reference/#scatter ).
+If Plotly Express does not provide a good starting point, it is possible to use the more generic `go.Scatter` function from `plotly.graph_objects`. Whereas `plotly.express` has two functions `scatter` and `line`, `go.Scatter` can be used both for plotting points (makers) or lines, depending on the value of `mode`. The different options of `go.Scatter` are documented in its [reference page](https://plot.ly/python/reference/#scatter ).
 
 
 #### Simple Line Plot
diff --git a/python/lines-on-maps.md b/python/lines-on-maps.md
@@ -39,15 +39,17 @@ jupyter:
 
 For other geographical and map charts see [the maps index page](../maps/).
 
-Below we show how to create geographical line plots using either plotly express with `px.line_geo` (for data available as tidy pandas DataFrame) or `go.Scattergeo` for the generic case.
+Below we show how to create geographical line plots using either plotly express with `px.line_geo` or the lower-level `go.Scattergeo`.
 
 ## Lines on Maps 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
 gapminder = px.data.gapminder().query("year == 2007")
-fig = px.line_geo(gapminder, locations="iso_alpha", 
-                  color="continent", # "continent" is one of the columns of gapminder 
+fig = px.line_geo(gapminder, locations="iso_alpha",
+                  color="continent", # "continent" is one of the columns of gapminder
                   projection="orthographic")
 fig.show()
 ```
diff --git a/python/parallel-coordinates-plot.md b/python/parallel-coordinates-plot.md
@@ -41,7 +41,7 @@ jupyter:
 
 ## Parallel Coordinates plot 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). In a parallel coordinates plot with `px.parallel_coordinates`, each row of the DataFrame is represented by a polyline mark which traverses a set of parallel axes, one for each of the dimensions. For other representations of multivariate data, also see [radar charts](../radar-chart/) and [scatterplot matrix (SPLOM)](../splom/).
+[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 parallel coordinates plot with `px.parallel_coordinates`, each row of the DataFrame is represented by a polyline mark which traverses a set of parallel axes, one for each of the dimensions. For other representations of multivariate data, also see [radar charts](../radar-chart/) and [scatterplot matrix (SPLOM)](../splom/).
 
 ```python
 import plotly.express as px
diff --git a/python/polar-chart.md b/python/polar-chart.md
diff --git a/python/px-arguments.md b/python/px-arguments.md
diff --git a/python/radar-chart.md b/python/radar-chart.md
diff --git a/python/scatter-plots-on-maps.md b/python/scatter-plots-on-maps.md
diff --git a/python/scattermapbox.md b/python/scattermapbox.md
diff --git a/python/splom.md b/python/splom.md
diff --git a/python/violin.md b/python/violin.md
diff --git a/python/wind-rose-charts.md b/python/wind-rose-charts.md
