[Doc] Add Reverse Scale, Update Example for Consistency, and make som…

…e minor syntax updates (#3228)

* [Doc] Add Reverse Scale and Update Example for Consistency

* Use more appropriate colors

* Minor syntax and formatting fixes

---------

Co-authored-by: Joel Ostblom <[email protected]>

doc/user_guide/customization.rst

@@ -138,7 +138,7 @@ By default an Altair chart does not have a title, as seen in this example.
        color="source:N"
    )
 
-You can add a simple title by passing the `title` keyword argument with the data.
+You can add a simple title by passing the ``title`` keyword argument with the data.
 
 .. altair-plot::
 
@@ -148,7 +148,7 @@ You can add a simple title by passing the `title` keyword argument with the data
        color="source:N"
    )
 
-It is also possible to add a subtitle by passing in an `alt.Title` object.
+It is also possible to add a subtitle by passing in an ``alt.Title`` object.
 
 .. altair-plot::
 
@@ -204,7 +204,7 @@ Adjusting Axis Limits
 ---------------------
 The default axis limit used by Altair is dependent on the type of the data.
 To fine-tune the axis limits beyond these defaults, you can use the
-:class:`Scale` property of the axis encodings. For example, consider the
+:meth:`scale` method of the axis encodings. For example, consider the
 following plot:
 
 .. altair-plot::
@@ -220,8 +220,8 @@ following plot:
     )
 
 Altair inherits from Vega-Lite the convention of always including the zero-point
-in quantitative axes; if you would like to turn this off, you can add a
-:class:`Scale` property to the :class:`X` encoding that specifies ``zero=False``:
+in quantitative axes; if you would like to turn this off, you can add the
+:meth:`scale` method to the :class:`X` encoding that specifies ``zero=False``:
 
 .. altair-plot::
 
@@ -273,8 +273,10 @@ For example consider this plot:
 .. altair-plot::
 
    import pandas as pd
-   df = pd.DataFrame({'x': [0.03, 0.04, 0.05, 0.12, 0.07, 0.15],
-                      'y': [10, 35, 39, 50, 24, 35]})
+   df = pd.DataFrame(
+       {'x': [0.03, 0.04, 0.05, 0.12, 0.07, 0.15],
+       'y': [10, 35, 39, 50, 24, 35]
+   })
 
    alt.Chart(df).mark_circle().encode(
        x='x',
@@ -283,7 +285,7 @@ For example consider this plot:
 
 To fine-tune the formatting of the tick labels and to add a custom title to
 each axis, we can pass to the :class:`X` and :class:`Y` encoding a custom
-:class:`Axis` definition.
+axis definition within the :meth:`axis` method.
 Here is an example of formatting the x labels as a percentage, and
 the y labels as a dollar value:
 
@@ -325,7 +327,7 @@ Additional formatting codes are available; for a listing of these see the
 Adjusting the Legend
 --------------------
 
-A legend is added to the chart automatically when the `color`, `shape` or `size` arguments are passed to the :func:`encode` function. In this example we'll use `color`.
+A legend is added to the chart automatically when the ``color``, ``shape`` or ``size`` arguments are passed to the :func:`encode` function. In this example we'll use ``color``.
 
 .. altair-plot::
 
@@ -340,9 +342,9 @@ A legend is added to the chart automatically when the `color`, `shape` or `size`
       color='species'
   )
 
-In this case, the legend can be customized by introducing the :class:`Color` class and taking advantage of its `legend` argument. The `shape` and `size` arguments have their own corresponding classes.
+In this case, the legend can be customized by introducing the :class:`Color` class and taking advantage of its :meth:`legend` method. The ``shape`` and ``size`` arguments have their own corresponding classes.
 
-The legend option on all of them expects a :class:`Legend` object as its input, which accepts arguments to customize many aspects of its appearance. One simple example is giving the legend a `title`.
+The legend option on all of them expects a :class:`Legend` object as its input, which accepts arguments to customize many aspects of its appearance. One example is to move the legend to another position with the ``orient`` argument.
 
 .. altair-plot::
 
@@ -354,10 +356,10 @@ The legend option on all of them expects a :class:`Legend` object as its input,
   alt.Chart(iris).mark_point().encode(
       x='petalWidth',
       y='petalLength',
-      color=alt.Color('species').title("Species by color")
+      color=alt.Color('species').legend(orient="left")
   )
 
-Another thing you can do is move the legend to another position with the `orient` argument.
+Another thing you can do is set a ``title``; in this case we can use the :meth:`title` method directly as a shortcut or specify the ``title`` parameter inside the :meth:`legend` method:.
 
 .. altair-plot::
 
@@ -369,9 +371,10 @@ Another thing you can do is move the legend to another position with the `orient
   alt.Chart(iris).mark_point().encode(
       x='petalWidth',
       y='petalLength',
-      color=alt.Color('species').legend(orient="left")
+      color=alt.Color('species').title("Species by color")
   )
 
+
 You can remove the legend entirely by submitting a null value.
 
 .. altair-plot::
@@ -407,7 +410,7 @@ As an example, let's start with a simple scatter plot.
         color='species'
     )
 
-First remove the grid using the :meth:`Chart.configure_axis` method.
+First remove the grid using the :meth:`configure_axis` method.
 
 .. altair-plot::
 
@@ -425,7 +428,7 @@ First remove the grid using the :meth:`Chart.configure_axis` method.
     )
 
 You'll note that while the inside rules are gone, the outside border remains.
-Hide it by setting ``stroke=None`` inside :meth:`Chart.configure_view`
+Hide it by setting ``stroke=None`` inside :meth:`configure_view`
 (``strokeWidth=0`` and ``strokeOpacity=0`` also works):
 
 .. altair-plot::
@@ -472,59 +475,83 @@ Customizing Colors
 
 As discussed in :ref:`type-legend-scale`, Altair chooses a suitable default color
 scheme based on the type of the data that the color encodes. These defaults can
-be customized using the `scale` argument of the :class:`Color` class.
-
-The :class:`Scale` class passed to the `scale` argument provides a number of options
-for customizing the color scale; we will discuss a few of them here.
+be customized using the :meth:`scale` method of the :class:`Color` class.
 
 Color Schemes
 ~~~~~~~~~~~~~
+
 Altair  includes a set of named color schemes for both categorical and sequential
 data, defined by the vega project; see the
 `Vega documentation <https://vega.github.io/vega/docs/schemes/>`_
 for a full gallery of available color schemes.  These schemes
-can be passed to the `scheme` argument of the :class:`Scale` class:
+can be passed to the `scheme` argument of the :meth:`scale` method:
 
 .. altair-plot::
 
-  import altair as alt
-  from vega_datasets import data
+    import altair as alt
+    from vega_datasets import data
 
-  iris = data.iris()
+    cars = data.cars()
 
-  alt.Chart(iris).mark_point().encode(
-      x='petalWidth',
-      y='petalLength',
-      color=alt.Color('species').scale(scheme='dark2')
-  )
+    alt.Chart(cars).mark_point().encode(
+        x='Horsepower',
+        y='Miles_per_Gallon',
+        color=alt.Color('Acceleration').scale(scheme="lightgreyred")
+    )
+
+The color scheme we used above highlights points on one end of the scale,
+while keeping the rest muted.
+If we want to highlight the lower ``Acceleration`` data to red color instead,
+we can use the ``reverse`` parameter to reverse the color scheme:
+
+.. altair-plot::
+
+    alt.Chart(cars).mark_point().encode(
+        x='Horsepower',
+        y='Miles_per_Gallon',
+        color=alt.Color('Acceleration').scale(scheme="lightgreyred", reverse=True)
+    )
 
 Color Domain and Range
 ~~~~~~~~~~~~~~~~~~~~~~
 
-To make a custom mapping of discrete values to colors, use the
-`domain` and `range` parameters of the :class:`Scale` class for
-values and colors respectively.
+To create a custom color scales,
+we can use the ``domain`` and ``range`` parameters
+of the ``scale`` method for
+the values and colors, respectively.
+This works both for continuous scales,
+where it can help highlight specific ranges of values:
 
 .. altair-plot::
 
-  import altair as alt
-  from vega_datasets import data
+    domain = [5, 8, 10, 12, 25]
+    range_ = ['#9cc8e2', '#9cc8e2', 'red', '#5ba3cf', '#125ca4']
 
-  iris = data.iris()
-  domain = ['setosa', 'versicolor', 'virginica']
-  range_ = ['red', 'green', 'blue']
+    alt.Chart(cars).mark_point().encode(
+        x='Horsepower',
+        y='Miles_per_Gallon',
+        color=alt.Color('Acceleration').scale(domain=domain, range=range_)
+    )
 
-  alt.Chart(iris).mark_point().encode(
-      x='petalWidth',
-      y='petalLength',
-      color=alt.Color('species').scale(domain=domain, range=range_)
-  )
+And for discrete scales:
+
+.. altair-plot::
+
+    domain = ['Europe', "Japan", "USA"]
+    range_ = ['seagreen', 'firebrick', 'rebeccapurple']
+
+    alt.Chart(cars).mark_point().encode(
+        x='Horsepower',
+        y='Miles_per_Gallon',
+        color=alt.Color('Origin').scale(domain=domain, range=range_)
+    )
 
 Raw Color Values
 ~~~~~~~~~~~~~~~~
+
 The ``scale`` is what maps the raw input values into an appropriate color encoding
 for displaying the data. If your data entries consist of raw color names or codes,
-you can set ``scale=None`` to use those colors directly:
+you can set ``scale(None)`` to use those colors directly:
 
 .. altair-plot::
 
@@ -546,6 +573,7 @@ you can set ``scale=None`` to use those colors directly:
 
 Adjusting the Width of Bar Marks
 --------------------------------
+
 The width of the bars in a bar plot are controlled through the ``size`` property in the :meth:`~Chart.mark_bar()`:
 
 .. altair-plot::
@@ -593,7 +621,7 @@ Here is an example of setting the step width for a discrete scale:
       y='value:Q'
   ).properties(width=alt.Step(100))
 
-The width of the bars are set using ``mark_bar(size=30)`` and the width that is allocated for each bar bar in the the chart is set using ``width=alt.Step(100)``
+The width of the bars are set using ``mark_bar(size=30)`` and the width that is allocated for each bar bar in the chart is set using ``width=alt.Step(100)``
 
 
 .. _customization-chart-size:
@@ -633,7 +661,7 @@ the subchart rather than to the overall chart:
    )
 
 If you want your chart size to respond to the width of the HTML page or container in which
-it is rendererd, you can set ``width`` or ``height`` to the string ``"container"``:
+it is rendered, you can set ``width`` or ``height`` to the string ``"container"``:
 
 .. altair-plot::
     :div_class_: full-width-plot
@@ -648,7 +676,7 @@ it is rendererd, you can set ``width`` or ``height`` to the string ``"container"
 
 Note that this will only scale with the container if its parent element has a size determined
 outside the chart itself; For example, the container may be a ``<div>`` element that has style
-``width: 100%; height: 300px``. 
+``width: 100%; height: 300px``.
 
 
 .. _chart-themes: