Point scales

Point scales are a variant of band scales with the bandwidth fixed to zero. Point scales are typically used for scatterplots with an ordinal or categorical dimension.

scalePoint(domain, range)

Examples · Source · Constructs a new point scale with the specified domain and range, no padding, no rounding and center alignment. If domain is not specified, it defaults to the empty domain. If range is not specified, it defaults to the unit range [0, 1].

point(value)

Examples · Source · Given a value in the input domain, returns the corresponding point derived from the output range.

const x = d3.scalePoint(["a", "b", "c"], [0, 960]);
x("a"); // 0
x("b"); // 480
x("c"); // 960
x("d"); // undefined

If the given value is not in the scale’s domain, returns undefined.

point.domain(domain)

Domain:

Examples · Source · If domain is specified, sets the domain to the specified array of values.

const x = d3.scalePoint([0, 960]).domain(["a", "b", "c", "d", "e", "f"]);

The first element in domain will be mapped to the first point, the second domain value to the second point, and so on. Domain values are stored internally in an InternMap from primitive value to index; the resulting index is then used to determine the point. Thus, a point scale’s values must be coercible to a primitive value, and the primitive domain value uniquely identifies the corresponding point. If domain is not specified, this method returns the current domain.

point.range(range)

Examples · Source · If range is specified, sets the scale’s range to the specified two-element array of numbers and returns this scale.

const x = d3.scalePoint().range([0, 960]);

If the elements in the given array are not numbers, they will be coerced to numbers. If range is not specified, returns the scale’s current range, which defaults to [0, 1].

point.rangeRound(range)

Examples · Source · Sets the scale’s range to the specified two-element array of numbers while also enabling rounding; returns this scale.

const x = d3.scalePoint().rangeRound([0, 960]);

This is a convenience method equivalent to:

point.range(range).round(true)

Rounding is sometimes useful for avoiding antialiasing artifacts, though also consider the shape-rendering “crispEdges” styles.

point.round(round)

Round:

Examples · Source · If round is specified, enables or disables rounding accordingly.

const x = d3.scalePoint(["a", "b", "c"], [0, 960]).round(false);

If round is not specified, returns whether rounding is enabled.

x.round() // false

If rounding is enabled, the position of each point will be integers. Rounding is sometimes useful for avoiding antialiasing artifacts, though also consider the shape-rendering “crispEdges” styles. Note that if the width of the domain is not a multiple of the cardinality of the range, there may be leftover unused space, even without padding! Use point.align to specify how the leftover space is distributed.

point.padding(padding)

Padding:0.10

Examples · Source · If padding is specified, sets the outer padding to the specified number which is typically in the range [0, 1].

const x = d3.scalePoint(["a", "b", "c"], [0, 960]).padding(0.1);

If padding is not specified, returns the current outer padding which defaults to 0.

x.padding() // 0.1

The outer padding specifies the amount of blank space, in terms of multiples of the step, to reserve before the first point and after the last point. Equivalent to band.paddingOuter.

point.align(align)

Align:0.50

Examples · Source · If align is specified, sets the alignment to the specified value which must be in the range [0, 1].

const x = d3.scalePoint(["a", "b", "c"], [0, 960]).align(0.5);

If align is not specified, returns the current alignment which defaults to 0.5.

x.align() // 0.5

The alignment specifies how any leftover unused space in the range is distributed. A value of 0.5 indicates that the leftover space should be equally distributed before the first point and after the last point; i.e., the points should be centered within the range. A value of 0 or 1 may be used to shift the points to one side, say to position them adjacent to an axis.

point.bandwidth()

Examples · Source · Returns zero.

point.step()

Examples · Source · Returns the distance between adjacent points.

point.copy()

Examples · Source · Returns an exact copy of this scale. Changes to this scale will not affect the returned scale, and vice versa.