<commit_before>---
layout: spec
title: Scales
permalink: /docs/scales/index.html
---

**Scales** map data values (numbers, dates, categories, _etc._) to visual values (pixels, colors, sizes). Scales are a fundamental building block of data visualization, as they determine the nature of visual encodings. Vega includes a range of scales for both continuous and discrete input data, and supports mappings for position, shape, size and color encodings.

To visualize scales, Vega specifications may include [axes](../axes) or [legends](../legends). For more about supported color encodings, see the [color scheme reference](../schemes). Internally, Vega uses the scales provided by the [d3-scale](https://github.com/d3/d3-scale) library; for more background see [Introducing d3-scale](https://medium.com/@mbostock/introducing-d3-scale-61980c51545f) by <NAME>.

## Documentation Overview

- [Scale Properties](#properties)
- [Scale Types](#types)
- [Scale Domains](#domain)
- [Scale Ranges](#range)


## <a name="properties"></a>Scale Properties

Properties shared across scale types.

| Property      | Type                           | Description    |
| :------------ | :----------------------------: | :------------- |
| name          | {% include type t="String" %}  | {% include required %} A unique name for the scale. Scales and [projections](../projections) share the same namespace; names must be unique across both.|
| type          | {% include type t="String" %}  | The type of scale (default `linear`). See the  [scale type reference](#types) for more.|
| domain        | [Domain](#domain)              | The domain of input data values for the scale. For quantitative data, this can take the form of a two-element array with minimum and maximum values. For ordinal or categorical data, this may be an array of valid input values. The domain may also be specified as a reference to a data source. See the [scale domain reference](#domain) for more.|
| domainMax     | {% include type t="Number" %}  | Sets the maximum value in the scale domain, overriding the _domain_ property. The _domainMax_ property is only intended for use with scales having continuous domains.|
| domainMin     | {% include type t="Number" %}  | Sets the minimum value in the scale domain, overriding the _domain_ property. The _domainMin_ property is only intended for use with scales having continuous domains.|
| domainMid     | {% include type t="Number" %}  | Inserts a single mid-point value into a two-element domain. The mid-point value must lie between the domain minimum and maximum values. This property can be useful for setting a midpoint for [diverging color scales](../schemes/#diverging). The _domainMid_ property is only intended for use with scales supporting continuous, piecewise domains.|
| domainRaw     | {% include type t="Array" %}   | An array of raw values that, if non-null, directly overrides the _domain_ property. This is useful for supporting interactions such as panning or zooming a scale. The scale may be initially determined using a data-driven _domain_, then modified in response to user input by setting the _rawDomain_ value.|
| range         | [Range](#range)                | The range of the scale, representing the set of visual values. For numeric values, the range can take the form of a two-element array with minimum and maximum values. For ordinal or quantized data, the range may be an array of desired output values, which are mapped to elements in the specified domain. See the [scale range reference](#range) for more.|
| reverse       | {% include type t="Boolean" %} | If true, reverses the order of the scale range.|
| round         | {% include type t="Boolean" %} | If true, rounds numeric output values to integers. Helpful for snapping to the pixel grid.|


## <a name="types"></a>Scale Types

- [**Quantitative Scales**](#quantitative)
  - [`linear`](#linear)
  - [`pow`](#pow)
  - [`sqrt`](#sqrt)
  - [`log`](#log)
  - [`time`](#time)
  - [`utc`](#utc)
  - [`sequential`](#sequential)
- [**Discrete Scales**](#discrete)
  - [`ordinal`](#ordinal)
  - [`band`](#band)
  - [`point`](#point)
- [**Discretizing Scales**](#discretizing)
  - [`quantile`](#quantile)
  - [`quantize`](#quantize)
  - [`threshold`](#threshold)
  - [`bin-linear`](#bin-linear)
  - [`bin-ordinal`](#bin-ordinal)
{: .column-set}

In addition, Vega can be extended at runtime with additional scales using the [`vega.scale`](https://github.com/vega/vega-scale/#scale) method.

## <a name="quantitative"></a>Quantitative Scales

A quantitative scale maps a continuous domain (numbers or dates) to a continuous output range (pixel locations, sizes, colors). The available quantitative scale _type_ values are [`linear`](#linear), [`pow`](#pow), [`sqrt`](#sqrt), [`log`](#log), [`time`](#time) and [`utc`](#utc). All quantitative scales except for `time` and `utc` use a default _domain_ of [0, 1] and default unit _range_ [0, 1].

| Property      | Type                                  | Description    |
| :------------ | :-----------------------------------: | :------------- |
| clamp         | {% include type t="Boolean" %}        | A boolean indicating if output values should be clamped to the _range_ (default `false`). If clamping is disabled and the scale is passed a value outside the _domain_, the scale may return a value outside the _range_ through extrapolation. If clamping is enabled, the output value of the scale is always within the scale's range.|
| interpolate   | {% include type t="String|Object" %}  | The interpolation method for range values. By default, a general interpolator for numbers, dates, strings and colors (in RGB space) is used. For color ranges, this property allows interpolation in alternative color spaces. Legal values include `rgb`, `hsl`, `hsl-long`, `lab`, `hcl`, `hcl-long`, `cubehelix` and `cubehelix-long` ('-long' variants use longer paths in polar coordinate spaces). If object-valued, this property accepts an object with a string-valued _type_ property and an optional numeric _gamma_ property applicable to rgb and cubehelix interpolators. For more, see the [d3-interpolate documentation](https://github.com/d3/d3-interpolate).|
| padding       | {% include type t="Number" %}         | Expands the scale domain to accommodate the specified number of pixels on each of the scale range. The scale range must represent pixels for this parameter to function as intended. Padding adjustment is performed _prior_ to all other adjustments, including the effects of the _zero_, _nice_, _domainMin_, and _domainMax_ properties.|
| nice          | {% include type t="Boolean|Number" %} | Extends the domain so that it starts and ends on nice round values. This method typically modifies the scale's domain, and may only extend the bounds to the nearest round value. Nicing is useful if the domain is computed from data and may be irregular. For example, for a domain of [0.201479…, 0.996679…], a nice domain might be [0.2, 1.0]. Domain values set via _domainMin_ and _domainMax_ (but **not** _domainRaw_) are subject to nicing. Using a number value for this parameter (representing a desired tick count) allows greater control over the step size used to extend the bounds, guaranteeing that the returned ticks will exactly cover the domain.|
| zero          | {% include type t="Boolean" %}        | Boolean flag indicating if the scale domain should include zero. The default value is `true` for `linear`, `sqrt` and `pow`, and `false` otherwise.|

### <a name="linear"></a>Linear Scales

Linear scales (`linear`) are [quantitative scales](#quantitative) scales that preserve proportional differences. Each range value _y_ can be expressed as a linear function of the domain value _x_: _y = mx + b_.

### <a name="pow"></a>Power Scales

Power scales (`pow`) are [quantitative scales](#quantitative) scales that apply an exponential transform to the input domain value before the output range value is computed. Each range value _y_ can be expressed as a polynomial function of the domain value _x_: _y = mx^k + b_, where _k_ is the exponent value. Power scales also support negative domain values, in which case the input value and the resulting output value are multiplied by -1.

| Property      | Type                           | Description    |
| :------------ | :----------------------------: | :------------- |
| exponent      | {% include type t="Number" %}  | The exponent to use in the scale transform (default `1`).|

### <a name="sqrt"></a>Square Root Scales

Square root (`sqrt`) scales are a convenient shorthand for [power scales](#pow) with an exponent of `0.5`, indicating a square root transform.

### <a name="log"></a>Logarithmic Scales

Log scales (`log`) are [quantitative scales](#quantitative) scales in which a logarithmic transform is applied to the input domain value before the output range value is computed. Log scales are particularly useful for plotting data that varies over multiple orders of magnitude. The mapping to the range value _y_ can be expressed as a logarithmic function of the domain value _x_: _y = m log(x) + b_.

As log(0) = -∞, a log scale domain must be strictly-positive or strictly-negative; the domain must not include or cross zero. A log scale with a positive domain has a well-defined behavior for positive values, and a log scale with a negative domain has a well-defined behavior for negative values. (For a negative domain, input and output values are implicitly multiplied by -1.) The behavior of the scale is undefined if you run a negative value through a log scale with a positive domain or vice versa.

| Property      | Type                           | Description    |
| :------------ | :----------------------------: | :------------- |
| base          | {% include type t="Number" %}  | The base of the logarithm (default `10`).|

### <a name="time"></a>Time and <a name="utc"></a>UTC Scales

Time scales (`time` and `utc`) are [quantitative scales](#quantitative) with a temporal domain: values in the input domain are assumed to be [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) objects or timestamps. The `time` scale type uses the current local timezone setting. UTC scales (`utc`) instead use [Coordinated Universal Time](https://en.wikipedia.org/wiki/Coordinated_Universal_Time). Both `time` and `utc` scales use a default _domain_ of [2000-01-01, 2000-01-02], and a default unit _range_ [0, 1].

| Property      | Type                                         | Description    |
| :------------ | :------------------------------------------: | :------------- |
| nice          | {% include type t="String|Object|Number|Boolean" %} | If specified, modifies the scale domain to use a more human-friendly value range. For `time` and `utc` scale types, the nice value can additionally be a string indicating the desired time interval. Legal values are `"millisecond"`, `"second"`, `"minute"`, `"hour"`, `"day"`, `"week"`, `"month"`, and `"year"`. Alternatively, `time` and `utc` scales can accept an object-valued interval specifier of the form `{"interval": "month", "step": 3}`, which includes a desired number of interval steps. Here, the domain would snap to quarter (Jan, Apr, Jul, Oct) boundaries.|

### <a name="sequential"></a>Sequential Scales

Sequential scales (`sequential`) are similar to [linear scales](#linear), but use a fixed interpolator to determine the output range. The major use case for sequential scales is continuous quantitative color scales. Sequential scales default to a _domain_ of [0, 1].

Akin to quantitative scales, sequential scales support piecewise _domain_ settings with more than two entries. In such cases, the output range is subdivided into equal-sized segments for each piecewise segment of the domain. For example, the domain [1, 4, 10] would lead to the interpolants `1 -> 0`, `4 -> 0.5`, and `10 -> 1`. Piecewise domains are useful for parameterizing [diverging color encodings](../schemes/#diverging), where a middle domain value corresponds to the mid-point of the color range.

| Property      | Type                           | Description    |
| :------------ | :----------------------------: | :------------- |
| clamp         | {% include type t="Boolean" %} | A boolean indicating if output values should be clamped to the _range_ (default `false`). If clamping is disabled and the scale is passed a value outside the _domain_, the scale may return a value outside the _range_ through extrapolation. If clamping is enabled, the output value of the scale is always within the scale's range.|
| domainMax     | {% include type t="Number" %}  | Sets the maximum value in the scale domain, overriding the _domain_ property.|
| domainMin     | {% include type t="Number" %}  | Sets the minimum value in the scale domain, overriding the _domain_ property.|
| domainMid     | {% include type t="Number" %}  | Inserts a single mid-point value into a two-element domain. The mid-point value must lie between the domain minimum and maximum values. This property can be useful for setting a midpoint for [diverging color scales](../schemes/#diverging).|
| range         | [Scheme](../schemes){% include or %}{% include type t="Color[]" %} | {% include required %} The _range_ value should either be a [color scheme](../schemes) object or an array of color strings. If an array of colors is provided, the array will be used to create a continuous interpolator via [basis spline interpolation in the RGB color space](https://github.com/d3/d3-interpolate#interpolateRgbBasis).|

[Back to scale type reference](#types)


## <a name="discrete"></a>Discrete Scales

Discrete scales map values from a discrete domain to a discrete range. In the case of `band` and `point` scales, the range is determined by discretizing a continuous numeric range.

### <a name="ordinal"></a>Ordinal Scales

Ordinal scales (`ordinal`) have a discrete domain and range. For example, an ordinal scale might map a set of named categories to a set of colors, or to a set of shapes. Ordinal scales function as a "lookup table" from a domain value to a range value.

This example uses an ordinal scale for color-coded categories, with up to 20 unique colors:

```json
{
  "scales": [
    {
      "name": "color",
      "type": "ordinal",
      "domain": {"data": "table", "field": "category"},
      "range": {"scheme": "category20"}
    }
  ]
}
```

### <a name="band"></a>Band Scales

Band scales (`band`) accept a discrete domain similar to [ordinal scales](#ordinal), but map this domain to a continuous, numeric output range such as pixels. Discrete output values are automatically computed by the scale by dividing the continuous range into uniform _bands_. Band scales are typically used for bar charts with an ordinal or categorical dimension.

In addition to a standard numerical _range_ value (such as `[0, 500]`), band scales can be given a fixed _step_ size for each band. The actual range is then determined by both the step size and the cardinality (element count) of the input domain. The step size is specified by an object with a _step_ property that provides the step size in pixels, for example `"range": {"step": 20}`.

This image from the [d3-scale documentation](https://github.com/d3/d3-scale#band-scales) illustrates how a band scale works:

<img src="https://raw.githubusercontent.com/d3/d3-scale/master/img/band.png"/>

| Property      | Type                          | Description    |
| :------------ | :---------------------------: | :------------- |
| align         | {% include type t="Number" %} | The alignment of elements within each band step, as a fraction of the step size (default `0.5`). This value must lie in the range [0,1].|
| domainImplicit| {% include type t="Number" %} | A flag (default `false`) indicating if an ordinal domain should be implicitly extended with new values. If false, the scale will return `undefined` for values not explicitly included in the domain. If true, new values will be appended to the domain and the matching range value will be returned.|
| padding       | {% include type t="Number" %} | Sets _paddingInner_ and _paddingOuter_ to the same padding value (default `0`). This value must lie in the range [0,1].|
| paddingInner  | {% include type t="Number" %} | The inner padding (spacing) within each band step, as a fraction of the step size (default `0`). This value must lie in the range [0,1].|
| paddingOuter  | {% include type t="Number" %} | The outer padding (spacing) at the ends of the scale range, as a fraction of the step size (default `0`). This value must lie in the range [0,1].|


### <a name="point"></a>Point Scales

Point scales (`point`) are a variant of [band scales](#band) where the internal band width is fixed to zero. Point scales are typically used for scatterplots with an ordinal or categorical dimension. Similar to band scales, point scale _range_ values may be specified using either a numerical extent (`[0, 500]`) or a step size (`{"step": 20}`). As point scales do not have internal band widths (only step sizes between bands), they do not accept the _paddingInner_ property.

This image from the [d3-scale documentation](https://github.com/d3/d3-scale#band-scales) illustrates how a point scale works:

<img src="https://raw.githubusercontent.com/d3/d3-scale/master/img/point.png"/>

| Property      | Type                          | Description    |
| :------------ | :---------------------------: | :------------- |
| align         | {% include type t="Number" %} | The alignment of elements within each band step, as a fraction of the step size (default `0.5`). This value must lie in the range [0,1].|
| padding       | {% include type t="Number" %} | An alias for _paddingOuter_ (default `0`). This value must lie in the range [0,1].|
| paddingOuter  | {% include type t="Number" %} | The outer padding (spacing) at the ends of the scale range, as a fraction of the step size (default `0`). This value must lie in the range [0,1].|<commit_msg>domainImplicit appears to be a boolean flag<commit_after>---
layout: spec
title: Scales
permalink: /docs/scales/index.html
---

**Scales** map data values (numbers, dates, categories, _etc._) to visual values (pixels, colors, sizes). Scales are a fundamental building block of data visualization, as they determine the nature of visual encodings. Vega includes a range of scales for both continuous and discrete input data, and supports mappings for position, shape, size and color encodings.

To visualize scales, Vega specifications may include [axes](../axes) or [legends](../legends). For more about supported color encodings, see the [color scheme reference](../schemes). Internally, Vega uses the scales provided by the [d3-scale](https://github.com/d3/d3-scale) library; for more background see [Introducing d3-scale](https://medium.com/@mbostock/introducing-d3-scale-61980c51545f) by <NAME>.

## Documentation Overview

- [Scale Properties](#properties)
- [Scale Types](#types)
- [Scale Domains](#domain)
- [Scale Ranges](#range)


## <a name="properties"></a>Scale Properties

Properties shared across scale types.

| Property      | Type                           | Description    |
| :------------ | :----------------------------: | :------------- |
| name          | {% include type t="String" %}  | {% include required %} A unique name for the scale. Scales and [projections](../projections) share the same namespace; names must be unique across both.|
| type          | {% include type t="String" %}  | The type of scale (default `linear`). See the  [scale type reference](#types) for more.|
| domain        | [Domain](#domain)              | The domain of input data values for the scale. For quantitative data, this can take the form of a two-element array with minimum and maximum values. For ordinal or categorical data, this may be an array of valid input values. The domain may also be specified as a reference to a data source. See the [scale domain reference](#domain) for more.|
| domainMax     | {% include type t="Number" %}  | Sets the maximum value in the scale domain, overriding the _domain_ property. The _domainMax_ property is only intended for use with scales having continuous domains.|
| domainMin     | {% include type t="Number" %}  | Sets the minimum value in the scale domain, overriding the _domain_ property. The _domainMin_ property is only intended for use with scales having continuous domains.|
| domainMid     | {% include type t="Number" %}  | Inserts a single mid-point value into a two-element domain. The mid-point value must lie between the domain minimum and maximum values. This property can be useful for setting a midpoint for [diverging color scales](../schemes/#diverging). The _domainMid_ property is only intended for use with scales supporting continuous, piecewise domains.|
| domainRaw     | {% include type t="Array" %}   | An array of raw values that, if non-null, directly overrides the _domain_ property. This is useful for supporting interactions such as panning or zooming a scale. The scale may be initially determined using a data-driven _domain_, then modified in response to user input by setting the _rawDomain_ value.|
| range         | [Range](#range)                | The range of the scale, representing the set of visual values. For numeric values, the range can take the form of a two-element array with minimum and maximum values. For ordinal or quantized data, the range may be an array of desired output values, which are mapped to elements in the specified domain. See the [scale range reference](#range) for more.|
| reverse       | {% include type t="Boolean" %} | If true, reverses the order of the scale range.|
| round         | {% include type t="Boolean" %} | If true, rounds numeric output values to integers. Helpful for snapping to the pixel grid.|


## <a name="types"></a>Scale Types

- [**Quantitative Scales**](#quantitative)
  - [`linear`](#linear)
  - [`pow`](#pow)
  - [`sqrt`](#sqrt)
  - [`log`](#log)
  - [`time`](#time)
  - [`utc`](#utc)
  - [`sequential`](#sequential)
- [**Discrete Scales**](#discrete)
  - [`ordinal`](#ordinal)
  - [`band`](#band)
  - [`point`](#point)
- [**Discretizing Scales**](#discretizing)
  - [`quantile`](#quantile)
  - [`quantize`](#quantize)
  - [`threshold`](#threshold)
  - [`bin-linear`](#bin-linear)
  - [`bin-ordinal`](#bin-ordinal)
{: .column-set}

In addition, Vega can be extended at runtime with additional scales using the [`vega.scale`](https://github.com/vega/vega-scale/#scale) method.

## <a name="quantitative"></a>Quantitative Scales

A quantitative scale maps a continuous domain (numbers or dates) to a continuous output range (pixel locations, sizes, colors). The available quantitative scale _type_ values are [`linear`](#linear), [`pow`](#pow), [`sqrt`](#sqrt), [`log`](#log), [`time`](#time) and [`utc`](#utc). All quantitative scales except for `time` and `utc` use a default _domain_ of [0, 1] and default unit _range_ [0, 1].

| Property      | Type                                  | Description    |
| :------------ | :-----------------------------------: | :------------- |
| clamp         | {% include type t="Boolean" %}        | A boolean indicating if output values should be clamped to the _range_ (default `false`). If clamping is disabled and the scale is passed a value outside the _domain_, the scale may return a value outside the _range_ through extrapolation. If clamping is enabled, the output value of the scale is always within the scale's range.|
| interpolate   | {% include type t="String|Object" %}  | The interpolation method for range values. By default, a general interpolator for numbers, dates, strings and colors (in RGB space) is used. For color ranges, this property allows interpolation in alternative color spaces. Legal values include `rgb`, `hsl`, `hsl-long`, `lab`, `hcl`, `hcl-long`, `cubehelix` and `cubehelix-long` ('-long' variants use longer paths in polar coordinate spaces). If object-valued, this property accepts an object with a string-valued _type_ property and an optional numeric _gamma_ property applicable to rgb and cubehelix interpolators. For more, see the [d3-interpolate documentation](https://github.com/d3/d3-interpolate).|
| padding       | {% include type t="Number" %}         | Expands the scale domain to accommodate the specified number of pixels on each of the scale range. The scale range must represent pixels for this parameter to function as intended. Padding adjustment is performed _prior_ to all other adjustments, including the effects of the _zero_, _nice_, _domainMin_, and _domainMax_ properties.|
| nice          | {% include type t="Boolean|Number" %} | Extends the domain so that it starts and ends on nice round values. This method typically modifies the scale's domain, and may only extend the bounds to the nearest round value. Nicing is useful if the domain is computed from data and may be irregular. For example, for a domain of [0.201479…, 0.996679…], a nice domain might be [0.2, 1.0]. Domain values set via _domainMin_ and _domainMax_ (but **not** _domainRaw_) are subject to nicing. Using a number value for this parameter (representing a desired tick count) allows greater control over the step size used to extend the bounds, guaranteeing that the returned ticks will exactly cover the domain.|
| zero          | {% include type t="Boolean" %}        | Boolean flag indicating if the scale domain should include zero. The default value is `true` for `linear`, `sqrt` and `pow`, and `false` otherwise.|

### <a name="linear"></a>Linear Scales

Linear scales (`linear`) are [quantitative scales](#quantitative) scales that preserve proportional differences. Each range value _y_ can be expressed as a linear function of the domain value _x_: _y = mx + b_.

### <a name="pow"></a>Power Scales

Power scales (`pow`) are [quantitative scales](#quantitative) scales that apply an exponential transform to the input domain value before the output range value is computed. Each range value _y_ can be expressed as a polynomial function of the domain value _x_: _y = mx^k + b_, where _k_ is the exponent value. Power scales also support negative domain values, in which case the input value and the resulting output value are multiplied by -1.

| Property      | Type                           | Description    |
| :------------ | :----------------------------: | :------------- |
| exponent      | {% include type t="Number" %}  | The exponent to use in the scale transform (default `1`).|

### <a name="sqrt"></a>Square Root Scales

Square root (`sqrt`) scales are a convenient shorthand for [power scales](#pow) with an exponent of `0.5`, indicating a square root transform.

### <a name="log"></a>Logarithmic Scales

Log scales (`log`) are [quantitative scales](#quantitative) scales in which a logarithmic transform is applied to the input domain value before the output range value is computed. Log scales are particularly useful for plotting data that varies over multiple orders of magnitude. The mapping to the range value _y_ can be expressed as a logarithmic function of the domain value _x_: _y = m log(x) + b_.

As log(0) = -∞, a log scale domain must be strictly-positive or strictly-negative; the domain must not include or cross zero. A log scale with a positive domain has a well-defined behavior for positive values, and a log scale with a negative domain has a well-defined behavior for negative values. (For a negative domain, input and output values are implicitly multiplied by -1.) The behavior of the scale is undefined if you run a negative value through a log scale with a positive domain or vice versa.

| Property      | Type                           | Description    |
| :------------ | :----------------------------: | :------------- |
| base          | {% include type t="Number" %}  | The base of the logarithm (default `10`).|

### <a name="time"></a>Time and <a name="utc"></a>UTC Scales

Time scales (`time` and `utc`) are [quantitative scales](#quantitative) with a temporal domain: values in the input domain are assumed to be [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) objects or timestamps. The `time` scale type uses the current local timezone setting. UTC scales (`utc`) instead use [Coordinated Universal Time](https://en.wikipedia.org/wiki/Coordinated_Universal_Time). Both `time` and `utc` scales use a default _domain_ of [2000-01-01, 2000-01-02], and a default unit _range_ [0, 1].

| Property      | Type                                         | Description    |
| :------------ | :------------------------------------------: | :------------- |
| nice          | {% include type t="String|Object|Number|Boolean" %} | If specified, modifies the scale domain to use a more human-friendly value range. For `time` and `utc` scale types, the nice value can additionally be a string indicating the desired time interval. Legal values are `"millisecond"`, `"second"`, `"minute"`, `"hour"`, `"day"`, `"week"`, `"month"`, and `"year"`. Alternatively, `time` and `utc` scales can accept an object-valued interval specifier of the form `{"interval": "month", "step": 3}`, which includes a desired number of interval steps. Here, the domain would snap to quarter (Jan, Apr, Jul, Oct) boundaries.|

### <a name="sequential"></a>Sequential Scales

Sequential scales (`sequential`) are similar to [linear scales](#linear), but use a fixed interpolator to determine the output range. The major use case for sequential scales is continuous quantitative color scales. Sequential scales default to a _domain_ of [0, 1].

Akin to quantitative scales, sequential scales support piecewise _domain_ settings with more than two entries. In such cases, the output range is subdivided into equal-sized segments for each piecewise segment of the domain. For example, the domain [1, 4, 10] would lead to the interpolants `1 -> 0`, `4 -> 0.5`, and `10 -> 1`. Piecewise domains are useful for parameterizing [diverging color encodings](../schemes/#diverging), where a middle domain value corresponds to the mid-point of the color range.

| Property      | Type                           | Description    |
| :------------ | :----------------------------: | :------------- |
| clamp         | {% include type t="Boolean" %} | A boolean indicating if output values should be clamped to the _range_ (default `false`). If clamping is disabled and the scale is passed a value outside the _domain_, the scale may return a value outside the _range_ through extrapolation. If clamping is enabled, the output value of the scale is always within the scale's range.|
| domainMax     | {% include type t="Number" %}  | Sets the maximum value in the scale domain, overriding the _domain_ property.|
| domainMin     | {% include type t="Number" %}  | Sets the minimum value in the scale domain, overriding the _domain_ property.|
| domainMid     | {% include type t="Number" %}  | Inserts a single mid-point value into a two-element domain. The mid-point value must lie between the domain minimum and maximum values. This property can be useful for setting a midpoint for [diverging color scales](../schemes/#diverging).|
| range         | [Scheme](../schemes){% include or %}{% include type t="Color[]" %} | {% include required %} The _range_ value should either be a [color scheme](../schemes) object or an array of color strings. If an array of colors is provided, the array will be used to create a continuous interpolator via [basis spline interpolation in the RGB color space](https://github.com/d3/d3-interpolate#interpolateRgbBasis).|

[Back to scale type reference](#types)


## <a name="discrete"></a>Discrete Scales

Discrete scales map values from a discrete domain to a discrete range. In the case of `band` and `point` scales, the range is determined by discretizing a continuous numeric range.

### <a name="ordinal"></a>Ordinal Scales

Ordinal scales (`ordinal`) have a discrete domain and range. For example, an ordinal scale might map a set of named categories to a set of colors, or to a set of shapes. Ordinal scales function as a "lookup table" from a domain value to a range value.

This example uses an ordinal scale for color-coded categories, with up to 20 unique colors:

```json
{
  "scales": [
    {
      "name": "color",
      "type": "ordinal",
      "domain": {"data": "table", "field": "category"},
      "range": {"scheme": "category20"}
    }
  ]
}
```

### <a name="band"></a>Band Scales

Band scales (`band`) accept a discrete domain similar to [ordinal scales](#ordinal), but map this domain to a continuous, numeric output range such as pixels. Discrete output values are automatically computed by the scale by dividing the continuous range into uniform _bands_. Band scales are typically used for bar charts with an ordinal or categorical dimension.

In addition to a standard numerical _range_ value (such as `[0, 500]`), band scales can be given a fixed _step_ size for each band. The actual range is then determined by both the step size and the cardinality (element count) of the input domain. The step size is specified by an object with a _step_ property that provides the step size in pixels, for example `"range": {"step": 20}`.

This image from the [d3-scale documentation](https://github.com/d3/d3-scale#band-scales) illustrates how a band scale works:

<img src="https://raw.githubusercontent.com/d3/d3-scale/master/img/band.png"/>

| Property      | Type                          | Description    |
| :------------ | :---------------------------: | :------------- |
| align         | {% include type t="Number" %} | The alignment of elements within each band step, as a fraction of the step size (default `0.5`). This value must lie in the range [0,1].|
| domainImplicit| {% include type t="Boolean" %} | A Boolean flag (default `false`) indicating if an ordinal domain should be implicitly extended with new values. If false, the scale will return `undefined` for values not explicitly included in the domain. If true, new values will be appended to the domain and the matching range value will be returned.|
| padding       | {% include type t="Number" %} | Sets _paddingInner_ and _paddingOuter_ to the same padding value (default `0`). This value must lie in the range [0,1].|
| paddingInner  | {% include type t="Number" %} | The inner padding (spacing) within each band step, as a fraction of the step size (default `0`). This value must lie in the range [0,1].|
| paddingOuter  | {% include type t="Number" %} | The outer padding (spacing) at the ends of the scale range, as a fraction of the step size (default `0`). This value must lie in the range [0,1].|


### <a name="point"></a>Point Scales

Point scales (`point`) are a variant of [band scales](#band) where the internal band width is fixed to zero. Point scales are typically used for scatterplots with an ordinal or categorical dimension. Similar to band scales, point scale _range_ values may be specified using either a numerical extent (`[0, 500]`) or a step size (`{"step": 20}`). As point scales do not have internal band widths (only step sizes between bands), they do not accept the _paddingInner_ property.

This image from the [d3-scale documentation](https://github.com/d3/d3-scale#band-scales) illustrates how a point scale works:

<img src="https://raw.githubusercontent.com/d3/d3-scale/master/img/point.png"/>

| Property      | Type                          | Description    |
| :------------ | :---------------------------: | :------------- |
| align         | {% include type t="Number" %} | The alignment of elements within each band step, as a fraction of the step size (default `0.5`). This value must lie in the range [0,1].|
| padding       | {% include type t="Number" %} | An alias for _paddingOuter_ (default `0`). This value must lie in the range [0,1].|
| paddingOuter  | {% include type t="Number" %} | The outer padding (spacing) at the ends of the scale range, as a fraction of the step size (default `0`). This value must lie in the range [0,1].|
{'fraction_non_alphanumeric': 0.12512105365097811, 'fraction_numerical': 0.007304723167593592, 'mean_word_length': 3.470806531420089, 'pattern_counts': {'":': 26, '<': 65, '<?xml version=': 0, '>': 71, 'https://': 22, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 9, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1158969', 'n_tokens_mistral': 9744, 'n_tokens_neox': 9046, 'n_words': 4594}