Skip to content

Commit db87dda

Browse files
nicolaskruchtennicolaskruchten
committed
revamp continuous color docs, add categorical color docs
1 parent 046040c commit db87dda

File tree

3 files changed

+453
-28
lines changed

3 files changed

+453
-28
lines changed

Diff for: ‎doc/python/builtin-colorscales.md

+15-1
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ jupyter:
3636
v4upgrade: true
3737
---
3838

39-
### Using Built-In Colorscales
39+
### Using Built-In Continuous Colorscales
4040

4141
Many Plotly Express functions accept a `color_continuous_scale` argument and many trace
4242
types have a `colorscale` attribute in their schema. Plotly comes with a large number of
@@ -49,6 +49,12 @@ The `plotly.colours` module is also available under `plotly.express.colors` so y
4949

5050
When using continuous colorscales, you will often want to [configure various aspects of its range and colorbar](/python/colorscales/).
5151

52+
53+
### Categorical Color Sequences
54+
55+
Plotly also comes with some built-in [categorical color sequences](/python/categorical-color/) which are *not intended* to be used with the `color_continuous_scale` argument as they are not designed for interpolation to occur between adjacent colors.
56+
57+
5258
### Named Built-In Colorscales
5359

5460
You can use any of the following names as string values to set `continuous_color_scale` or `colorscale` arguments.
@@ -62,6 +68,14 @@ named_colorscales = px.colors.named_colorscales()
6268
print("\n".join(wrap("".join('{:<12}'.format(c) for c in named_colorscales), 96)))
6369
```
6470

71+
Built-in color scales are stored as lists of CSS colors:
72+
73+
```python
74+
import plotly.express as px
75+
76+
print(px.colors.sequential.Plasma)
77+
```
78+
6579
### Built-In Sequential Colorscales
6680

6781
A collection of predefined sequential colorscales is provided in the `plotly.colors.sequential` module. Sequential color scales are appropriate for most continuous data, but in some cases it can be helpful to use a diverging or cyclical color scale (see below).

Diff for: ‎doc/python/categorical-colors.md

+231
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
---
2+
jupyter:
3+
jupytext:
4+
notebook_metadata_filter: all
5+
text_representation:
6+
extension: .md
7+
format_name: markdown
8+
format_version: "1.2"
9+
jupytext_version: 1.3.1
10+
kernelspec:
11+
display_name: Python 3
12+
language: python
13+
name: python3
14+
language_info:
15+
codemirror_mode:
16+
name: ipython
17+
version: 3
18+
file_extension: .py
19+
mimetype: text/x-python
20+
name: python
21+
nbconvert_exporter: python
22+
pygments_lexer: ipython3
23+
version: 3.6.8
24+
plotly:
25+
description:
26+
How to use and configure categorical (also known as qualitative or
27+
discrete) color sequences.
28+
display_as: file_settings
29+
has_thumbnail: true
30+
ipynb: ~notebook_demo/187
31+
language: python
32+
layout: base
33+
name: Categorical Colors
34+
order: 27
35+
permalink: python/categorical-color/
36+
thumbnail: thumbnail/heatmap_colorscale.jpg
37+
v4upgrade: true
38+
---
39+
40+
### Categorical vs Continuous Color
41+
42+
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 categorical data. This page is about using color to represent **categorical** data, but Plotly can also [represent continuous values with color](/python/colorscales/).
43+
44+
### Categorical Color Concepts
45+
46+
This document explains the following categorical-color-related concepts:
47+
48+
- **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.
49+
- **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 categorical equivalent of [continous color bars](/python/colorscales/)
50+
51+
### Categorical Color with Plotly Express
52+
53+
Most Plotly Express functions accept a `color` argument which automatically assigns data values to categorical 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.
54+
55+
For example, in the `tips` dataset, the `smoker` column contains strings:
56+
57+
```python
58+
import plotly.express as px
59+
df = px.data.tips()
60+
fig = px.scatter(df, x="total_bill", y="tip", color="smoker", title="String 'smoker' values mean categorical colors")
61+
62+
fig.show()
63+
```
64+
65+
The `size` column, however, contains numbers:
66+
67+
```python
68+
import plotly.express as px
69+
df = px.data.tips()
70+
fig = px.scatter(df, x="total_bill", y="tip", color="size", title="Numeric 'size' values mean continous color")
71+
72+
fig.show()
73+
```
74+
75+
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 categorical order):
76+
77+
```python
78+
import plotly.express as px
79+
df = px.data.tips()
80+
df["size"] = df["size"].astype(str)
81+
fig = px.scatter(df, x="total_bill", y="tip", color="size", title="String 'size' values mean categorical colors")
82+
83+
fig.show()
84+
```
85+
86+
Converting a string column to a numeric one is also quite straightforward:
87+
88+
```python
89+
import plotly.express as px
90+
df = px.data.tips()
91+
df["size"] = df["size"].astype(str) #convert to string
92+
df["size"] = df["size"].astype(float) #convert back to numeric
93+
94+
fig = px.scatter(df, x="total_bill", y="tip", color="size", title="Numeric 'size' values mean continous color")
95+
96+
fig.show()
97+
```
98+
99+
### Color Sequences in Plotly Express
100+
101+
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.
102+
103+
```python
104+
import plotly.express as px
105+
106+
fig = px.colors.qualitative.swatches()
107+
fig.show()
108+
```
109+
110+
Color sequences in the `px.colors.qualitative` module are stored as lists of CSS colors:
111+
112+
```python
113+
import plotly.express as px
114+
115+
print(px.colors.qualitative.Plotly)
116+
```
117+
118+
Here is an example that creates a scatter plot using Plotly Express, with points colored using the built-in qualitative `G10` color sequence.
119+
120+
```python
121+
import plotly.express as px
122+
df = px.data.gapminder()
123+
fig = px.line(df, y="lifeExp", x="year", color="continent", line_group="country",
124+
line_shape="spline", render_mode="svg",
125+
color_discrete_sequence=px.colors.qualitative.G10,
126+
title="Built-in G10 color sequence")
127+
128+
fig.show()
129+
```
130+
131+
### Explicity Constructing a Color Sequence
132+
133+
The Plotly Express `color_discrete_sequence` argument accepts explicitly-constructed color sequences as well, as lists of CSS colors:
134+
135+
```python
136+
import plotly.express as px
137+
df = px.data.gapminder().query("year == 2007")
138+
fig = px.bar(df, y="continent", x="pop", color="continent", orientation="h", hover_name="country",
139+
color_discrete_sequence=["red", "green", "blue", "goldenrod", "magenta"],
140+
title="Explicit color sequence"
141+
)
142+
143+
fig.show()
144+
```
145+
146+
**_Warning_**: If your color sequence is 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:
147+
148+
```python
149+
import plotly.express as px
150+
df = px.data.tips()
151+
fig = px.scatter(df, x="total_bill", y="tip", color="day",
152+
color_discrete_sequence=["red", "blue"],
153+
title="<b>Ambiguous!</b> Explicit color sequence cycling because it is too short"
154+
)
155+
156+
fig.show()
157+
```
158+
159+
### Directly Mapping Colors to Data Values
160+
161+
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:
162+
163+
```python
164+
import plotly.express as px
165+
df = px.data.gapminder().query("year == 2007")
166+
fig = px.bar(df, y="continent", x="pop", color="continent", orientation="h", hover_name="country",
167+
color_discrete_map={
168+
"Europe": "red",
169+
"Asia": "green",
170+
"Americas": "blue",
171+
"Oceania": "goldenrod",
172+
"Africa": "magenta"},
173+
title="Explicit color mapping")
174+
175+
fig.show()
176+
```
177+
178+
### Controlling Categorical Order
179+
180+
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`.
181+
182+
```python
183+
import plotly.express as px
184+
df = px.data.gapminder().query("year == 2007")
185+
fig = px.bar(df, y="continent", x="pop", color="continent", orientation="h", hover_name="country",
186+
color_discrete_map={
187+
"Europe": "red",
188+
"Asia": "green",
189+
"Americas": "blue",
190+
"Oceania": "goldenrod",
191+
"Africa": "magenta"},
192+
category_orders={"continent": ["Oceania", "Europe", "Asia", "Africa", "Americas"]},
193+
title="Explicit color sequence with explicit ordering"
194+
)
195+
196+
fig.show()
197+
```
198+
199+
```python
200+
import plotly.express as px
201+
df = px.data.gapminder().query("year == 2007")
202+
fig = px.bar(df, y="continent", x="pop", color="continent", orientation="h", hover_name="country",
203+
color_discrete_sequence=["red", "green", "blue", "goldenrod", "magenta"],
204+
category_orders={"continent": ["Oceania", "Europe", "Asia", "Africa", "Americas"]},
205+
title="Explicit color mapping with explicit ordering"
206+
)
207+
208+
fig.show()
209+
```
210+
211+
### Using Sequential Scales as Categorical Sequences
212+
213+
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 categorical sequence, as in the following [wind rose chart](/python/wind-rose-charts/):
214+
215+
```python
216+
import plotly.express as px
217+
df = px.data.wind()
218+
fig = px.bar_polar(df, r="frequency", theta="direction", color="strength",
219+
color_discrete_sequence= px.colors.sequential.Plasma[-2::-1],
220+
title="Part of a continuous color scale used as a discrete sequence"
221+
)
222+
fig.show()
223+
```
224+
225+
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:
226+
227+
```python
228+
import plotly.express as px
229+
230+
print(px.colors.sequential.Plasma)
231+
```

0 commit comments

Comments
 (0)