D3 in Depth covers versions 6 and 7 of D3

Get book discounts and receive D3.js related news and tips.

Subscribe

# D3 Scale functions

How to use D3 scale functions to transform data values into visual values such as positions and colours. After explaning scale basics we cover linear, square root, log, sequential, quantized, quantile, threshold, ordinal, band and point scales.

Scale functions are JavaScript functions that:

• take an input (usually a number, date or category) and
• return a value (such as a coordinate, a colour, a length or a radius)

They're typically used to transform (or 'map') data values into visual variables (such as position, length and colour).

For example, suppose you have some data:

``[ 0, 2, 3, 5, 7.5, 9, 10 ]``

you can create a scale function using:

``let myScale = d3.scaleLinear()  .domain([0, 10])  .range([0, 600]);``

D3 creates a function `myScale` which accepts input between 0 and 10 (the domain) and maps it to output between 0 and 600 (the range).

You can use `myScale` to calculate positions based on the data:

``myScale(0);   // returns 0myScale(2);   // returns 120myScale(3);   // returns 180...myScale(10);  // returns 600``

Scales are mainly used for transforming data values to visual variables such as position, length and colour.

For example they can transform:

• data values into lengths between 0 and 500 for a bar chart
• data values into positions between 0 and 200 for line charts
• % change data (+4%, +10%, -5% etc.) into a continuous range of colours (with red for negative and green for positive)
• dates into positions along an x-axis.

### Constructing scales

(In this chapter we'll just focus on linear scales as these are the most commonly used scale type. We'll cover other types later on.)

To create a linear scale you use:

``let myScale = d3.scaleLinear();``
Versions 4 and above use a different naming convention to v3. `d3.scaleLinear()` is used in v4 and above and `d3.scale.linear()` is used in v3.

As it stands the above function isn't very useful so you can configure the input bounds (the domain) as well as the output bounds (the range):

``myScale  .domain([0, 100])  .range([0, 800]);``

This results in a scale function that accepts input between 0 and 100 and linearly maps it to between 0 and 800:

``myScale(0);    // returns 0myScale(50);   // returns 400myScale(100);  // returns 800``
Try experimenting with scale functions by copying code fragments and pasting them into the console of this page. (I've included D3 version 6.2.0 on every page of D3 in Depth.)

### D3 scale types

D3 has around 12 different scale types (scaleLinear, scalePow, scaleQuantise, scaleOrdinal etc.) and broadly speaking they can be classified into 3 groups:

Continuous data is typically numeric data but also includes time and dates. Discrete data has a set number of values (such as the twelve months of the year).)

We'll now look at each of these three categories.

### Scales with continuous input and continuous output

In this chapter we cover scale functions that map from a continuous input domain to a continuous output range.

#### scaleLinear

Linear scales are probably the most commonly used scale type as they are the most suitable scale for transforming data values into positions and lengths.

They use a linear function y=mx+c to interpolate across the domain and range. (Imagine a graph where the domain is on the x-axis and the range is on the y-axis.)

``let linearScale = d3.scaleLinear()  .domain([0, 10])  .range([0, 600]);linearScale(0);   // returns 0linearScale(5);   // returns 300linearScale(10);  // returns 600``

Linear scale functions are typically used to transform data values into positions and lengths. They are useful when creating bar charts, line charts and many other chart types.

The output range can also be specified as colours:

``let linearScale = d3.scaleLinear()  .domain([0, 10])  .range(['yellow', 'red']);linearScale(0);   // returns "rgb(255, 255, 0)"linearScale(5);   // returns "rgb(255, 128, 0)"linearScale(10);  // returns "rgb(255, 0, 0)"``

This can be useful for visualisations such as choropleth maps, but also consider `scaleQuantize`, `scaleQuantile` and `scaleThreshold`.

#### scaleSqrt

The `scaleSqrt` scale is useful for sizing circles by area (rather than radius). (When using circle size to represent data, it's considered better practice to set the area, rather than the radius proportionally to the data.)

``let sqrtScale = d3.scaleSqrt()  .domain([0, 100])  .range([0, 30]);sqrtScale(0);   // returns 0sqrtScale(50);  // returns 21.21...sqrtScale(100); // returns 30``

#### scalePow

`scalePow` is a more general version of `scaleSqrt`. This scale interpolates using a power function y=mxk+c. The exponent `k` is set using `.exponent()`:

``let powerScale = d3.scalePow()  .exponent(0.5)  .domain([0, 100])  .range([0, 30]);powerScale(0);   // returns 0powerScale(50);  // returns 21.21...powerScale(100); // returns 30``

(I've never used this scale, by the way!)

#### scaleLog

`scaleLog` interpolates using a log function y=m*log(x)+b and can be useful when the data has an exponential nature to it.

``let logScale = d3.scaleLog()  .domain([10, 100000])  .range([0, 600]);logScale(10);     // returns 0logScale(100);    // returns 150logScale(1000);   // returns 300logScale(100000); // returns 600``

#### scaleTime

`scaleTime` is similar to `scaleLinear` except the domain is expressed as an array of dates. (It's very useful when dealing with time series data.)

``timeScale = d3.scaleTime()  .domain([new Date(2016, 0, 1), new Date(2017, 0, 1)])  .range([0, 700]);timeScale(new Date(2016, 0, 1));   // returns 0timeScale(new Date(2016, 6, 1));   // returns 348.00...timeScale(new Date(2017, 0, 1));   // returns 700``

#### scaleSequential

`scaleSequential` is used for mapping continuous values to an output range determined by a preset (or custom) interpolator. (An interpolator is a function that accepts input between 0 and 1 and outputs an interpolated value between two numbers, colours, strings etc.)

D3 provides a number of preset interpolators including many colour ones. For example you can use `d3.interpolateRainbow` to create the well known rainbow colour scale:

``let sequentialScale = d3.scaleSequential()  .domain([0, 100])  .interpolator(d3.interpolateRainbow);sequentialScale(0);   // returns 'rgb(110, 64, 170)'sequentialScale(50);  // returns 'rgb(175, 240, 91)'sequentialScale(100); // returns 'rgb(110, 64, 170)'``

Note that the interpolator determines the output range so you don't need to specify the range yourself.

The example below shows some of the other colour interpolators provided by D3:

There's also a plug-in d3-scale-chromatic which provides the well known ColorBrewer colour schemes.

#### Clamping

By default `scaleLinear`, `scalePow`, `scaleSqrt`, `scaleLog`, `scaleTime` and `scaleSequential` extrapolate when the input value goes beyond the domain.

For example:

``let linearScale = d3.scaleLinear()  .domain([0, 10])  .range([0, 100]);linearScale(20);  // returns 200linearScale(-10); // returns -100``

You can clamp the scale function so that the input value stays within the domain using `.clamp`:

``linearScale.clamp(true);linearScale(20);  // returns 100linearScale(-10); // returns 0``

You can switch off clamping using `.clamp(false)`.

#### Nice

If the domain has been computed automatically from real data (e.g. by using `d3.extent`) the start and end values might not be round figures. This isn't necessarily a problem, but if using the scale to define an axis, it can look a bit untidy:

``let data = [0.243, 0.584, 0.987, 0.153, 0.433];let extent = d3.extent(data);let linearScale = d3.scaleLinear()  .domain(extent)  .range([0, 100]);``

Therefore D3 provides a function `.nice()` on the scales in this chapter which will round the domain to 'nice' round values:

``let data = [0.243, 0.584, 0.987, 0.153, 0.433];let extent = d3.extent(data);let linearScale = d3.scaleLinear()  .domain(extent)  .range([0, 100])  .nice();``

Note that `.nice()` must be called each time the domain is updated.

#### Multiple segments

The domain and range of `scaleLinear`, `scalePow`, `scaleSqrt`, `scaleLog` and `scaleTime` usually consists of two values, but if you provide 3 or more values the scale function is subdivided into multiple segments:

``let linearScale = d3.scaleLinear()  .domain([-10, 0, 10])  .range(['red', '#ddd', 'blue']);linearScale(-10);  // returns "rgb(255, 0, 0)"linearScale(0);    // returns "rgb(221, 221, 221)"linearScale(5);    // returns "rgb(111, 111, 238)"``

Typically multiple segments are used for distinguishing between negative and positive values (such as in the example above). You can use as many segments as you like as long as the domain and range are of the same length.

#### Inversion

The `.invert()` method lets you determine a scale function's input value given an output value (provided the scale function has a numeric domain):

``let linearScale = d3.scaleLinear()  .domain([0, 10])  .range([0, 100]);linearScale.invert(50);   // returns 5linearScale.invert(100);  // returns 10``

A common use case is when you want to convert a user's click along an axis into a domain value:

### Scales with continuous input and discrete output

#### scaleQuantize

`scaleQuantize` accepts continuous input and outputs a number of discrete quantities defined by the range.

``let quantizeScale = d3.scaleQuantize()  .domain([0, 100])  .range(['lightblue', 'orange', 'lightgreen', 'pink']);quantizeScale(10);  // returns 'lightblue'quantizeScale(30);  // returns 'orange'quantizeScale(90);  // returns 'pink'``

Each range value is mapped to an equal sized chunk in the domain so in the example above:

• 0 ≤ u < 25 is mapped to 'lightblue'
• 25 ≤ u < 50 is mapped to 'orange'
• 50 ≤ u < 75 is mapped to 'lightgreen'
• 75 ≤ u < 100 is mapped to 'pink'

where u is the input value.

Input values outside the domain are clamped so in our example `quantizeScale(-10)` returns 'lightblue' and `quantizeScale(110)` returns 'pink'.

#### scaleQuantile

`scaleQuantile` maps continuous numeric input to discrete values. The domain is defined by an array of numbers:

``let myData = [0, 5, 7, 10, 20, 30, 35, 40, 60, 62, 65, 70, 80, 90, 100];let quantileScale = d3.scaleQuantile()  .domain(myData)  .range(['lightblue', 'orange', 'lightgreen']);quantileScale(0);   // returns 'lightblue'quantileScale(20);  // returns 'lightblue'quantileScale(30);  // returns 'orange'quantileScale(65);  // returns 'lightgreen'``

The (sorted) domain array is divided into n equal sized groups where n is the number of range values.

Therefore in the above example the domain array is split into 3 groups where:

• the first 5 values are mapped to 'lightblue'
• the next 5 values to 'orange' and
• the last 5 values to 'lightgreen'.

The split points of the domain can be accessed using `.quantiles()`:

``quantileScale.quantiles();  // returns [26.66..., 63]``

If the range contains 4 values `quantileScale` computes the quartiles of the data. In other words, the lowest 25% of the data is mapped to `range`, the next 25% of the data is mapped to `range` etc.

#### scaleThreshold

`scaleThreshold` maps continuous numeric input to discrete values defined by the range. n-1 domain split points are specified where n is the number of range values.

In the following example we split the domain at `0`, `50` and `100`

• u < 0 is mapped to '#ccc'
• 0 ≤ u < 50 to 'lightblue'
• 50 ≤ u < 100 to 'orange'
• u ≥ 100 to '#ccc'

where u is the input value.

``let thresholdScale = d3.scaleThreshold()  .domain([0, 50, 100])  .range(['#ccc', 'lightblue', 'orange', '#ccc']);thresholdScale(-10);  // returns '#ccc'thresholdScale(20);   // returns 'lightblue'thresholdScale(70);   // returns 'orange'thresholdScale(110);  // returns '#ccc'``

### Scales with discrete input and discrete output

#### scaleOrdinal

`scaleOrdinal` maps discrete values (specified by an array) to discrete values (also specified by an array). The domain array specifies the possible input values and the range array the output values. The range array will repeat if it's shorter than the domain array.

``let myData = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']let ordinalScale = d3.scaleOrdinal()  .domain(myData)  .range(['black', '#ccc', '#ccc']);ordinalScale('Jan');  // returns 'black';ordinalScale('Feb');  // returns '#ccc';ordinalScale('Mar');  // returns '#ccc';ordinalScale('Apr');  // returns 'black';``

By default if a value that's not in the domain is used as input, the scale will implicitly add the value to the domain:

``ordinalScale('Monday');  // returns 'black';``

If this isn't the desired behvaiour you can specify an output value for unknown values using `.unknown()`:

``ordinalScale.unknown('Not a month');ordinalScale('Tuesday'); // returns 'Not a month'``

D3 can also provide preset colour schemes (from ColorBrewer):

``let ordinalScale = d3.scaleOrdinal()  .domain(myData)  .range(d3.schemePaired);``

#### scaleBand

When creating bar charts `scaleBand` helps to determine the geometry of the bars, taking into account padding between each bar. The domain is specified as an array of values (one value for each band) and the range as the minimum and maximum extents of the bands (e.g. the total width of the bar chart).

In effect `scaleBand` will split the range into n bands (where n is the number of values in the domain array) and compute the positions and widths of the bands taking into account any specified padding.

``let bandScale = d3.scaleBand()  .domain(['Mon', 'Tue', 'Wed', 'Thu', 'Fri'])  .range([0, 200]);bandScale('Mon'); // returns 0bandScale('Tue'); // returns 40bandScale('Fri'); // returns 160``

The width of each band can be accessed using `.bandwidth()`:

``bandScale.bandwidth();  // returns 40``

Two types of padding may be configured:

• `paddingInner` which specifies (as a percentage of the band width) the amount of padding between each band
• `paddingOuter` which specifies (as a percentage of the band width) the amount of padding before the first band and after the last band

``bandScale.paddingInner(0.05);bandScale.bandWidth();  // returns 38.38...bandScale('Mon');       // returns 0bandScale('Tue');       // returns 40.40...``

Putting this all together we can create this bar chart:

#### scalePoint

`scalePoint` creates scale functions that map from a discrete set of values to equally spaced points along the specified range:

``let pointScale = d3.scalePoint()  .domain(['Mon', 'Tue', 'Wed', 'Thu', 'Fri'])  .range([0, 500]);pointScale('Mon');  // returns 0pointScale('Tue');  // returns 125pointScale('Fri');  // returns 500``

The distance between the points can be accessed using `.step()`:

``pointScale.step();  // returns 125``

Outside padding can be specified as the ratio of the padding to point spacing. For example, for the outside padding to be a quarter of the point spacing use a value of 0.25:

``pointScale.padding(0.25);pointScale('Mon');  // returns 27.77...pointScale.step();  // returns 111.11...``

ColorBrewer schemes for D3

Mike Bostock on d3-scale

BOOKS & COURSES Visualising Data with JavaScript teaches you how to build charts, dashboards and data stories using Chart.js, Leaflet, D3 and React.

Find out more "One of the best D3 books I've read. The contents are very clear, it is easy to follow and the concepts are very solid."

Javier García Fernández

Learn how to make a custom data visualisation using D3.js.

Find out more Learn the fundamentals of HTML, SVG, CSS and JavaScript for building data visualisations on the web.

Find out more