---
jupyter:
jupytext:
notebook_metadata_filter: all
text_representation:
extension: .md
format_name: markdown
format_version: '1.3'
jupytext_version: 1.14.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.8.8
plotly:
description: How to use and configure discrete color sequences, also known as
categorical or qualitative color scales.
display_as: file_settings
has_thumbnail: true
ipynb: ~notebook_demo/187
language: python
layout: base
name: Discrete Colors
order: 30
permalink: python/discrete-color/
thumbnail: thumbnail/heatmap_colorscale.jpg
v4upgrade: true
---
### Discrete vs Continuous Color
In the same way as the X or Y position of a mark in cartesian coordinates can be used to represent continuous values (i.e. amounts or moments in time) or categories (i.e. labels), color can be used to represent continuous or discrete data. This page is about using color to represent **categorical** data using discrete colors, but Plotly can also [represent continuous values with color](/python/colorscales/).
### Discrete Color Concepts
This document explains the following discrete-color-related concepts:
- **color sequences** are lists of colors to be mapped onto discrete data values. No interpolation occurs when using color sequences, unlike with [continuous color scales](/python/colorscales/), and each color is used as-is. Color sequence defaults depend on the `layout.colorway` attribute of the active [template](/python/templates/), and can be explicitly specified using the `color_discrete_sequence` argument for many [Plotly Express](/python/plotly-express/) functions.
- **legends** are visible representations of the mapping between colors and data values. Legend markers also change shape when used with various kinds of traces, such as symbols or lines for scatter-like traces. [Legends are configurable](/python/legend/) under the `layout.legend` attribute. Legends are the discrete equivalent of [continuous color bars](/python/colorscales/)
### Discrete Color with Plotly Express
Most Plotly Express functions accept a `color` argument which automatically assigns data values to discrete colors **if the data is non-numeric**. If the data is numeric, the color will automatically be considered [continuous](/python/colorscales/). This means that numeric strings must be parsed to be used for continuous color, and conversely, numbers used as category codes must be converted to strings.
For example, in the `tips` dataset, the `smoker` column contains strings:
```python
import plotly.express as px
df = px.data.tips()
fig = px.scatter(df, x="total_bill", y="tip", color="smoker",
title="String 'smoker' values mean discrete colors")
fig.show()
```
The `size` column, however, contains numbers:
```python
import plotly.express as px
df = px.data.tips()
fig = px.scatter(df, x="total_bill", y="tip", color="size",
title="Numeric 'size' values mean continuous color")
fig.show()
```
Converting this column to strings is very straightforward, but note that the ordering in the legend is not sequential by default (see below for how to control discrete order):
```python
import plotly.express as px
df = px.data.tips()
df["size"] = df["size"].astype(str)
fig = px.scatter(df, x="total_bill", y="tip", color="size",
title="String 'size' values mean discrete colors")
fig.show()
```
Converting a string column to a numeric one is also quite straightforward:
```python
import plotly.express as px
df = px.data.tips()
df["size"] = df["size"].astype(str) #convert to string
df["size"] = df["size"].astype(float) #convert back to numeric
fig = px.scatter(df, x="total_bill", y="tip", color="size",
title="Numeric 'size' values mean continuous color")
fig.show()
```
### Discrete Colors in Dash
[Dash](https://plotly.com/dash/) is the best way to build analytical apps in Python using Plotly figures. To run the app below, run `pip install dash`, click "Download" to get the code and run `python app.py`.
Get started with [the official Dash docs](https://dash.plotly.com/installation) and **learn how to effortlessly [style](https://plotly.com/dash/design-kit/) & publish apps like this with Dash Enterprise or Plotly Cloud.**
```python hide_code=true
from IPython.display import IFrame
snippet_url = 'https://python-docs-dash-snippets.herokuapp.com/python-docs-dash-snippets/'
IFrame(snippet_url + 'discrete-color', width='100%', height=1200)
```
Sign up for Dash Club → Free cheat sheets plus updates from Chris Parmer and Adam Schroeder delivered to your inbox every two months. Includes tips and tricks, community apps, and deep dives into the Dash architecture.
Join now.
### Color Sequences in Plotly Express
By default, Plotly Express will use the color sequence from the active [template](/python/templates/)'s `layout.colorway` attribute, and the default active template is `plotly` which uses the `plotly` color sequence. You can choose any of the following built-in qualitative color sequences from the `px.colors.qualitative` module, however, or define your own.
```python
import plotly.express as px
fig = px.colors.qualitative.swatches()
fig.show()
```
Color sequences in the `px.colors.qualitative` module are stored as lists of CSS colors:
```python
import plotly.express as px
print(px.colors.qualitative.Plotly)
```
Here is an example that creates a scatter plot using Plotly Express, with points colored using the built-in qualitative `G10` color sequence.
```python
import plotly.express as px
df = px.data.gapminder()
fig = px.line(df, y="lifeExp", x="year", color="continent", line_group="country",
line_shape="spline", render_mode="svg",
color_discrete_sequence=px.colors.qualitative.G10,
title="Built-in G10 color sequence")
fig.show()
```
### Explicitly Constructing a Color Sequence
The Plotly Express `color_discrete_sequence` argument accepts explicitly-constructed color sequences as well, as lists of CSS colors:
```python
import plotly.express as px
df = px.data.gapminder().query("year == 2007")
fig = px.bar(df, y="continent", x="pop", color="continent", orientation="h", hover_name="country",
color_discrete_sequence=["red", "green", "blue", "goldenrod", "magenta"],
title="Explicit color sequence"
)
fig.show()
```
**_Warning_**: If your color sequence has fewer colors than the number of unique values in the column you are mapping to `color`, the colors will cycle through and repeat, possibly leading to ambiguity:
```python
import plotly.express as px
df = px.data.tips()
fig = px.scatter(df, x="total_bill", y="tip", color="day",
color_discrete_sequence=["red", "blue"],
title="Ambiguous! Explicit color sequence cycling because it is too short"
)
fig.show()
```
### Directly Mapping Colors to Data Values
The example above assigned colors to data values on a first-come-first-served basis, but you can directly map colors to data values if this is important to your application with `color_discrete_map`. Note that this does not change the order in which values appear in the figure or legend, as can be controlled below:
```python
import plotly.express as px
df = px.data.gapminder().query("year == 2007")
fig = px.bar(df, y="continent", x="pop", color="continent", orientation="h", hover_name="country",
color_discrete_map={
"Europe": "red",
"Asia": "green",
"Americas": "blue",
"Oceania": "goldenrod",
"Africa": "magenta"},
title="Explicit color mapping")
fig.show()
```
If your data set already contains valid CSS colors which you wish to use directly, you can pass the special value `"identity"` to `color_discrete_map`, in which case the legend is hidden by default, and the color does not appear in the hover label:
```python
import plotly.express as px
fig = px.bar(x=["a","b","c"], y=[1,3,2], color=["red", "goldenrod", "#00D"], color_discrete_map="identity")
fig.show()
```
### Controlling Discrete Color Order
Plotly Express lets you specify an ordering over categorical variables with `category_orders`, which will apply to colors and legends as well as symbols, [axes](/python/axes/) and [facets](/python/facet-plots/). This can be used with either `color_discrete_sequence` or `color_discrete_map`.
```python
import plotly.express as px
df = px.data.gapminder().query("year == 2007")
fig = px.bar(df, y="continent", x="pop", color="continent", orientation="h", hover_name="country",
color_discrete_sequence=["red", "green", "blue", "goldenrod", "magenta"],
category_orders={"continent": ["Oceania", "Europe", "Asia", "Africa", "Americas"]},
title="Explicit color sequence with explicit ordering"
)
fig.show()
```
```python
import plotly.express as px
df = px.data.gapminder().query("year == 2007")
fig = px.bar(df, y="continent", x="pop", color="continent", orientation="h", hover_name="country",
color_discrete_map={
"Europe": "red",
"Asia": "green",
"Americas": "blue",
"Oceania": "goldenrod",
"Africa": "magenta"},
category_orders={"continent": ["Oceania", "Europe", "Asia", "Africa", "Americas"]},
title="Explicit color mapping with explicit ordering"
)
fig.show()
```
### Using Sequential Scales as Discrete Sequences
In most cases, discrete/qualitative/categorical data values have no meaningful natural ordering, such as in the continents example used above. In some cases, however, there is a meaningful order, and in this case it can be helpful and appealing to use part of a continuous scale as a discrete sequence, as in the following [wind rose chart](/python/wind-rose-charts/):
```python
import plotly.express as px
df = px.data.wind()
fig = px.bar_polar(df, r="frequency", theta="direction", color="strength",
color_discrete_sequence= px.colors.sequential.Plasma_r,
title="Part of a continuous color scale used as a discrete sequence"
)
fig.show()
```
This works because just like in `px.colors.qualitative`, all [built-in continuous color scales](/python/builtin-colorscales/) are stored as lists of CSS colors:
```python
import plotly.express as px
print(px.colors.sequential.Plasma)
```