Plotly Express (px) is the high-level interface to Plotly and provides functions for generating charts. px functions support data provided in a number of different formats (long, wide, and mixed) and as different types of objects, including pandas and Polars dataframes.

Data for the Examples¶

The examples on this page use datasets available in the data package in px. px.data contains functions that when called return a dataset as a dataframe. Some of the datasets included in px.data are:

carshare - Each row represents the availability of car-sharing services near the centroid of a zone in Montreal over a month-long period.
election - Each row represents voting results for an electoral district in the 2013 Montreal mayoral election.
iris - Each row represents a flower.

To access the iris dataset, we call its function and assign it to a variable:

In [1]:

import plotly.express as px

df = px.data.iris()
df.head()

Out[1]:

	sepal_length	sepal_width	petal_length	petal_width	species	species_id
0	5.1	3.5	1.4	0.2	setosa	1
1	4.9	3.0	1.4	0.2	setosa	1
2	4.7	3.2	1.3	0.2	setosa	1
3	4.6	3.1	1.5	0.2	setosa	1
4	5.0	3.6	1.4	0.2	setosa	1

By default px.data functions return a pandas DataFrame object, but you can specify an alternative dataframe type using return_type. pandas, polars, pyarrow, modin, and cuDF are supported return types.

In [2]:

df = px.data.iris(return_type='polars')
df.head()

Out[2]:

shape: (5, 6)

sepal_length	sepal_width	petal_length	petal_width	species	species_id
f64	f64	f64	f64	str	i64
5.1	3.5	1.4	0.2	"setosa"	1
4.9	3.0	1.4	0.2	"setosa"	1
4.7	3.2	1.3	0.2	"setosa"	1
4.6	3.1	1.5	0.2	"setosa"	1
5.0	3.6	1.4	0.2	"setosa"	1

Long, Wide, and Mixed-Form Data¶

There are three common conventions for storing column-oriented data, usually in a data frame with column names:

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".
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.
mixed-form data is a hybrid of long-form and wide-form data, with one row per value of one variable, and some columns representing values of another, and some columns representing more variables. See the wide-form documentation for examples of how to use Plotly Express to visualize this kind of data.

Every Plotly Express function can operate on long-form data (other than px.imshow which operates only on wide-form input), and in addition, the following 2D-Cartesian functions can operate on wide-form and mixed-form data: px.scatter, px.line, px.area, px.bar, px.histogram, px.violin, px.box, px.strip, px.funnel, px.density_heatmap and px.density_contour.

By way of example here is the same data, represented in long-form first, and then in wide-form:

In [3]:

import plotly.express as px
long_df = px.data.medals_long()
long_df

Out[3]:

	nation	medal	count
0	South Korea	gold	24
1	China	gold	10
2	Canada	gold	9
3	South Korea	silver	13
4	China	silver	15
5	Canada	silver	12
6	South Korea	bronze	11
7	China	bronze	8
8	Canada	bronze	12

In [4]:

import plotly.express as px
wide_df = px.data.medals_wide()
wide_df

Out[4]:

	nation	gold	silver	bronze
0	South Korea	24	13	11
1	China	10	15	8
2	Canada	9	12	12

Plotly Express can produce the same plot from either form:

In [5]:

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()

In [6]:

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()

You might notice that y-axis and legend labels are slightly different for the second plot: they are "value" and "variable", respectively, and this is also reflected in the hoverlabel text. Note that the labels "medal" and "count" do not appear in the wide-form data frame, so in this case, you must supply these yourself, or you can use a data frame with named row- and column-indexes. You can rename these labels with the labels argument:

In [7]:

import plotly.express as px
wide_df = px.data.medals_wide()

fig = px.bar(wide_df, x=