Merge pull request #3326 from plotly/px_line_marker

ability to show markers on lines

CHANGELOG.md

@@ -7,6 +7,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Added
   - Extra flags were added to the `gapminder` and `stocks` dataset to facilitate testing, documentation and demos [#3305](https://github.com/plotly/plotly.py/issues/3305)
+  - All line-like Plotly Express functions now accept `markers` argument to display markers, and all but `line_mapbox` accept `symbol` to map a field to the symbol attribute, similar to scatter-like functions [#3326](https://github.com/plotly/plotly.py/issues/3326)
 
 ### Fixed
   - Fixed regression introduced in version 5.0.0 where pandas/numpy arrays with `dtype` of Object were being converted to `list` values when added to a Figure ([#3292](https://github.com/plotly/plotly.py/issues/3292), [#3293](https://github.com/plotly/plotly.py/pull/3293))

doc/python/axes.md

@@ -51,7 +51,7 @@ Other kinds of subplots and axes are described in other tutorials:
 The different types of Cartesian axes are configured via the `xaxis.type` or `yaxis.type` attribute, which can take on the following values:
 
 - `'linear'` as described in this page
-- `'log'` (see the [log plot tutorial](/python/log-plots/))
+- `'log'` (see the [log plot tutorial](/python/log-plot/))
 - `'date'` (see the [tutorial on timeseries](/python/time-series/))
 - `'category'` (see the [categorical axes tutorial](/python/categorical-axes/))
 - `'multicategory'` (see the [categorical axes tutorial](/python/categorical-axes/))

doc/python/bubble-charts.md

@@ -5,8 +5,8 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.1'
-      jupytext_version: 1.1.1
+      format_version: '1.2'
+      jupytext_version: 1.4.2
   kernelspec:
     display_name: Python 3
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.6.7
+    version: 3.7.7
   plotly:
     description: How to make bubble charts in Python with Plotly.
     display_as: basic
@@ -36,7 +36,7 @@ jupyter:
 
 ## Bubble chart with plotly.express
 
-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://plotly.com/python/line-and-scatter/).
+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 [scatter plot documentation](https://plotly.com/python/line-and-scatter/).
 
 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 a variety of types of data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/). The size of markers is set from the dataframe column given as the `size` parameter.
 
@@ -222,4 +222,4 @@ fig.show()
 
 ### Reference
 
-See https://plotly.com/python/reference/scatter/ for more information and chart attribute options!
+See https://plotly.com/python/reference/scatter/ for more information and chart attribute options!

doc/python/categorical-axes.md

@@ -41,7 +41,7 @@ This page shows examples of how to configure [2-dimensional Cartesian axes](/pyt
 The different types of Cartesian axes are configured via the `xaxis.type` or `yaxis.type` attribute, which can take on the following values:
 
 - `'linear'` (see the [linear axes tutorial](/python/axes/))
-- `'log'` (see the [log plot tutorial](/python/log-plots/))
+- `'log'` (see the [log plot tutorial](/python/log-plot/))
 - `'date'` (see the [tutorial on timeseries](/python/time-series/))
 - `'category'` see below
 - `'multicategory'` see below
@@ -64,6 +64,39 @@ fig.update_xaxes(type='category')
 fig.show()
 ```
 
+### Categorical Axes and Trace Types
+
+Every cartesian trace type is compatible with categorical axes, not just `bar`.
+
+Scatter plots where one axis is categorical are often known as [dot plots](https://plotly.com/python/dot-plots/).
+
+```python
+import plotly.express as px
+df = px.data.medals_long()
+
+fig = px.scatter(df, y="nation", x="count", color="medal", symbol="medal")
+fig.update_traces(marker_size=10)
+fig.show()
+```
+
+[Box plots]() and [violin plots]() are often shown with one categorical and one continuous axis.
+
+```python
+import plotly.express as px
+df = px.data.tips()
+
+fig = px.box(df, x="sex", y="total_bill", color="smoker")
+fig.show()
+```
+
+```python
+import plotly.express as px
+df = px.data.tips()
+
+fig = px.violin(df, x="sex", y="total_bill", color="smoker")
+fig.show()
+```
+
 ### Controlling the Category Order with Plotly Express
 
 [Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on a variety of types of data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/).

doc/python/dot-plots.md

@@ -5,8 +5,8 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.1'
-      jupytext_version: 1.1.1
+      format_version: '1.2'
+      jupytext_version: 1.4.2
   kernelspec:
     display_name: Python 3
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.6.7
+    version: 3.7.7
   plotly:
     description: How to make dot plots in Python with Plotly.
     display_as: basic
@@ -35,12 +35,21 @@ 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](/python/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)>)) are [scatter plots](https://plotly.com/python/line-and-scatter/) with one categorical axis and one continuous axis. They can be used to show changes between two (or more) points in time or between two (or more) conditions. Compared to a [bar chart](/python/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` or `go.Scatter`.
 
 [Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on a variety of types of data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/).
 
+```python
+import plotly.express as px
+df = px.data.medals_long()
+
+fig = px.scatter(df, y="nation", x="count", color="medal", symbol="medal")
+fig.update_traces(marker_size=10)
+fig.show()
+```
+
 ```python
 import plotly.express as px
 import pandas as pd

doc/python/line-and-scatter.md

@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.2'
-      jupytext_version: 1.6.0
+      jupytext_version: 1.4.2
   kernelspec:
     display_name: Python 3
     language: python
@@ -34,7 +34,7 @@ jupyter:
     thumbnail: thumbnail/line-and-scatter.jpg
 ---
 
-## Scatter plot with Plotly Express
+## Scatter plots with Plotly Express
 
 [Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on a variety of types of data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/).
 
@@ -55,9 +55,9 @@ fig = px.scatter(df, x="sepal_width", y="sepal_length")
 fig.show()
 ```
 
-#### Set size and color with column names
+#### Setting size and color with column names
 
-Note that `color` and `size` data are added to hover information. You can add other columns to hover data with the `hover_data` argument of `px.scatter`.
+Scatter plots with variable-sized circular markers are often known as [bubble charts](https://plotly.com/python/bubble-charts/). Note that `color` and `size` data are added to hover information. You can add other columns to hover data with the `hover_data` argument of `px.scatter`.
 
 ```python
 import plotly.express as px
@@ -67,7 +67,16 @@ fig = px.scatter(df, x="sepal_width", y="sepal_length", color="species",
 fig.show()
 ```
 
-## Scatter plot in Dash
+The `symbol` argument can be mapped to a column as well. A [wide variety of symbols](https://plotly.com/python/marker-style/) are available.
+
+```python
+import plotly.express as px
+df = px.data.iris()
+fig = px.scatter(df, x="sepal_width", y="sepal_length", color="species", symbol="species")
+fig.show()
+```
+
+## Scatter plots in Dash
 
 [Dash](https://plotly.com/dash/) is the best way to build analytical apps in Python using Plotly figures. To run the app below, run `pip install dash`, click "Download" to get the code and run `python app.py`.
 
@@ -80,7 +89,22 @@ snippet_url = 'https://dash-gallery.plotly.host/python-docs-dash-snippets/'
 IFrame(snippet_url + 'line-and-scatter', width='100%', height=630)
 ```
 
-## Line plot with Plotly Express
+### Scatter plots and Categorical Axes
+
+Scatters plots can be made on using any type of cartesian axis, including [linear](https://plotly.com/python/axes/), [logarithmic](https://plotly.com/python/log-plot/), [categorical](https://plotly.com/python/categorical-axes/) or [date](https://plotly.com/python/time-series/) axes.
+
+Scatter plots where one axis is categorical are often known as [dot plots](https://plotly.com/python/dot-plots/).
+
+```python
+import plotly.express as px
+df = px.data.medals_long()
+
+fig = px.scatter(df, y="nation", x="count", color="medal", symbol="medal")
+fig.update_traces(marker_size=10)
+fig.show()
+```
+
+## Line plots with Plotly Express
 
 ```python
 import plotly.express as px
@@ -99,7 +123,75 @@ fig = px.line(df, x='year', y='lifeExp', color='country')
 fig.show()
 ```
 
-## Scatter and line plot with go.Scatter
+The `markers` argument can be set to `True` to show markers on lines.
+
+```python
+import plotly.express as px
+df = px.data.gapminder().query("continent == 'Oceania'")
+fig = px.line(df, x='year', y='lifeExp', color='country', markers=True)
+fig.show()
+```
+
+The `symbol` argument can be used to map a data field to the marker symbol. A [wide variety of symbols](https://plotly.com/python/marker-style/) are available.
+
+```python
+import plotly.express as px
+df = px.data.gapminder().query("continent == 'Oceania'")
+fig = px.line(df, x='year', y='lifeExp', color='country', symbol="country")
+fig.show()
+```
+
+### Line plots on Date axes
+
+Line plots can be made on using any type of cartesian axis, including [linear](https://plotly.com/python/axes/), [logarithmic](https://plotly.com/python/log-plot/), [categorical](https://plotly.com/python/categorical-axes/) or date axes. Line plots on date axes are often called [time-series charts](https://plotly.com/python/time-series/).
+
+Plotly auto-sets the axis type to a date format when the corresponding data are either ISO-formatted date strings or if they're a [date pandas column](https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html) or [datetime NumPy array](https://docs.scipy.org/doc/numpy/reference/arrays.datetime.html).
+
+```python
+import plotly.express as px
+
+df = px.data.stocks()
+fig = px.line(df, x='date', y="GOOG")
+fig.show()
+```
+
+### Data Order in Scatter and Line Charts
+
+Plotly line charts are implemented as [connected scatterplots](https://www.data-to-viz.com/graph/connectedscatter.html) (see below), meaning that the points are plotted and connected with lines **in the order they are provided, with no automatic reordering**. 
+
+This makes it possible to make charts like the one below, but also means that it may be required to explicitly sort data before passing it to Plotly to avoid lines moving "backwards" across the chart.
+
+```python
+import plotly.express as px
+import pandas as pd
+
+df = pd.DataFrame(dict(
+    x = [1, 3, 2, 4],
+    y = [1, 2, 3, 4]
+))
+fig = px.line(df, x="x", y="y", title="Unsorted Input") 
+fig.show()
+
+df = df.sort_values(by="x")
+fig = px.line(df, x="x", y="y", title="Sorted Input") 
+fig.show()
+```
+
+### Connected Scatterplots
+
+In a connected scatterplot, two continuous variables are plotted against each other, with a line connecting them in some meaningful order, usually a time variable. In the plot below, we show the "trajectory" of a pair of countries through a space defined by GDP per Capita and Life Expectancy. Botswana's life expectancy 
+
+```python
+import plotly.express as px
+
+df = px.data.gapminder().query("country in ['Canada', 'Botswana']")
+
+fig = px.line(df, x="lifeExp", y="gdpPercap", color="country", text="year")
+fig.update_traces(textposition="bottom right")
+fig.show()
+```
+
+## Scatter and line plots with go.Scatter
 
 If Plotly Express does not provide a good starting point, it is possible to use [the more generic `go.Scatter` class from `plotly.graph_objects`](/python/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://plotly.com/python/reference/scatter/).