diff --git a/python/animations.md b/python/animations.md index f4ea15c4b..1e3c0cd5c 100644 --- a/python/animations.md +++ b/python/animations.md @@ -26,7 +26,7 @@ jupyter: #### Animated figures with Plotly Express Several Plotly Express functions support the creation of animated figures through the `animation_frame` and `animation_group` arguments. -Here is an example of an animated scatter plot creating using Plotly Express +Here is an example of an animated scatter plot creating using Plotly Express. Note that you should always fix the `x_range` and `y_range` to ensure that your data remains visible throughout the animation. ```python import plotly.express as px @@ -36,6 +36,22 @@ px.scatter(gapminder, x="gdpPercap", y="lifeExp", animation_frame="year", animat log_x=True, size_max=55, range_x=[100,100000], range_y=[25,90]) ``` +#### Animated Bar Charts with Plotly Express + + Note that you should always fix the `y_range` to ensure that your data remains visible throughout the animation. + +```python +import plotly.express as px + +gapminder = px.data.gapminder() + +fig = px.bar(gapminder, x="continent", y="pop", color="continent", + animation_frame="year", animation_group="country", range_y=[0,4000000000]) +fig.show() +``` + +#### Animated figures with Graph Objects + The remainder of this section describes the low-level API for constructing animated figures manually. diff --git a/python/facet-plots.md b/python/facet-plots.md index d7a282570..17d3a0f50 100644 --- a/python/facet-plots.md +++ b/python/facet-plots.md @@ -20,7 +20,7 @@ jupyter: name: python nbconvert_exporter: python pygments_lexer: ipython3 - version: 3.6.7 + version: 3.6.8 plotly: description: How to make Facet and Trellis Plots in Python with Plotly. display_as: statistical @@ -58,6 +58,18 @@ fig = px.bar(tips, x="size", y="total_bill", color="sex", facet_row="smoker") fig.show() ``` +### Wrapping Column Facets + +When the facet dimension has a large number of unique values, it is possible to wrap columns using the `facet_col_wrap` argument. + +```python +import plotly.express as px +df = px.data.gapminder() +fig = px.scatter(df, x='gdpPercap', y='lifeExp', color='continent', size='pop', + facet_col='year', facet_col_wrap=4) +fig.show() +``` + ### Histogram Facet Grids ```python @@ -67,3 +79,27 @@ fig = px.histogram(tips, x="total_bill", y="tip", color="sex", facet_row="time", category_orders={"day": ["Thur", "Fri", "Sat", "Sun"], "time": ["Lunch", "Dinner"]}) fig.show() ``` + +### Facets with independent axes + +By default, facet axes are linked together: zooming inside one of the facets will also zoom in the other facets. You can disable this behaviour when you use `facet_row` only, by disabling `matches` on the Y axes, or when using `facet_col` only, by disabling `matches` on the X axes. It is not recommended to use this approach when using `facet_row` and `facet_col` together, as in this case it becomes very hard to understand the labelling of axes and grid lines. + +```python +import plotly.express as px +df = px.data.tips() +fig = px.scatter(df, x="total_bill", y="tip", color='sex', facet_row="day") +fig.update_yaxes(matches=None) +fig.show() +``` + +```python +import plotly.express as px +df = px.data.tips() +fig = px.scatter(df, x="total_bill", y="tip", color='sex', facet_col="day") +fig.update_xaxes(matches=None) +fig.show() +``` + +```python + +``` diff --git a/python/images.md b/python/images.md index f31937110..44034fde9 100644 --- a/python/images.md +++ b/python/images.md @@ -6,7 +6,7 @@ jupyter: extension: .md format_name: markdown format_version: '1.1' - jupytext_version: 1.1.7 + jupytext_version: 1.1.1 kernelspec: display_name: Python 3 language: python @@ -20,7 +20,7 @@ jupyter: name: python nbconvert_exporter: python pygments_lexer: ipython3 - version: 3.6.5 + version: 3.7.3 plotly: description: How to add images to charts as background images or logos. display_as: file_settings @@ -30,10 +30,13 @@ jupyter: order: 31 permalink: python/images/ thumbnail: thumbnail/images.png + v4upgrade: true --- #### Add a Background Image +In this page we explain how to add static, non-interactive images as background, logo or annotation images to a figure. For exploring image data in interactive charts, see the [tutorial on displaying image data](/python/imshow). + ```python import plotly.graph_objects as go @@ -46,8 +49,7 @@ fig.add_trace( ) # Add images -fig.update_layout( - images=[ +fig.add_layout_image( go.layout.Image( source="https://images.plot.ly/language-icons/api-home/python-logo.png", xref="x", @@ -59,7 +61,6 @@ fig.update_layout( sizing="stretch", opacity=0.5, layer="below") - ] ) # Set templates @@ -112,14 +113,14 @@ fig.add_trace( ) # Add image -fig.update_layout( - images=[dict( +fig.add_layout_image( + dict( source="https://raw.githubusercontent.com/cldougl/plot_images/add_r_img/vox.png", xref="paper", yref="paper", x=1, y=1.05, sizex=0.2, sizey=0.2, xanchor="right", yanchor="bottom" - )], + ) ) # update layout properties @@ -171,30 +172,26 @@ for (x, y), n in zip(simulated_absorptions, names): fig.add_trace(go.Scatter(x=x, y=y, name=n)) # Add images -fig.update_layout( - images=[go.layout.Image( +fig.add_layout_image( + go.layout.Image( source="https://raw.githubusercontent.com/michaelbabyn/plot_data/master/benzene.png", - xref="paper", - yref="paper", x=0.75, y=0.65, - sizex=0.3, - sizey=0.3, - xanchor="right", - yanchor="bottom" - ), go.layout.Image( + )) +fig.add_layout_image(go.layout.Image( source="https://raw.githubusercontent.com/michaelbabyn/plot_data/master/naphthalene.png", - xref="paper", - yref="paper", x=0.9, y=0.3, + ) +) +fig.update_layout_images(dict( + xref="paper", + yref="paper", sizex=0.3, sizey=0.3, xanchor="right", yanchor="bottom" - ) - ] -) +)) # Add annotations fig.update_layout( @@ -277,8 +274,8 @@ fig.update_yaxes( ) # Add image -fig.update_layout( - images=[go.layout.Image( +fig.add_layout_image( + go.layout.Image( x=0, sizex=img_width * scale_factor, y=img_height * scale_factor, @@ -288,7 +285,7 @@ fig.update_layout( opacity=1.0, layer="below", sizing="stretch", - source="https://raw.githubusercontent.com/michaelbabyn/plot_data/master/bridge.jpg")] + source="https://raw.githubusercontent.com/michaelbabyn/plot_data/master/bridge.jpg") ) # Configure other layout diff --git a/python/imshow.md b/python/imshow.md new file mode 100644 index 000000000..12a477c38 --- /dev/null +++ b/python/imshow.md @@ -0,0 +1,190 @@ +--- +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 display image data in Python with Plotly. + display_as: scientific + has_thumbnail: true + ipynb: ~notebook_demo/34 + language: python + layout: base + name: Imshow + order: 3 + page_type: example_index + permalink: python/imshow/ + thumbnail: thumbnail/imshow.jpg + v4upgrade: true +--- + +This tutorial shows how to display and explore image data. If you would like +instead a logo or static image, use `go.layout.Image` as explained +[here](/python/images). + +### Displaying RBG image data with px.imshow + +`px.imshow` displays multichannel (RGB) or single-channel ("grayscale") image data. + +```python +import plotly.express as px +import numpy as np +img_rgb = np.array([[[255, 0, 0], [0, 255, 0], [0, 0, 255]], + [[0, 255, 0], [0, 0, 255], [255, 0, 0]] + ], dtype=np.uint8) +fig = px.imshow(img_rgb) +fig.show() +``` + +### Read image arrays from image files + +In order to create a numerical array to be passed to `px.imshow`, you can use a third-party library like [PIL](https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.open), [scikit-image](https://scikit-image.org/docs/dev/user_guide/getting_started.html) or [opencv](https://opencv-python-tutroals.readthedocs.io/en/latest/py_tutorials/py_gui/py_image_display/py_image_display.html). We show below how to open an image from a file with `skimage.io.imread`, and alternatively how to load a demo image from `skimage.data`. + +```python +import plotly.express as px +from skimage import io +img = io.imread('https://upload.wikimedia.org/wikipedia/commons/thumb/0/00/Crab_Nebula.jpg/240px-Crab_Nebula.jpg') +fig = px.imshow(img) +fig.show() +``` + +```python +import plotly.express as px +from skimage import data +img = data.astronaut() +fig = px.imshow(img) +fig.show() +``` + +### Display single-channel 2D image as grayscale + +For a 2D image, `px.imshow` uses a colorscale to map scalar data to colors. The default colorscale is the one of the active template (see [the tutorial on templates](/python/templates/)). + +```python +import plotly.express as px +import numpy as np +img = np.arange(15**2).reshape((15, 15)) +fig = px.imshow(img) +fig.show() +``` + +### Choose the colorscale to display a single-channel image + + +```python +import plotly.express as px +import numpy as np +img = np.arange(100).reshape((10, 10)) +fig = px.imshow(img, color_continuous_scale='gray') +fig.show() +``` + +### Display multichannel image data with go.Image + +It is also possible to use the `go.Image` trace from the low-level `graph_objects` API in order to display image data. Note that `go.Image` only accepts multichannel images. For single images, use [`go.Heatmap`](/python/heatmaps). + +Note that the `go.Image` trace is different from the `go.layout.Image` class, which can be used for [adding background images or logos to figures](/python/images). + +```python +import plotly.graph_objects as go +img_rgb = [[[255, 0, 0], [0, 255, 0], [0, 0, 255]], + [[0, 255, 0], [0, 0, 255], [255, 0, 0]]] +fig = go.Figure(go.Image(z=img_rgb)) +fig.show() +``` + +### Defining the data range covered by the color range with zmin and zmax + +The data range and color range are mapped together using the parameters `zmin` and `zmax`, which correspond respectively to the data values mapped to black `[0, 0, 0]` and white `[255, 255, 255]`, or to the extreme colors of the colorscale in the case on single-channel data. + +For single-channel data, the defaults values of `zmin` and `zmax` used by `px.imshow` and `go.Heatmap` are the extrema of the data range. For multichannel data, `px.imshow` and `go.Image` use slightly different default values for `zmin` and `zmax`. For `go.Image`, the default value is `zmin=[0, 0, 0]` and `zmax=[255, 255, 255]`, no matter the data type. On the other hand, `px.imshow` adapts the default `zmin` and `zmax` to the data type: +- for integer data types, `zmin` and `zmax` correspond to the extreme values of the data type, for example 0 and 255 for `uint8`, 0 and 65535 for `uint16`, etc. +- for float numbers, the maximum value of the data is computed, and zmax is 1 if the max is smaller than 1, 255 if the max is smaller than 255, etc. (with higher thresholds 2**16 - 1 and 2**32 -1). + +These defaults can be overriden by setting the values of `zmin` and `zmax`. For `go.Image`, `zmin` and `zmax` need to be given for all channels, whereas it is also possible to pass a scalar value (used for all channels) to `px.imshow`. + +```python +import plotly.express as px +from skimage import data +img = data.astronaut() +# Increase contrast by clipping the data range between 50 and 200 +fig = px.imshow(img, zmin=50, zmax=200) +# We customize the hovertemplate to show both the data and the color values +# See https://plot.ly/python/hover-text-and-formatting/#customize-tooltip-text-with-a-hovertemplate +fig.update_traces(hovertemplate="x: %{x}
y: %{y}
z: %{z}
color: %{color}") +fig.show() +``` + +```python +import plotly.express as px +from skimage import data +img = data.astronaut() +# Stretch the contrast of the red channel only, resulting in a more red image +fig = px.imshow(img, zmin=[50, 0, 0], zmax=[200, 255, 255]) +fig.show() +``` + +### Ticks and margins around image data + +```python +import plotly.express as px +from skimage import data +img = data.astronaut() +fig = px.imshow(img) +fig.update_layout(width=400, height=400, margin=dict(l=10, r=10, b=10, t=10)) +fig.update_xaxes(showticklabels=False).update_yaxes(showticklabels=False) +fig.show() +``` + +### Combining image charts and other traces + +```python +import plotly.express as px +import plotly.graph_objects as go +from skimage import data +img = data.camera() +fig = px.imshow(img, color_continuous_scale='gray') +fig.add_trace(go.Contour(z=img, showscale=False, + contours=dict(start=0, end=70, size=70, coloring='lines'), + line_width=2)) +fig.add_trace(go.Scatter(x=[230], y=[100], marker=dict(color='red', size=16))) +fig.show() +``` + +### Displaying an image and the histogram of color values + +```python +from plotly.subplots import make_subplots +from skimage import data +img = data.chelsea() +fig = make_subplots(1, 2) +# We use go.Image because subplots require traces, whereas px functions return a figure +fig.add_trace(go.Image(z=img), 1, 1) +for channel, color in enumerate(['red', 'green', 'blue']): + fig.add_trace(go.Histogram(x=img[..., channel].ravel(), opacity=0.5, + marker_color=color, name='%s channel' %color), 1, 2) +fig.update_layout(height=400) +fig.show() +``` + +#### Reference +See https://plot.ly/python/reference/#image for more information and chart attribute options! + diff --git a/python/templates.md b/python/templates.md index 30abdc1a5..75a8ebbac 100644 --- a/python/templates.md +++ b/python/templates.md @@ -50,7 +50,7 @@ From this, we can see that the default theme is `"plotly"`, and we can see the n #### Specifying themes in Plotly Express -All Plotly Express functions accept a `template` argument that can be set to the name of a registered theme (or to a `Template` object as discussed later in this section). Here is an example of using Plotly Express to build and display the same scatter plot with five different themes. +All Plotly Express functions accept a `template` argument that can be set to the name of a registered theme (or to a `Template` object as discussed later in this section). Here is an example of using Plotly Express to build and display the same scatter plot with six different themes. ```python import plotly.express as px @@ -58,7 +58,7 @@ import plotly.express as px gapminder = px.data.gapminder() gapminder_2007 = gapminder.query("year==2007") -for template in ["plotly", "plotly_white", "plotly_dark", "ggplot2", "seaborn", "none"]: +for template in ["plotly", "plotly_white", "plotly_dark", "ggplot2", "seaborn", "simple_white", "none"]: fig = px.scatter(gapminder_2007, x="gdpPercap", y="lifeExp", size="pop", color="continent", log_x=True, size_max=60, @@ -67,7 +67,7 @@ for template in ["plotly", "plotly_white", "plotly_dark", "ggplot2", "seaborn", ``` #### Specifying themes in graph object figures -The theme for a particular graph object figure can be specified by setting the `template` property of the figure's `layout` to the name of a registered theme (or to a `Template` object as discussed later in this section). Here is an example of constructing a surface plot and then displaying it with each of five themes. +The theme for a particular graph object figure can be specified by setting the `template` property of the figure's `layout` to the name of a registered theme (or to a `Template` object as discussed later in this section). Here is an example of constructing a surface plot and then displaying it with each of six themes. ```python import plotly.graph_objects as go @@ -83,7 +83,7 @@ fig = go.Figure( height=500, )) -for template in ["plotly", "plotly_white", "plotly_dark", "ggplot2", "seaborn", "none"]: +for template in ["plotly", "plotly_white", "plotly_dark", "ggplot2", "seaborn", "simple_white", "none"]: fig.update_layout(template=template, title="Mt Bruno Elevation: '%s' theme" % template) fig.show() ```