diff --git a/.gitignore b/.gitignore index fea742858b5..64c3de539e2 100644 --- a/.gitignore +++ b/.gitignore @@ -46,3 +46,4 @@ temp-plot.html doc/python/.ipynb_checkpoints doc/python/.mapbox_token doc/.ipynb_checkpoints +doc/check-or-enforce-order.py diff --git a/doc/apidoc/plotly.graph_objects.rst b/doc/apidoc/plotly.graph_objects.rst index feef8d10135..8be47ff86d9 100644 --- a/doc/apidoc/plotly.graph_objects.rst +++ b/doc/apidoc/plotly.graph_objects.rst @@ -43,6 +43,7 @@ Simple Traces Bar Pie Heatmap + Heatmapgl Image Contour Table diff --git a/doc/python/axes.md b/doc/python/axes.md index 2b829e16f7c..90a9271247b 100644 --- a/doc/python/axes.md +++ b/doc/python/axes.md @@ -29,7 +29,7 @@ jupyter: language: python layout: base name: Axes - order: 12 + order: 13 permalink: python/axes/ thumbnail: thumbnail/axes.png --- diff --git a/doc/python/builtin-colorscales.md b/doc/python/builtin-colorscales.md index 6bd57f206c1..1a0b8feb240 100644 --- a/doc/python/builtin-colorscales.md +++ b/doc/python/builtin-colorscales.md @@ -30,7 +30,7 @@ jupyter: language: python layout: base name: Built-in Continuous Color Scales - order: 26 + order: 27 permalink: python/builtin-colorscales/ thumbnail: thumbnail/heatmap_colorscale.jpg v4upgrade: true diff --git a/doc/python/colorscales.md b/doc/python/colorscales.md index 550f537edbc..e8be06eb628 100644 --- a/doc/python/colorscales.md +++ b/doc/python/colorscales.md @@ -30,7 +30,7 @@ jupyter: language: python layout: base name: Continuous Color Scales and Color Bars - order: 19 + order: 20 permalink: python/colorscales/ redirect_from: python/logarithmic-color-scale/ thumbnail: thumbnail/heatmap_colorscale.jpg diff --git a/doc/python/configuration-options.md b/doc/python/configuration-options.md index 5593708c263..d3124234fe5 100644 --- a/doc/python/configuration-options.md +++ b/doc/python/configuration-options.md @@ -28,7 +28,7 @@ jupyter: language: python layout: base name: Configuration - order: 8 + order: 9 page_type: u-guide permalink: python/configuration-options/ thumbnail: thumbnail/modebar-icons.png diff --git a/doc/python/creating-and-updating-figures.md b/doc/python/creating-and-updating-figures.md index b69100b777a..dbc1919b626 100644 --- a/doc/python/creating-and-updating-figures.md +++ b/doc/python/creating-and-updating-figures.md @@ -37,17 +37,13 @@ jupyter: v4upgrade: true --- -### Representing Figures +The `plotly` Python package exists to create, manipulate and [render](/python/renderers/) graphical figures (i.e. charts, plots, maps and diagrams) represented by [data structures also referred to as figures](/python/figure-structure/). The rendering process uses the [Plotly.js JavaScript library](https://plotly.com/javascript/) under the hood although Python developers using this module very rarely need to interact with the Javascript library directly, if ever. Figures can be represented in Python either as dicts or as instances of the `plotly.graph_objects.Figure` class, and are serialized as text in [JavaScript Object Notation (JSON)](https://json.org/) before being passed to Plotly.js. -The goal of the plotly.py package is to provide a pleasant Python interface for creating figure specifications which are displayed by the [plotly.js](https://plot.ly/javascript) JavaScript graphing library. +> Note: the recommended entry-point into the plotly package is the [high-level plotly.express module, also known as Plotly Express](/python/plotly-express/), which consists of Python functions which return fully-populated `plotly.graph_objects.Figure` objects. This page exists to document the structure of the data structure that these objects represent for users who wish to understand more about how to customize them, or assemble them from other `plotly.graph_objects` components. -In the context of the plotly.js library, a figure is specified by a declarative [JSON](https://www.json.org/json-en.html) data structure. +### Figures As Dictionaries -Therefore, you should always keep in mind as you are creating and updating figures using the plotly.py package that its ultimate goal is to help users produce Python [dictionaries](https://docs.python.org/3/tutorial/datastructures.html#dictionaries) that can be automatically [serialized](https://en.wikipedia.org/wiki/Serialization) into the JSON data structure that the plotly.js graphing library understands. - -#### Figures As Dictionaries - -The `fig` dictonary in the example below describes a figure. It contains a single `bar` trace and a title. +At a low level, figures can be represented as dictionaries and displayed using functions from the `plotly.io` module. The `fig` dictonary in the example below describes a figure. It contains a single `bar` trace and a title. ```python fig = dict({ @@ -63,27 +59,11 @@ import plotly.io as pio pio.show(fig) ``` -Let's take a closer look at structure of the `fig` dictionary in order to better understand how `plotly.py` figures are built. - -##### The `"data"` Key - -The `"data"` key stores the value of list which describes the trace or traces which make up a figure. It is still a list even if the figure only contains one trace, as in the example above. - -Each trace in the list stored by the `"data"` key is itself defined by a dictionary. The type of the trace (`"bar"`, `"scatter"`, `"contour"`, etc...) is specified with a `"type"` key, and the rest of the keys in a trace specification dictionary (`x`, `y`, etc...) are used to define the properties specific to the trace of that type. - -##### The `"layout"` Key +### Figures as Graph Objects -The`"layout"` key stores a dictionary that specifies properties related to customizing how the figure looks, such as its title, typography, margins, axes, annotations, shapes, legend and more. In contrast to trace configuration options, which apply only to individual traces, layout configuration options apply to the figure as a whole. +The `plotly.graph_objects` module provides a hierarchy of classes called "graph objects" that may be used to represent figures. The *recommended alternative* to working with Python dictionaries is to [create figures using Plotly Express](/python/plotly-express/) and to manipulate the resulting `plotly.graph_objects.Figure` objects as described in this page. -The [_Full Reference_](https://plot.ly/python/reference/) page contains descriptions of all of the supported trace and layout attributes and configuration options. - -If working from the _Full Reference_ to build figures as Python dictionaries and lists suites your needs, go for it! - -This is a perfectly valid way to use `plotly.py` to build figures. On the other hand, if you would like to use an API that offers you a bit more assistance in the figure creation process, read on to learn about `graph objects`. - -#### Figures as Graph Objects - -As an alternative to working with Python dictionaries, the `plotly.py` graphing library provides a hierarchy of classes called "graph objects" that may be used to construct figures. Graph objects have several benefits compared to plain Python dictionaries. +Graph objects have several benefits compared to plain Python dictionaries. 1. Graph objects provide precise data validation. If you provide an invalid property name or an invalid property value as the key to a graph object, an exception will be raised with a helpful error message describing the problem. This is not the case if you use plain Python dictionaries and lists to build your figures. @@ -151,26 +131,12 @@ print("\n\n") This section summarizes several ways to create new graph object figures with the `plotly.py` graphing library. -#### Graph Objects `Figure` Constructor - -As demonstrated above, you can build a complete figure by passing trace and layout specifications to the `plotly.graph_objects.Figure` constructor. These trace and layout specifications can be either dictionaries or graph objects. - -In the following example, the traces are specified using graph objects and the layout is specified as a dictionary. - -```python -import plotly.graph_objects as go - -fig = go.Figure( - data=[go.Bar(x=[1, 2, 3], y=[1, 3, 2])], - layout=dict(title=dict(text="A Figure Specified By A Graph Object")) -) +> The *recommended way* to create figures and populate them is to use [Plotly Express](/python/plotly-express/) but this page documents various other options for completeness -fig.show() -``` #### Plotly Express -[Plotly Express](https://plot.ly/python/plotly-express/) (included as the `plotly.express` module) is a high-level data exploration API that produces graph object figures. +[Plotly Express](https://plot.ly/python/plotly-express/) (included as the `plotly.express` module) is a high-level data visualization API that produces fully-populated graph object figures. ```python import plotly.express as px @@ -184,6 +150,23 @@ fig = px.scatter(df, x="sepal_width", y="sepal_length", color="species", title=" fig.show() ``` +#### Graph Objects `Figure` Constructor + +As demonstrated above, you can build a complete figure by passing trace and layout specifications to the `plotly.graph_objects.Figure` constructor. These trace and layout specifications can be either dictionaries or graph objects. + +In the following example, the traces are specified using graph objects and the layout is specified as a dictionary. + +```python +import plotly.graph_objects as go + +fig = go.Figure( + data=[go.Bar(x=[1, 2, 3], y=[1, 3, 2])], + layout=dict(title=dict(text="A Figure Specified By A Graph Object")) +) + +fig.show() +``` + #### Figure Factories [Figure factories](/python/figure-factories) (included in `plotly.py` in the `plotly.figure_factory` module) are functions that produce graph object figures, often to satisfy the needs of specialized domains. Here's an example of using the `create_quiver()` figure factory to construct a graph object figure that displays a 2D quiver plot. diff --git a/doc/python/discrete-color.md b/doc/python/discrete-color.md index cb7457da2ea..bd48754d0b1 100644 --- a/doc/python/discrete-color.md +++ b/doc/python/discrete-color.md @@ -30,7 +30,7 @@ jupyter: language: python layout: base name: Discrete Colors - order: 27 + order: 28 permalink: python/discrete-color/ thumbnail: thumbnail/heatmap_colorscale.jpg v4upgrade: true diff --git a/doc/python/figure-factories.md b/doc/python/figure-factories.md index 881185e332a..aee4ddd5adc 100644 --- a/doc/python/figure-factories.md +++ b/doc/python/figure-factories.md @@ -28,7 +28,7 @@ jupyter: language: python layout: base name: Figure Factories - order: 31 + order: 32 permalink: python/figure-factories/ thumbnail: thumbnail/streamline.jpg --- diff --git a/doc/python/figure-labels.md b/doc/python/figure-labels.md index 2e8d229feee..783ce2705b8 100644 --- a/doc/python/figure-labels.md +++ b/doc/python/figure-labels.md @@ -28,7 +28,7 @@ jupyter: language: python layout: base name: Setting the Font, Title, Legend Entries, and Axis Titles - order: 11 + order: 12 permalink: python/figure-labels/ redirect_from: python/font/ thumbnail: thumbnail/figure-labels.png diff --git a/doc/python/figure-structure.md b/doc/python/figure-structure.md new file mode 100644 index 00000000000..6e1102d1f34 --- /dev/null +++ b/doc/python/figure-structure.md @@ -0,0 +1,176 @@ +--- +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: The structure of a figure - data, traces and layout explained. + display_as: file_settings + language: python + layout: base + name: The Figure Data Structure + order: 1 + page_type: u-guide + permalink: python/figure-structure/ + thumbnail: thumbnail/violin.jpg +--- + +The `plotly` Python package exists to [create, manipulate](/python/creating-and-updating-figures/) and [render](/python/renderers/) graphical figures (i.e. charts, plots, maps and diagrams) represented by data structures also referred to as figures. The rendering process uses the [Plotly.js JavaScript library](https://plotly.com/javascript/) under the hood although Python developers using this module very rarely need to interact with the Javascript library directly, if ever. Figures can be represented in Python either as dicts or as instances of the `plotly.graph_objects.Figure` class, and are serialized as text in [JavaScript Object Notation (JSON)](https://json.org/) before being passed to Plotly.js. + +> Note: the recommended entry-point into the plotly package is the [high-level plotly.express module, also known as Plotly Express](/python/plotly-express/), which consists of Python functions which return fully-populated `plotly.graph_objects.Figure` objects. This page exists to document the architecture of the data structure that these objects represent for users who wish to understand more about how to customize them, or assemble them from other `plotly.graph_objects` components. + +Viewing the underlying data structure for any `plotly.graph_objects.Figure` object, including those returned by Plotly Express, can be done via `print(fig)` or, in JupyterLab, with the special `fig.show("json")` renderer. Figures also support `fig.to_dict()` and `fig.to_json()` methods. `print()`ing the figure will result in the often-verbose `layout.template` key being represented as ellipses `'...'` for brevity. + +```python +import plotly.express as px + +fig = px.line(x=["a","b","c"], y=[1,3,2], title="sample figure") +print(fig) +fig.show() +``` + +Plotly.js supports inputs adhering to a well-defined schema, whose overall architecture is explained in this page and which is exhaustively documented in the [Figure Reference](/python/reference/) (which is itself generated from a [machine-readable JSON representation of the schema](https://raw.githubusercontent.com/plotly/plotly.js/master/dist/plot-schema.json)). + +Figures are represented as trees with named nodes called "attributes" which are referred to in text and in the [Figure Reference](/python/reference/) by their full "path" i.e. the dot-delimited concatenation of their parents. For example `"layout.width"` refers to the attribute whose key is `"width"` inside a dict which is the value associated with a key `"layout"` at the root of the figure. If one of the parents is a list rather than a dict, a set of brackets is inserted in the path when referring to the attribute in the abstract, e.g. `"layout.annotations[].text"`. Finally, as explained below, the top-level "data" attribute defines a list of typed objects called "traces" with the schema dependent upon the type, and these attributes' paths are listed in the [Figure Reference](/python/reference/) as `"data[type=scatter].name"`. When [manipulating a `plotly.graph_objects.Figure` object](/python/creating-and-updating-figures/), attributes can be set either directly using Python object attributes e.g. `fig.layout.title.font.family="Open Sans"` or using [update methods and "magic underscores"](/python/creating-and-updating-figures/#magic-underscore-notation) e.g. `fig.update_layout(title_font_family="Open Sans")` + +When building a figure, it is *not necessary to populate every attribute* of every object. At render-time, the JavaScript layer will compute default values for each required unspecified attribute, depending upon the ones that are specified, as documented in the [Figure Reference](/python/reference/). An example of this would be `layout.xaxis.range`, which may be specified explicitly, but if not will be computed based on the range of `x` values for every trace linked to that axis. The JavaScript layer will ignore unknown attributes or malformed values, although the `plotly.graph_objects` module provides Python-side validation for attribute values. Note also that if [the `layout.template` key is present (as it is by default)](/python/templates/) then default values will be drawn first from the contents of the template and only if missing from there will the JavaScript layer infer further defaults. The built-in template can be disabled by setting `layout.template="none"`. + +## High-Level Structure + +The root node of a figure may contain three attributes: + +* `data`, whose value must be a list of dicts referred to as "traces". + * Each trace has one of more than 40 possible types (see below for a list organized by subplot type, including e.g. [`scatter`](/python/line-and-scatter/), [`bar`](/python/bar-charts/), [`pie`](/python/pie-charts/), [`surface`](/python/3d-surface-plots/), [`choropleth`](/python/choropleth-maps/) etc), and represents a set of related graphical marks in a figure. + * Each trace is drawn on a single [subplot](/python/subplots/) whose type must be compatible with the trace's type, or is its own subplot (see below). + * Traces may have a single [legend](/python/legend/) entry, with the exception of pie and funnelarea traces (see below). + * Certain trace types support [continuous color, with an associated colorbar](/python/colorscales/), which can be controlled by attributes either within the trace, or within the layout when using the [coloraxis attribute](/python/colorscales/). +* `layout`, whose value is referred to in text as "the layout" and must be a dict, containing attributes that control positioning and configuration of non-data-related parts of the figure such as + * Dimensions and margins, which define the bounds of "paper coordinates" (see below) + * Figure-wide defaults: [templates](/python/templates/), [fonts](/python/figure-labels/), colors, hover-label and modebar defaults + * [Title](/python/figure-labels/) and [legend](/python/legend/) (positionable in container and/or paper coordinates) + * [Color axes and associated color bars](/python/colorscales/) (positionable in paper coordinates) + * Subplots of various types on which can be drawn multiple traces and which are positioned in paper coordinates: + * `xaxis`, `yaxis`, `xaxis2`, `yaxis3` etc: X and Y cartesian axes, the intersections of which are cartesian subplots + * `scene`, `scene2`, `scene3` etc: 3d scene subplots + * `ternary`, `ternary2`, `ternary3`, `polar`, `polar2`, `polar3`, `geo`, `geo2`, `geo3`, `mapbox`, `mapbox2`, `mabox3` etc: ternary, polar, geo or mapbox subplots + * Non-data marks which can be positioned in paper coordinates, or in data coordinates linked to 2d cartesian subplots: + * `annotations`: [textual annotations with or without arrows](/python/text-and-annotations/) + * `shapes`: [lines, rectangles, ellipses or open or closed paths](/python/shapes/) + * `images`: [background or decorative images](/python/images/) + * Controls which can be positioned in paper coordinates and which can trigger Plotly.js functions when interacted with by a user: + * `updatemenus`: [single buttons, toggles](/python/custom-buttons/) and [dropdown menus](/python/dropdowns/) + * `sliders`: [slider controls](/python/sliders/) +* `frames`, whose value must be a list of dicts that define sequential frames in an [animated plot](/python/animations/). Each frame contains its own data attribute as well as other parameters. Animations are usually triggered and controlled via controls defined in layout.sliders and/or layout.updatemenus + +> Note: At [render-time](/python/renderers/), it is also possible to control certain figure behaviors which are not considered part of the figure proper i.e. the behaviour of the "modebar" and how the figure relates to mouse actions like scrolling. The object that contains these options is called the [`config`, and has its own documentation page](/python/configuration-options/). It is exposed in Python as the `config` keyword argument of the `.show()` method on `plotly.graph_objects.Figure` objects. + +## Positioning With Paper or Container Coordinates + +Various figure components configured within the layout of the figure support positioning attributes named `x` or `y`, whose values may be specified in "paper coordinates" (sometimes referred to as "plot fractions" or "normalized coordinates"). Examples include `layout.xaxis.domain` or `layout.legend.x` or `layout.annotation[].x`. + +Positioning in paper coordinates is not done in absolute pixel terms, but rather in terms relative to a coordinate system defined with an origin `(0,0)` at `(layout.margin.l, layout.margin.b)` and a point `(1,1)` at `(layout.width-layout.margin.r, layout.height-layout.margin.t)`. Values less than 0 or greater than 1 are permitted, and refer to areas within the plot margins. + +Note that the contents of the `layout.margin` attribute are by default computed based on the position and dimensions of certain items like the title or legend, and may be made dependent on the position and dimensions of tick labels as well when setting the `layout.xaxis.automargin` attribute to `True`. This has the effect of automatically increasing the margin values and therefore shrinking the physical area defined between the `(0,0)` and `(1,1)` points. Positioning certain items at paper coordinates less than 0 or greater than 1 will also trigger this behavior. + +The figure title may be positioned using "container coordinates" which have `(0,0)` and `(1,1)` anchored at the bottom-left and top-right of the figure, respectively, and therefore are independent of the values of layout.margin. + +## 2D Cartesian Trace Types and Subplots + +The most commonly-used kind of subplot is a [two-dimensional Cartesian subplot](/python/axes/). Traces compatible with these subplots support `xaxis` and `yaxis` attributes whose values must refer to corresponding objects in the layout portion of the figure. For example, if `xaxis="x"`, and `yaxis="y"` (which is the default) then this trace is drawn on the subplot at the intersection of the axes configured under `layout.xaxis` and `layout.yaxis`, but if `xaxis="x2"` and `yaxis="y3"` then the trace is drawn at the intersection of the axes configured under `layout.xaxis2` and `layout.yaxis3`. Note that attributes such as `layout.xaxis` and `layout.xaxis2` etc do not have to be explicitly defined, in which case default values will be inferred. Multiple traces of different types can be drawn on the same subplot. + +X- and Y-axes support the `type` attribute, which enables them to represent [continuous values (`type="linear"`, `type="log"`)](/python/axes/), [temporal values (`type="date"`)](/python/time-series/) or [categorical values (`type="category"`, `type="multicategory`)](/python/bar-charts/). Axes can also be overlaid on top of one another to create [dual-axis or multiple-axis charts](/python/multiple-axes/). 2-d cartesian subplots lend themselves very well to creating ["small multiples" figures, also known as facet or trellis plots](/python/facet-plots/). + +The following trace types are compatible with 2d-cartesian subplots via the `xaxis` and `yaxis` attributes: + +* scatter-like trace types: [`scatter`](/python/line-and-scatter/) and [`scattergl`](/python/webgl-vs-svg/), which can be used to draw [scatter plots](/python/line-and-scatter/), [line plots and curves](/python/line-charts/), [time-series plots](/python/time-series/), [bubble charts](/python/bubble-charts/), [dot plots](/python/dot-plots/) and [filled areas](/python/filled-area-plots/) and also support [error bars](/python/error-bars/) +* [`bar`](/python/bar-charts/), [`funnel`](/python/funnel-charts/), [`waterfall`](/python/waterfall-charts/): bar-like trace types which can also be used to draw [timelines and Gantt charts](/python/gantt/) +* [`histogram`](/python/histograms/): an *aggregating* bar-like trace type +* [`box`](/python/box-plots/) and `violin`: 1-dimensional distribution-like trace types +* [`histogram2d`](/python/2D-Histogram/) and [`histogram2dcontour`](/python/2d-histogram-contour/): 2-dimensional distribution-like density trace types +* [`image`](/python/imshow/), [`heatmap`](/python/heatmaps/) and [`contour`](/python/contour-plots/): matrix trace types +* [`ohlc`](/python/ohlc-charts/) and [`candlestick`](/python/candlestick-charts/): stock-like trace types +* [`carpet`](/python/carpet-plot/): a special trace type for building [carpet plots](/python/carpet-plot/), in that other traces can use as subplots (see below) +* [`splom`](/python/splom/): multi-dimensional scatter plots which implicitly refer to many 2-d cartesian subplots at once. + +## 3D, Polar and Ternary Trace Types and Subplots + +Beyond 2D cartesian subplots, figures can include [three-dimensional cartesian subplots](/python/3d-charts/), [polar subplots](/python/polar-chart/) and [ternary subplots](/python/ternary-plots/). The following trace types support attributes named `scene`, `polar` or `ternary`, whose values must refer to corresponding objects in the layout portion of the figure i.e. `ternary="ternary2"` etc. Note that attributes such as `layout.scene` and `layout.ternary2` etc do not have to be explicitly defined, in which case default values will be inferred. Multiple traces of a compatible type can be placed on the same subplot. + +The following trace types are compatible with 3D subplots via the `scene` attribute, which contains special [camera controls](/python/3d-camera-controls/): + +* [`scatter3d`](/python/3d-scatter-plots/), which can be used to draw [individual markers](/python/3d-scatter-plots/), [3d bubble charts](/python/3d-bubble-charts/) and [lines and curves](/python/3d-line-plots/) +* [`surface`](/python/3d-surface-plots/) and [`mesh`](/python/3d-mesh/): 3d surface trace types +* [`cone`](/python/cone-plot/) and [`streamtube`](/python/streamtube-plot/): 3d vector field trace types +* [`volume`](/python/3d-volume-plots/) and [`isosurface`](/python/3d-isosurface-plots/): 3d volume trace types + +The following trace types are compatible with polar subplots via the `polar` attribute: + +* scatter-like trace types: [`scatterpolar` and `scatterpolargl`](/python/polar-chart/), which can be used to draw individual markers, [curves and filled areas (i.e. radar or spider charts)](/python/radar-chart/) +* [`barpolar`](/python/wind-rose-charts/): useful for [wind roses](/python/wind-rose-charts/) and other polar bar charts + +The following trace types are compatible with ternary subplots via the `ternary` attribute: + +* [`scatterternary`](/python/ternary-plots/), which can be used to draw individual markers, [curves and filled areas](/python/ternary-contour/) + +## Map Trace Types and Subplots + +Figures can include two different types of map subplots: [geo subplots for outline maps](/python/map-configuration/) and [mapbox subplots for tile maps](/python/mapbox-layers/). The following trace types support attributes named `geo` or `mapbox`, whose values must refer to corresponding objects in the layout i.e. `geo="geo2"` etc. Note that attributes such as `layout.geo2` and `layout.mapbox` etc do not have to be explicitly defined, in which case default values will be inferred. Multiple traces of a compatible type can be placed on the same subplot. + +The following trace types are compatible with geo subplots via the `geo` attribute: + +* [`scattergeo`](/python/scatter-plots-on-maps/), which can be used to draw [individual markers](/python/scatter-plots-on-maps/), [line and curves](/python/lines-on-maps/) and filled areas on outline maps +* [`choropleth`](/python/choropleth-maps/): [colored polygons](/python/choropleth-maps/) on outline maps + +The following trace types are compatible with mapbox subplots via the `mapbox` attribute: + +* [`scattermapbox`](/python/scattermapbox/), which can be used to draw [individual markers](/python/scattermapbox/), [lines and curves](/python/lines-on-mapbox/) and [filled areas](/python/filled-area-on-mapbox/) on tile maps +* [`choroplethmapbox`](/python/mapbox-county-choropleth/): colored polygons on tile maps +* [`densitymapbox`](/python/mapbox-density-heatmaps/): density heatmaps on tile maps + +## Traces Which Are Their Own Subplots + +Certain trace types cannot share subplots, and hence have no attribute to map to a corresponding subplot in the layout. Instead, these traces are their own subplot and support a `domain` attribute for position, which enables the trace to be positioned in paper coordinates (see below). With the exception of `pie` and `funnelarea`, such traces also do not support legends (see below) + +The following trace types are their own subplots and support a domain attribute: + +* [`pie`](/python/pie-charts/) and [`funnelarea`](/python/waterfall-charts/): one-level part-to-whole relationships with legend items +* [`sunburst`](/python/sunburst-charts/) and [`treemap`](/python/treemaps/): hierarchical multi-level part-to-whole relationships +* [`parcoords`](/python/parallel-coordinates-plot/) and [`parcats`](/python/parallel-categories-diagram/): continuous and categorical multidimensional figures with [parallel coordinates](/python/parallel-coordinates-plot/) and [parallel sets](/python/parallel-categories-diagram/) +* [`sankey`](/python/sankey-diagram/): [flow diagrams](/python/sankey-diagram/) +* [`table`](/python/table/): [text-based tables](/python/table/) +* [`indicator`](http://indicators/): big numbers, [gauges](/python/gauge-charts/), and [bullet charts](/python/bullet-charts/) + +## Carpet Trace Types and Subplots + +Certain trace types use [traces of type `carpet` as a subplot](/python/carpet-plot/). These support a `carpet` attribute whose value must match the value of the `carpet` attribute of the `carpet` trace they are to be drawn on. Multiple compatible traces can be placed on the same `carpet` trace. + +The following trace types are compatible with `carpet` trace subplots via the `carpet` attribute: + +* [`scattercarpet`](/python/carpet-scatter/), which can be used to draw individual markers, curves and filled areas +* [`contourcarpet`](/python/carpet-plot/) + +## Trace Types, Legends and Color Bars + +Traces of most types can be optionally associated with a single legend item in the [legend](/python/legend/), which can be shown via the `showlegend` attribute. Traces which are their own subplots (see above) do not support this, with the exception of traces of type `pie` and `funnelarea` for which every distinct color represented in the trace gets a separate legend item. Users may show or hide traces by clicking or double-clicking on their associated legend item. Traces that support legend items also support the `legendgroup` attribute, and all traces with the same legend group are treated the same way during click/double-click interactions. + +The fact that legend items are linked to traces means that when using [discrete color](/python/discrete-color/), a figure must have one trace per color in order to get a meaningful legend. [Plotly Express has robust support for discrete color](/python/discrete-color/) to make this easy. + +Traces which support [continuous color](/python/colorscales/) can also be associated with color axes in the layout via the `coloraxis` attribute. Multiple traces can be linked to the same color axis. Color axes have a legend-like component called color bars. Alternatively, color axes can be configured within the trace itself. diff --git a/doc/python/getting-started.md b/doc/python/getting-started.md index a9e8e69fbc7..7824876e369 100644 --- a/doc/python/getting-started.md +++ b/doc/python/getting-started.md @@ -38,15 +38,25 @@ jupyter: ### Overview -The plotly Python library ([plotly.py](https://plotly.com/python/)) is an interactive, [open-source](https://github.com/plotly/plotly.py) plotting library that supports over 40 unique chart types covering a wide range of statistical, financial, geographic, scientific, and 3-dimensional use-cases. +The [`plotly` Python library](/python/) is an interactive, [open-source](/python/is-plotly-free) plotting library that supports over 40 unique chart types covering a wide range of statistical, financial, geographic, scientific, and 3-dimensional use-cases. -Built on top of the Plotly JavaScript library ([plotly.js](https://plotly.com/javascript/)), plotly.py enables Python users to create beautiful interactive web-based visualizations that can be displayed in Jupyter notebooks, saved to standalone HTML files, or served as part of pure Python-built web applications using Dash. +Built on top of the Plotly JavaScript library ([plotly.js](https://plotly.com/javascript/)), `plotly` enables Python users to create beautiful interactive web-based visualizations that can be displayed in Jupyter notebooks, saved to standalone HTML files, or served as part of pure Python-built web applications using Dash. The `plotly` Python library is sometimes referred to as "plotly.py" to differentiate it from the JavaScript library. -Thanks to deep integration with the [orca](https://github.com/plotly/orca) image export utility, plotly.py also provides great support for non-web contexts including desktop editors (e.g. QtConsole, Spyder, PyCharm) and static document publishing (e.g. exporting notebooks to PDF with high-quality vector images). +Thanks to deep integration with the [orca](https://github.com/plotly/orca) image export utility, `plotly` also provides great support for non-web contexts including desktop editors (e.g. QtConsole, Spyder, PyCharm) and static document publishing (e.g. exporting notebooks to PDF with high-quality vector images). + +This Getting Started guide explains how to install `plotly` and related optional pages. Once you've installed, you can use our documentation in three main ways: + +1. You jump right in to **examples** of how to make [basic charts](/python/basic-charts/), [statistical charts](/python/statistical-charts/), [scientific charts](/python/scientific-charts/), [financial charts](/python/financial-charts/), [maps](/python/maps/), and [3-dimensional charts](/python/3d-charts/). +2. If you prefer to learn about the **fundamentals** of the library first, you can read about [the structure of figures](/python/figure-structure/), [how to create and update figures](/python/creating-and-updating-figures/), [how to display figures](/python/renderers/), [how to theme figures with templates](/python/templates/), [how to export figures to various formats](/python/static-image-export/) and about [Plotly Express, the high-level API](/python/plotly-express/) for doing all of the above. +3. You can check out our exhaustive reference guides: the [Python API reference](/python-api-reference) or the [Figure Reference](/python/reference) + +For information on using Python to build web applications containing plotly figures, see the [_Dash User Guide_](https://dash.plotly.com/). + +We also encourage you to join the [Plotly Community Forum](http://community.plotly.com/) if you want help with anything related to `plotly`. ### Installation -plotly.py may be installed using pip... +`plotly` may be installed using pip... ``` $ pip install plotly==4.8.1 @@ -164,7 +174,7 @@ fig = go.FigureWidget(data=go.Bar(y=[2, 3, 1])) fig ``` -Please check out our [Troubleshooting guide](https://plotly.com/python/troubleshooting/) if you run into any problems with JupyterLab. +Please check out our [Troubleshooting guide](/python/troubleshooting/) if you run into any problems with JupyterLab. @@ -223,7 +233,7 @@ or conda. $ conda install -c plotly plotly-geo=1.0.0 ``` -See [_USA County Choropleth Maps in Python_](https://plotly.com/python/county-choropleth/) for more information on the county choropleth figure factory. +See [_USA County Choropleth Maps in Python_](/python/county-choropleth/) for more information on the county choropleth figure factory. #### Chart Studio Support @@ -244,18 +254,14 @@ $ conda install -c plotly chart-studio=1.0.0 ### Where to next? -Now that you have everything installed, you are ready to start reading and running examples of [basic charts](/python/basic-charts/), [statistical charts](/python/statistical-charts/), [scientific charts](/python/scientific-charts/), [financial charts](/python/#financial-charts), [geographic charts and maps](/python/maps/), and [3-dimensional charts](/python/3d-charts/). +Once you've installed, you can use our documentation in three main ways: -For a complete overview of all of the ways that figures can be created and updated, see the [_Plotly User Guide for Python_](/python/user-guide/). - -For information on configuring figure layout options (e.g. axes, titles, legends, etc) and styling figures (e.g. colors, fonts, annotations, images, shapes, etc.), see [_Plotly Fundamentals_](/python/plotly-fundamentals). - -For information on theming plotly figures, see [_Theming and templates with plotly for Python_](/python/templates/). - -For information on all of the ways that plotly figures can be displayed, see [_Displaying plotly figures with plotly for Python_](/python/renderers/). - -For the full searchable reference of every figure property, see the [_Python figure reference_](https://plotly.com/python/reference/). +1. You jump right in to **examples** of how to make [basic charts](/python/basic-charts/), [statistical charts](/python/statistical-charts/), [scientific charts](/python/scientific-charts/), [financial charts](/python/financial-charts/), [maps](/python/maps/), and [3-dimensional charts](/python/3d-charts/). +2. If you prefer to learn about the **fundamentals** of the library first, you can read about [the structure of figures](/python/figure-structure/), [how to create and update figures](/python/creating-and-updating-figures/), [how to display figures](/python/renderers/), [how to theme figures with templates](/python/templates/), [how to export figures to various formats](/python/static-image-export/) and about [Plotly Express, the high-level API](/python/plotly-express/) for doing all of the above. +3. You can check out our exhaustive reference guides: the [Python API reference](/python-api-reference) or the [Figure Reference](/python/reference) For information on using Python to build web applications containing plotly figures, see the [_Dash User Guide_](https://dash.plotly.com/). +We also encourage you to join the [Plotly Community Forum](http://community.plotly.com/) if you want help with anything related to `plotly`. + diff --git a/doc/python/graphing-multiple-chart-types.md b/doc/python/graphing-multiple-chart-types.md index d563042789b..213af2edb22 100644 --- a/doc/python/graphing-multiple-chart-types.md +++ b/doc/python/graphing-multiple-chart-types.md @@ -27,7 +27,7 @@ jupyter: language: python layout: base name: Multiple Chart Types - order: 16 + order: 17 page_type: u-guide permalink: python/graphing-multiple-chart-types/ thumbnail: thumbnail/multiple-chart-type.jpg diff --git a/doc/python/hover-text-and-formatting.md b/doc/python/hover-text-and-formatting.md index 37cd419a3e3..770d07536e7 100644 --- a/doc/python/hover-text-and-formatting.md +++ b/doc/python/hover-text-and-formatting.md @@ -27,7 +27,7 @@ jupyter: language: python layout: base name: Hover Text and Formatting - order: 21 + order: 22 permalink: python/hover-text-and-formatting/ thumbnail: thumbnail/hover-text.png --- diff --git a/doc/python/images.md b/doc/python/images.md index 32d5826f826..5985e88a537 100644 --- a/doc/python/images.md +++ b/doc/python/images.md @@ -27,7 +27,7 @@ jupyter: language: python layout: base name: Images - order: 22 + order: 23 permalink: python/images/ thumbnail: thumbnail/images.png v4upgrade: true diff --git a/doc/python/interactive-html-export.md b/doc/python/interactive-html-export.md index 981a0fab79b..9af1706b57e 100644 --- a/doc/python/interactive-html-export.md +++ b/doc/python/interactive-html-export.md @@ -28,7 +28,7 @@ jupyter: language: python layout: base name: Interactive HTML Export - order: 29 + order: 30 page_type: u-guide permalink: python/interactive-html-export/ thumbnail: thumbnail/static-image-export.png diff --git a/doc/python/ipython-vs-python.md b/doc/python/ipython-vs-python.md index d3fb88b409e..020297219fe 100644 --- a/doc/python/ipython-vs-python.md +++ b/doc/python/ipython-vs-python.md @@ -27,7 +27,7 @@ jupyter: language: python layout: base name: IPython vs Python - order: 24 + order: 25 permalink: python/ipython-vs-python/ thumbnail: thumbnail/venn.jpg --- diff --git a/doc/python/legend.md b/doc/python/legend.md index 9d62ae391df..3d6f23a6c4c 100644 --- a/doc/python/legend.md +++ b/doc/python/legend.md @@ -27,7 +27,7 @@ jupyter: language: python layout: base name: Legends - order: 13 + order: 14 permalink: python/legend/ redirect_from: python/horizontal-legend/ thumbnail: thumbnail/legends.gif diff --git a/doc/python/marker-style.md b/doc/python/marker-style.md index 8110d154a83..96bbcc3b01e 100644 --- a/doc/python/marker-style.md +++ b/doc/python/marker-style.md @@ -27,7 +27,7 @@ jupyter: language: python layout: base name: Styling Markers - order: 18 + order: 19 permalink: python/marker-style/ thumbnail: thumbnail/marker-style.gif --- diff --git a/doc/python/multiple-axes.md b/doc/python/multiple-axes.md index 245a0442d44..1950a9a0f42 100644 --- a/doc/python/multiple-axes.md +++ b/doc/python/multiple-axes.md @@ -27,7 +27,7 @@ jupyter: language: python layout: base name: Multiple Axes - order: 14 + order: 15 permalink: python/multiple-axes/ thumbnail: thumbnail/multiple-axes.jpg --- @@ -225,4 +225,4 @@ fig.show() ``` #### Reference -All of the y-axis properties are found here: https://plotly.com/python/reference/#YAxis. For more information on creating subplots see the [Subplots in Python](/python/subplots/) section. +All of the y-axis properties are found here: https://plotly.com/python/reference/#YAxis. For more information on creating subplots see the [Subplots in Python](/python/subplots/) section. \ No newline at end of file diff --git a/doc/python/orca-management.md b/doc/python/orca-management.md index f49e28dec70..061cca29cd5 100644 --- a/doc/python/orca-management.md +++ b/doc/python/orca-management.md @@ -28,7 +28,7 @@ jupyter: language: python layout: base name: Orca Management - order: 7 + order: 8 permalink: python/orca-management/ thumbnail: thumbnail/orca-management.png --- diff --git a/doc/python/pandas-backend.md b/doc/python/pandas-backend.md index c568ea225b2..41be97978a5 100644 --- a/doc/python/pandas-backend.md +++ b/doc/python/pandas-backend.md @@ -28,7 +28,7 @@ jupyter: language: python layout: base name: Pandas Plotting Backend - order: 30 + order: 31 permalink: python/pandas-backend/ redirect_from: python/cufflinks/ thumbnail: thumbnail/plotly-express.png diff --git a/doc/python/px-arguments.md b/doc/python/px-arguments.md index 45db70dadab..8eccb579cd5 100644 --- a/doc/python/px-arguments.md +++ b/doc/python/px-arguments.md @@ -27,7 +27,7 @@ jupyter: language: python layout: base name: Plotly Express Arguments - order: 17 + order: 18 page_type: u-guide permalink: python/px-arguments/ thumbnail: thumbnail/plotly-express.png diff --git a/doc/python/renderers.md b/doc/python/renderers.md index dd808183cc0..871b9b65eda 100644 --- a/doc/python/renderers.md +++ b/doc/python/renderers.md @@ -27,16 +27,16 @@ jupyter: language: python layout: base name: Displaying Figures - order: 1 + order: 3 page_type: example_index permalink: python/renderers/ redirect_from: python/offline/ thumbnail: thumbnail/displaying-figures.png --- -# Displaying Figures +# Displaying Figures -Plotly's Python graphing library, `plotly.py`, gives you a wide range of options for how and where to display your figures. +Plotly's Python graphing library, `plotly.py`, gives you a wide range of options for how and where to display your figures. In general, there are three different approaches you can take in order to display figures: @@ -72,7 +72,7 @@ fig > To be precise, figures will display themselves using the current default renderer when the two following conditions are true. First, the last expression in a cell must evaluate to a figure. Second, `plotly.py` must be running from within an `IPython` kernel. -**In many contexts, an appropriate renderer will be chosen automatically and you will not need to perform any additional configuration.** These contexts include the classic [Jupyter Notebook](https://jupyter.org/), [JupyterLab](https://jupyterlab.readthedocs.io/en/stable/) (provided the `jupyterlab-plotly` JupyterLab extension is installed), [Visual Studio Code notebooks](https://code.visualstudio.com/docs/python/jupyter-support), [Google Colaboratory](https://colab.research.google.com/notebooks/intro.ipynb), [Kaggle](https://www.kaggle.com/kernels) notebooks, [Azure](https://notebooks.azure.com/) notebooks, and the [Python interactive shell](https://www.python.org/shell/). +**In many contexts, an appropriate renderer will be chosen automatically and you will not need to perform any additional configuration.** These contexts include the classic [Jupyter Notebook](https://jupyter.org/), [JupyterLab](https://jupyterlab.readthedocs.io/en/stable/) (provided the `jupyterlab-plotly` JupyterLab extension is installed), [Visual Studio Code notebooks](https://code.visualstudio.com/docs/python/jupyter-support), [Google Colaboratory](https://colab.research.google.com/notebooks/intro.ipynb), [Kaggle](https://www.kaggle.com/kernels) notebooks, [Azure](https://notebooks.azure.com/) notebooks, and the [Python interactive shell](https://www.python.org/shell/). Additional contexts are supported by choosing a compatible renderer including the [IPython console](https://docs.spyder-ide.org/ipythonconsole.html), [QtConsole](https://qtconsole.readthedocs.io/en/stable/), [Spyder](https://www.spyder-ide.org/), and more. @@ -228,7 +228,7 @@ fig.show(renderer="png", width=800, height=300) ``` ## Displaying Figures Using `ipywidgets` -Plotly figures can be displayed in [ipywidgets](https://ipywidgets.readthedocs.io/en/stable/) contexts using `plotly.graph_objects.FigureWidget` objects. `FigureWidget` is a figure graph object (just like `plotly.graph_objects.Figure`), so you can add traces to it and update it just like a regular `Figure`. But `FigureWidget` is also an `ipywidgets` object, which means that you can display it alongside other `ipywidgets` to build user interfaces right in the notebook. +Plotly figures can be displayed in [ipywidgets](https://ipywidgets.readthedocs.io/en/stable/) contexts using `plotly.graph_objects.FigureWidget` objects. `FigureWidget` is a figure graph object (just like `plotly.graph_objects.Figure`), so you can add traces to it and update it just like a regular `Figure`. But `FigureWidget` is also an `ipywidgets` object, which means that you can display it alongside other `ipywidgets` to build user interfaces right in the notebook. See the [Plotly FigureWidget Overview](https://plot.ly/python/figurewidget/) for more information on integrating `plotly.py` figures with `ipywidgets`. diff --git a/doc/python/setting-graph-size.md b/doc/python/setting-graph-size.md index 6bc503bb091..efef306205d 100644 --- a/doc/python/setting-graph-size.md +++ b/doc/python/setting-graph-size.md @@ -27,7 +27,7 @@ jupyter: language: python layout: base name: Setting Graph Size - order: 9 + order: 10 permalink: python/setting-graph-size/ thumbnail: thumbnail/sizing.png --- diff --git a/doc/python/shapes.md b/doc/python/shapes.md index 55415dfc716..10653522935 100644 --- a/doc/python/shapes.md +++ b/doc/python/shapes.md @@ -28,7 +28,7 @@ jupyter: language: python layout: base name: Shapes - order: 23 + order: 24 permalink: python/shapes/ thumbnail: thumbnail/shape.jpg --- diff --git a/doc/python/styling-plotly-express.md b/doc/python/styling-plotly-express.md index 5379ea0bfef..7108957dde3 100644 --- a/doc/python/styling-plotly-express.md +++ b/doc/python/styling-plotly-express.md @@ -29,7 +29,7 @@ jupyter: language: python layout: base name: Styling Plotly Express Figures - order: 28 + order: 29 page_type: u-guide permalink: python/styling-plotly-express/ thumbnail: thumbnail/plotly-express.png diff --git a/doc/python/subplots.md b/doc/python/subplots.md index 50d7b90e8e5..db5d872400a 100644 --- a/doc/python/subplots.md +++ b/doc/python/subplots.md @@ -28,7 +28,7 @@ jupyter: language: python layout: base name: Subplots - order: 15 + order: 16 page_type: u-guide permalink: python/subplots/ redirect_from: ipython-notebooks/subplots/ diff --git a/doc/python/templates.md b/doc/python/templates.md index d3f548cecf0..2e2af68c845 100644 --- a/doc/python/templates.md +++ b/doc/python/templates.md @@ -27,7 +27,7 @@ jupyter: language: python layout: base name: Theming and templates - order: 6 + order: 7 page_type: u-guide permalink: python/templates/ thumbnail: thumbnail/theming-and-templates.png diff --git a/doc/python/text-and-annotations.md b/doc/python/text-and-annotations.md index bd956a173a8..785138ea57e 100644 --- a/doc/python/text-and-annotations.md +++ b/doc/python/text-and-annotations.md @@ -27,7 +27,7 @@ jupyter: language: python layout: base name: Text and Annotations - order: 20 + order: 21 permalink: python/text-and-annotations/ thumbnail: thumbnail/text-and-annotations.png --- diff --git a/doc/python/tick-formatting.md b/doc/python/tick-formatting.md index e41e9c016c1..62f5273279c 100644 --- a/doc/python/tick-formatting.md +++ b/doc/python/tick-formatting.md @@ -27,7 +27,7 @@ jupyter: language: python layout: base name: Formatting Ticks - order: 10 + order: 11 permalink: python/tick-formatting/ thumbnail: thumbnail/tick-formatting.gif --- diff --git a/doc/python/troubleshooting.md b/doc/python/troubleshooting.md index 4d8fa1b9abf..30cdcb8139b 100644 --- a/doc/python/troubleshooting.md +++ b/doc/python/troubleshooting.md @@ -28,7 +28,7 @@ jupyter: language: python layout: base name: Troubleshooting - order: 25 + order: 26 page_type: u-guide permalink: python/troubleshooting/ thumbnail: thumbnail/modebar-icons.png diff --git a/doc/python/v4-migration.md b/doc/python/v4-migration.md index ae058acf9c1..af13e0e8b67 100644 --- a/doc/python/v4-migration.md +++ b/doc/python/v4-migration.md @@ -27,7 +27,7 @@ jupyter: language: python layout: base name: Version 4 Migration Guide - order: 3 + order: 6 page_type: example_index permalink: python/v4-migration/ thumbnail: thumbnail/v4-migration.png diff --git a/doc/python/wide-form.md b/doc/python/wide-form.md index c67813c1fc4..d95ea383fe4 100644 --- a/doc/python/wide-form.md +++ b/doc/python/wide-form.md @@ -28,7 +28,7 @@ jupyter: language: python layout: base name: Plotly Express Wide-Form Support - order: 32 + order: 33 page_type: u-guide permalink: python/wide-form/ thumbnail: thumbnail/plotly-express.png