From db87dda2169d62be1b6a677cd0636e0ee8b39349 Mon Sep 17 00:00:00 2001
From: Nicolas Kruchten <nicolas@plot.ly>
Date: Sat, 4 Jan 2020 15:53:06 -0500
Subject: [PATCH 1/3] revamp continuous color docs, add categorical color docs

---
 doc/python/builtin-colorscales.md |  16 +-
 doc/python/categorical-colors.md  | 231 +++++++++++++++++++++++++++++
 doc/python/colorscales.md         | 234 ++++++++++++++++++++++++++----
 3 files changed, 453 insertions(+), 28 deletions(-)
 create mode 100644 doc/python/categorical-colors.md

diff --git a/doc/python/builtin-colorscales.md b/doc/python/builtin-colorscales.md
index 0363100c401..e0063f3acdf 100644
--- a/doc/python/builtin-colorscales.md
+++ b/doc/python/builtin-colorscales.md
@@ -36,7 +36,7 @@ jupyter:
     v4upgrade: true
 ---
 
-### Using Built-In Colorscales
+### Using Built-In Continuous Colorscales
 
 Many Plotly Express functions accept a `color_continuous_scale` argument and many trace
 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
 
 When using continuous colorscales, you will often want to [configure various aspects of its range and colorbar](/python/colorscales/).
 
+
+### Categorical Color Sequences
+
+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.
+
+
 ### Named Built-In Colorscales
 
 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()
 print("\n".join(wrap("".join('{:<12}'.format(c) for c in named_colorscales), 96)))
 ```
 
+Built-in color scales are stored as lists of CSS colors:
+
+```python
+import plotly.express as px
+
+print(px.colors.sequential.Plasma)
+```
+
 ### Built-In Sequential Colorscales
 
 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 --git a/doc/python/categorical-colors.md b/doc/python/categorical-colors.md
new file mode 100644
index 00000000000..030f03653ec
--- /dev/null
+++ b/doc/python/categorical-colors.md
@@ -0,0 +1,231 @@
+---
+jupyter:
+  jupytext:
+    notebook_metadata_filter: all
+    text_representation:
+      extension: .md
+      format_name: markdown
+      format_version: "1.2"
+      jupytext_version: 1.3.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.6.8
+  plotly:
+    description:
+      How to use and configure categorical (also known as qualitative or
+      discrete) color sequences.
+    display_as: file_settings
+    has_thumbnail: true
+    ipynb: ~notebook_demo/187
+    language: python
+    layout: base
+    name: Categorical Colors
+    order: 27
+    permalink: python/categorical-color/
+    thumbnail: thumbnail/heatmap_colorscale.jpg
+    v4upgrade: true
+---
+
+### Categorical 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 categorical data. This page is about using color to represent **categorical** data, but Plotly can also [represent continuous values with color](/python/colorscales/).
+
+### Categorical Color Concepts
+
+This document explains the following categorical-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 categorical equivalent of [continous color bars](/python/colorscales/)
+
+### Categorical Color with Plotly Express
+
+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.
+
+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 categorical 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 continous 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 categorical 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 categorical 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 continous color")
+
+fig.show()
+```
+
+### 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()
+```
+
+### Explicity 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 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:
+
+```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="<b>Ambiguous!</b> 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()
+```
+
+### Controlling Categorical 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_map={
+                "Europe": "red",
+                "Asia": "green",
+                "Americas": "blue",
+                "Oceania": "goldenrod",
+                "Africa": "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_sequence=["red", "green", "blue", "goldenrod", "magenta"],
+             category_orders={"continent": ["Oceania", "Europe", "Asia", "Africa", "Americas"]},
+             title="Explicit color mapping with explicit ordering"
+            )
+
+fig.show()
+```
+
+### Using Sequential Scales as Categorical 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 categorical 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[-2::-1],
+                   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)
+```
diff --git a/doc/python/colorscales.md b/doc/python/colorscales.md
index b51081bd5cf..a8c1f016c96 100644
--- a/doc/python/colorscales.md
+++ b/doc/python/colorscales.md
@@ -5,7 +5,7 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: "1.2"
+      format_version: '1.2'
       jupytext_version: 1.3.1
   kernelspec:
     display_name: Python 3
@@ -22,15 +22,14 @@ jupyter:
     pygments_lexer: ipython3
     version: 3.6.8
   plotly:
-    description:
-      How to set colorscales and heatmap colorscales in Python and Plotly.
-      Divergent, sequential, and qualitative colorscales.
+    description: How to set, create and control continous color scales and color bars
+      in scatter, bar, map and heatmap figures.
     display_as: file_settings
     has_thumbnail: true
     ipynb: ~notebook_demo/187
     language: python
     layout: base
-    name: Colorscales
+    name: Continuous Color Scales and Color Bars
     order: 20
     permalink: python/colorscales/
     redirect_from: python/logarithmic-color-scale/
@@ -38,11 +37,49 @@ jupyter:
     v4upgrade: true
 ---
 
-### Built-In Colorscales
+### Continuous vs Categorical Color
 
-Plotly comes with a large number of [Built-in Continuous Colorscales](/python/builtin-colorscales/).
+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 **continuous** data, but Plotly can also [represent categorical values with color](/python/categorical-color/).
 
-### Using Built-In Colorscales in Plotly Express
+
+### Continuous Color Concepts
+
+This document explains the following four continuous-color-related concepts:
+
+- **color scales** represent a mapping between the range 0 to 1 and some color domain within which colors are to be interpolated (unlike [categorical color sequences](/python/categorical-color/) which are never interpolated). Color scale defaults depend on the `layout.colorscales` attributes of the active [template](/python/templates/), and can be explicitly specified using the `color_continuous_scale` argument for many [Plotly Express](/python/plotly-express/) functions or the `colorscale` argument in various `graph_objects` such as `layout.coloraxis` or `marker.colorscale` in `go.Scatter` traces. For example `[(0,"blue"), (1,"red")]` is a simple color scale that interpolated between blue and red via purple, which can also be implicitly represented as `["blue", "red"]` and happens to be one of the [built-in color scales](/python/builtin-colorscales) and therefore referred to as `"bluered"` or `plotly.colors.sequential.Bluered`.
+- **color ranges** represent the minimum to maximum range of data to be mapped onto the 0 to 1 input range of the color scale. Color ranges default to the range of the input data and can be explicitly specified using either the `range_color` or `color_continous_midpoint` arguments for many Plotly Express functions, or `cmin`/`cmid`/`cmax` or `zmin`/`zmid`/`zmax` for various `graph_objects` such as `layout.coloraxis.cmin` or `marker.cmin` in `go.Scatter` traces. For example, if a color range of `[100, 200]` is used with the color scale above, then any mark with a color value of 100 or less will be blue, and 200 or more will be red. Marks with values in between will be various shades of purple.
+- **color bars** are legend-like visible representations of the color range and color scale with optional tick labels and tick marks. Color bars can be configured with attributes inside `layout.coloraxis.colorbar` or in places like `marker.colorbar` in `go.Scatter` traces.
+- **color axes** connect color scales, color ranges and color bars to a trace's data. By default, any colorable attribute in a trace is attached to its own local color axis, but color axes may also be shared across attributes and traces by setting e.g. `marker.coloraxis` in `go.Scatter` traces. Local color axis attributes are configured within traces e.g. `marker.showscale` whereas shared color axis attributes are configured within the Layout e.g. `layout.coloraxis.showscale`.
+
+
+### Continuous Color with Plotly Express
+
+Most Plotly Express functions accept a `color` argument which automatically assigns data values to continuous color **if the data is numeric**. If the data contains strings, the color will automatically be considered [discrete (also known as categorical or qualitative)](/python/categorical-color/). 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 `size` column 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 continous color")
+
+fig.show()
+```
+
+Converting this column to strings is very straightforward:
+
+```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()
+```
+
+### Color Scales in Plotly Express
+
+By default, Plotly Express will use the color scale from the active [template](/python/templates/)'s `layout.colorscales.sequential` attribute, and the default active template is `plotly` which uses the `Plasma` color scale. You can choose any of the [built-in colorscales](/python/builtin-colorscales/), however, or define your own.
 
 Here is an example that creates a scatter plot using Plotly Express, with points colored using the Viridis colorscale.
 
@@ -55,26 +92,26 @@ fig = px.scatter(df, x="sepal_width", y="sepal_length",
 fig.show()
 ```
 
-It is also possible to specify colorscales by name. Here is an example that specifies the Magma colorscale by name, as a string
+It is also possible to specify colorscales by name. Here is an example that specifies the `Inferno` colorscale by name, as a string
 
 ```python
 import plotly.express as px
 df = px.data.iris()
 fig = px.scatter(df, x="sepal_width", y="sepal_length",
-                 color="sepal_length", color_continuous_scale='Magma')
+                 color="sepal_length", color_continuous_scale='Inferno')
 
 fig.show()
 ```
 
-### Reversing a predefined colorscale
+### Reversing a built-in colorscale
 
-You can reverse a predefined colorscale by appending `_r` to its name, for colorscales given either as a string or a `plotly` object.
+You can reverse a [built-in colorscale](/python/builtin-colorscales/) by appending `_r` to its name, for colorscales given either as a string or a `plotly` object.
 
 ```python
 import plotly.express as px
-df = px.data.iris()
-fig = px.scatter(df, x="sepal_width", y="sepal_length",
-                 color="sepal_length", color_continuous_scale='Magma_r')
+df = px.data.gapminder().query("year == 2007").sort_values(by="lifeExp")
+fig = px.bar(df, y="continent", x="pop", color="lifeExp", orientation="h",
+             color_continuous_scale='Bluered_r', hover_name="country")
 
 fig.show()
 ```
@@ -84,11 +121,154 @@ import plotly.express as px
 data = [[1, .3, .5, .9],
         [.3, .1, .4, 1],
         [.2, .8, .9, .3]]
-fig = px.imshow(data, color_continuous_scale=px.colors.diverging.Tealrose_r)
+fig = px.imshow(data, color_continuous_scale=px.colors.sequential.Cividis_r)
+fig.show()
+```
+
+### Explicity Constructing a Colorscale
+
+The Plotly Express `color_continuous_scale` argument accepts explicitly-constructed colorscales as well:
+
+```python
+import plotly.express as px
+df = px.data.iris()
+fig = px.scatter(df, x="sepal_width", y="sepal_length", color="sepal_length",
+                 color_continuous_scale=["red", "green", "blue"])
+
+fig.show()
+```
+
+The example above provided a list of CSS colors to construct a scale, which inferred the reference points to be evenly spaced, but specific reference points can be provided as well. The following example has the same result:
+
+```python
+import plotly.express as px
+df = px.data.iris()
+fig = px.scatter(df, x="sepal_width", y="sepal_length", color="sepal_length",
+                 color_continuous_scale=[(0, "red"), (0.5, "green"), (1, "blue")])
+
+fig.show()
+```
+
+### Constructing a Discrete or Discontinuous Color Scale
+
+You can create a discrete color scale, with discontinuous color, by setting the same reference point twice in a row. This is useful for example with chart types that don't support categorical colors, like [Parallel Coordinates plots](/python/parallel-coordinates-plot/). See below for how to customize tick text.
+
+```python
+import plotly.express as px
+df = px.data.iris()
+fig = px.parallel_coordinates(df, color="species_id",
+                             color_continuous_scale=[(0.00, "red"),   (0.33, "red"),
+                                                     (0.33, "green"), (0.66, "green"),
+                                                     (0.66, "blue"),  (1.00, "blue")])
+fig.show()
+```
+
+### Explicitly setting a Color Range
+
+When using the range of the input data as the color range is inappropriate, for example when producing many figures which must have comparable color ranges, or to clip the color range to account for outliers, the Plotly Express `range_color` argument can be used. Here we clip the top of the color range above the lower range of the data and extend it below the lower range of the data:
+
+```python
+import plotly.express as px
+df = px.data.iris()
+fig = px.scatter(df, x="sepal_width", y="sepal_length", color="sepal_length", range_color=[5,8])
+
+fig.show()
+```
+
+### Setting the Midpoint of a Color Range for a Diverging Colorscale
+
+Diverging colorscales have a well-defined midpoint color, and are best-used when that midpoint is mapped to a meaningful data value. The `color_continuous_midpoint` argument to most Plotly Express functions is used for this. It cannot be used with `range_color` because setting it forces the color range to be centered on the midpoint while including the entire dataset. This means that for asymmetric data distributions, not all colors in the color scale will appear in the figure.
+
+For example, a diverging colorscale could be used to highlight points with a higher and lower value than the median in a choropleth map like this:
+
+```python
+import plotly.express as px
+
+df = px.data.gapminder().query("year == 2007")
+avg_lifeExp = (df['lifeExp']*df['pop']).sum()/df['pop'].sum()
+
+fig = px.choropleth(df, locations="iso_alpha", color="lifeExp",
+                    color_continuous_scale=px.colors.diverging.BrBG,
+                    color_continuous_midpoint=avg_lifeExp,
+                    title="World Average Life Expectancy in 2007 in years was %.1f" % avg_lifeExp)
+fig.show()
+```
+
+### Hiding or Customizing the Plotly Express Color Bar
+
+Plotly Express binds all traces to [`layout.coloraxis`](/python/reference/#layout-coloraxis), rather than using trace-specific color axes. This means that the color bar can configured there, for example it can be hidden:
+
+```python
+import plotly.express as px
+df = px.data.tips()
+fig = px.density_heatmap(df, x="total_bill", y="tip", title="No color bar on this density plot")
+
+fig.update_layout(coloraxis_showscale=False)
+
+fig.show()
+```
+
+You can also configure the title, size, placement and tick marks and labels on a color bar:
+
+```python
+import plotly.express as px
+df = px.data.tips()
+fig = px.density_heatmap(df, x="total_bill", y="tip", title="Customized color bar on this density plot")
+
+fig.update_layout(coloraxis_colorbar=dict(
+    title="Number of Bills per Cell",
+    thicknessmode="pixels", thickness=50,
+    lenmode="pixels", len=200,
+    yanchor="top", y=1,
+    ticks="outside", ticksuffix=" bills",
+    dtick=5
+))
+
+fig.show()
+```
+
+### Customizing Tick Text on Discrete Color Bars
+
+This is the same example as the Parallel Coordinates plot above, with customized tick text for species:
+
+```python
+import plotly.express as px
+df = px.data.iris()
+fig = px.parallel_coordinates(df, dimensions=["sepal_length", "sepal_width", "petal_length", "petal_width"],
+                             color="species_id", range_color=[0.5, 3.5],
+                             color_continuous_scale=[(0.00, "red"),   (0.33, "red"),
+                                                     (0.33, "green"), (0.66, "green"),
+                                                     (0.66, "blue"),  (1.00, "blue")])
+
+fig.update_layout(coloraxis_colorbar=dict(
+    title="Species",
+    tickvals=[1,2,3],
+    ticktext=["setosa","versicolor","virginica"],
+    lenmode="pixels", len=100,
+))
+fig.show()
+```
+
+### Customizing Tick Text on Logarithmic Color Bars
+
+You can customize text on a logarithmic color bar to make it more readable:
+
+```python
+import plotly.express as px
+import numpy as np
+
+df = px.data.gapminder().query("year == 2007")
+fig = px.scatter(df, y="lifeExp", x="pop", color=np.log10(df["pop"]), hover_name="country", log_x=True)
+
+fig.update_layout(coloraxis_colorbar=dict(
+    title="Population",
+    tickvals=[6,7,8,9],
+    ticktext=["1M", "10M", "100M", "1B"],
+))
 fig.show()
 ```
 
-### Custom Discretized Heatmap Colorscale
+### Custom Discretized Heatmap Colorscale with Graph Objects
 
 ```python
 import plotly.graph_objects as go
@@ -142,7 +322,7 @@ fig.add_trace(go.Heatmap(
 fig.show()
 ```
 
-### Colorscale for Scatter Plots
+### Colorscale for Scatter Plots with Graph Objects
 
 ```python
 import plotly.graph_objects as go
@@ -170,7 +350,7 @@ fig.add_trace(go.Scatter(
 fig.show()
 ```
 
-### Colorscale for Contour Plot
+### Colorscale for Contour Plot with Graph Objects
 
 ```python
 import plotly.graph_objects as go
@@ -189,7 +369,7 @@ fig.add_trace(go.Contour(
 fig.show()
 ```
 
-### Custom Heatmap Colorscale
+### Custom Heatmap Colorscale with Graph Objects
 
 ```python
 import plotly.graph_objects as go
@@ -222,9 +402,9 @@ fig.add_trace(go.Heatmap(
 fig.show()
 ```
 
-### Setting the Midpoint of a Diverging Colorscale
+### Setting the Midpoint of a Diverging Colorscale with Graph Objects
 
-The following example uses [marker.cmid](https://plot.ly/python/reference/#scatter-marker-cmid) attribute to set the mid-point of the color domain by scaling 'cmin' and/or 'cmax' to be equidistant to this point. It only has impact when [marker.color](https://plot.ly/python/reference/#scattercarpet-marker-line-color) sets to a numerical array, and 'marker.cauto' is `True`.
+The following example uses the [marker.cmid](https://plot.ly/python/reference/#scatter-marker-cmid) attribute to set the mid-point of the color domain by scaling 'cmin' and/or 'cmax' to be equidistant to this point. It only has impact when [marker.color](https://plot.ly/python/reference/#scattercarpet-marker-line-color) sets to a numerical array, and 'marker.cauto' is `True`.
 
 ```python
 import plotly.graph_objects as go
@@ -255,7 +435,7 @@ fig = go.Figure(go.Heatmap(
 fig.show()
 ```
 
-### Custom Contour Plot Colorscale
+### Custom Contour Plot Colorscale with Graph Objects
 
 ```python
 import plotly.graph_objects as go
@@ -279,7 +459,7 @@ fig.add_trace(go.Contour(
 fig.show()
 ```
 
-### Custom Colorbar Title, Labels, and Ticks
+### Custom Colorbar Title, Labels, and Ticks with Graph Objects
 
 Like axes, you can customize the colorbar ticks, labels, and values with `ticks`, `ticktext`, and `tickvals`.
 
@@ -312,9 +492,9 @@ fig.add_trace(go.Heatmap(
 fig.show()
 ```
 
-### Share Color Axis
+### Sharing a Color Axis with Graph Objects
 
-This example shows how traces can share colorbars. To share colorscale information in multiple subplots, you can use [coloraxis](https://plot.ly/javascript/reference/#scatter-marker-line-coloraxis).
+To share colorscale information in multiple subplots, you can use [coloraxis](https://plot.ly/javascript/reference/#scatter-marker-line-coloraxis).
 
 ```python
 import plotly.graph_objects as go
@@ -332,7 +512,7 @@ fig.update_layout(coloraxis = {'colorscale':'viridis'})
 fig.show()
 ```
 
-### Logarithmic Colorscale
+### Logarithmic Colorscale with Graph Objects
 
 ```python
 import plotly.graph_objects as go

From 94bef10244aef63adf15d2dcaa231bd72b681088 Mon Sep 17 00:00:00 2001
From: Nicolas Kruchten <nicolas@plot.ly>
Date: Mon, 6 Jan 2020 21:42:18 -0500
Subject: [PATCH 2/3] addressing PR comments

---
 doc/python/categorical-colors.md | 30 +++++++++++++++++-------------
 doc/python/colorscales.md        | 27 +++++++++++++++++++++------
 2 files changed, 38 insertions(+), 19 deletions(-)

diff --git a/doc/python/categorical-colors.md b/doc/python/categorical-colors.md
index 030f03653ec..83d3dfca9fe 100644
--- a/doc/python/categorical-colors.md
+++ b/doc/python/categorical-colors.md
@@ -31,7 +31,7 @@ jupyter:
     language: python
     layout: base
     name: Categorical Colors
-    order: 27
+    order: 28
     permalink: python/categorical-color/
     thumbnail: thumbnail/heatmap_colorscale.jpg
     v4upgrade: true
@@ -57,7 +57,8 @@ 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 categorical colors")
+fig = px.scatter(df, x="total_bill", y="tip", color="smoker",
+                 title="String 'smoker' values mean categorical colors")
 
 fig.show()
 ```
@@ -67,7 +68,8 @@ 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 continous color")
+fig = px.scatter(df, x="total_bill", y="tip", color="size",
+                 title="Numeric 'size' values mean continous color")
 
 fig.show()
 ```
@@ -78,7 +80,8 @@ Converting this column to strings is very straightforward, but note that the ord
 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 categorical colors")
+fig = px.scatter(df, x="total_bill", y="tip", color="size",
+                 title="String 'size' values mean categorical colors")
 
 fig.show()
 ```
@@ -91,7 +94,8 @@ 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 continous color")
+fig = px.scatter(df, x="total_bill", y="tip", color="size",
+                 title="Numeric 'size' values mean continous color")
 
 fig.show()
 ```
@@ -128,7 +132,7 @@ fig = px.line(df, y="lifeExp", x="year", color="continent", line_group="country"
 fig.show()
 ```
 
-### Explicity Constructing a Color Sequence
+### Explicitly Constructing a Color Sequence
 
 The Plotly Express `color_discrete_sequence` argument accepts explicitly-constructed color sequences as well, as lists of CSS colors:
 
@@ -183,12 +187,7 @@ Plotly Express lets you specify an ordering over categorical variables with `cat
 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"},
+             color_discrete_sequence=["red", "green", "blue", "goldenrod", "magenta"],
              category_orders={"continent": ["Oceania", "Europe", "Asia", "Africa", "Americas"]},
              title="Explicit color sequence with explicit ordering"
             )
@@ -200,7 +199,12 @@ fig.show()
 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"],
+             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"
             )
diff --git a/doc/python/colorscales.md b/doc/python/colorscales.md
index a8c1f016c96..b50806fa5e4 100644
--- a/doc/python/colorscales.md
+++ b/doc/python/colorscales.md
@@ -46,10 +46,10 @@ In the same way as the X or Y position of a mark in cartesian coordinates can be
 
 This document explains the following four continuous-color-related concepts:
 
-- **color scales** represent a mapping between the range 0 to 1 and some color domain within which colors are to be interpolated (unlike [categorical color sequences](/python/categorical-color/) which are never interpolated). Color scale defaults depend on the `layout.colorscales` attributes of the active [template](/python/templates/), and can be explicitly specified using the `color_continuous_scale` argument for many [Plotly Express](/python/plotly-express/) functions or the `colorscale` argument in various `graph_objects` such as `layout.coloraxis` or `marker.colorscale` in `go.Scatter` traces. For example `[(0,"blue"), (1,"red")]` is a simple color scale that interpolated between blue and red via purple, which can also be implicitly represented as `["blue", "red"]` and happens to be one of the [built-in color scales](/python/builtin-colorscales) and therefore referred to as `"bluered"` or `plotly.colors.sequential.Bluered`.
-- **color ranges** represent the minimum to maximum range of data to be mapped onto the 0 to 1 input range of the color scale. Color ranges default to the range of the input data and can be explicitly specified using either the `range_color` or `color_continous_midpoint` arguments for many Plotly Express functions, or `cmin`/`cmid`/`cmax` or `zmin`/`zmid`/`zmax` for various `graph_objects` such as `layout.coloraxis.cmin` or `marker.cmin` in `go.Scatter` traces. For example, if a color range of `[100, 200]` is used with the color scale above, then any mark with a color value of 100 or less will be blue, and 200 or more will be red. Marks with values in between will be various shades of purple.
-- **color bars** are legend-like visible representations of the color range and color scale with optional tick labels and tick marks. Color bars can be configured with attributes inside `layout.coloraxis.colorbar` or in places like `marker.colorbar` in `go.Scatter` traces.
-- **color axes** connect color scales, color ranges and color bars to a trace's data. By default, any colorable attribute in a trace is attached to its own local color axis, but color axes may also be shared across attributes and traces by setting e.g. `marker.coloraxis` in `go.Scatter` traces. Local color axis attributes are configured within traces e.g. `marker.showscale` whereas shared color axis attributes are configured within the Layout e.g. `layout.coloraxis.showscale`.
+- **color scales** represent a mapping between the range 0 to 1 and some color domain within which colors are to be interpolated (unlike [categorical color sequences](/python/categorical-color/) which are never interpolated). Color scale defaults depend on the `layout.colorscales` attributes of the active [template](/python/templates/), and can be explicitly specified using the `color_continuous_scale` argument for many [Plotly Express](/python/plotly-express/) functions or the `colorscale` argument in various `graph_objects` such as `layout.coloraxis` or `marker.colorscale` in `go.Scatter` traces or `colorscale` in `go.Heatmap` traces. For example `[(0,"blue"), (1,"red")]` is a simple color scale that interpolated between blue and red via purple, which can also be implicitly represented as `["blue", "red"]` and happens to be one of the [built-in color scales](/python/builtin-colorscales) and therefore referred to as `"bluered"` or `plotly.colors.sequential.Bluered`.
+- **color ranges** represent the minimum to maximum range of data to be mapped onto the 0 to 1 input range of the color scale. Color ranges default to the range of the input data and can be explicitly specified using either the `range_color` or `color_continous_midpoint` arguments for many Plotly Express functions, or `cmin`/`cmid`/`cmax` or `zmin`/`zmid`/`zmax` for various `graph_objects` such as `layout.coloraxis.cmin` or `marker.cmin` in `go.Scatter` traces or `cmin` in `go.Heatmap` traces. For example, if a color range of `[100, 200]` is used with the color scale above, then any mark with a color value of 100 or less will be blue, and 200 or more will be red. Marks with values in between will be various shades of purple.
+- **color bars** are legend-like visible representations of the color range and color scale with optional tick labels and tick marks. Color bars can be configured with attributes inside `layout.coloraxis.colorbar` or in places like `marker.colorbar` in `go.Scatter` traces or `colorbar` in `go.Heatmap` traces.
+- **color axes** connect color scales, color ranges and color bars to a trace's data. By default, any colorable attribute in a trace is attached to its own local color axis, but color axes may also be shared across attributes and traces by setting e.g. `marker.coloraxis` in `go.Scatter` traces or `coloraxis` in `go.Heatmap` traces. Local color axis attributes are configured within traces e.g. `marker.showscale` whereas shared color axis attributes are configured within the Layout e.g. `layout.coloraxis.showscale`.
 
 
 ### Continuous Color with Plotly Express
@@ -61,7 +61,8 @@ For example, in the `tips` dataset, the `size` column 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 continous color")
+fig = px.scatter(df, x="total_bill", y="tip", color="size", 
+                 title="Numeric 'size' values mean continous color")
 
 fig.show()
 ```
@@ -72,7 +73,21 @@ Converting this column to strings is very straightforward:
 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 = px.scatter(df, x="total_bill", y="tip", color="size", 
+                 title="String 'size' values mean discrete colors")
+
+fig.show()
+```
+
+If you have stringified numbers you can convert back just as easily:
+
+```python
+import plotly.express as px
+df = px.data.tips()
+df["size"] = df["size"].astype(str)
+df["size"] = df["size"].astype(float)
+fig = px.scatter(df, x="total_bill", y="tip", color="size", 
+                 title="Numeric 'size' values mean continous color")
 
 fig.show()
 ```

From e9117dd21e86049e0bae7667df178c12a224b83c Mon Sep 17 00:00:00 2001
From: Nicolas Kruchten <nicolas@plot.ly>
Date: Wed, 8 Jan 2020 09:04:16 -0500
Subject: [PATCH 3/3] categorical to discrete

---
 doc/python/builtin-colorscales.md             | 33 +++++-----
 doc/python/colorscales.md                     | 61 +++++++++----------
 ...ategorical-colors.md => discrete-color.md} | 34 +++++------
 3 files changed, 62 insertions(+), 66 deletions(-)
 rename doc/python/{categorical-colors.md => discrete-color.md} (84%)

diff --git a/doc/python/builtin-colorscales.md b/doc/python/builtin-colorscales.md
index e0063f3acdf..7f6e674e22c 100644
--- a/doc/python/builtin-colorscales.md
+++ b/doc/python/builtin-colorscales.md
@@ -5,7 +5,7 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.2'
+      format_version: "1.2"
       jupytext_version: 1.3.1
   kernelspec:
     display_name: Python 3
@@ -22,40 +22,39 @@ jupyter:
     pygments_lexer: ipython3
     version: 3.6.8
   plotly:
-    description: A reference for the built-in named continuous (sequential, diverging
-      and cylclical) colorscales in Plotly.
+    description:
+      A reference for the built-in named continuous (sequential, diverging
+      and cylclical) color scales in Plotly.
     display_as: file_settings
     has_thumbnail: true
     ipynb: ~notebook_demo/187
     language: python
     layout: base
-    name: Built-in Continuous Colorscales
+    name: Built-in Continuous Color Scales
     order: 27
     permalink: python/builtin-colorscales/
     thumbnail: thumbnail/heatmap_colorscale.jpg
     v4upgrade: true
 ---
 
-### Using Built-In Continuous Colorscales
+### Using Built-In Continuous Color Scales
 
 Many Plotly Express functions accept a `color_continuous_scale` argument and many trace
 types have a `colorscale` attribute in their schema. Plotly comes with a large number of
-built-in continuous colorscales, which can be referred to in Python code when setting the above arguments,
+built-in continuous color scales, which can be referred to in Python code when setting the above arguments,
 either by name in a case-insensitive string e.g. `px.scatter(continuous_color_scale="Viridis"`) or by reference e.g.
 `go.Scatter(marker_colorscale=plotly.colors.sequential.Viridis)`. They can also be reversed by adding `_r` at the end
 e.g. `"Viridis_r"` or `plotly.colors.sequential.Viridis_r`.
 
 The `plotly.colours` module is also available under `plotly.express.colors` so you can refer to it as `px.colors`.
 
-When using continuous colorscales, you will often want to [configure various aspects of its range and colorbar](/python/colorscales/).
+When using continuous color scales, you will often want to [configure various aspects of its range and colorbar](/python/colorscales/).
 
+### Discrete Color Sequences
 
-### Categorical Color Sequences
+Plotly also comes with some built-in [discrete color sequences](/python/discrete-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.
 
-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.
-
-
-### Named Built-In Colorscales
+### Named Built-In Continuous Color Scales
 
 You can use any of the following names as string values to set `continuous_color_scale` or `colorscale` arguments.
 These strings are case-insensitive and you can append `_r` to them to reverse the order of the scale.
@@ -76,7 +75,7 @@ import plotly.express as px
 print(px.colors.sequential.Plasma)
 ```
 
-### Built-In Sequential Colorscales
+### Built-In Sequential Color scales
 
 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).
 
@@ -92,9 +91,9 @@ fig.show()
 Note: `RdBu` was included in this module by mistake, even though it is a diverging color scale.
 It is intentionally left in for backwards-compatibility reasons.
 
-### Built-In Diverging Colorscales
+### Built-In Diverging Color scales
 
-A collection of predefined diverging colorscales is provided in the `plotly.colors.diverging` module.
+A collection of predefined diverging color scales is provided in the `plotly.colors.diverging` module.
 Diverging color scales are appropriate for continuous data that has a natural midpoint
 other otherwise informative special value, such as 0 altitude, or the boiling point
 of a liquid. These scales are intended to be used when [explicitly setting the midpoint of the scale](/python/colorscales/#setting-the-midpoint-of-a-diverging-colorscale).
@@ -108,9 +107,9 @@ fig = px.colors.diverging.swatches()
 fig.show()
 ```
 
-### Built-In Cyclical Colorscales
+### Built-In Cyclical Color scales
 
-A collection of predefined cyclical colorscales is provided in the `plotly.colors.cyclical` module.
+A collection of predefined cyclical color scales is provided in the `plotly.colors.cyclical` module.
 Cyclical color scales are appropriate for continuous data that has a natural cyclical
 structure, such as temporal data (hour of day, day of week, day of year, seasons) or
 complex numbers or other phase or angular data.
diff --git a/doc/python/colorscales.md b/doc/python/colorscales.md
index b50806fa5e4..918c308557c 100644
--- a/doc/python/colorscales.md
+++ b/doc/python/colorscales.md
@@ -5,7 +5,7 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.2'
+      format_version: "1.2"
       jupytext_version: 1.3.1
   kernelspec:
     display_name: Python 3
@@ -22,7 +22,8 @@ jupyter:
     pygments_lexer: ipython3
     version: 3.6.8
   plotly:
-    description: How to set, create and control continous color scales and color bars
+    description:
+      How to set, create and control continous color scales and color bars
       in scatter, bar, map and heatmap figures.
     display_as: file_settings
     has_thumbnail: true
@@ -37,31 +38,29 @@ jupyter:
     v4upgrade: true
 ---
 
-### Continuous vs Categorical 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 categorical data. This page is about using color to represent **continuous** data, but Plotly can also [represent categorical values with color](/python/categorical-color/).
+### Continuous vs Discrete 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 categorical data. This page is about using color to represent **continuous** data, but Plotly can also [represent categorical values with color](/python/discrete-color/).
 
 ### Continuous Color Concepts
 
 This document explains the following four continuous-color-related concepts:
 
-- **color scales** represent a mapping between the range 0 to 1 and some color domain within which colors are to be interpolated (unlike [categorical color sequences](/python/categorical-color/) which are never interpolated). Color scale defaults depend on the `layout.colorscales` attributes of the active [template](/python/templates/), and can be explicitly specified using the `color_continuous_scale` argument for many [Plotly Express](/python/plotly-express/) functions or the `colorscale` argument in various `graph_objects` such as `layout.coloraxis` or `marker.colorscale` in `go.Scatter` traces or `colorscale` in `go.Heatmap` traces. For example `[(0,"blue"), (1,"red")]` is a simple color scale that interpolated between blue and red via purple, which can also be implicitly represented as `["blue", "red"]` and happens to be one of the [built-in color scales](/python/builtin-colorscales) and therefore referred to as `"bluered"` or `plotly.colors.sequential.Bluered`.
+- **color scales** represent a mapping between the range 0 to 1 and some color domain within which colors are to be interpolated (unlike [discrete color sequences](/python/discrete-color/) which are never interpolated). Color scale defaults depend on the `layout.colorscales` attributes of the active [template](/python/templates/), and can be explicitly specified using the `color_continuous_scale` argument for many [Plotly Express](/python/plotly-express/) functions or the `colorscale` argument in various `graph_objects` such as `layout.coloraxis` or `marker.colorscale` in `go.Scatter` traces or `colorscale` in `go.Heatmap` traces. For example `[(0,"blue"), (1,"red")]` is a simple color scale that interpolated between blue and red via purple, which can also be implicitly represented as `["blue", "red"]` and happens to be one of the [built-in color scales](/python/builtin-colorscales) and therefore referred to as `"bluered"` or `plotly.colors.sequential.Bluered`.
 - **color ranges** represent the minimum to maximum range of data to be mapped onto the 0 to 1 input range of the color scale. Color ranges default to the range of the input data and can be explicitly specified using either the `range_color` or `color_continous_midpoint` arguments for many Plotly Express functions, or `cmin`/`cmid`/`cmax` or `zmin`/`zmid`/`zmax` for various `graph_objects` such as `layout.coloraxis.cmin` or `marker.cmin` in `go.Scatter` traces or `cmin` in `go.Heatmap` traces. For example, if a color range of `[100, 200]` is used with the color scale above, then any mark with a color value of 100 or less will be blue, and 200 or more will be red. Marks with values in between will be various shades of purple.
 - **color bars** are legend-like visible representations of the color range and color scale with optional tick labels and tick marks. Color bars can be configured with attributes inside `layout.coloraxis.colorbar` or in places like `marker.colorbar` in `go.Scatter` traces or `colorbar` in `go.Heatmap` traces.
 - **color axes** connect color scales, color ranges and color bars to a trace's data. By default, any colorable attribute in a trace is attached to its own local color axis, but color axes may also be shared across attributes and traces by setting e.g. `marker.coloraxis` in `go.Scatter` traces or `coloraxis` in `go.Heatmap` traces. Local color axis attributes are configured within traces e.g. `marker.showscale` whereas shared color axis attributes are configured within the Layout e.g. `layout.coloraxis.showscale`.
 
-
 ### Continuous Color with Plotly Express
 
-Most Plotly Express functions accept a `color` argument which automatically assigns data values to continuous color **if the data is numeric**. If the data contains strings, the color will automatically be considered [discrete (also known as categorical or qualitative)](/python/categorical-color/). 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.
+Most Plotly Express functions accept a `color` argument which automatically assigns data values to continuous color **if the data is numeric**. If the data contains strings, the color will automatically be considered [discrete (also known as categorical or qualitative)](/python/discrete-color/). 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 `size` column contains numbers:
 
 ```python
 import plotly.express as px
 df = px.data.tips()
-fig = px.scatter(df, x="total_bill", y="tip", color="size", 
+fig = px.scatter(df, x="total_bill", y="tip", color="size",
                  title="Numeric 'size' values mean continous color")
 
 fig.show()
@@ -73,7 +72,7 @@ Converting this column to strings is very straightforward:
 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", 
+fig = px.scatter(df, x="total_bill", y="tip", color="size",
                  title="String 'size' values mean discrete colors")
 
 fig.show()
@@ -86,7 +85,7 @@ import plotly.express as px
 df = px.data.tips()
 df["size"] = df["size"].astype(str)
 df["size"] = df["size"].astype(float)
-fig = px.scatter(df, x="total_bill", y="tip", color="size", 
+fig = px.scatter(df, x="total_bill", y="tip", color="size",
                  title="Numeric 'size' values mean continous color")
 
 fig.show()
@@ -94,9 +93,9 @@ fig.show()
 
 ### Color Scales in Plotly Express
 
-By default, Plotly Express will use the color scale from the active [template](/python/templates/)'s `layout.colorscales.sequential` attribute, and the default active template is `plotly` which uses the `Plasma` color scale. You can choose any of the [built-in colorscales](/python/builtin-colorscales/), however, or define your own.
+By default, Plotly Express will use the color scale from the active [template](/python/templates/)'s `layout.colorscales.sequential` attribute, and the default active template is `plotly` which uses the `Plasma` color scale. You can choose any of the [built-in color scales](/python/builtin-colorscales/), however, or define your own.
 
-Here is an example that creates a scatter plot using Plotly Express, with points colored using the Viridis colorscale.
+Here is an example that creates a scatter plot using Plotly Express, with points colored using the Viridis color scale.
 
 ```python
 import plotly.express as px
@@ -107,7 +106,7 @@ fig = px.scatter(df, x="sepal_width", y="sepal_length",
 fig.show()
 ```
 
-It is also possible to specify colorscales by name. Here is an example that specifies the `Inferno` colorscale by name, as a string
+It is also possible to specify color scales by name. Here is an example that specifies the `Inferno` color scale by name, as a string
 
 ```python
 import plotly.express as px
@@ -118,9 +117,9 @@ fig = px.scatter(df, x="sepal_width", y="sepal_length",
 fig.show()
 ```
 
-### Reversing a built-in colorscale
+### Reversing a built-in color scale
 
-You can reverse a [built-in colorscale](/python/builtin-colorscales/) by appending `_r` to its name, for colorscales given either as a string or a `plotly` object.
+You can reverse a [built-in color scale](/python/builtin-colorscales/) by appending `_r` to its name, for color scales given either as a string or a `plotly` object.
 
 ```python
 import plotly.express as px
@@ -140,9 +139,9 @@ fig = px.imshow(data, color_continuous_scale=px.colors.sequential.Cividis_r)
 fig.show()
 ```
 
-### Explicity Constructing a Colorscale
+### Explicity Constructing a Color scale
 
-The Plotly Express `color_continuous_scale` argument accepts explicitly-constructed colorscales as well:
+The Plotly Express `color_continuous_scale` argument accepts explicitly-constructed color scales as well:
 
 ```python
 import plotly.express as px
@@ -166,7 +165,7 @@ fig.show()
 
 ### Constructing a Discrete or Discontinuous Color Scale
 
-You can create a discrete color scale, with discontinuous color, by setting the same reference point twice in a row. This is useful for example with chart types that don't support categorical colors, like [Parallel Coordinates plots](/python/parallel-coordinates-plot/). See below for how to customize tick text.
+You can create a discrete color scale, with discontinuous color, by setting the same reference point twice in a row. This is useful for example with chart types that don't support discrete colors, like [Parallel Coordinates plots](/python/parallel-coordinates-plot/). See below for how to customize tick text.
 
 ```python
 import plotly.express as px
@@ -190,11 +189,11 @@ fig = px.scatter(df, x="sepal_width", y="sepal_length", color="sepal_length", ra
 fig.show()
 ```
 
-### Setting the Midpoint of a Color Range for a Diverging Colorscale
+### Setting the Midpoint of a Color Range for a Diverging Color scale
 
-Diverging colorscales have a well-defined midpoint color, and are best-used when that midpoint is mapped to a meaningful data value. The `color_continuous_midpoint` argument to most Plotly Express functions is used for this. It cannot be used with `range_color` because setting it forces the color range to be centered on the midpoint while including the entire dataset. This means that for asymmetric data distributions, not all colors in the color scale will appear in the figure.
+Diverging color scales have a well-defined midpoint color, and are best-used when that midpoint is mapped to a meaningful data value. The `color_continuous_midpoint` argument to most Plotly Express functions is used for this. It cannot be used with `range_color` because setting it forces the color range to be centered on the midpoint while including the entire dataset. This means that for asymmetric data distributions, not all colors in the color scale will appear in the figure.
 
-For example, a diverging colorscale could be used to highlight points with a higher and lower value than the median in a choropleth map like this:
+For example, a diverging color scale could be used to highlight points with a higher and lower value than the median in a choropleth map like this:
 
 ```python
 import plotly.express as px
@@ -283,7 +282,7 @@ fig.update_layout(coloraxis_colorbar=dict(
 fig.show()
 ```
 
-### Custom Discretized Heatmap Colorscale with Graph Objects
+### Custom Discretized Heatmap Color scale with Graph Objects
 
 ```python
 import plotly.graph_objects as go
@@ -337,7 +336,7 @@ fig.add_trace(go.Heatmap(
 fig.show()
 ```
 
-### Colorscale for Scatter Plots with Graph Objects
+### Color scale for Scatter Plots with Graph Objects
 
 ```python
 import plotly.graph_objects as go
@@ -365,7 +364,7 @@ fig.add_trace(go.Scatter(
 fig.show()
 ```
 
-### Colorscale for Contour Plot with Graph Objects
+### Color scale for Contour Plot with Graph Objects
 
 ```python
 import plotly.graph_objects as go
@@ -384,7 +383,7 @@ fig.add_trace(go.Contour(
 fig.show()
 ```
 
-### Custom Heatmap Colorscale with Graph Objects
+### Custom Heatmap Color scale with Graph Objects
 
 ```python
 import plotly.graph_objects as go
@@ -417,7 +416,7 @@ fig.add_trace(go.Heatmap(
 fig.show()
 ```
 
-### Setting the Midpoint of a Diverging Colorscale with Graph Objects
+### Setting the Midpoint of a Diverging Color scale with Graph Objects
 
 The following example uses the [marker.cmid](https://plot.ly/python/reference/#scatter-marker-cmid) attribute to set the mid-point of the color domain by scaling 'cmin' and/or 'cmax' to be equidistant to this point. It only has impact when [marker.color](https://plot.ly/python/reference/#scattercarpet-marker-line-color) sets to a numerical array, and 'marker.cauto' is `True`.
 
@@ -450,7 +449,7 @@ fig = go.Figure(go.Heatmap(
 fig.show()
 ```
 
-### Custom Contour Plot Colorscale with Graph Objects
+### Custom Contour Plot Color scale with Graph Objects
 
 ```python
 import plotly.graph_objects as go
@@ -474,9 +473,9 @@ fig.add_trace(go.Contour(
 fig.show()
 ```
 
-### Custom Colorbar Title, Labels, and Ticks with Graph Objects
+### Custom Color bar Title, Labels, and Ticks with Graph Objects
 
-Like axes, you can customize the colorbar ticks, labels, and values with `ticks`, `ticktext`, and `tickvals`.
+Like axes, you can customize the color bar ticks, labels, and values with `ticks`, `ticktext`, and `tickvals`.
 
 ```python
 import plotly.graph_objects as go
@@ -527,7 +526,7 @@ fig.update_layout(coloraxis = {'colorscale':'viridis'})
 fig.show()
 ```
 
-### Logarithmic Colorscale with Graph Objects
+### Logarithmic Color scale with Graph Objects
 
 ```python
 import plotly.graph_objects as go
diff --git a/doc/python/categorical-colors.md b/doc/python/discrete-color.md
similarity index 84%
rename from doc/python/categorical-colors.md
rename to doc/python/discrete-color.md
index 83d3dfca9fe..c80d9552788 100644
--- a/doc/python/categorical-colors.md
+++ b/doc/python/discrete-color.md
@@ -22,35 +22,33 @@ jupyter:
     pygments_lexer: ipython3
     version: 3.6.8
   plotly:
-    description:
-      How to use and configure categorical (also known as qualitative or
-      discrete) color sequences.
+    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: Categorical Colors
+    name: Discrete Colors
     order: 28
-    permalink: python/categorical-color/
+    permalink: python/discrete-color/
     thumbnail: thumbnail/heatmap_colorscale.jpg
     v4upgrade: true
 ---
 
-### Categorical vs Continuous Color
+### 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 categorical data. This page is about using color to represent **categorical** data, but Plotly can also [represent continuous values with color](/python/colorscales/).
+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/).
 
-### Categorical Color Concepts
+### Discrete Color Concepts
 
-This document explains the following categorical-color-related 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 categorical equivalent of [continous color bars](/python/colorscales/)
+- **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 [continous color bars](/python/colorscales/)
 
-### Categorical Color with Plotly Express
+### Discrete Color with Plotly Express
 
-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.
+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:
 
@@ -58,7 +56,7 @@ For example, in the `tips` dataset, the `smoker` column contains strings:
 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 categorical colors")
+                 title="String 'smoker' values mean discrete colors")
 
 fig.show()
 ```
@@ -74,14 +72,14 @@ fig = px.scatter(df, x="total_bill", y="tip", color="size",
 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 categorical order):
+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 categorical colors")
+                 title="String 'size' values mean discrete colors")
 
 fig.show()
 ```
@@ -179,7 +177,7 @@ fig = px.bar(df, y="continent", x="pop", color="continent", orientation="h", hov
 fig.show()
 ```
 
-### Controlling Categorical Order
+### 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`.
 
@@ -212,9 +210,9 @@ fig = px.bar(df, y="continent", x="pop", color="continent", orientation="h", hov
 fig.show()
 ```
 
-### Using Sequential Scales as Categorical Sequences
+### 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 categorical sequence, as in the following [wind rose chart](/python/wind-rose-charts/):
+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