<commit_before>---
layout: docs
menu: docs
title: Scale
permalink: /docs/scale.html
---

Scales are functions that transform a domain of data values (numbers, dates, strings, etc.) to a range of visual values (pixels, colors, sizes). Internally, Vega-Lite uses [Vega scales](https://vega.github.io/vega/docs/scales/), which are derived from the [d3-scale](https://github.com/d3/d3-scale) library. For more background about scales, please see ["Introducing d3-scale"](https://medium.com/@mbostock/introducing-d3-scale-61980c51545f) by <NAME>.

Vega-Lite automatically creates scales for fields that are mapped to [position](encoding.html#position) and [mark property](encoding.html#mark-prop) channels. To customize the scale of a field, users can provide a `scale` object as a part of the [field definition](encoding.html#field) to customize scale properties (e.g., [type](#type), [domain](#domain), and [range](#range)).

```js
// A Single View or a Layer Specification
{
  ...,
  "mark/layer": ...,
  "encoding": {
    "x": {
      "field": ...,
      "type": ...,
      "scale": {                // scale
        "type": ...,
        ...
      },
      ...
    },
    "y": ...,
    ...
  },
  ...
}
```

Besides the `scale` property of each encoding channel, the top-level configuration object ([`config`](config.html)) also provides [scale config](#config) (`config: {scale: {...}}`) for setting default scale properties for all scales.

For more information about guides that visualize the scales, please see the [axes](axis.html) and [legends](legend.html) pages.

<!--prettier-ignore-start-->
## Documentation Overview
{:.no_toc}

- TOC
{:toc}

<!--prettier-ignore-end-->

{:#type}

## Scale Types

The `type` property can be specified to customize the scale type.

{% include table.html props="type" source="Scale" %}

By default, Vega-Lite use the following scale types for the following [data types](type.html) and [encoding channels](encoding.html#channel):

|  | Nominal / Ordinal | Quantitative | Bin-Quantitative<sup>1</sup> | Temporal |
| --: | :-: | :-: | :-: | :-: |
| **X, Y** | [Band](#band) / [Point](#point)<sup>2</sup> | [Linear](#linear) | [Linear](#linear) | [Time](#time) |
| **Size, Opacity** | [Point](#point) | [Linear](#linear) | [Linear](#linear) | [Time](#time) |
| **Color** | [Ordinal](#ordinal) | [Linear](#linear) | [Bin-Ordinal](#bin-ordinal) | [Linear](#linear) |
| **Shape** | [Ordinal](#ordinal) | N/A | N/A | N/A |

<span class="note-line">
<sup>1</sup> Quantitative fields with the [`bin`](bin.html) transform.
</span>
<span class="note-line">
<sup>2</sup> For positional (x and y) nominal and ordinal fields, `"band"` scale is the default scale type for
bar, image, rect, and rule marks while `"point"` is the default scales for all other marks.
</span>

{:#domain}

## Scale Domains

By default, a scale in Vega-Lite draws domain values directly from a channel's encoded field. Users can specify the `domain` property of a scale to customize its domain values. To sort the order of the domain of the encoded, the [`sort`](sort.html) property of a [field definition](encoding.html#field-def) can be specified.

{% include table.html props="domain,domainMid" source="Scale" %}

A common use case for the `domain` property is to limit, for example, the `x` range of values to include in a plot. However, setting the domain property alone is insufficient to achieve the desired effect.

### Example: Customizing Domain for a Time Scale

For a time scale, we can set scale domain to an array [datetime objects](types.html#datetime), as shown below.

<div class="vl-example" data-name="bar_custom_time_domain"></div>

### Example: Clipping or Removing Unwanted Data Points

For example, consider the line plot specification below in which the `x` domain is restricted to the range `[300, 450]`.

<div class="vl-example" data-name="line_outside_domain"></div>

There are two approaches to keep the mark from being plotted outside the desired `x` range of values.

- The first one is to set `clip: true` in mark definition.

  <div class="vl-example" data-name="line_inside_domain_using_clip"></div>

- The second approach is to use `transform`. Note that these two approaches have slightly different behaviors. Using `transform` removes unwanted data points, yet setting `clip` to `true` clips the mark to be the enclosing group's width and height.

<div class="vl-example" data-name="line_inside_domain_using_transform"></div>

<!--
#### Example: Custom Domain
TODO: Custom Domain for quantitative / discrete scales
-->

{:#range}

## Scale Ranges

The range of the scale represents the set of output visual values. Vega-Lite automatically determines the default range for each [encoding channel](encoding.html#channel) using the following rules:

| Channels | Default Range |
| :-- | :-- |
| `x` | The range is _by default_ `[0, width]`. |
| `y` | The range is _by default_ `[0, height]`. |
| `opacity` | Derived from the [scale config](#config)'s `min/maxOpacity`. |
| `color` | Derived from the following [named ranges](scale.html#range-config) based on the field's [`type`](type.html): <br/> • `"category"` for _nominal_ fields. <br/> • `"ordinal"` for _ordinal_ fields. <br/> • `"heatmap"` for _quantitative_ and _temporal_ fields with `"rect"` marks and `"ramp'` for other marks. <br/><br/> See the [color scheme](#scheme) section for examples. |
| `size` | Derived from the following [named ranges](#config) based on the `mark` type: <br/> • `min/maxBandSize` for bar and tick. <br/> • `min/maxStrokeWidth` for line and rule. <br/> • `min/maxSize` for point, square, and circle <br/> • `min/maxFontSize` for text |
| `shape` | Derived from the [pre-defined named range](#range-config) `"symbol"`. |

To customize range values, users can directly specify `range` or specify the special [`scheme`](#scheme) property for [ordinal](#ordinal) and [continuous](#continuous) color scales.

{% include table.html props="range" source="Scale" %}

{:#scheme}

### Color Schemes

Color schemes provide a set of named color palettes as a scale range for the `color` channel. Vega-Lite (via Vega) provides a collection of perceptually-motivated color schemes, many of which are drawn from the [d3-scale](https://github.com/d3/d3-scale), [d3-scale-chromatic](https://github.com/d3/d3-scale-chromatic), and [ColorBrewer](http://colorbrewer2.org/) projects.

By default, Vega-Lite assigns different [default color schemes](#range-config) based on the types of the encoded fields:

- _Nominal_ fields use the `"categorical"` [pre-defined named range](#range-config) (the [`"tableau10"`](https://vega.github.io/vega/docs/schemes/#tableau10) scheme by default).

<div class="vl-example" data-name="point_color"></div>

- _Ordinal_ fields use the `"ordinal"` [pre-defined named color range](#range-config) (the [`"blues"`](https://vega.github.io/vega/docs/schemes/#blues) color scheme by default).

<div class="vl-example" data-name="point_color_ordinal"></div>

- _Quantitative_ and _temporal_ fields use the [pre-defined named color range](#range-config) `"heatmap"` (the [`"viridis"`](https://vega.github.io/vega/docs/schemes/#viridis) scheme by default) for rect marks and `"ramp"` (the [`"blues"`](https://vega.github.io/vega/docs/schemes/#blues) scheme by default) for other marks.

<div class="vl-example" data-name="rect_heatmap"></div>

<div class="vl-example" data-name="point_color_quantitative"></div>

There are multiple ways to customize the scale range for the color encoding channel:

#### 1. Set a custom `scheme`.

{% include table.html props="scheme" source="Scale" %}

You can customize the scheme by referencing an [existing color scheme](https://vega.github.io/vega/docs/schemes/). For example, the following plot uses the `"category20b"` scheme.

<div class="vl-example" data-name="stacked_area"></div>

{:#scheme-params}

The `scheme` property can also be a **scheme parameter object**, which contain the following properties:

{% include table.html props="name,extent,count" source="SchemeParams" %}

#### 2. Setting the `range` property to an array of valid CSS color strings.

<div class="vl-example" data-name="point_color_custom"></div>

#### 3. Change the default color schemes using the [range config](#range-config).

{:#continuous}

## Common Scale Properties

In addition to `type`, `domain`, and `range`, all scales share the following properties:

{% include table.html props="reverse,round" source="Scale" %}

## Continuous Scales

Continuous scales map a continuous domain (numbers or dates) to a continuous output range (pixel locations, sizes, colors). Supported continuous scale types for _quantitative_ fields are [`"linear"`](#linear), [`"log"`](#log), [`"pow"`](#pow), [`"sqrt"`](#sqrt), and [`"symlog"`](#symlog). Meanwhile, supported continuous scale types for _temporal_ fields are [`"time"`](#time), [`"utc"`](#utc), and [`"symlog"`](#symlog).<commit_msg>docs: follow up fix for #6600 (#6601)<commit_after>---
layout: docs
menu: docs
title: Scale
permalink: /docs/scale.html
---

Scales are functions that transform a domain of data values (numbers, dates, strings, etc.) to a range of visual values (pixels, colors, sizes). Internally, Vega-Lite uses [Vega scales](https://vega.github.io/vega/docs/scales/), which are derived from the [d3-scale](https://github.com/d3/d3-scale) library. For more background about scales, please see ["Introducing d3-scale"](https://medium.com/@mbostock/introducing-d3-scale-61980c51545f) by <NAME>.

Vega-Lite automatically creates scales for fields that are mapped to [position](encoding.html#position) and [mark property](encoding.html#mark-prop) channels. To customize the scale of a field, users can provide a `scale` object as a part of the [field definition](encoding.html#field) to customize scale properties (e.g., [type](#type), [domain](#domain), and [range](#range)).

```js
// A Single View or a Layer Specification
{
  ...,
  "mark/layer": ...,
  "encoding": {
    "x": {
      "field": ...,
      "type": ...,
      "scale": {                // scale
        "type": ...,
        ...
      },
      ...
    },
    "y": ...,
    ...
  },
  ...
}
```

Besides the `scale` property of each encoding channel, the top-level configuration object ([`config`](config.html)) also provides [scale config](#config) (`config: {scale: {...}}`) for setting default scale properties for all scales.

For more information about guides that visualize the scales, please see the [axes](axis.html) and [legends](legend.html) pages.

<!--prettier-ignore-start-->
## Documentation Overview
{:.no_toc}

- TOC
{:toc}

<!--prettier-ignore-end-->

{:#type}

## Scale Types

The `type` property can be specified to customize the scale type.

{% include table.html props="type" source="Scale" %}

By default, Vega-Lite use the following scale types for the following [data types](type.html) and [encoding channels](encoding.html#channel):

|  | Nominal / Ordinal | Quantitative | Bin-Quantitative<sup>1</sup> | Temporal |
| --: | :-: | :-: | :-: | :-: |
| **X, Y** | [Band](#band) / [Point](#point)<sup>2</sup> | [Linear](#linear) | [Linear](#linear) | [Time](#time) |
| **Size, Opacity** | [Point](#point) | [Linear](#linear) | [Linear](#linear) | [Time](#time) |
| **Color** | [Ordinal](#ordinal) | [Linear](#linear) | [Bin-Ordinal](#bin-ordinal) | [Linear](#linear) |
| **Shape** | [Ordinal](#ordinal) | N/A | N/A | N/A |

<span class="note-line">
<sup>1</sup> Quantitative fields with the [`bin`](bin.html) transform.
</span>
<span class="note-line">
<sup>2</sup> For positional (x and y) nominal and ordinal fields, `"band"` scale is the default scale type for
bar, image, rect, and rule marks while `"point"` is the default scales for all other marks.
</span>

{:#domain}

## Scale Domains

By default, a scale in Vega-Lite draws domain values directly from a channel's encoded field. Users can specify the `domain` property of a scale to customize its domain values. To sort the order of the domain of the encoded, the [`sort`](sort.html) property of a [field definition](encoding.html#field-def) can be specified.

{% include table.html props="domain,domainMid" source="Scale" %}

A common use case for the `domain` property is to limit, for example, the `x` range of values to include in a plot. However, setting the domain property alone is insufficient to achieve the desired effect.

### Example: Customizing Domain for a Time Scale

For a time scale, we can set scale domain to an array [datetime objects](types.html#datetime), as shown below.

<div class="vl-example" data-name="bar_custom_time_domain"></div>

### Example: Clipping or Removing Unwanted Data Points

For example, consider the line plot specification below in which the `x` domain is restricted to the range `[300, 450]`.

<div class="vl-example" data-name="line_outside_domain"></div>

There are two approaches to keep the mark from being plotted outside the desired `x` range of values.

- The first one is to set `clip: true` in mark definition.

  <div class="vl-example" data-name="line_inside_domain_using_clip"></div>

- The second approach is to use `transform`. Note that these two approaches have slightly different behaviors. Using `transform` removes unwanted data points, yet setting `clip` to `true` clips the mark to be the enclosing group's width and height.

<div class="vl-example" data-name="line_inside_domain_using_transform"></div>

<!--
#### Example: Custom Domain
TODO: Custom Domain for quantitative / discrete scales
-->

{:#range}

## Scale Ranges

The range of the scale represents the set of output visual values. Vega-Lite automatically determines the default range for each [encoding channel](encoding.html#channel) using the following rules:

| Channels | Default Range |
| :-- | :-- |
| `x` | The range is _by default_ `[0, width]`. |
| `y` | The range is _by default_ `[0, height]`. |
| `opacity` | Derived from the [scale config](#config)'s `min/maxOpacity`. |
| `color` | Derived from the following [named ranges](scale.html#range-config) based on the field's [`type`](type.html): <br/> • `"category"` for _nominal_ fields. <br/> • `"ordinal"` for _ordinal_ fields. <br/> • `"heatmap"` for _quantitative_ and _temporal_ fields with `"rect"` marks and `"ramp'` for other marks. <br/><br/> See the [color scheme](#scheme) section for examples. |
| `size` | Derived from the following [named ranges](#config) based on the `mark` type: <br/> • `min/maxBandSize` for bar and tick. <br/> • `min/maxStrokeWidth` for line and rule. <br/> • `min/maxSize` for point, square, and circle <br/> • `min/maxFontSize` for text |
| `shape` | Derived from the [pre-defined named range](#range-config) `"symbol"`. |

To customize range values, users can directly specify `range` or specify the special [`scheme`](#scheme) property for [ordinal](#ordinal) and [continuous](#continuous) color scales.

{% include table.html props="range" source="Scale" %}

{:#scheme}

### Color Schemes

Color schemes provide a set of named color palettes as a scale range for the `color` channel. Vega-Lite (via Vega) provides a collection of perceptually-motivated color schemes, many of which are drawn from the [d3-scale](https://github.com/d3/d3-scale), [d3-scale-chromatic](https://github.com/d3/d3-scale-chromatic), and [ColorBrewer](http://colorbrewer2.org/) projects.

By default, Vega-Lite assigns different [default color schemes](#range-config) based on the types of the encoded fields:

- _Nominal_ fields use the `"categorical"` [pre-defined named range](#range-config) (the [`"tableau10"`](https://vega.github.io/vega/docs/schemes/#tableau10) scheme by default).

<div class="vl-example" data-name="point_color"></div>

- _Ordinal_ fields use the `"ordinal"` [pre-defined named color range](#range-config) (the [`"blues"`](https://vega.github.io/vega/docs/schemes/#blues) color scheme by default).

<div class="vl-example" data-name="point_color_ordinal"></div>

- _Quantitative_ and _temporal_ fields use the [pre-defined named color range](#range-config) `"heatmap"` (the [`"viridis"`](https://vega.github.io/vega/docs/schemes/#viridis) scheme by default) for rect marks and `"ramp"` (the [`"blues"`](https://vega.github.io/vega/docs/schemes/#blues) scheme by default) for other marks.

<div class="vl-example" data-name="rect_heatmap"></div>

<div class="vl-example" data-name="point_color_quantitative"></div>

There are multiple ways to customize the scale range for the color encoding channel:

#### 1. Set a custom `scheme`.

{% include table.html props="scheme" source="Scale" %}

You can customize the scheme by referencing an [existing color scheme](https://vega.github.io/vega/docs/schemes/). For example, the following plot uses the `"category20b"` scheme.

<div class="vl-example" data-name="stacked_area"></div>

{:#scheme-params}

The `scheme` property can also be a **scheme parameter object**, which contain the following properties:

{% include table.html props="name,extent,count" source="SchemeParams" %}

#### 2. Setting the `range` property to an array of valid CSS color strings.

<div class="vl-example" data-name="point_color_custom"></div>

#### 3. Change the default color schemes using the range config.

See the [range config](#range-config) documentation for details.

{:#continuous}

## Common Scale Properties

In addition to `type`, `domain`, and `range`, all scales share the following properties:

{% include table.html props="reverse,round" source="Scale" %}

## Continuous Scales

Continuous scales map a continuous domain (numbers or dates) to a continuous output range (pixel locations, sizes, colors). Supported continuous scale types for _quantitative_ fields are [`"linear"`](#linear), [`"log"`](#log), [`"pow"`](#pow), [`"sqrt"`](#sqrt), and [`"symlog"`](#symlog). Meanwhile, supported continuous scale types for _temporal_ fields are [`"time"`](#time), [`"utc"`](#utc), and [`"symlog"`](#symlog).
{'fraction_non_alphanumeric': 0.15395771740949407, 'fraction_numerical': 0.005243487476990015, 'mean_word_length': 4.673417721518987, 'pattern_counts': {'":': 16, '<': 93, '<?xml version=': 0, '>': 93, 'https://': 20, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7120962', 'n_tokens_mistral': 5623, 'n_tokens_neox': 5296, 'n_words': 1950}