Diverging scales

detroit.scale_diverging() → DivergingLinear

detroit.scale_diverging(interpolator: Callable) → DivergingLinear

detroit.scale_diverging(domain: list[int | float], interpolator: Callable) → DivergingLinear

Builds a new diverging scale with the specified domain and interpolator function or array.

Parameters:

• domain (list[Number]) – Array of numbers

• interpolator (Callable) – Interpolator function

Returns:

Diverging object

Return type:

DivergingLinear

Examples

>>> scale = d3.scale_diverging([-1, 0, 1], d3.interpolate_rdbu)
>>> steps = 8
>>> for x in range(steps + 1):
...     x = -1 + 2 * x / steps
...     print(x, scale(x))
...
...
-1.0 rgb(103, 0, 31)
-0.75 rgb(184, 45, 53)
-0.5 rgb(228, 130, 104)
-0.25 rgb(250, 204, 180)
0.0 rgb(242, 239, 238)
0.25 rgb(191, 220, 235)
0.5 rgb(107, 172, 208)
0.75 rgb(42, 113, 174)
1.0 rgb(5, 48, 97)
>>> d3.interpolate_rdbu(0)
'rgb(103, 0, 31)'
>>> d3.interpolate_rdbu(1)
'rgb(5, 48, 97)'

detroit.scale_diverging_log() → DivergingLog

detroit.scale_diverging_log(interpolator: Callable) → DivergingLog

detroit.scale_diverging_log(domain: list[int | float], interpolator: Callable) → DivergingLog

Builds a new diverging scale with a logarithmic transform, analogous to a log scale.

Parameters:

• domain (list[Number]) – Array of numbers

• interpolator (Callable) – Interpolator function

Returns:

Diverging object

Return type:

DivergingLog

Examples

>>> scale = d3.scale_diverging_log([1, 10, 100], d3.interpolate_rdbu)
>>> steps = 10
>>> for x in range(steps + 1):
...     x = 2 * x / steps
...     x = 10 ** x
...     print(x, scale(x))
...
...
1.0 rgb(103, 0, 31)
1.5848931924611136 rgb(172, 32, 47)
2.51188643150958 rgb(213, 96, 80)
3.9810717055349722 rgb(240, 162, 133)
6.309573444801933 rgb(250, 215, 196)
10.0 rgb(242, 239, 238)
15.848931924611133 rgb(205, 227, 238)
25.118864315095795 rgb(143, 194, 220)
39.810717055349734 rgb(74, 148, 196)
63.09573444801933 rgb(34, 101, 163)
100.0 rgb(5, 48, 97)
>>> d3.interpolate_rdbu(0)
'rgb(103, 0, 31)'
>>> d3.interpolate_rdbu(1)
'rgb(5, 48, 97)'

detroit.scale_diverging_symlog() → DivergingSymlog

detroit.scale_diverging_symlog(interpolator: Callable) → DivergingSymlog

detroit.scale_diverging_symlog(domain: list[int | float], interpolator: Callable) → DivergingSymlog

Builds a new diverging scale with a symmetric logarithmic transform, analogous to a symlog scale.

Parameters:

• domain (list[Number]) – Array of numbers

• interpolator (Callable) – Interpolator function

Returns:

Diverging object

Return type:

DivergingSymlog

Examples

>>> scale = d3.scale_diverging_symlog([1, 10, 100], d3.interpolate_rdbu)
>>> scale = scale.set_constant(2)
>>> steps = 10
>>> for x in range(steps + 1):
...     x = 2 * x / steps
...     x = 10 ** x
...     print(x, scale(x))
...
...
1.0 rgb(44, 0, 19)
1.5848931924611136 rgb(79, 0, 27)
2.51188643150958 rgb(129, 9, 35)
3.9810717055349722 rgb(181, 41, 51)
6.309573444801933 rgb(218, 106, 87)
10.0 rgb(244, 176, 147)
15.848931924611133 rgb(250, 228, 216)
25.118864315095795 rgb(228, 237, 242)
39.810717055349734 rgb(180, 214, 231)
63.09573444801933 rgb(111, 174, 210)
100.0 rgb(53, 126, 184)
>>> d3.interpolate_rdbu(0)
'rgb(103, 0, 31)'
>>> d3.interpolate_rdbu(1)
'rgb(5, 48, 97)'

detroit.scale_diverging_pow() → DivergingPow

detroit.scale_diverging_pow(interpolator: Callable) → DivergingPow

detroit.scale_diverging_pow(domain: list[int | float], interpolator: Callable) → DivergingPow

Builds a new diverging scale with an exponential transform, analogous to a power scale.

Parameters:

• domain (list[Number]) – Array of numbers

• interpolator (Callable) – Interpolator function

Returns:

Diverging object

Return type:

DivergingPow

Examples

>>> from math import sqrt
>>> scale = d3.scale_diverging_pow([0, 1, 10], d3.interpolate_rdbu)
>>> scale = scale.set_exponent(2)
>>> steps = 10
>>> for x in range(steps + 1):
...     x = sqrt(10) * x / steps
...     print(x, scale(x))
...
...
0.0 rgb(103, 0, 31)
0.31622776601683794 rgb(140, 13, 37)
0.6324555320336759 rgb(213, 96, 80)
0.9486832980505138 rgb(249, 232, 221)
1.2649110640673518 rgb(233, 239, 242)
1.5811388300841898 rgb(213, 231, 240)
1.8973665961010275 rgb(180, 214, 232)
2.213594362117866 rgb(131, 187, 217)
2.5298221281347035 rgb(74, 148, 196)
2.8460498941515415 rgb(36, 103, 166)
3.1622776601683795 rgb(5, 48, 97)
>>> d3.interpolate_rdbu(0)
'rgb(103, 0, 31)'
>>> d3.interpolate_rdbu(1)
'rgb(5, 48, 97)'

detroit.scale_diverging_sqrt() → DivergingPow

detroit.scale_diverging_sqrt(interpolator: Callable) → DivergingPow

detroit.scale_diverging_sqrt(domain: list[int | float], interpolator: Callable) → DivergingPow

Builds a new diverging scale with a square-root transform, analogous to a sqrt scale.

Parameters:

• domain (list[Number]) – Array of numbers

• interpolator (Callable) – Interpolator function

Returns:

Diverging object

Return type:

DivergingPow

Examples

>>> scale = d3.scale_diverging_sqrt([0, 1, 10], d3.interpolate_rdbu)
>>> steps = 10
>>> for x in range(steps + 1):
...     x = 100 * x / steps
...     print(x, scale(x))
...
...
0.0 rgb(103, 0, 31)
10.0 rgb(194, 221, 235)
20.0 rgb(148, 197, 222)
30.0 rgb(108, 172, 209)
40.0 rgb(77, 150, 197)
50.0 rgb(56, 130, 186)
60.0 rgb(42, 113, 174)
70.0 rgb(31, 96, 159)
80.0 rgb(22, 79, 139)
90.0 rgb(13, 63, 118)
100.0 rgb(5, 48, 97)
>>> d3.interpolate_rdbu(0)
'rgb(103, 0, 31)'
>>> d3.interpolate_rdbu(1)
'rgb(5, 48, 97)'

class detroit.scale.diverging.Diverging(t: Callable[[float], float])

Diverging scales are similar to linear scales in that they map a continuous, numeric input domain to a continuous output range. Unlike linear scales, the input domain and output range of a diverging scale always have exactly three elements, and the output range is typically specified as an interpolator rather than an array of values. Diverging scales are typically used for a color encoding; see also d3-scale-chromatic. These scales do not expose invert and interpolate methods. There are also log, pow, and symlog variants of diverging scales.

Parameters:

t (Callable[[float], float]) – Transform function

__call__(x: int | float) → float

Given a value from the domain, returns the corresponding value from the range.

Parameters:

x (Number) – Input value

Returns:

Corresponding value from the range

Return type:

T

set_domain(domain: list[int | float]) → Diverging

Sets the scale’s domain to the specified array of numbers

Parameters:

domain (list[Number]) – Domain

Returns:

Itself

Return type:

Diverging

set_range(range_vals: list[T]) → Diverging

The given two-element array is converted to an interpolator function using interpolate

Parameters:

range_vals (list[T]) – Two values

Returns:

Itself

Return type:

Diverging

set_range_round(range_vals: list[T]) → Diverging

Sets the scale’s range to the specified array of values and sets scale’s interpolator to interpolate_round.

Parameters:

range_vals (list[T]) – Range values

Returns:

Itself

Return type:

Diverging

set_interpolator(interpolator: Callable) → Diverging

Sets the scale’s interpolator to the specified function.

Parameters:

interpolator (Callable) – Interpolator function

Returns:

Itself

Return type:

Diverging

set_clamp(clamp: bool) → Diverging

Enables or disables clamping accordingly.

Parameters:

clamp (bool) – Clamp value

Returns:

Itself

Return type:

Diverging

set_unknown(unknown: Any) → Diverging

Sets the output value of the scale for undefined or NaN input values.

Parameters:

unknown (Any) – Unknown value

Returns:

Itself

Return type:

Diverging

class detroit.scale.diverging.DivergingLinear

ticks(count: int | None = None) → list[int | float]

Returns approximately count representative values from the scale’s domain.

Parameters:

count (int | None) – Count. If specified, the scale may return more or fewer values depending on the domain

Returns:

Tick values are uniformly spaced, have human-readable values (such as multiples of powers of 10), and are guaranteed to be within the extent of the domain. Ticks are often used to display reference lines, or tick marks, in conjunction with the visualized data.

Return type:

list[Number]

tick_format(count: int | None = None, specifier: str | None = None) → Callable[[int | float], str]

Returns a number format function suitable for displaying a tick value, automatically computing the appropriate precision based on the fixed interval between tick values. The specified count should have the same value as the count that is used to generate the tick values.

Parameters:

• count (int | None) – Count. It should have the same value as the count that is used to generate the tick values.

• specifier (str | None) – Specifier

Returns:

Tick format function

Return type:

Callable[[Number], str]

nice(count: int | None = None) → LinearBase

Extends the domain so that it starts and ends on nice round values.

Parameters:

count (int | None) – Count argument allows greater control over the step size used to extend the bounds, guaranteeing that the returned ticks will exactly cover the domain

Returns:

Itself

Return type:

LinearBase

class detroit.scale.diverging.DivergingLog

ticks(count: int | None = None) → LogBase

Like ScaleLinear.ticks, but customized for a log scale.

Parameters:

count (int | None) – Count. If specified, the scale may return more or fewer values depending on the domain

Returns:

Itself

Return type:

LogBase

tick_format(count: int | None = None, specifier: str | None = None) → LogBase

Like ScaleLinear.tick_format, but customized for a log scale. The specified count typically has the same value as the count that is used to generate the tick values.

Parameters:

• count (int | None) – Count. It should have the same value as the count that is used to generate the tick values.

• specifier (str | None) – Specifier

Returns:

Itself

Return type:

LogBase

nice() → LogBase

Like ScaleLinear.nice, except extends the domain to integer powers of base.

Returns:

Itself

Return type:

LogBase

class detroit.scale.diverging.DivergingSymlog(c: int | float = 1)

set_constant(c: int | float) → DivergingSymlog

Sets the symlog constant to the specified number and returns this scale.

Parameters:

c (Number) – Constant value

Returns:

Itself

Return type:

DivergingSymlog

class detroit.scale.diverging.DivergingPow(t: Callable = <function identity>)

set_exponent(exponent: int | float) → DivergingPow

Sets the scale’s exponent value.

Parameters:

exponent (Number) – Exponent value

Returns:

Itself

Return type:

DivergingPow

ticks(count: int | None = None) → list[int | float]

Returns approximately count representative values from the scale’s domain.

Parameters:

count (int | None) – Count. If specified, the scale may return more or fewer values depending on the domain

Returns:

Tick values are uniformly spaced, have human-readable values (such as multiples of powers of 10), and are guaranteed to be within the extent of the domain. Ticks are often used to display reference lines, or tick marks, in conjunction with the visualized data.

Return type:

list[Number]

tick_format(count: int | None = None, specifier: str | None = None) → Callable[[int | float], str]

Returns a number format function suitable for displaying a tick value, automatically computing the appropriate precision based on the fixed interval between tick values. The specified count should have the same value as the count that is used to generate the tick values.

Parameters:

• count (int | None) – Count. It should have the same value as the count that is used to generate the tick values.

• specifier (str | None) – Specifier

Returns:

Tick format function

Return type:

Callable[[Number], str]

nice(count: int | None = None) → LinearBase

Extends the domain so that it starts and ends on nice round values.

Parameters:

count (int | None) – Count argument allows greater control over the step size used to extend the bounds, guaranteeing that the returned ticks will exactly cover the domain

Returns:

Itself

Return type:

LinearBase