diff --git a/.circleci/config.yml b/.circleci/config.yml index 151471f0f3a..5e58717cc4a 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -425,8 +425,8 @@ jobs: . venv/bin/activate echo ${mapbox_token} > python/.mapbox_token make -kj8 || make -kj8 - curl https://raw.githubusercontent.com/plotly/documentation/source-design-merge/front-matter-ci.py > front-matter-ci.py - curl https://raw.githubusercontent.com/plotly/documentation/source-design-merge/check-or-enforce-order.py > check-or-enforce-order.py + curl https://raw.githubusercontent.com/plotly/graphing-library-docs/master/front-matter-ci.py > front-matter-ci.py + curl https://raw.githubusercontent.com/plotly/graphing-library-docs/master/check-or-enforce-order.py > check-or-enforce-order.py python front-matter-ci.py build/html python check-or-enforce-order.py build/html if [ "${CIRCLE_BRANCH}" == "doc-prod" ]; then @@ -448,14 +448,14 @@ jobs: name: trigger doc build command: | if [ "${CIRCLE_BRANCH}" == "doc-prod" ]; then - git clone --depth=1 --branch=source-design-merge https://github.com/plotly/documentation.git - cd documentation + git clone --depth=1 https://github.com/plotly/graphing-library-docs.git + cd graphing-library-docs git config user.name plotlydocbot git config user.email accounts@plot.ly git commit --allow-empty -m "deploying https://github.com/plotly/plotly.py/commit/${CIRCLE_SHA1}" git push cd .. - rm -rf documentation + rm -rf graphing-library-docs fi - run: diff --git a/binder/requirements.txt b/binder/requirements.txt index 52868c42d97..d59fb34283f 100644 --- a/binder/requirements.txt +++ b/binder/requirements.txt @@ -12,3 +12,5 @@ psutil requests networkx scikit-image +datashader +pyarrow diff --git a/doc/python/3d-scatter-plots.md b/doc/python/3d-scatter-plots.md index 0d5beba1bb8..e102cac7fe4 100644 --- a/doc/python/3d-scatter-plots.md +++ b/doc/python/3d-scatter-plots.md @@ -35,7 +35,7 @@ jupyter: ## 3D 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/). +[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-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. diff --git a/doc/python/bar-charts.md b/doc/python/bar-charts.md index 883140cb7e3..d4302dac5d0 100644 --- a/doc/python/bar-charts.md +++ b/doc/python/bar-charts.md @@ -5,7 +5,7 @@ jupyter: text_representation: extension: .md format_name: markdown - format_version: '1.2' + format_version: "1.2" jupytext_version: 1.3.0 kernelspec: display_name: Python 3 @@ -35,7 +35,7 @@ jupyter: ### Bar chart 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/). +[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/). With `px.bar`, each row of the DataFrame is represented as a rectangular mark. diff --git a/doc/python/box-plots.md b/doc/python/box-plots.md index bcb3ea81466..9a4fddd4dac 100644 --- a/doc/python/box-plots.md +++ b/doc/python/box-plots.md @@ -5,7 +5,7 @@ jupyter: text_representation: extension: .md format_name: markdown - format_version: '1.2' + format_version: "1.2" jupytext_version: 1.3.1 kernelspec: display_name: Python 3 @@ -31,8 +31,8 @@ jupyter: page_type: example_index permalink: python/box-plots/ redirect_from: - - /python/box/ - - /python/basic_statistics/ + - /python/box/ + - /python/basic_statistics/ thumbnail: thumbnail/box.jpg --- @@ -40,7 +40,7 @@ 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/). +[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/). In a box plot created by `px.box`, the distribution of the column given as `y` argument is represented. @@ -73,13 +73,13 @@ fig.show() ### Choosing The Algorithm For Computing Quartiles -By default, quartiles for box plots are computed using the `linear` method (for more about linear interpolation, see #10 listed on [http://www.amstat.org/publications/jse/v14n3/langford.html](http://www.amstat.org/publications/jse/v14n3/langford.html) and [https://en.wikipedia.org/wiki/Quartile](https://en.wikipedia.org/wiki/Quartile) for more details). +By default, quartiles for box plots are computed using the `linear` method (for more about linear interpolation, see #10 listed on [http://www.amstat.org/publications/jse/v14n3/langford.html](http://www.amstat.org/publications/jse/v14n3/langford.html) and [https://en.wikipedia.org/wiki/Quartile](https://en.wikipedia.org/wiki/Quartile) for more details). -However, you can also choose to use an `exclusive` or an `inclusive` algorithm to compute quartiles. +However, you can also choose to use an `exclusive` or an `inclusive` algorithm to compute quartiles. -The *exclusive* algorithm uses the median to divide the ordered dataset into two halves. If the sample is odd, it does not include the median in either half. Q1 is then the median of the lower half and Q3 is the median of the upper half. +The _exclusive_ algorithm uses the median to divide the ordered dataset into two halves. If the sample is odd, it does not include the median in either half. Q1 is then the median of the lower half and Q3 is the median of the upper half. -The *inclusive* algorithm also uses the median to divide the ordered dataset into two halves, but if the sample is odd, it includes the median in both halves. Q1 is then the median of the lower half and Q3 the median of the upper half. +The _inclusive_ algorithm also uses the median to divide the ordered dataset into two halves, but if the sample is odd, it includes the median in both halves. Q1 is then the median of the lower half and Q3 the median of the upper half. ```python import plotly.express as px @@ -92,7 +92,8 @@ fig.show() ``` #### Difference Between Quartile Algorithms -It can sometimes be difficult to see the difference between the linear, inclusive, and exclusive algorithms for computing quartiles. In the following example, the same dataset is visualized using each of the three different quartile computation algorithms. + +It can sometimes be difficult to see the difference between the linear, inclusive, and exclusive algorithms for computing quartiles. In the following example, the same dataset is visualized using each of the three different quartile computation algorithms. ```python import plotly.express as px @@ -103,7 +104,7 @@ df = pd.DataFrame(dict( linear=data, inclusive=data, exclusive=data -)).melt(var_name="quartilemethod") +)).melt(var_name="quartilemethod") fig = px.box(df, y="value", facet_col="quartilemethod", color="quartilemethod", @@ -204,7 +205,7 @@ fig.show() You can specify precomputed quartile attributes rather than using a built-in quartile computation algorithm. -This could be useful if you have already pre-computed those values or if you need to use a different algorithm than the ones provided. +This could be useful if you have already pre-computed those values or if you need to use a different algorithm than the ones provided. ```python import plotly.graph_objects as go @@ -217,9 +218,9 @@ fig.add_trace(go.Box(y=[ [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ] ], name="Precompiled Quartiles")) -fig.update_traces(q1=[ 1, 2, 3 ], median=[ 4, 5, 6 ], - q3=[ 7, 8, 9 ], lowerfence=[-1, 0, 1], - upperfence=[5, 6, 7], mean=[ 2.2, 2.8, 3.2 ], +fig.update_traces(q1=[ 1, 2, 3 ], median=[ 4, 5, 6 ], + q3=[ 7, 8, 9 ], lowerfence=[-1, 0, 1], + upperfence=[5, 6, 7], mean=[ 2.2, 2.8, 3.2 ], sd=[ 0.2, 0.4, 0.6 ], notchspan=[ 0.2, 0.4, 0.6 ] ) fig.show() diff --git a/doc/python/bubble-charts.md b/doc/python/bubble-charts.md index d9df36022db..4018c782b7d 100644 --- a/doc/python/bubble-charts.md +++ b/doc/python/bubble-charts.md @@ -38,7 +38,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](/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. +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/) 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. ```python import plotly.express as px diff --git a/doc/python/bubble-maps.md b/doc/python/bubble-maps.md index 6563221d923..864312a6a1e 100644 --- a/doc/python/bubble-maps.md +++ b/doc/python/bubble-maps.md @@ -39,7 +39,7 @@ Plotly figures made with `px.scatter_geo`, `px.line_geo` or `px.choropleth` func ### Bubble 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/). 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/) and produces [easy-to-style figures](/python/styling-plotly-express/). 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/doc/python/choropleth-maps.md b/doc/python/choropleth-maps.md index ca2b1383f58..b847966b30c 100644 --- a/doc/python/choropleth-maps.md +++ b/doc/python/choropleth-maps.md @@ -56,7 +56,7 @@ The GeoJSON data is passed to the `geojson` argument, and the data is passed int ### 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/). +[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/). #### GeoJSON with `feature.id` diff --git a/doc/python/datashader.md b/doc/python/datashader.md new file mode 100644 index 00000000000..9a9a3ba9f52 --- /dev/null +++ b/doc/python/datashader.md @@ -0,0 +1,129 @@ +--- +jupyter: + jupytext: + notebook_metadata_filter: all + text_representation: + extension: .md + format_name: markdown + format_version: "1.2" + jupytext_version: 1.3.1 + kernelspec: + display_name: Python 3 + language: python + name: python3 + language_info: + codemirror_mode: + name: ipython + version: 3 + file_extension: .py + mimetype: text/x-python + name: python + nbconvert_exporter: python + pygments_lexer: ipython3 + version: 3.6.8 + plotly: + description: + How to use datashader to rasterize large datasets, and visualize + the generated raster data with plotly. + display_as: scientific + language: python + layout: base + name: Plotly and Datashader + order: 21 + page_type: u-guide + permalink: python/datashader/ + thumbnail: thumbnail/datashader.jpg +--- + +[datashader](https://datashader.org/) creates rasterized representations of large datasets for easier visualization, with a pipeline approach consisting of several steps: projecting the data on a regular grid, creating a color representation of the grid, etc. + +### Passing datashader rasters as a mabox image layer + +We visualize here the spatial distribution of taxi rides in New York City. A higher density +is observed on major avenues. For more details about mapbox charts, see [the mapbox layers tutorial](/python/mapbox-layers). No mapbox token is needed here. + +```python +import pandas as pd +df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/uber-rides-data1.csv') +dff = df.query('Lat < 40.82').query('Lat > 40.70').query('Lon > -74.02').query('Lon < -73.91') + +import datashader as ds +cvs = ds.Canvas(plot_width=1000, plot_height=1000) +agg = cvs.points(dff, x='Lon', y='Lat') +# agg is an xarray object, see http://xarray.pydata.org/en/stable/ for more details +coords_lat, coords_lon = agg.coords['Lat'].values, agg.coords['Lon'].values +# Corners of the image, which need to be passed to mapbox +coordinates = [[coords_lon[0], coords_lat[0]], + [coords_lon[-1], coords_lat[0]], + [coords_lon[-1], coords_lat[-1]], + [coords_lon[0], coords_lat[-1]]] + +from colorcet import fire +import datashader.transfer_functions as tf +img = tf.shade(agg, cmap=fire)[::-1].to_pil() + +import plotly.express as px +# Trick to create rapidly a figure with mapbox axes +fig = px.scatter_mapbox(dff[:1], lat='Lat', lon='Lon', zoom=12) +# Add the datashader image as a mapbox layer image +fig.update_layout(mapbox_style="carto-darkmatter", + mapbox_layers = [ + { + "sourcetype": "image", + "source": img, + "coordinates": coordinates + }] +) +fig.show() +``` + +### Exploring correlations of a large dataset + +Here we explore the flight delay dataset from https://www.kaggle.com/usdot/flight-delays. In order to get a visual impression of the correlation between features, we generate a datashader rasterized array which we plot using a `Heatmap` trace. It creates a much clearer visualization than a scatter plot of (even a fraction of) the data points, as shown below. + +Note that instead of datashader it would theoretically be possible to create a [2d histogram](/python/2d-histogram-contour/) with plotly but this is not recommended here because you would need to load the whole dataset (5M rows !) in the browser for plotly.js to compute the heatmap, which is practically not tractable. Datashader offers the possibility to reduce the size of the dataset before passing it to the browser. + +```python +import plotly.graph_objects as go +import pandas as pd +import numpy as np +import datashader as ds +df = pd.read_parquet('https://raw.githubusercontent.com/plotly/datasets/master/2015_flights.parquet') +fig = go.Figure(go.Scattergl(x=df['SCHEDULED_DEPARTURE'][::200], + y=df['DEPARTURE_DELAY'][::200], + mode='markers') +) +fig.update_layout(title_text='A busy plot') +fig.show() +``` + +```python +import plotly.graph_objects as go +import pandas as pd +import numpy as np +import datashader as ds +df = pd.read_parquet('https://raw.githubusercontent.com/plotly/datasets/master/2015_flights.parquet') + +cvs = ds.Canvas(plot_width=100, plot_height=100) +agg = cvs.points(df, 'SCHEDULED_DEPARTURE', 'DEPARTURE_DELAY') +x = np.array(agg.coords['SCHEDULED_DEPARTURE']) +y = np.array(agg.coords['DEPARTURE_DELAY']) + +# Assign nan to zero values so that the corresponding pixels are transparent +agg = np.array(agg.values, dtype=np.float) +agg[agg<1] = np.nan + +fig = go.Figure(go.Heatmap( + z=np.log10(agg), x=x, y=y, + hoverongaps=False, + hovertemplate='Scheduled departure: %{x:.1f}h
Depature delay: %{y}
Log10(Count): %{z}', + colorbar=dict(title='Count (Log)', tickprefix='1.e'))) +fig.update_xaxes(title_text='Scheduled departure') +fig.update_yaxes(title_text='Departure delay') +fig.show() + +``` + +```python + +``` diff --git a/doc/python/distplot.md b/doc/python/distplot.md index bf1987a77c9..b2bedfeffbe 100644 --- a/doc/python/distplot.md +++ b/doc/python/distplot.md @@ -37,7 +37,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](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/). +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/) and produces [easy-to-style figures](/python/styling-plotly-express/). ```python import plotly.express as px diff --git a/doc/python/dot-plots.md b/doc/python/dot-plots.md index dffe1d9b8ac..a5aaa6997ee 100644 --- a/doc/python/dot-plots.md +++ b/doc/python/dot-plots.md @@ -5,7 +5,7 @@ jupyter: text_representation: extension: .md format_name: markdown - format_version: '1.1' + format_version: "1.1" jupytext_version: 1.1.1 kernelspec: display_name: Python 3 @@ -35,11 +35,11 @@ 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]()) 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` (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/). +[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/). ```python import plotly.express as px @@ -158,5 +158,4 @@ fig.show() ### Reference - See https://plot.ly/python/reference/#scatter for more information and chart attribute options! diff --git a/doc/python/error-bars.md b/doc/python/error-bars.md index e4870b7a223..37867c149f6 100644 --- a/doc/python/error-bars.md +++ b/doc/python/error-bars.md @@ -35,7 +35,7 @@ jupyter: ### Error Bars 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/). 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/) and produces [easy-to-style figures](/python/styling-plotly-express/). 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/doc/python/filled-area-plots.md b/doc/python/filled-area-plots.md index b32c7915110..f45ca14d143 100644 --- a/doc/python/filled-area-plots.md +++ b/doc/python/filled-area-plots.md @@ -37,7 +37,7 @@ This example shows how to fill the area enclosed by traces. ## Filled area 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/). +[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/). `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/doc/python/funnel-charts.md b/doc/python/funnel-charts.md index e786eca4fbc..669b3221f3a 100644 --- a/doc/python/funnel-charts.md +++ b/doc/python/funnel-charts.md @@ -5,7 +5,7 @@ jupyter: text_representation: extension: .md format_name: markdown - format_version: '1.2' + format_version: "1.2" jupytext_version: 1.3.0 kernelspec: display_name: Python 3 @@ -24,23 +24,20 @@ jupyter: thumbnail: thumbnail/funnel.jpg --- - ### Introduction Funnel charts are often used to represent data in different stages of a business process. It’s an important mechanism in Business Intelligence to identify potential problem areas of a process. For example, it’s used to observe the revenue or loss in a sales process for each stage, and displays values that are decreasing progressively. Each stage is illustrated as a percentage of the total of all values. - ### Basic Funnel 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/). +[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/). With `px.funnel`, each row of the DataFrame is represented as a stage of the funnel. - ```python import plotly.express as px data = dict( - number=[39, 27.4, 20.6, 11, 2], + number=[39, 27.4, 20.6, 11, 2], stage=["Website visit", "Downloads", "Potential customers", "Requested price", "invoice sent"]) fig = px.funnel(data, x='number', y='stage') fig.show() @@ -76,6 +73,7 @@ fig.show() ``` ### Setting Marker Size and Color + This example uses [textposition](https://plot.ly/python/reference/#scatter-textposition) and [textinfo](https://plot.ly/python/reference/#funnel-textinfo) to determine information apears on the graph, and shows how to customize the bars. ```python @@ -167,7 +165,6 @@ fig.show() #### Multiple Area Funnels - ```python from plotly import graph_objects as go @@ -204,4 +201,5 @@ fig.show() ``` #### Reference + See https://plot.ly/python/reference/#funnel and https://plot.ly/python/reference/#funnelarea for more information and chart attribute options! diff --git a/doc/python/heatmaps.md b/doc/python/heatmaps.md index aac6a570455..ec2735bf725 100644 --- a/doc/python/heatmaps.md +++ b/doc/python/heatmaps.md @@ -162,5 +162,10 @@ fig.update_layout( fig.show() ``` +### Heatmap and datashader + +Arrays of rasterized values build by datashader can be visualized using +plotly's heatmaps, as shown in the [plotly and datashader tutorial](/python/datashader/). + #### Reference See https://plot.ly/python/reference/#heatmap for more information and chart attribute options! diff --git a/doc/python/histograms.md b/doc/python/histograms.md index 7ec7f6b2d1c..76bc94d1d7d 100644 --- a/doc/python/histograms.md +++ b/doc/python/histograms.md @@ -41,7 +41,7 @@ bar, go to the [Bar Chart tutorial](/python/bar-charts/). ## Histogram 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/). +[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/). ```python import plotly.express as px diff --git a/doc/python/horizontal-bar-charts.md b/doc/python/horizontal-bar-charts.md index c5e9de9b188..b9daa15e407 100644 --- a/doc/python/horizontal-bar-charts.md +++ b/doc/python/horizontal-bar-charts.md @@ -37,7 +37,7 @@ See more examples of bar charts (including vertical bar charts) and styling opti ### Horizontal Bar Chart 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/). 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/) and produces [easy-to-style figures](/python/styling-plotly-express/). For a horizontal bar char, use the `px.bar` function with `orientation='h'`. #### Basic Horizontal Bar Chart with Plotly Express diff --git a/doc/python/imshow.md b/doc/python/imshow.md index 349732e82a7..ba5b0c20cb7 100644 --- a/doc/python/imshow.md +++ b/doc/python/imshow.md @@ -198,6 +198,13 @@ fig.update_layout(height=400) fig.show() ``` +### imshow and datashader + +Arrays of rasterized values build by datashader can be visualized using +imshow. See the [plotly and datashader tutorial](/python/datashader/) for +examples on how to use plotly and datashader. + + #### Reference See https://plot.ly/python/reference/#image for more information and chart attribute options! diff --git a/doc/python/line-and-scatter.md b/doc/python/line-and-scatter.md index 9479bb63f50..42c46606d9f 100644 --- a/doc/python/line-and-scatter.md +++ b/doc/python/line-and-scatter.md @@ -36,7 +36,7 @@ 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/). +[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/). With `px.scatter`, each data point is represented as a marker point, which location is given by the `x` and `y` columns. diff --git a/doc/python/line-charts.md b/doc/python/line-charts.md index 13d151494e7..1de7699bfa0 100644 --- a/doc/python/line-charts.md +++ b/doc/python/line-charts.md @@ -37,7 +37,7 @@ jupyter: ### Line 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.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/) and produces [easy-to-style figures](/python/styling-plotly-express/). 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/). diff --git a/doc/python/linear-fits.md b/doc/python/linear-fits.md index 795a334a7a6..7d1c970efca 100644 --- a/doc/python/linear-fits.md +++ b/doc/python/linear-fits.md @@ -37,7 +37,7 @@ jupyter: ### Linear fit trendlines 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/). +[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/). Plotly Express allows you to add [Ordinary Least](https://en.wikipedia.org/wiki/Ordinary_least_squares) Squares regression trendline to scatterplots with the `trendline` argument. In order to do so, you will need to install `statsmodels` and its dependencies. Hovering over the trendline will show the equation of the line and its R-squared value. diff --git a/doc/python/lines-on-maps.md b/doc/python/lines-on-maps.md index 514a6a51e1a..55cb9294396 100644 --- a/doc/python/lines-on-maps.md +++ b/doc/python/lines-on-maps.md @@ -41,7 +41,7 @@ Plotly figures made with `px.scatter_geo`, `px.line_geo` or `px.choropleth` func ## 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/). +[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/). ```python import plotly.express as px diff --git a/doc/python/mapbox-county-choropleth.md b/doc/python/mapbox-county-choropleth.md index dd5cbebd978..10b26e914b1 100644 --- a/doc/python/mapbox-county-choropleth.md +++ b/doc/python/mapbox-county-choropleth.md @@ -80,7 +80,7 @@ df.head() ### Choropleth map using plotly.express and carto base map (no token needed) -[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/). +[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/). With `px.choropleth_mapbox`, each row of the DataFrame is represented as a region of the choropleth. diff --git a/doc/python/mapbox-density-heatmaps.md b/doc/python/mapbox-density-heatmaps.md index e17a0ae5ef8..7c4535e22b4 100644 --- a/doc/python/mapbox-density-heatmaps.md +++ b/doc/python/mapbox-density-heatmaps.md @@ -5,7 +5,7 @@ jupyter: text_representation: extension: .md format_name: markdown - format_version: '1.2' + format_version: "1.2" jupytext_version: 1.3.0 kernelspec: display_name: Python 3 @@ -33,17 +33,13 @@ jupyter: thumbnail: thumbnail/mapbox-density.png --- - #### Mapbox Access Token -To plot on Mapbox maps with Plotly you *may* need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/python/mapbox-layers/) documentation for more information. - - - +To plot on Mapbox maps with Plotly you _may_ need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/python/mapbox-layers/) documentation for more information. ### Stamen Terrain base map (no token needed): density mapbox 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/). +[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/). With `px.density_mapbox`, each row of the DataFrame is represented as a point smoothed with a given radius of influence. @@ -67,7 +63,7 @@ import pandas as pd quakes = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/earthquakes-23k.csv') import plotly.graph_objects as go -fig = go.Figure(go.Densitymapbox(lat=quakes.Latitude, lon=quakes.Longitude, z=quakes.Magnitude, +fig = go.Figure(go.Densitymapbox(lat=quakes.Latitude, lon=quakes.Longitude, z=quakes.Magnitude, radius=10)) fig.update_layout(mapbox_style="stamen-terrain", mapbox_center_lon=180) fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0}) @@ -75,4 +71,5 @@ fig.show() ``` #### Reference + See https://plot.ly/python/reference/#densitymapbox for more information about mapbox and their attribute options. diff --git a/doc/python/mapbox-layers.md b/doc/python/mapbox-layers.md index 0aac4981c1a..ecb68d5cf3b 100644 --- a/doc/python/mapbox-layers.md +++ b/doc/python/mapbox-layers.md @@ -186,6 +186,10 @@ fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0}) fig.show() ``` +#### Using a mapbox image layer to display a datashader raster image + +See the example in the [plotly and datashader tutorial](/python/datashader). + #### Reference See https://plot.ly/python/reference/#layout-mapbox for more information and options! diff --git a/doc/python/parallel-coordinates-plot.md b/doc/python/parallel-coordinates-plot.md index ae9b9349ec4..b33b410ab42 100644 --- a/doc/python/parallel-coordinates-plot.md +++ b/doc/python/parallel-coordinates-plot.md @@ -37,7 +37,7 @@ jupyter: ## Parallel Coordinates 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 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 [parallel categories](/python/parallel-categories-diagram/), [radar charts](/python/radar-chart/) and [scatterplot matrix (SPLOM)](/python/splom/). +[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/). 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 [parallel categories](/python/parallel-categories-diagram/), [radar charts](/python/radar-chart/) and [scatterplot matrix (SPLOM)](/python/splom/). ```python import plotly.express as px diff --git a/doc/python/pie-charts.md b/doc/python/pie-charts.md index a3fe1160c8f..75905b990cf 100644 --- a/doc/python/pie-charts.md +++ b/doc/python/pie-charts.md @@ -5,7 +5,7 @@ jupyter: text_representation: extension: .md format_name: markdown - format_version: '1.2' + format_version: "1.2" jupytext_version: 1.3.0 kernelspec: display_name: Python 3 @@ -33,14 +33,14 @@ jupyter: thumbnail: thumbnail/pie-chart.jpg --- -A pie chart is a circular statistical chart, which is divided into sectors to illustrate numerical proportion. +A pie chart is a circular statistical chart, which is divided into sectors to illustrate numerical proportion. If you're looking instead for a multilevel hierarchical pie-like chart, go to the [Sunburst tutorial](/python/sunburst-charts/). ### Pie chart 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/). +[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/). In `px.pie`, data visualized by the sectors of the pie is set in `values`. The sector labels are set in `names`. @@ -80,7 +80,7 @@ In the example below, we first create a pie chart with `px,pie`, using some of i ```python import plotly.express as px df = px.data.gapminder().query("year == 2007").query("continent == 'Americas'") -fig = px.pie(df, values='pop', names='country', +fig = px.pie(df, values='pop', names='country', title='Population of American continent', hover_data=['lifeExp'], labels={'lifeExp':'life expectancy'}) fig.update_traces(textposition='inside', textinfo='percent+label') @@ -91,8 +91,7 @@ fig.show() If Plotly Express does not provide a good starting point, it is also possible to use the more generic `go.Pie` function from `plotly.graph_objects`. - -In `go.Pie`, data visualized by the sectors of the pie is set in `values`. The sector labels are set in `labels`. The sector colors are set in `marker.colors`. +In `go.Pie`, data visualized by the sectors of the pie is set in `values`. The sector labels are set in `labels`. The sector colors are set in `marker.colors`. If you're looking instead for a multilevel hierarchical pie-like chart, go to the [Sunburst tutorial](/python/sunburst-charts/). @@ -141,7 +140,7 @@ fig.show() The `insidetextorientation` attribute controls the orientation of text inside sectors. With "auto" the texts may automatically be rotated to fit with the maximum size inside the slice. Using "horizontal" (resp. "radial", "tangential") forces text to be horizontal (resp. radial or tangential) -For a figure `fig` created with plotly express, use `fig.update_traces(insidetextorientation='...')` to change the text orientation. +For a figure `fig` created with plotly express, use `fig.update_traces(insidetextorientation='...')` to change the text orientation. ```python import plotly.graph_objects as go @@ -157,7 +156,6 @@ fig.show() ### Donut Chart - ```python import plotly.graph_objects as go @@ -211,7 +209,6 @@ fig.update_layout( fig.show() ``` - ```python import plotly.graph_objects as go from plotly.subplots import make_subplots @@ -291,4 +288,5 @@ fig.show() ``` #### Reference + See https://plot.ly/python/reference/#pie for more information and chart attribute options! diff --git a/doc/python/plotly-express.md b/doc/python/plotly-express.md index bdee32bb0c2..b5584b757b9 100644 --- a/doc/python/plotly-express.md +++ b/doc/python/plotly-express.md @@ -5,7 +5,7 @@ jupyter: text_representation: extension: .md format_name: markdown - format_version: '1.2' + format_version: "1.2" jupytext_version: 1.3.1 kernelspec: display_name: Python 3 @@ -22,7 +22,8 @@ jupyter: pygments_lexer: ipython3 version: 3.6.8 plotly: - description: Plotly Express is a terse, consistent, high-level API for rapid data + description: + Plotly Express is a terse, consistent, high-level API for rapid data exploration and figure generation. display_as: file_settings language: python @@ -36,11 +37,11 @@ jupyter: ### Plotly Express -Plotly Express is a terse, consistent, high-level wrapper around `plotly.graph_objects` for rapid data exploration and figure generation. +Plotly Express is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/). Every Plotly Express function returns a `graph_objects.Figure` object whose `data` and `layout` has been pre-populated according to the provided arguments. -**Note**: Plotly Express was previously its own separately-installed `plotly_express` package but is now part of `plotly`! +> **Note**: Plotly Express was previously its own separately-installed `plotly_express` package but is now part of `plotly` and importable via `import plotly.express as px`. -This notebook demonstrates various `plotly.express` features. [Reference documentation](https://plotly.github.io/plotly_express/plotly_express/) is also available, as well as a [tutorial on input argument types](/python/px-arguments). +This notebook demonstrates various `plotly.express` features. [Reference documentation](https://plot.ly/python-api-reference/plotly.express.html) is also available, as well as a [tutorial on input argument types](/python/px-arguments) and one on how to [style figures made with Plotly Express](/python/styling-plotly-express/). You can also read our original [Medium announcement article](https://medium.com/@plotlygraphs/introducing-plotly-express-808df010143d) for more information on this library. @@ -54,6 +55,8 @@ px.data.iris().head() #### Scatter and Line plots +Refer to the main [scatter and line plot page](/python/line-and-scatter/) for full documentation. + ```python import plotly.express as px df = px.data.iris() @@ -172,6 +175,8 @@ fig.show() #### Visualize Distributions +Refer to the main [statistical graphs page](/python/statistical-charts/) for full documentation. + ```python import plotly.express as px df = px.data.iris() @@ -357,33 +362,3 @@ df = px.data.gapminder() fig = px.choropleth(df, locations="iso_alpha", color="lifeExp", hover_name="country", animation_frame="year", range_color=[20,80]) fig.show() ``` - -#### Built-in Color Scales and Sequences (and a way to see them!) - -```python -px.colors.qualitative.swatches() -``` - -```python -px.colors.sequential.swatches() -``` - -```python -px.colors.diverging.swatches() -``` - -```python -px.colors.cyclical.swatches() -``` - -```python -px.colors.colorbrewer.swatches() -``` - -```python -px.colors.cmocean.swatches() -``` - -```python -px.colors.carto.swatches() -``` diff --git a/doc/python/polar-chart.md b/doc/python/polar-chart.md index 7043cc73f13..ce6ac9aee0b 100644 --- a/doc/python/polar-chart.md +++ b/doc/python/polar-chart.md @@ -37,7 +37,7 @@ jupyter: A polar chart represents data along radial and angular axes. With Plotly Express, it is possible to represent polar data as scatter markers with `px.scatter_polar`, and as lines with `px.line_polar`. -[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/). +[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/). For other types of arguments, see the section below using `go.Scatterpolar`. diff --git a/doc/python/px-arguments.md b/doc/python/px-arguments.md index add81956987..9cb7827738e 100644 --- a/doc/python/px-arguments.md +++ b/doc/python/px-arguments.md @@ -51,6 +51,7 @@ import pandas as pd print("This is the same data in 'long' format, ready for Plotly Express:") wide_df = pd.DataFrame(dict(Month=["Jan", "Feb", "Mar"], London=[1,2,3], Paris=[3,1,2])) tidy_df = wide_df.melt(id_vars="Month") +tidy_df ``` ```python diff --git a/doc/python/radar-chart.md b/doc/python/radar-chart.md index a180a8ee74e..6ffa8c5fbfb 100644 --- a/doc/python/radar-chart.md +++ b/doc/python/radar-chart.md @@ -5,7 +5,7 @@ jupyter: text_representation: extension: .md format_name: markdown - format_version: '1.1' + format_version: "1.1" jupytext_version: 1.1.1 kernelspec: display_name: Python 3 @@ -33,13 +33,13 @@ jupyter: thumbnail: thumbnail/radar.gif --- -A [Radar Chart](https://en.wikipedia.org/wiki/Radar_chart) (also known as a spider plot or star plot) displays multivariate data in the form of a two-dimensional chart of quantitative variables represented on axes originating from the center. The relative position and angle of the axes is typically uninformative. It is equivalent to a [parallel coordinates plot](/python/parallel-coordinates-plot/) with the axes arranged radially. +A [Radar Chart](https://en.wikipedia.org/wiki/Radar_chart) (also known as a spider plot or star plot) displays multivariate data in the form of a two-dimensional chart of quantitative variables represented on axes originating from the center. The relative position and angle of the axes is typically uninformative. It is equivalent to a [parallel coordinates plot](/python/parallel-coordinates-plot/) with the axes arranged radially. For a Radar Chart, use a [polar chart](/python/polar-chart/) with categorical angular variables, with `px.line_polar` for data available as a tidy pandas DataFrame, or with `go.Scatterpolar` in the general case. See more examples of [polar charts here](/python/polar-chart/). #### Radar Chart 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/). +[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/). Use `line_close=True` for closed lines. @@ -70,7 +70,6 @@ fig.show() ### Basic Radar Chart with go.Scatterpolar - ```python import plotly.graph_objects as go @@ -129,4 +128,5 @@ fig.show() ``` #### Reference + See https://plot.ly/python/reference/#scatterpolar for more information and chart attribute options! diff --git a/doc/python/scatter-plots-on-maps.md b/doc/python/scatter-plots-on-maps.md index be23088be84..debe6c4771b 100644 --- a/doc/python/scatter-plots-on-maps.md +++ b/doc/python/scatter-plots-on-maps.md @@ -43,7 +43,7 @@ Plotly figures made with `px.scatter_geo`, `px.line_geo` or `px.choropleth` func Here we show the [Plotly Express](/python/plotly-express/) function `px.scatter_geo` for a geographical scatter plot. The `size` argument is used to set the size of markers from a given column of the DataFrame. -[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/). +[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/). ```python import plotly.express as px diff --git a/doc/python/scattermapbox.md b/doc/python/scattermapbox.md index 0f9a32aea2e..d8383dd3171 100644 --- a/doc/python/scattermapbox.md +++ b/doc/python/scattermapbox.md @@ -41,7 +41,7 @@ To plot on Mapbox maps with Plotly you _may_ need a Mapbox account and a public Here we show the [Plotly Express](/python/plotly-express/) function `px.scatter_mapbox` for a scatter plot on a tile map. -[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/). +[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/). ```python import plotly.express as px diff --git a/doc/python/splom.md b/doc/python/splom.md index 0101ebfb094..e46d8147d3e 100644 --- a/doc/python/splom.md +++ b/doc/python/splom.md @@ -42,7 +42,7 @@ A scatterplot matrix is a matrix associated to n numerical arrays (data variable Here we show the Plotly Express function `px.scatter_matrix` to plot the scatter matrix for the columns of the dataframe. By default, all columns are considered. -[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/). +[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/). ```python import plotly.express as px diff --git a/doc/python/styling-plotly-express.md b/doc/python/styling-plotly-express.md new file mode 100644 index 00000000000..3151b09f15d --- /dev/null +++ b/doc/python/styling-plotly-express.md @@ -0,0 +1,183 @@ +--- +jupyter: + jupytext: + notebook_metadata_filter: all + text_representation: + extension: .md + format_name: markdown + format_version: "1.2" + jupytext_version: 1.3.1 + kernelspec: + display_name: Python 3 + language: python + name: python3 + language_info: + codemirror_mode: + name: ipython + version: 3 + file_extension: .py + mimetype: text/x-python + name: python + nbconvert_exporter: python + pygments_lexer: ipython3 + version: 3.6.8 + plotly: + description: Figures made with Plotly Express can be customized in all the same ways as figures made with graph objects, as well as with PX-specific function arguments. + display_as: file_settings + language: python + layout: base + name: Styling Plotly Express Figures + order: 29 + page_type: u-guide + permalink: python/styling-plotly-express/ + thumbnail: thumbnail/plotly-express.png +--- + +### Styling Figures made 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/). Every Plotly Express function returns a `graph_objects.Figure` object whose `data` and `layout` has been pre-populated according to the provided arguments. + +> You can style and customize figures made with Plotly Express _in all the same ways_ as you can style figures made more manually by explicitly assembling `graph_objects` into a figure. + +More specifically, here are the 4 ways you can style and customize figures made with Plotly Express: + +1. Control common parameters like width & height, titles, labeling and colors using built-in Plotly Express function arguments +2. Updating the figure attributes using [update methods or by directly setting attributes](/python/creating-and-updating-figures/) +3. Using Plotly's [theming/templating mechanism](/python/templates/) via the `template` argument to every Plotly Express function +4. Setting default values for common parameters using `px.defaults` + +### Built-in Plotly Express Styling Arguments + +Many common styling options can be set directly in the `px` function call. Every Plotly Express function accepts the following arguments: + +- `title` to set the figure title +- `width` and `height` to set the figure dimensions +- `labels` to override the default axis and legend labels behaviour, which is to use the data frame column name if available, and otherwise to use the label name itself like "x", "y", "color" etc. `labels` accepts a `dict` whose keys are the label to rename and whose values are the desired labels. +- `category_orders` to override the default category ordering behaviour, which is to use the order in which the data appears in the input. `category_orders` accepts a `dict` whose keys are the column name to reorder and whose values are a `list` of values in the desired order. +- [Various color-related attributes](/python/colorscales/) such as `color_continuous_scale`, `color_range`, `color_discrete_sequence` and/or `color_discrete_map` set the colors used in the figure. `color_discrete_map` accepts a dict whose keys are values mapped to `color` and whose values are the desired CSS colors. +- `template` to [set many styling parameters at once](/python/templates/) (see below for more details) + +To illustrate each of these, here is a simple, default figure made with Plotly Express. Note the default orderings for the x-axis categories and the usage of lowercase & snake_case data frame columns for axis labelling. + +```python +import plotly.express as px +df = px.data.tips() +fig = px.histogram(df, x="day", y="total_bill", color="sex", histfunc="sum") +fig.show() +``` + +Here is the same figure, restyled by adding some extra parameters to the initial Plotly Express call: + +```python +import plotly.express as px +df = px.data.tips() +fig = px.histogram(df, x="day", y="total_bill", color="sex", histfunc="sum", + title="Receipts by Payer Gender and Day of Week", + width=600, height=400, + labels={ # replaces default labels by column name + "sex": "Payer Gender", "day": "Day of Week", "total_bill": "Receipts" + }, + category_orders={ # replaces default order by column name + "day": ["Thur", "Fri", "Sat", "Sun"], "sex": ["Male", "Female"] + }, + color_discrete_map={ # replaces default color mapping by value + "Male": "RebeccaPurple", "Female": "MediumPurple" + }, + template="simple_white" + ) +fig.show() +``` + +### Updating or Modifying Figures made with Plotly Express + +If none of the built-in Plotly Express arguments allow you to customize the figure the way you need to, you can use [the `update_*` and `add_*` methods](/python/creating-and-updating-figures/) on the `graph_objects.Figure` object returned by the PX function to make any further modifications to the figure. This approach is the one used throughout the Plotly.py documentation to [customize axes](/python/axes/), control [legends](/python/legend/) and [colorbars](/python/colorscales/), add [shapes](/python/shapes/) and [annotations](/python/text-and-annotations/) etc. + +Here is the same figure as above, with some additional customizations to the axes and legend via `.update_yaxes()`, and `.update_layout()`, as well as some annotations added via `.add_shape()` and `.add_annotation()`. + +```python +import plotly.express as px +df = px.data.tips() +fig = px.histogram(df, x="day", y="total_bill", color="sex", histfunc="sum", + title="Receipts by Payer Gender and Day of Week vs Target", + width=600, height=400, + labels={"sex": "Payer Gender", "day": "Day of Week", "total_bill": "Receipts"}, + category_orders={"day": ["Thur", "Fri", "Sat", "Sun"], "sex": ["Male", "Female"]}, + color_discrete_map={"Male": "RebeccaPurple", "Female": "MediumPurple"}, + template="simple_white" + ) + +fig.update_yaxes( # the y-axis is in dollars + tickprefix="$", showgrid=True +) + +fig.update_layout( # customize font and legend orientation & position + font_family="Rockwell", + legend=dict( + title=None, orientation="h", y=1, yanchor="bottom", x=0.5, xanchor="center" + ) +) + +fig.add_shape( # add a horizontal "target" line + type="line", line_color="salmon", line_width=3, opacity=1, line_dash="dot", + x0=0, x1=1, xref="paper", y0=950, y1=950, yref="y" +) + +fig.add_annotation( # add a text callout with arrow + text="below target!", x="Fri", y=400, arrowhead=1, showarrow=True +) + +fig.show() +``` + +### How Plotly Express Works with Templates + +Plotly has a [theming system based on templates](/python/templates/) and figures created with Plotly Express interact smoothly with this system: + +- Plotly Express methods will use the default template if one is set in `plotly.io` (by default, this is set to `plotly`) or in `plotly.express.defaults` (see below) +- The template in use can always be overridden via the `template` argument to every PX function +- The default `color_continuous_scale` will be the value of `layout.colorscales.sequential` in the template in use, unless it is overridden via the corresponding function argument or via `plotly.express.defaults` (see below) +- The default `color_discrete_sequence` will be the value of `layout.colorway` in the template in use, unless it is overridden via the corresponding function argument or via `plotly.express.defaults` (see below) + +By way of example, in the following figure, simply setting the `template` argument will automatically change the default continuous color scale, even though we have not specified `color_continuous_scale` directly. + +```python +import plotly.express as px +df = px.data.iris() +fig = px.density_heatmap(df, x="sepal_width", y="sepal_length", template="seaborn") +fig.show() +``` + +### Setting Plotly Express Styling Defaults + +Plotly Express supports a simple default-configuration system via the `plotly.express.defaults` singleton object. The values of the properties set on this object are used for the rest of the active session in place of `None` as the default values for any argument to a PX function with a matching name: + +- `width` and `height` can be set once globally for all Plotly Express functions +- `template` can override the setting of `plotly.io.templates.default` for all Plotly Express functions +- `color_continuous_scale` and `color_discrete_scale` can override the contents of the template in use for all Plotly Express functions that accept these arguments +- `line_dash_sequence`, `symbol_sequence` and `size_max` can be set once globally for all Plotly Express functions that accept these arguments + +To illustrate this "defaults hierarchy", in the following example: + +- we set the Plotly-wide default template to `simple_white`, but +- we override the default template for Plotly Express to be `ggplot2`, but +- we also set the default `color_continuous_scale`, and +- we set the default `height` and `width` to 400 by 600, but +- we override the default `width` to 400 via the function argument. + +As a result, any figure produced with Plotly Express thereafter uses the `ggplot2` settings for all attributes except for the continuous color scale (visible because `simple_white` doesn't set a plot background, and neither the `simple_white` nor `ggplot2` template uses `Blackbody` as a color scale), and uses the Plotly Express defaults for height but not width (visible because the figure height is the same as the figure width, despite the default). + +```python +import plotly.express as px +import plotly.io as pio + +pio.templates.default = "simple_white" + +px.defaults.template = "ggplot2" +px.defaults.color_continuous_scale = px.colors.sequential.Blackbody +px.defaults.width = 600 +px.defaults.height = 400 + +df = px.data.iris() +fig = px.scatter(df, x="sepal_width", y="sepal_length", color="sepal_length", width=400) +fig.show() +``` diff --git a/doc/python/sunburst-charts.md b/doc/python/sunburst-charts.md index cb9bc8f8cdd..69f89133c35 100644 --- a/doc/python/sunburst-charts.md +++ b/doc/python/sunburst-charts.md @@ -5,7 +5,7 @@ jupyter: text_representation: extension: .md format_name: markdown - format_version: '1.2' + format_version: "1.2" jupytext_version: 1.3.0 kernelspec: display_name: Python 3 @@ -36,13 +36,14 @@ jupyter: Sunburst plots visualize hierarchical data spanning outwards radially from root to leaves. The sunburst sector hierarchy is determined by the entries in `labels` (`names` in `px.sunburst`) and in `parents`. The root starts from the center and children are added to the outer rings. Main arguments: + 1. `labels` (`names` in `px.sunburst` since `labels` is reserved for overriding columns names): sets the labels of sunburst sectors. 2. `parents`: sets the parent sectors of sunburst sectors. An empty string `''` is used for the root node in the hierarchy. In this example, the root is "Eve". 3. `values`: sets the values associated with sunburst sectors, determining their width (See the `branchvalues` section below for different modes for setting the width). ### Basic Sunburst 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/). +[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/). With `px.sunburst`, each row of the DataFrame is represented as a sector of the sunburst. @@ -75,15 +76,15 @@ fig.show() ### Sunburst of a rectangular DataFrame with continuous color argument in px.sunburst -If a `color` argument is passed, the color of a node is computed as the average of the color values of its children, weighted by their values. +If a `color` argument is passed, the color of a node is computed as the average of the color values of its children, weighted by their values. ```python import plotly.express as px import numpy as np df = px.data.gapminder().query("year == 2007") -fig = px.sunburst(df, path=['continent', 'country'], values='pop', +fig = px.sunburst(df, path=['continent', 'country'], values='pop', color='lifeExp', hover_data=['iso_alpha'], - color_continuous_scale='RdBu', + color_continuous_scale='RdBu', color_continuous_midpoint=np.average(df['lifeExp'], weights=df['pop'])) fig.show() ``` @@ -133,7 +134,6 @@ fig.show() If Plotly Express does not provide a good starting point, it is also possible to use the more generic `go.Sunburst` function from `plotly.graph_objects`. - ```python import plotly.graph_objects as go @@ -242,7 +242,7 @@ fig.show() The `insidetextorientation` attribute controls the orientation of text inside sectors. With "auto" the texts may automatically be rotated to fit with the maximum size inside the slice. Using "horizontal" (resp. "radial", "tangential") forces text to be horizontal (resp. radial or tangential). Note that `plotly` may reduce the font size in order to fit the text with the requested orientation. -For a figure `fig` created with plotly express, use `fig.update_traces(insidetextorientation='...')` to change the text orientation. +For a figure `fig` created with plotly express, use `fig.update_traces(insidetextorientation='...')` to change the text orientation. ```python import plotly.graph_objects as go @@ -288,7 +288,7 @@ fig.show() ### Sunburst chart with a continuous colorscale -The example below visualizes a breakdown of sales (corresponding to sector width) and call success rate (corresponding to sector color) by region, county and salesperson level. For example, when exploring the data you can see that although the East region is behaving poorly, the Tyler county is still above average -- however, its performance is reduced by the poor success rate of salesperson GT. +The example below visualizes a breakdown of sales (corresponding to sector width) and call success rate (corresponding to sector color) by region, county and salesperson level. For example, when exploring the data you can see that although the East region is behaving poorly, the Tyler county is still above average -- however, its performance is reduced by the poor success rate of salesperson GT. In the right subplot which has a `maxdepth` of two levels, click on a sector to see its breakdown to lower levels. @@ -308,7 +308,7 @@ def build_hierarchical_dataframe(df, levels, value_column, color_columns=None): """ Build a hierarchy of levels for Sunburst or Treemap charts. - Levels are given starting from the bottom to the top of the hierarchy, + Levels are given starting from the bottom to the top of the hierarchy, ie the last level corresponds to the root. """ df_all_trees = pd.DataFrame(columns=['id', 'parent', 'value', 'color']) @@ -324,7 +324,7 @@ def build_hierarchical_dataframe(df, levels, value_column, color_columns=None): df_tree['value'] = dfg[value_column] df_tree['color'] = dfg[color_columns[0]] / dfg[color_columns[1]] df_all_trees = df_all_trees.append(df_tree, ignore_index=True) - total = pd.Series(dict(id='total', parent='', + total = pd.Series(dict(id='total', parent='', value=df[value_column].sum(), color=df[color_columns[0]].sum() / df[color_columns[1]].sum())) df_all_trees = df_all_trees.append(total, ignore_index=True) @@ -335,7 +335,7 @@ df_all_trees = build_hierarchical_dataframe(df, levels, value_column, color_colu average_score = df['sales'].sum() / df['calls'].sum() fig = make_subplots(1, 2, specs=[[{"type": "domain"}, {"type": "domain"}]],) - + fig.add_trace(go.Sunburst( labels=df_all_trees['id'], parents=df_all_trees['parent'], @@ -367,4 +367,5 @@ fig.show() ``` #### Reference + See https://plot.ly/python/reference/#sunburst for more information and chart attribute options! diff --git a/doc/python/ternary-plots.md b/doc/python/ternary-plots.md index f26fbd532fb..195b028b5b1 100644 --- a/doc/python/ternary-plots.md +++ b/doc/python/ternary-plots.md @@ -30,7 +30,7 @@ jupyter: order: 4 page_type: example_index permalink: python/ternary-plots/ - thumbnail: thumbnail/ternary.jpg + thumbnail: thumbnail/v4-migration.png --- ### Basic Ternary Plot with Markers diff --git a/doc/python/treemaps.md b/doc/python/treemaps.md index 3d55ae316a6..36dd866e008 100644 --- a/doc/python/treemaps.md +++ b/doc/python/treemaps.md @@ -5,7 +5,7 @@ jupyter: text_representation: extension: .md format_name: markdown - format_version: '1.2' + format_version: "1.2" jupytext_version: 1.3.1 kernelspec: display_name: Python 3 @@ -33,12 +33,11 @@ jupyter: thumbnail: thumbnail/treemap.png --- - [Treemap charts](https://en.wikipedia.org/wiki/Treemapping) visualize hierarchical data using nested rectangles. Same as [Sunburst](https://plot.ly/python/sunburst-charts/) the hierarchy is defined by [labels](https://plot.ly/python/reference/#treemap-labels) (`names` for `px.treemap`) and [parents](https://plot.ly/python/reference/#treemap-parents) attributes. Click on one sector to zoom in/out, which also displays a pathbar in the upper-left corner of your treemap. To zoom out you can use the path bar as well. ### Basic Treemap 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/). +[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/). With `px.treemap`, each row of the DataFrame is represented as a sector of the treemap. @@ -123,11 +122,11 @@ print(df) fig = px.treemap(df, path=['all', 'regions', 'sectors', 'vendors'], values='sales') fig.show() ``` + ### Basic Treemap with go.Treemap If Plotly Express does not provide a good starting point, it is also possible to use the more generic `go.Treemap` function from `plotly.graph_objects`. - ```python import plotly.graph_objects as go @@ -143,11 +142,11 @@ fig.show() This example uses the following attributes: - 1. [values](https://plot.ly/python/reference/#treemap-values): sets the values associated with each of the sectors. - 2. [textinfo](https://plot.ly/python/reference/#treemap-textinfo): determines which trace information appear on the graph that can be 'text', 'value', 'current path', 'percent root', 'percent entry', and 'percent parent', or any combination of them. - 3. [pathbar](https://plot.ly/python/reference/#treemap-pathbar): a main extra feature of treemap to display the current path of the visible portion of the hierarchical map. It may also be useful for zooming out of the graph. - 4. [branchvalues](https://plot.ly/python/reference/#treemap-branchvalues): determines how the items in `values` are summed. When set to "total", items in `values` are taken to be value of all its descendants. In the example below Eva = 65, which is equal to 14 + 12 + 10 + 2 + 6 + 6 + 1 + 4. -When set to "remainder", items in `values` corresponding to the root and the branches sectors are taken to be the extra part not part of the sum of the values at their leaves. +1. [values](https://plot.ly/python/reference/#treemap-values): sets the values associated with each of the sectors. +2. [textinfo](https://plot.ly/python/reference/#treemap-textinfo): determines which trace information appear on the graph that can be 'text', 'value', 'current path', 'percent root', 'percent entry', and 'percent parent', or any combination of them. +3. [pathbar](https://plot.ly/python/reference/#treemap-pathbar): a main extra feature of treemap to display the current path of the visible portion of the hierarchical map. It may also be useful for zooming out of the graph. +4. [branchvalues](https://plot.ly/python/reference/#treemap-branchvalues): determines how the items in `values` are summed. When set to "total", items in `values` are taken to be value of all its descendants. In the example below Eva = 65, which is equal to 14 + 12 + 10 + 2 + 6 + 6 + 1 + 4. + When set to "remainder", items in `values` corresponding to the root and the branches sectors are taken to be the extra part not part of the sum of the values at their leaves. ```python import plotly.graph_objects as go @@ -188,7 +187,8 @@ fig.show() ### Set Color of Treemap Sectors There are three different ways to change the color of the sectors in Treemap: - 1) [marker.colors](https://plot.ly/python/reference/#treemap-marker-colors), 2) [colorway](https://plot.ly/python/reference/#treemap-colorway), 3) [colorscale](https://plot.ly/python/reference/#treemap-colorscale). The following examples show how to use each of them. + +1. [marker.colors](https://plot.ly/python/reference/#treemap-marker-colors), 2) [colorway](https://plot.ly/python/reference/#treemap-colorway), 3) [colorscale](https://plot.ly/python/reference/#treemap-colorscale). The following examples show how to use each of them. ```python import plotly.graph_objects as go @@ -240,7 +240,7 @@ fig.show() ### Treemap chart with a continuous colorscale -The example below visualizes a breakdown of sales (corresponding to sector width) and call success rate (corresponding to sector color) by region, county and salesperson level. For example, when exploring the data you can see that although the East region is behaving poorly, the Tyler county is still above average -- however, its performance is reduced by the poor success rate of salesperson GT. +The example below visualizes a breakdown of sales (corresponding to sector width) and call success rate (corresponding to sector color) by region, county and salesperson level. For example, when exploring the data you can see that although the East region is behaving poorly, the Tyler county is still above average -- however, its performance is reduced by the poor success rate of salesperson GT. In the right subplot which has a `maxdepth` of two levels, click on a sector to see its breakdown to lower levels. @@ -260,7 +260,7 @@ def build_hierarchical_dataframe(df, levels, value_column, color_columns=None): """ Build a hierarchy of levels for Sunburst or Treemap charts. - Levels are given starting from the bottom to the top of the hierarchy, + Levels are given starting from the bottom to the top of the hierarchy, ie the last level corresponds to the root. """ df_all_trees = pd.DataFrame(columns=['id', 'parent', 'value', 'color']) @@ -276,7 +276,7 @@ def build_hierarchical_dataframe(df, levels, value_column, color_columns=None): df_tree['value'] = dfg[value_column] df_tree['color'] = dfg[color_columns[0]] / dfg[color_columns[1]] df_all_trees = df_all_trees.append(df_tree, ignore_index=True) - total = pd.Series(dict(id='total', parent='', + total = pd.Series(dict(id='total', parent='', value=df[value_column].sum(), color=df[color_columns[0]].sum() / df[color_columns[1]].sum())) df_all_trees = df_all_trees.append(total, ignore_index=True) @@ -287,7 +287,7 @@ df_all_trees = build_hierarchical_dataframe(df, levels, value_column, color_colu average_score = df['sales'].sum() / df['calls'].sum() fig = make_subplots(1, 2, specs=[[{"type": "domain"}, {"type": "domain"}]],) - + fig.add_trace(go.Treemap( labels=df_all_trees['id'], parents=df_all_trees['parent'], @@ -378,4 +378,5 @@ fig.show() ``` #### Reference + See https://plot.ly/python/reference/#treemap for more information and chart attribute options! diff --git a/doc/python/violin.md b/doc/python/violin.md index 9665755b5ed..149f7f49c9c 100644 --- a/doc/python/violin.md +++ b/doc/python/violin.md @@ -42,7 +42,7 @@ See also the [list of other statistical charts](https://plot.ly/python/statistic ### Basic Violin 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/). +[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/). ```python import plotly.express as px diff --git a/doc/python/webgl-vs-svg.md b/doc/python/webgl-vs-svg.md index 7b30d51527c..ff11ace247f 100644 --- a/doc/python/webgl-vs-svg.md +++ b/doc/python/webgl-vs-svg.md @@ -33,6 +33,10 @@ jupyter: thumbnail: thumbnail/webgl.jpg --- +Here we show that it is possible to represent millions of points with WebGL. +For larger datasets, or for a clearer visualization of the density of points, +it is also possible to use [datashader](/python/datashader/). + #### Compare WebGL and SVG Checkout [this notebook](https://plot.ly/python/compare-webgl-svg) to compare WebGL and SVG scatter plots with 75,000 random data points diff --git a/doc/python/wind-rose-charts.md b/doc/python/wind-rose-charts.md index 7aa46ea7b4a..f2596fa4120 100644 --- a/doc/python/wind-rose-charts.md +++ b/doc/python/wind-rose-charts.md @@ -39,7 +39,7 @@ jupyter: A [wind rose chart](https://en.wikipedia.org/wiki/Wind_rose) (also known as a polar bar chart) is a graphical tool used to visualize how wind speed and direction are typically distributed at a given location. You can use the `px.bar_polar` function from Plotly Express as below, otherwise use `go.Barpolar` as explained in the next section. -[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/). +[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/). ```python import plotly.express as px diff --git a/doc/requirements.txt b/doc/requirements.txt index 988f05efdbb..37d0944f8f2 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -22,3 +22,5 @@ sphinx_bootstrap_theme recommonmark pathlib python-frontmatter +datashader +pyarrow