diff --git a/doc/apidoc/_static/favicon.ico b/doc/apidoc/_static/favicon.ico index 91d73214217..d9e8bda1f22 100644 Binary files a/doc/apidoc/_static/favicon.ico and b/doc/apidoc/_static/favicon.ico differ diff --git a/doc/apidoc/_static/logo.png b/doc/apidoc/_static/logo.png index c2052c8948f..29082f9705e 100644 Binary files a/doc/apidoc/_static/logo.png and b/doc/apidoc/_static/logo.png differ diff --git a/doc/apidoc/_static/plotly-style.css b/doc/apidoc/_static/plotly-style.css index ae8b06d3f90..a5b9433487c 100644 --- a/doc/apidoc/_static/plotly-style.css +++ b/doc/apidoc/_static/plotly-style.css @@ -1,60 +1,106 @@ .navbar-default { - background-color: #00004f; + background-color: #fff; } .navbar { - min-height: 75px; + border-bottom: 1px solid #e7e7e7; } .navbar-brand { - font-family: "Open Sans", sans-serif; - padding: 10px 10px; + font-family: "Open Sans", sans-serif; + padding: 10px 10px; } + +.navbar-nav > li > a { + padding-top: 10px; + padding-bottom: 0; +} + .body { - font-family: "Open Sans", sans-serif; + font-family: "Open Sans", sans-serif; } + .navbar-brand img { - height: 30px; - margin-top: 4px; + height: 30px; + margin-top: 4px; } .navbar .container { - padding-top: 8px; -} - -a { - color: #2391fe !important; + padding-top: 8px; } code { - color: #2c3e50 !important; + color: #2c3e50 !important; } .alert-info { - background: lightgrey; + background: lightgrey; } - -.dropdown-menu>li>a:hover, .dropdown-menu>li>a:focus { - background: lightgrey; +.dropdown-menu > li > a:hover, +.dropdown-menu > li > a:focus { + background: lightgrey; } dt { - font-weight: normal; + font-weight: normal; } dd { - margin-left: 20px; + margin-left: 20px; } blockquote { - font-size: 15px; - border-left: none; + font-size: 15px; + border-left: none; } li { - margin-top: 8px; - margin-bottom: 8px; + margin-top: 8px; + margin-bottom: 8px; } code { - background-color: #F5F5F5 + background-color: #f5f5f5; +} + +h1, +h2, +h3, +h4, +h5, +h6 { + font-family: "jubilat", sans-serif; +} + +@font-face { + font-family: "jubilat"; + src: url("https://use.typekit.net/af/275f06/00000000000000003b9b0d24/27/l?primer=7cdcb44be4a7db8877ffa5c0007b8dd865b3bbc383831fe2ea177f62257a9191&fvd=n4&v=3") + format("woff2"), + url("https://use.typekit.net/af/275f06/00000000000000003b9b0d24/27/d?primer=7cdcb44be4a7db8877ffa5c0007b8dd865b3bbc383831fe2ea177f62257a9191&fvd=n4&v=3") + format("woff"), + url("https://use.typekit.net/af/275f06/00000000000000003b9b0d24/27/a?primer=7cdcb44be4a7db8877ffa5c0007b8dd865b3bbc383831fe2ea177f62257a9191&fvd=n4&v=3") + format("opentype"); + font-display: auto; + font-style: normal; + font-weight: 400; +} + +@font-face { + font-family: "jubilat"; + src: url("https://use.typekit.net/af/d16a24/00000000000000003b9b0d22/27/l?primer=7cdcb44be4a7db8877ffa5c0007b8dd865b3bbc383831fe2ea177f62257a9191&fvd=n5&v=3") + format("woff2"), + url("https://use.typekit.net/af/d16a24/00000000000000003b9b0d22/27/d?primer=7cdcb44be4a7db8877ffa5c0007b8dd865b3bbc383831fe2ea177f62257a9191&fvd=n5&v=3") + format("woff"), + url("https://use.typekit.net/af/d16a24/00000000000000003b9b0d22/27/a?primer=7cdcb44be4a7db8877ffa5c0007b8dd865b3bbc383831fe2ea177f62257a9191&fvd=n5&v=3") + format("opentype"); + font-display: auto; + font-style: normal; + font-weight: 500; +} + +a { + color: #506784 !important; +} + +a:hover { + color: #0d67bf !important; } diff --git a/doc/apidoc/plotly.express.rst b/doc/apidoc/plotly.express.rst index c1c56c3c51b..ec267b5092d 100644 --- a/doc/apidoc/plotly.express.rst +++ b/doc/apidoc/plotly.express.rst @@ -28,6 +28,7 @@ plotly's high-level API for rapid figure generation. :: line_geo area bar + timeline bar_polar violin box diff --git a/doc/apidoc/plotly.figure_factory.rst b/doc/apidoc/plotly.figure_factory.rst index a8ecf068da1..44f44b8d36c 100644 --- a/doc/apidoc/plotly.figure_factory.rst +++ b/doc/apidoc/plotly.figure_factory.rst @@ -18,6 +18,7 @@ create_distplot create_facet_grid create_gantt + create_hexbin_mapbox create_ohlc create_quiver create_scatterplotmatrix diff --git a/doc/python/3d-surface-coloring.md b/doc/python/3d-surface-coloring.md deleted file mode 100644 index ad117c446d8..00000000000 --- a/doc/python/3d-surface-coloring.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -jupyter: - jupytext: - notebook_metadata_filter: all - text_representation: - extension: .md - format_name: markdown - format_version: '1.1' - jupytext_version: 1.1.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.7.3 - plotly: - description: How to Color 3D Surface Plots in Python with Plotly. - display_as: 3d_charts - language: python - layout: base - name: 3D Surface Coloring - order: 8 - permalink: python/3d-surface-coloring/ - thumbnail: thumbnail/3d-surface-color.jpg ---- - -```python -import plotly.graph_objects as go -from plotly.subplots import make_subplots - -# Equation of ring cyclide -# see https://en.wikipedia.org/wiki/Dupin_cyclide -import numpy as np -a, b, d = 1.32, 1., 0.8 -c = a**2 - b**2 -u, v = np.mgrid[0:2*np.pi:100j, 0:2*np.pi:100j] -x = (d * (c - a * np.cos(u) * np.cos(v)) + b**2 * np.cos(u)) / (a - c * np.cos(u) * np.cos(v)) -y = b * np.sin(u) * (a - d*np.cos(v)) / (a - c * np.cos(u) * np.cos(v)) -z = b * np.sin(v) * (c*np.cos(u) - d) / (a - c * np.cos(u) * np.cos(v)) - -fig = make_subplots(rows=1, cols=2, - specs=[[{'is_3d': True}, {'is_3d': True}]], - subplot_titles=['Color corresponds to z', 'Color corresponds to distance to origin'], - ) - -fig.add_trace(go.Surface(x=x, y=y, z=z, colorbar_x=-0.07), 1, 1) -fig.add_trace(go.Surface(x=x, y=y, z=z, surfacecolor=x**2 + y**2 + z**2), 1, 2) -fig.update_layout(title_text="Ring cyclide") -fig.show() -``` - -#### Reference - - -See https://plotly.com/python/reference/#surface-surfacecolor for more information! \ No newline at end of file diff --git a/doc/python/3d-surface-plots.md b/doc/python/3d-surface-plots.md index 78e6720133c..010f6649512 100644 --- a/doc/python/3d-surface-plots.md +++ b/doc/python/3d-surface-plots.md @@ -30,6 +30,7 @@ jupyter: order: 3 page_type: example_index permalink: python/3d-surface-plots/ + redirect_from: python/3d-surface-coloring/ thumbnail: thumbnail/3d-surface.jpg --- @@ -54,7 +55,7 @@ fig.show() ### Passing x and y data to 3D Surface Plot -If you do not specify `x` and `y` coordinates, integer indices are used for the `x` and `y` axis. You can also pass `x` and `y` values to `go.Surface`. +If you do not specify `x` and `y` coordinates, integer indices are used for the `x` and `y` axis. You can also pass `x` and `y` values to `go.Surface`. ```python import plotly.graph_objects as go @@ -98,7 +99,7 @@ fig.update_layout(title='Mt Bruno Elevation', autosize=False, fig.show() ``` #### Configure Surface Contour Levels -This example shows how to slice the surface graph on the desired position for each of x, y and z axis. [contours.x.start](https://plotly.com/python/reference/#surface-contours-x-start) sets the starting contour level value, `end` sets the end of it, and `size` sets the step between each contour level. +This example shows how to slice the surface graph on the desired position for each of x, y and z axis. [contours.x.start](https://plotly.com/python/reference/#surface-contours-x-start) sets the starting contour level value, `end` sets the end of it, and `size` sets the step between each contour level. ```python import plotly.graph_objects as go @@ -163,7 +164,36 @@ fig = go.Figure(data=[ fig.show() ``` +### Setting the Surface Color + +You can use the `surfacecolor` attribute to define the color of the surface of your figure. In this example, the surface color represents the distance from the origin, rather than the default, which is the `z` value. + +```python +import plotly.graph_objects as go +from plotly.subplots import make_subplots + +# Equation of ring cyclide +# see https://en.wikipedia.org/wiki/Dupin_cyclide +import numpy as np +a, b, d = 1.32, 1., 0.8 +c = a**2 - b**2 +u, v = np.mgrid[0:2*np.pi:100j, 0:2*np.pi:100j] +x = (d * (c - a * np.cos(u) * np.cos(v)) + b**2 * np.cos(u)) / (a - c * np.cos(u) * np.cos(v)) +y = b * np.sin(u) * (a - d*np.cos(v)) / (a - c * np.cos(u) * np.cos(v)) +z = b * np.sin(v) * (c*np.cos(u) - d) / (a - c * np.cos(u) * np.cos(v)) + +fig = make_subplots(rows=1, cols=2, + specs=[[{'is_3d': True}, {'is_3d': True}]], + subplot_titles=['Color corresponds to z', 'Color corresponds to distance to origin'], + ) + +fig.add_trace(go.Surface(x=x, y=y, z=z, colorbar_x=-0.07), 1, 1) +fig.add_trace(go.Surface(x=x, y=y, z=z, surfacecolor=x**2 + y**2 + z**2), 1, 2) +fig.update_layout(title_text="Ring cyclide") +fig.show() +``` + #### Reference -See https://plotly.com/python/reference/#surface for more information! \ No newline at end of file +See https://plotly.com/python/reference/#surface for more information! diff --git a/doc/python/axes.md b/doc/python/axes.md index 90a9271247b..38410f143fa 100644 --- a/doc/python/axes.md +++ b/doc/python/axes.md @@ -531,6 +531,20 @@ fig.update_yaxes(range=[3, 9]) fig.show() ``` +#### Disabling Pan/Zoom on Axes (Fixed Range) + +Pan/Zoom can be disabled for a given axis by setting `fixedrange` to `True`. + +```python +import plotly.express as px +df = px.data.iris() + +fig = px.scatter(df, x="sepal_width", y="sepal_length", facet_col="species") +fig.update_xaxes(fixedrange=True) + +fig.show() +``` + ### Fixed Ratio Axes The `scaleanchor` and `scaleratio` axis properties can be used to force a fixed ratio of pixels per unit between two axes. @@ -742,7 +756,7 @@ fig.show() #### Synchronizing axes in subplots with `matches` -Using `facet_col` from `plotly.express` let [zoom](https://help.plotly.com/zoom-pan-hover-controls/#step-3-zoom-in-and-zoom-out-autoscale-the-plot) and [pan](https://help.plotly.com/zoom-pan-hover-controls/#step-6-pan-along-axes) each facet to the same range implicitly. However, if the subplots are created with `make_subplots`, the axis needs to be updated with `matches` parameter to update all the subplots accordingly. +Using `facet_col` from `plotly.express` let [zoom](https://help.plotly.com/zoom-pan-hover-controls/#step-3-zoom-in-and-zoom-out-autoscale-the-plot) and [pan](https://help.plotly.com/zoom-pan-hover-controls/#step-6-pan-along-axes) each facet to the same range implicitly. However, if the subplots are created with `make_subplots`, the axis needs to be updated with `matches` parameter to update all the subplots accordingly. Zoom in one trace below, to see the other subplots zoomed to the same x-axis range. To pan all the subplots, click and drag from the center of x-axis to the side: @@ -763,4 +777,4 @@ fig.show() #### Reference -See https://plotly.com/python/reference/#layout-xaxis and https://plotly.com/python/reference/#layout-yaxis for more information and chart attribute options! \ No newline at end of file +See https://plotly.com/python/reference/#layout-xaxis and https://plotly.com/python/reference/#layout-yaxis for more information and chart attribute options! diff --git a/doc/python/bar-charts.md b/doc/python/bar-charts.md index 38d1cc33c7b..11a2ca910c0 100644 --- a/doc/python/bar-charts.md +++ b/doc/python/bar-charts.md @@ -6,7 +6,7 @@ jupyter: extension: .md format_name: markdown format_version: '1.2' - jupytext_version: 1.3.0 + jupytext_version: 1.3.4 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.7.0 plotly: description: How to make Bar Charts in Python with Plotly. display_as: basic @@ -46,8 +46,43 @@ fig = px.bar(data_canada, x='year', y='pop') fig.show() ``` + +#### Bar chart with Long Format Data + +Long-form data has one row per observation, and one column per variable. This is suitable for storing and displaying multivariate data i.e. with dimension greater than 2. This format is sometimes called "tidy". + +To learn more about how to provide a specific form of column-oriented data to 2D-Cartesian Plotly Express functions such as `px.bar`, see the [Plotly Express Wide-Form Support in Python +documentation](https://plotly.com/python/wide-form/). + +For detailed column-input-format documentation, see the [Plotly Express Arguments documentation](https://plotly.com/python/px-arguments/). + +```python +import plotly.express as px + +long_df = px.data.medals_long() + +fig = px.bar(long_df, x="nation", y="count", color="medal", title="Long-Form Input") +fig.show() +``` + +```python +long_df +``` + +#### Bar chart with Wide Format Data +Wide-form data has one row per value of one of the first variable, and one column per value of the second variable. This is suitable for storing and displaying 2-dimensional data. + +```python +import plotly.express as px + +wide_df = px.data.medals_wide() + +fig = px.bar(wide_df, x="nation", y=["gold", "silver", "bronze"], title="Wide-Form Input") +fig.show() +``` + ```python -data_canada +wide_df ``` ### Customize bar chart with Plotly Express @@ -77,7 +112,8 @@ fig.show() ```python # Change the default stacking import plotly.express as px -fig = px.bar(df, x="sex", y="total_bill", color='smoker', barmode='group', +fig = px.bar(df, x="sex", y="total_bill", + color='smoker', barmode='group', height=400) fig.show() ``` @@ -384,6 +420,26 @@ fig.show() See examples of horizontal bar charts [here](https://plotly.com/python/horizontal-bar-charts/). +### Bar Charts With Multicategory Axis Type + +If your traces have arrays for `x` or `y`, then the axis type is automatically inferred to be `multicategory`. + +```python +import plotly.graph_objects as go +x = [ + ["BB+", "BB+", "BB+", "BB", "BB", "BB"], + [16, 17, 18, 16, 17, 18,] +] +fig = go.Figure() +fig.add_bar(x=x,y=[1,2,3,4,5,6]) +fig.add_bar(x=x,y=[6,5,4,3,2,1]) +fig.update_layout(barmode="relative") +fig.show() +``` + + + + ### Reference -See https://plotly.com/python/reference/#bar for more information and chart attribute options! \ No newline at end of file +See https://plotly.com/python/reference/#bar for more information and chart attribute options! diff --git a/doc/python/box-plots.md b/doc/python/box-plots.md index 900b3cf1b84..912f52f292f 100644 --- a/doc/python/box-plots.md +++ b/doc/python/box-plots.md @@ -489,6 +489,17 @@ fig.update_layout( fig.show() ``` +### Box Plot With Only Points + +A [strip chart](/python/strip-charts/) is like a box plot with points showing, and no box: + +```python +import plotly.express as px +df = px.data.tips() +fig = px.strip(df, x='day', y='tip') +fig.show() +``` + #### Reference -See https://plotly.com/python/reference/#box for more information and chart attribute options! \ No newline at end of file +See https://plotly.com/python/reference/#box for more information and chart attribute options! diff --git a/doc/python/configuration-options.md b/doc/python/configuration-options.md index d3124234fe5..452d90bb000 100644 --- a/doc/python/configuration-options.md +++ b/doc/python/configuration-options.md @@ -6,7 +6,7 @@ jupyter: extension: .md format_name: markdown format_version: '1.2' - jupytext_version: 1.3.0 + 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.7.3 + version: 3.7.7 plotly: description: How to set the configuration options of figures using the Plotly Python graphing library. @@ -34,7 +34,7 @@ jupyter: thumbnail: thumbnail/modebar-icons.png --- -# Configuration Options +## Configuration Options The `.show()` method that you use to display your figures also accepts a `config` parameter. @@ -44,7 +44,7 @@ If you don't set an option's value, it will be automatically be set to the defau For the complete list of configuration options and their defaults see: https://github.com/plotly/plotly.js/blob/master/src/plot_api/plot_config.js -##### Enabling Scroll Zoom +### Enabling Scroll Zoom This option allows users to zoom in and out of figures using the scroll wheel on their mouse and/or a two-finger scroll. @@ -63,7 +63,7 @@ fig.add_trace( fig.show(config=config) ``` -##### Forcing The Modebar to Always Be Visible +### Forcing The Modebar to Always Be Visible When users hover over a figure generated with plotly.py, a modebar appears in the top-right of the figure. This presents users with several options for interacting with the figure. @@ -84,7 +84,7 @@ fig.add_trace( fig.show(config=config) ``` -##### Preventing the Modebar from Appearing +### Preventing the Modebar from Appearing When users hover over a figure generated with `plotly.py`, a modebar appears in the top-right of the figure. This presents users with several options for interacting with the figure. @@ -106,7 +106,7 @@ fig.show(config=config) ``` -##### Hiding the Plotly Logo on the Modebar +### Hiding the Plotly Logo on the Modebar ```python import plotly.graph_objects as go @@ -123,7 +123,7 @@ fig.add_trace( fig.show(config=config) ``` -##### Turning Off Responsiveness +### Turning Off Responsiveness By default, figures you create with the `plotly.py` package are [responsive](https://en.wikipedia.org/wiki/Responsive_web_design). Responsive figures automatically change their height and width when the size of the window they are displayed in changes. This is true for figures which are displayed in web browsers on desktops and mobile, Jupyter Notebooks, and other [rendering](https://plot.ly/python/renderers/) environments. @@ -146,7 +146,7 @@ fig.add_trace( fig.show(config=config) ``` -##### Making A Static Chart +### Making A Static Chart ```python import plotly.graph_objects as go @@ -163,12 +163,14 @@ fig.add_trace( fig.show(config=config) ``` -##### Customizing Download Plot Options +### Customizing Download Plot Button Options -```python -import plotly.graph_objects as go +The camera icon on the modebar causes a static version of the figure to be downloaded via the user's browser. The default behaviour is to download a PNG of size 700 by 450 pixels. -fig = go.Figure() +This behavior can be controlled via the `toImageButtonOptions` configuration key. + +```python +import plotly.express as px config = { 'toImageButtonOptions': { @@ -180,15 +182,27 @@ config = { } } -fig.add_trace( - go.Scatter( - x=[1, 2, 3], - y=[1, 3, 1])) +fig = px.bar(x=[1, 2, 3], y=[1, 3, 1]) + +fig.show(config=config) +``` + +Figures can be set to download at the currently-rendered size by setting `height` and `width` to `None`: + + +```python +import plotly.express as px + +config = { + 'toImageButtonOptions': { 'height': None, 'width': None, } +} + +fig = px.bar(x=[1, 2, 3], y=[1, 3, 1]) fig.show(config=config) ``` -##### Specifying Multiple Configuration Options Simultaneously +### Specifying Multiple Configuration Options Simultaneously The dictionary that you use to specify configuration options for your figures can contain more than one configuration key/value pair. @@ -211,7 +225,7 @@ fig.add_trace( fig.show(config=config) ``` -##### Removing Modebar Buttons +### Removing Modebar Buttons To delete buttons from the modebar, pass an array of strings containing the names of the buttons you want to remove to the `modeBarButtonsToRemove` attribute in the figure's configuration dictionary. Note that different chart types have different default modebars. The following is a list of all the modebar buttons and the chart types they are associated with: @@ -279,10 +293,10 @@ fig.update_layout(xaxis = {'type': 'date'}) fig.show(config=config) ``` -#### Configuring Figures in Dash Apps +### Configuring Figures in Dash Apps The same configuration dictionary that you pass to the `config` parameter of the `show()` method can also be passed to the [`config` property of a `dcc.Graph` component](https://dash.plotly.com/dash-core-components/graph). #### Reference -See config options at https://github.com/plotly/plotly.js/blob/master/src/plot_api/plot_config.js#L6 \ No newline at end of file +See config options at https://github.com/plotly/plotly.js/blob/master/src/plot_api/plot_config.js#L6 diff --git a/doc/python/facet-plots.md b/doc/python/facet-plots.md index 2de009c0ef6..94d2d6137da 100644 --- a/doc/python/facet-plots.md +++ b/doc/python/facet-plots.md @@ -39,7 +39,9 @@ jupyter: ### Facet and Trellis Plots Facet plots, also known as trellis plots or small multiples, are figures made up of multiple subplots which have the same set of axes, where each subplot shows a subset of the data. While it is straightforward to use `plotly`'s -[subplot capabilities](/python/subplots/) to make such figures, it's far easier to use the built-in `facet_row` and `facet_col` arguments in the various [Plotly Express](/python/plotly-express/) functions. +[subplot capabilities](/python/subplots/) to make such figures, it's far easier to use the built-in `facet_row` and `facet_col` arguments in the various Plotly Express functions. + +[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/). ### Scatter Plot Column Facets diff --git a/doc/python/graphing-multiple-chart-types.md b/doc/python/graphing-multiple-chart-types.md index 213af2edb22..8bc409df6b7 100644 --- a/doc/python/graphing-multiple-chart-types.md +++ b/doc/python/graphing-multiple-chart-types.md @@ -5,8 +5,8 @@ jupyter: text_representation: extension: .md format_name: markdown - format_version: '1.1' - jupytext_version: 1.1.7 + 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.7.2 + version: 3.7.7 plotly: description: How to design figures with multiple chart types in python. display_as: file_settings @@ -33,6 +33,29 @@ jupyter: thumbnail: thumbnail/multiple-chart-type.jpg --- +### Chart Types versus Trace Types + +Plotly's [figure data structure](/python/figure-structure/) supports defining [subplots](/python/subplots/) of [various types](/python/mixed-subplots/) (e.g. [cartesian](/python/axes/), [polar](/python/polar-chart/), [3-dimensional](/python/3d-charts/), [maps](/python/maps/) etc) with attached traces of [various compatible types](/python/figure-structure/) (e.g. scatter, bar, choropleth, surface etc). This means that **Plotly figures are not constrained to representing a fixed set of "chart types"** such as scatter plots only or bar charts only or line charts only: any subplot can contain multiple traces of different types. + + +### Multiple Trace Types 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/). + +Plotly Express exposes a number of functions such as `px.scatter()` and `px.choropleth()` which generally speaking only contain traces of the same type, with exceptions made for [trendlines](/python/linear-fits/) and [marginal distribution plots](/python/marginal-plots/). + +Figures produced with Plotly Express functions support the `add_trace()` method documented below, just like figures created with [graph objects](/python/graph-objects/) so it is easy to start with a Plotly Express figure containing only traces of a given type, and add traces of another type. + +```python +import plotly.express as px + +fruits = ["apples", "oranges", "bananas"] +fig = px.line(x=fruits, y=[1,3,2], color=px.Constant("This year"), + labels=dict(x="Fruit", y="Amount", color="Time Period")) +fig.add_bar(x=fruits, y=[2,1,3], name="Last year") +fig.show() +``` + #### Line Chart and a Bar Chart ```python @@ -98,4 +121,4 @@ fig.show() ``` #### Reference -See https://plotly.com/python/reference/ for more information and attribute options! \ No newline at end of file +See https://plotly.com/python/reference/ for more information and attribute options! diff --git a/doc/python/line-and-scatter.md b/doc/python/line-and-scatter.md index 65b5a11a1a5..e11e9bfcb32 100644 --- a/doc/python/line-and-scatter.md +++ b/doc/python/line-and-scatter.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.8 + version: 3.7.7 plotly: description: How to make scatter plots in Python with Plotly. display_as: basic @@ -276,4 +276,4 @@ fig.show() ### Reference -See https://plotly.com/python/reference/#scatter or https://plotly.com/python/reference/#scattergl for more information and chart attribute options! \ No newline at end of file +See https://plotly.com/python/reference/#scatter or https://plotly.com/python/reference/#scattergl for more information and chart attribute options! diff --git a/doc/python/line-charts.md b/doc/python/line-charts.md index d1dda0aea89..f335054be0c 100644 --- a/doc/python/line-charts.md +++ b/doc/python/line-charts.md @@ -69,6 +69,33 @@ fig = px.line(df, x="year", y="lifeExp", color="continent", fig.show() ``` +### Sparklines with Plotly Express + +Sparklines are scatter plots inside subplots, with gridlines, axis lines, and ticks removed. + +```python +import plotly.express as px +df = px.data.stocks(indexed=True) +fig = px.line(df, facet_row="company", facet_row_spacing=0.01, height=200, width=200) + +# hide and lock down axes +fig.update_xaxes(visible=False, fixedrange=True) +fig.update_yaxes(visible=False, fixedrange=True) + +# remove facet/subplot labels +fig.update_layout(annotations=[], overwrite=True) + +# strip down the rest of the plot +fig.update_layout( + showlegend=False, + plot_bgcolor="white", + margin=dict(t=10,l=10,b=10,r=10) +) + +# disable the modebar for such a small plot +fig.show(config=dict(displayModeBar=False)) +``` + ### Line Plot 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). @@ -407,4 +434,4 @@ fig.show() #### Reference -See https://plotly.com/python/reference/#scatter for more information and chart attribute options! \ No newline at end of file +See https://plotly.com/python/reference/#scatter for more information and chart attribute options! diff --git a/doc/python/marginal-plots.md b/doc/python/marginal-plots.md new file mode 100644 index 00000000000..49728403f7f --- /dev/null +++ b/doc/python/marginal-plots.md @@ -0,0 +1,122 @@ +--- +jupyter: + jupytext: + notebook_metadata_filter: all + text_representation: + extension: .md + format_name: markdown + format_version: '1.2' + jupytext_version: 1.4.2 + 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.7.7 + plotly: + description: How to add marginal distribution plots. + display_as: statistical + language: python + layout: base + name: Marginal Distribution Plots + order: 13 + page_type: u-guide + permalink: python/marginal-plots/ + thumbnail: thumbnail/figure-labels.png +--- + +### Overview + +Marginal distribution plots are small subplots above or to the right of a main plot, which show the distribution of data along only one dimension. Marginal distribution plot capabilities are built into various Plotly Express functions such as `scatter` and `histogram`. [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/). + +### Scatter Plot Marginals + +The `marginal_x` and `marginal_y` arguments accept one of `"histogram"`, `"rug"`, `"box"`, or `"violin"` (see also how to create [histograms](/python/histograms/), [box plots](/python/box-plots/) and [violin plots](/python/violin-plots/) as the main figure). + +Marginal plots are linked to the main plot: try zooming or panning on the main plot. + +Marginal plots also support hover, including per-point hover as with the rug-plot on the right: try hovering over the points on the right marginal plot. + +```python +import plotly.express as px +df = px.data.iris() +fig = px.scatter(df, x="sepal_length", y="sepal_width", marginal_x="histogram", marginal_y="rug") +fig.show() +``` + +```python +import plotly.express as px +df = px.data.iris() +fig = px.density_heatmap(df, x="sepal_length", y="sepal_width", marginal_x="box", marginal_y="violin") +fig.show() +``` + +### Marginal Plots and Color + +Marginal plots respect the `color` argument as well, and are linked to the respective legend elements. Try clicking on the legend items. + +```python +import plotly.express as px +df = px.data.iris() +fig = px.scatter(df, x="sepal_length", y="sepal_width", color="species", + marginal_x="box", marginal_y="violin", + title="Click on the legend items!") +fig.show() +``` + +### Marginal Plots on Histograms + +[Histograms](/python/histograms/) are often used to show the distribution of a variable, and they also support marginal plots in Plotly Express, with the `marginal` argument: + +```python +import plotly.express as px +df = px.data.iris() +fig = px.histogram(df, x="sepal_length", color="species", marginal="box") +fig.show() +``` + +Try hovering over the rug plot points to identify individual country values in the histogram below: + +```python +import plotly.express as px +df = px.data.gapminder().query("year == 2007") +fig = px.histogram(df, x="lifeExp", color="continent", marginal="rug", hover_name="country", + title="Hover over the rug plot!") +fig.show() +``` + +### Marginal Plots and Facets + +Marginal plots can be used in conjunction with [Plotly Express facets](/python/facet-plots/) so long as they go along different directions: + +```python +import plotly.express as px +df = px.data.tips() +fig = px.scatter(df, x="total_bill", y="tip", color="sex", facet_col="day", + marginal_x="box") +fig.show() +``` + +```python +import plotly.express as px +df = px.data.tips() +fig = px.scatter(df, x="total_bill", y="tip", color="sex", facet_row="time", + marginal_y="box") +fig.show() +``` + +```python +import plotly.express as px +df = px.data.tips() +fig = px.histogram(df, x="total_bill", y="tip", color="sex", facet_col="day", + marginal="box") +fig.show() +``` diff --git a/doc/python/mixed-subplots.md b/doc/python/mixed-subplots.md index 56299456ffa..13737b5f6d1 100644 --- a/doc/python/mixed-subplots.md +++ b/doc/python/mixed-subplots.md @@ -5,8 +5,8 @@ jupyter: text_representation: extension: .md format_name: markdown - format_version: '1.1' - jupytext_version: 1.1.6 + 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.7.3 + version: 3.7.7 plotly: description: How to make mixed subplots in Python with Plotly. display_as: multiple_axes @@ -33,6 +33,13 @@ jupyter: thumbnail: thumbnail/mixed_subplot.JPG --- +### Mixed Subplots and 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/). + +> *Note*: At this time, Plotly Express does not support creating figures with arbitrary mixed subplots i.e. figures with subplots of different types. Plotly Express only supports [facet plots](/python/facet-plots/) and [marginal distribution subplots](/python/marginal-plots/). To make a figure with mixed subplots, use the [`make_subplots()`](/python/subplots/) function in conjunction with [graph objects](/python/graph-objects/) as documented below. + + #### Mixed Subplot ```python diff --git a/doc/python/multiple-axes.md b/doc/python/multiple-axes.md index d2b9675beb8..f9956231285 100644 --- a/doc/python/multiple-axes.md +++ b/doc/python/multiple-axes.md @@ -5,8 +5,8 @@ jupyter: text_representation: extension: .md format_name: markdown - format_version: '1.1' - jupytext_version: 1.1.7 + format_version: '1.2' + jupytext_version: 1.4.2 kernelspec: display_name: Python 3 language: python @@ -20,9 +20,10 @@ jupyter: name: python nbconvert_exporter: python pygments_lexer: ipython3 - version: 3.7.2 + version: 3.7.7 plotly: - description: How to make a graph with multiple axes (dual y-axis plots, plots with secondary axes) in python. + description: How to make a graph with multiple axes (dual y-axis plots, plots + with secondary axes) in python. display_as: file_settings language: python layout: base @@ -32,6 +33,13 @@ jupyter: thumbnail: thumbnail/multiple-axes.jpg --- +### Multiple Y Axes and 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/). + +> *Note*: At this time, Plotly Express does not support multiple Y axes on a single figure. To make such a figure, use the [`make_subplots()`](/python/subplots/) function in conjunction with [graph objects](/python/graph-objects/) as documented below. + + #### Two Y Axes ```python diff --git a/doc/python/plotly-express.md b/doc/python/plotly-express.md index 2bb0865ef90..bbbc875bf71 100644 --- a/doc/python/plotly-express.md +++ b/doc/python/plotly-express.md @@ -42,9 +42,9 @@ Plotly Express provides [more than 30 functions for creating different types of Plotly Express currently includes the following functions: -* **Basics**: [`scatter`](/python/line-and-scatter/), [`line`](/python/line-charts/), [`area`](/python/filled-area-plots/), [`bar`](/python/bar-charts/), [`funnel`](/python/funnel-charts/) +* **Basics**: [`scatter`](/python/line-and-scatter/), [`line`](/python/line-charts/), [`area`](/python/filled-area-plots/), [`bar`](/python/bar-charts/), [`funnel`](/python/funnel-charts/), [`timeline`](https://plotly.com/python/gantt/) * **Part-of-Whole**: [`pie`](/python/pie-charts/), [`sunburst`](/python/sunburst-charts/), [`treemap`](/python/treemaps/), [`funnel_area`](/python/funnel-charts/) -* **1D Distributions**: [`histogram`](/python/histograms/), [`box`](/python/box-plots/), [`violin`](/python/violin/), `strip` +* **1D Distributions**: [`histogram`](/python/histograms/), [`box`](/python/box-plots/), [`violin`](/python/violin/), [`strip`](/python/strip-charts/) * **2D Distributions**: [`density_heatmap`](/python/2D-Histogram/), [`density_contour`](/python/2d-histogram-contour/) * **Matrix Input**: [`imshow`](/python/imshow/) * **3-Dimensional**: [`scatter_3d`](/python/3d-scatter-plots/), [`line_3d`](/python/3d-line-plots/) @@ -67,7 +67,7 @@ The Plotly Express API in general offers the following features: * **Styling Control**: PX functions [read styling information from the default figure template](/python/styling-plotly-express/), and support commonly-needed [cosmetic controls like `category_orders` and `color_discrete_map`](/python/styling-plotly-express/) to precisely control categorical variables. * **Uniform Color Handling**: PX functions automatically switch between [continuous](/python/colorscales/) and [categorical color](/python/discrete-color/) based on the input type. * **Faceting**: the 2D-cartesian plotting functions support [row, column and wrapped facetting with `facet_row`, `facet_col` and `facet_col_wrap` arguments](/python/facet-plots/). -* **Marginal Plots**: the 2D-cartesian plotting functions support marginal distribution plots with the `marginal`, `marginal_x` and `marginal_y` arguments. +* **Marginal Plots**: the 2D-cartesian plotting functions support [marginal distribution plots](/python/marginal-plots/) with the `marginal`, `marginal_x` and `marginal_y` arguments. * **A Pandas backend**: the 2D-cartesian plotting functions are available as [a Pandas plotting backend](/python/pandas-backend/) so you can call them via `df.plot()`. * **Trendlines**: `px.scatter` supports [built-in trendlines with accessible model output](/python/linear-fits/). * **Animations**: many PX functions support [simple animation support via the `animation_frame` and `animation_group` arguments](/python/animations/). diff --git a/doc/python/px-arguments.md b/doc/python/px-arguments.md index 7065f3b2f44..7cb668626c8 100644 --- a/doc/python/px-arguments.md +++ b/doc/python/px-arguments.md @@ -35,6 +35,8 @@ jupyter: ### Plotly Express works with Column-oriented, Matrix or Geographic Data +[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/). + Plotly Express provides functions to visualize a variety of types of data. Most functions such as `px.bar` or `px.scatter` expect to operate on column-oriented data of the type you might store in a Pandas `DataFrame` (in either "long" or "wide" format, see below). [`px.imshow` operates on matrix-like data](/python/imshow/) you might store in a `numpy` or `xarray` array and functions like [`px.choropleth` and `px.choropleth_mapbox` can operate on geographic data](/python/maps/) of the kind you might store in a GeoPandas `GeoDataFrame`. This page details how to provide column-oriented data to most Plotly Express functions. diff --git a/doc/python/sliders.md b/doc/python/sliders.md index 461cb2dc397..aae9f1db7f7 100644 --- a/doc/python/sliders.md +++ b/doc/python/sliders.md @@ -34,7 +34,7 @@ jupyter: --- ### Simple Slider Control -Sliders can be used in Plotly to change the data displayed or style of a plot. +Sliders can be used in Plotly to change the data displayed or style of a plot. ```python import plotly.graph_objects as go @@ -83,13 +83,14 @@ fig.show() #### Methods The method determines which [plotly.js function](https://plot.ly/javascript/plotlyjs-function-reference/) will be used to update the chart. Plotly can use several [updatemenu](https://plot.ly/python/reference/#layout-updatemenus-items-updatemenu-buttons-items-button-method) methods to add the slider: +- `"update"`: modify **data and layout** attributes (as above) - `"restyle"`: modify **data** attributes - `"relayout"`: modify **layout** attributes -- `"update"`: modify **data and layout** attributes - `"animate"`: start or pause an animation + ### Sliders in Plotly Express -Plotly Express provide sliders, but with implicit animation. The animation can be ommited by removing `updatemenus` in the `layout`: +Plotly Express provide sliders, but with implicit animation using the `"animate"` method described above. The animation play button can be ommited by removing `updatemenus` in the `layout`: ```python import plotly.express as px diff --git a/doc/python/strip-charts.md b/doc/python/strip-charts.md new file mode 100644 index 00000000000..8a1673d646c --- /dev/null +++ b/doc/python/strip-charts.md @@ -0,0 +1,60 @@ +--- +jupyter: + jupytext: + notebook_metadata_filter: all + text_representation: + extension: .md + format_name: markdown + format_version: '1.2' + jupytext_version: 1.4.2 + 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.7.7 + plotly: + description: Strip charts are like 1-dimensional jittered scatter plots. + display_as: statistical + language: python + layout: base + name: Strip Charts + order: 14 + page_type: u-guide + permalink: python/strip-charts/ + thumbnail: thumbnail/figure-labels.png +--- + +### Strip Charts 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/). + +The `px.strip()` function will make strip charts using underlying `box` traces with the box hidden. + +See also [box plots](/python/box-plots/) and [violin plots](/python/violin/). + +```python +import plotly.express as px + +df = px.data.tips() +fig = px.strip(df, x="total_bill", y="day") +fig.show() +``` + +Strip charts support [faceting](/python/facet-plots/) and [discrete color](/python/discrete-color/): + +```python +import plotly.express as px + +df = px.data.tips() +fig = px.strip(df, x="total_bill", y="time", color="sex", facet_col="day") +fig.show() +``` diff --git a/doc/python/subplots.md b/doc/python/subplots.md index db5d872400a..c1cfb6dc9c9 100644 --- a/doc/python/subplots.md +++ b/doc/python/subplots.md @@ -6,7 +6,7 @@ jupyter: extension: .md format_name: markdown format_version: '1.2' - jupytext_version: 1.3.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.7.0 + version: 3.7.7 plotly: description: How to make subplots in with Plotly's Python graphing library. Examples of stacked, custom-sized, gridded, and annotated subplots. @@ -35,6 +35,15 @@ jupyter: thumbnail: thumbnail/subplots.jpg --- +### Subplots and 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/). + +Plotly Express does not support arbitrary subplot capabilities, instead it supports [faceting by a given data dimension](/python/facet-plots/), and it also supports [marginal charts to display distribution information](/python/marginal-plots/). + +This page documents the usage of the lower-level `plotly.subplots` module and the `make_subplots` function it exposes to construct figures with arbitrary subplots. **Plotly Express faceting uses `make_subplots` internally** so adding traces to Plotly Express facets works just as documented here, with `fig.add_trace(..., row=, col=)`. + + #### Simple Subplot Figures with subplots are created using the `make_subplots` function from the `plotly.subplots` module. @@ -579,4 +588,4 @@ All of the y-axis properties are found here: https://plotly.com/python/reference ```python from plotly.subplots import make_subplots help(make_subplots) -``` \ No newline at end of file +``` diff --git a/doc/python/time-series.md b/doc/python/time-series.md index 65ffa3c2fcd..07f794be92c 100644 --- a/doc/python/time-series.md +++ b/doc/python/time-series.md @@ -113,8 +113,9 @@ fig.show() A range slider is a small subplot-like area below a plot which allows users to pan and zoom the X-axis while maintaining an overview of the chart. Check out the reference for more options: https://plotly.com/python/reference/#layout-xaxis-rangeslider ```python -import plotly.graph_objects as go +import plotly.express as px import pandas as pd + df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/finance-charts-apple.csv') fig = px.line(df, x='Date', y='AAPL.High', title='Time Series with Rangeslider') @@ -128,8 +129,9 @@ fig.show() Range selector buttons are special controls that work well with time series and range sliders, and allow users to easily set the range of the x-axis. Check out the reference for more options: https://plotly.com/python/reference/#layout-xaxis-rangeselector ```python -import plotly.graph_objects as go +import plotly.express as px import pandas as pd + df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/finance-charts-apple.csv') fig = px.line(df, x='Date', y='AAPL.High', title='Time Series with Range Slider and Selectors') @@ -154,6 +156,7 @@ fig.show() The `tickformatstops` attribute can be used to customize the formatting of tick labels depending on the zoom level. Try zooming in to the chart below and see how the tick label formatting changes. Check out the reference for more options: https://plotly.com/python/reference/#layout-xaxis-tickformatstops ```python +import plotly.graph_objects as go import pandas as pd df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/finance-charts-apple.csv') @@ -189,6 +192,7 @@ The `rangebreaks` attribute available on x- and y-axes of type `date` can be use ```python import plotly.express as px import pandas as pd + df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/finance-charts-apple.csv') fig = px.scatter(df, x='Date', y='AAPL.High', range_x=['2015-12-01', '2016-01-15'], @@ -199,6 +203,7 @@ fig.show() ```python import plotly.express as px import pandas as pd + df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/finance-charts-apple.csv') fig = px.scatter(df, x='Date', y='AAPL.High', range_x=['2015-12-01', '2016-01-15'], diff --git a/doc/python/trisurf.md b/doc/python/trisurf.md index 313c889b5c1..df0127d15c2 100644 --- a/doc/python/trisurf.md +++ b/doc/python/trisurf.md @@ -28,7 +28,7 @@ jupyter: language: python layout: base name: Trisurf Plots - order: 14 + order: 8 permalink: python/trisurf/ thumbnail: thumbnail/trisurf.jpg --- @@ -128,4 +128,4 @@ fig.show() #### Reference -For more info on `ff.create_trisurf()`, see the [full function reference](https://plotly.com/python-api-reference/generated/plotly.figure_factory.create_trisurf.html) \ No newline at end of file +For more info on `ff.create_trisurf()`, see the [full function reference](https://plotly.com/python-api-reference/generated/plotly.figure_factory.create_trisurf.html) diff --git a/doc/python/violin.md b/doc/python/violin.md index 568f385e08c..6613c5a3c4a 100644 --- a/doc/python/violin.md +++ b/doc/python/violin.md @@ -30,7 +30,9 @@ jupyter: order: 10 page_type: u-guide permalink: python/violin/ - redirect_from: /python/violin-plot/ + redirect_from: + - /python/violin-plot/ + - /python/violin-plots/ thumbnail: thumbnail/violin.jpg --- @@ -258,6 +260,17 @@ fig.update_layout(xaxis_showgrid=False, xaxis_zeroline=False) fig.show() ``` +### Violin Plot With Only Points + +A [strip chart](/python/strip-charts/) is like a violin plot with points showing, and no violin: + +```python +import plotly.express as px +df = px.data.tips() +fig = px.strip(df, x='day', y='tip') +fig.show() +``` + #### Reference -See https://plotly.com/python/reference/#violin for more information and chart attribute options! \ No newline at end of file +See https://plotly.com/python/reference/#violin for more information and chart attribute options!