Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 42 ยท Getting Started

Plotly Express Basics

Learn Plotly Express: one function call turns a DataFrame into a chart. Map columns to x, y, color, size, symbol and facets, set labels and titles, and tweak the result.

Plotly Express, imported as px, is the fastest way to make a Plotly chart. You give it a table of data and tell it which columns should control which visual property. Express does the rest: it creates one trace per group, picks colors, builds a legend, writes axis titles and adds hover text.

The idea behind Express is that you describe the meaning of the chart ("put sepal width on x, sepal length on y, color by species") rather than the drawing steps. This lesson teaches that mapping idea, which every Express function shares.

One function per chart type

Each chart type has its own function, and nearly all of them take the same arguments:

Function Chart
px.line, px.scatter, px.bar, px.area Basic charts
px.histogram, px.box, px.violin, px.ecdf Distributions
px.pie, px.sunburst, px.treemap, px.funnel Parts of a whole
px.density_heatmap, px.imshow Heatmaps and images
px.scatter_3d, px.scatter_geo, px.choropleth 3D and maps

Each call returns an ordinary go.Figure, so everything you learn about figures later also applies to Express charts.

Mapping columns to visual properties

The data should be in tidy (long) form: one row per observation, one column per variable. The argument x="col" means "use the column named col". Here are the most important arguments:

Argument What it controls
x, y Position
color Color; a different color per distinct value (or a gradient for numbers)
size Marker size (scatter, bubble)
symbol Marker shape
line_dash Dash style of lines
facet_col, facet_row Split into a grid of small charts
hover_name, hover_data What the tooltip shows
text Labels drawn on the chart
title, labels, template Title, renamed axis/legend labels, theme
Python Map columns to color, size and symbol

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Express created three traces, one per species, because color="species" splits the data. The axis titles were copied from the column names, and the legend title is species. Each trace holds only its own rows (50 points each). You get all of this with one call.

The result is a normal figure

Because px.scatter returns a go.Figure, you can adjust it afterwards. These two methods cover most tweaks:

  • fig.update_layout(...) changes title, size, axes, legend, template.
  • fig.update_traces(...) changes every trace, for example marker size or line width.
Python
fig.update_layout(title="Iris, by species", width=700)
fig.update_traces(marker=dict(opacity=0.7))

You can also give Express the answers up front. labels renames columns for display, range_x and range_y fix axis limits, width and height set the pixel size, and template picks a theme.

Python Labels, ranges and facets

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The data is split twice: color makes one trace per smoker group and facet_col makes one panel per meal time, so you get 2 x 2 = 4 traces. The facet panels get their own x axes (xaxis, xaxis2), and the panel titles are stored as layout annotations.

What Express does under the hood

To see that Express is not magic, here is the same idea written by hand in plotly.js. One trace per group, a color per trace, a shared layout. Express automates exactly this loop.

What px.scatter(color=...) does

Wide data and long data

Express accepts wide data too: a DataFrame where each column is a series. Pass the list of columns as y, and Express reshapes it internally:

Python
wide = pd.DataFrame({"month": [1, 2, 3], "tea": [3, 4, 6], "coffee": [5, 7, 8]})
fig = px.line(wide, x="month", y=["tea", "coffee"])

This gives two lines. Express creates two helper columns named variable and value, and those names appear in the legend and axis titles unless you rename them with labels. The next lessons explain wide versus long in detail.

Common mistakes

  • Passing the column as the data: write px.scatter(df, x="a", y="b") (names as strings) rather than px.scatter(x=df["a"], y=df["b"]). Both work, but only the first gives you axis titles for free.
  • Wide data with color: color expects a column that contains categories. For wide data pass several columns to y instead.
  • Treating numbers as categories: a numeric color column makes a continuous gradient. Convert it to strings (df["year"].astype(str)) when you want discrete colors.
  • Forgetting to import pandas in the browser runner: add import pandas as pd so the page loads it before Express needs it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does px.scatter(df, x="a", y="b", color="g") do with the column g?

    Mapping a categorical column to color splits the data into one trace per category.
  2. 2. What type of object does a Plotly Express function return?

    Express returns a normal graph-objects figure, so you can keep editing it with update_layout and update_traces.
  3. 3. px.scatter(tips, x="total_bill", y="tip", color="smoker", facet_col="time") has two smoker values and two time values. How many traces are there?

    Each combination of color group and facet panel gets its own trace: 2 x 2 = 4.
  4. 4. Which argument renames the axis title for column total_bill?

    labels maps column names to display names for axes, legends and hover text. title sets the chart title.

Summary

  • Express functions (px.scatter, px.line, px.bar, ...) build a full chart from a DataFrame in one call.
  • Map columns to properties: x, y, color, size, symbol, facet_col, hover_name, text.
  • Tidy data works best; wide data works if you pass several columns to y.
  • labels, title, range_x, range_y, template and width/height customise the result in the same call.
  • The result is a go.Figure: refine it with update_layout and update_traces.

Next: Graph Objects and Figure Anatomy