Linear scales¶

detroit.scale_linear() → ScaleLinear[T]¶

detroit.scale_linear(range_vals: list[T]) → ScaleLinear[T]

detroit.scale_linear(domain: list[int | float], range_vals: list[T]) → ScaleLinear[T]

Builds a new linear scale with the specified domain and range, the default interpolator, and clamping disabled.

Parameters:

domain (list[Number]) – Array of numbers
range_vals (list[T]) – Array of values

Returns:

Scale object

Return type:

ScaleLinear[T]

Examples

>>> scale = d3.scale_linear([0, 100], ["red", "blue"])
>>> for x in range(11):
...     x = x * 10
...     print(x, scale(x))
...
...
0 rgb(255, 0, 0)
10 rgb(230, 0, 26)
20 rgb(204, 0, 51)
30 rgb(178, 0, 76)
40 rgb(153, 0, 102)
50 rgb(128, 0, 128)
60 rgb(102, 0, 153)
70 rgb(76, 0, 178)
80 rgb(51, 0, 204)
90 rgb(26, 0, 230)
100 rgb(0, 0, 255)

class detroit.scale.linear.ScaleLinear(t: ~collections.abc.Callable[[int | float], int | float] = <function identity>, u: ~collections.abc.Callable[[int | float], int | float] = <function identity>)¶

Linear scales map a continuous, quantitative input domain to a continuous output range using a linear transformation (translate and scale). If the range is also numeric, the mapping may be inverted. Linear scales are a good default choice for continuous quantitative data because they preserve proportional differences. Each range value y can be expressed as a function of the domain value x: \(y = m \cdot x + b\).

Parameters:

t (Callable[[Number], T]) – Transform function
u (Callable[[T], Number]) – Untransform function

__call__(x: int | float | datetime) → T¶

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

Parameters:: x (int | float) – Input value
Returns:: Corresponding value from the range
Return type:: T

invert(y: T) → int | float¶

Given a value from the range, returns the corresponding value from the domain. Inversion is useful for interaction, say to determine the data value corresponding to the position of the mouse.

Parameters:: y (T) – Input value
Returns:: Corresponding value from the domain
Return type:: Number

set_domain(domain)¶

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

Parameters:: domain (list[Number] | list[datetime]) – Domain
Returns:: Itself
Return type:: Transformer[T]

set_range(range_vals)¶

Sets the scale’s range to the specified array of values

Parameters:: range_vals (list[T]) – Range values
Returns:: Itself
Return type:: Transformer[T]

set_range_round(range_vals: list[T]) → Transformer¶

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:: Transformer

set_clamp(clamp: bool) → Transformer¶

Enables or disables clamping.

Parameters:: clamp (bool) – Clamp value
Returns:: Itself
Return type:: Transformer

set_interpolate(interpolate: Callable[[T, T], Callable[[float], T]]) → Transformer[T]¶

Sets the scale’s range interpolator factory.

Parameters:: interpolate (Callable[[T, T], Callable[[float], T]]) – Interpolate function
Returns:: Itself
Return type:: Transformer[T]

set_unknown(unknown: Any) → Transformer¶

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

Parameters:: unknown (Any) – Unknown value
Returns:: Itself
Return type:: Transformer

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

detroit.scale_identity(values: list[T] | None = None) → Identity[T]¶

Build a new identity scale with the specified range (and by extension, domain).

Parameters:: values (list[T] | None) – Values to set
Returns:: Scale object
Return type:: Identity

Examples

>>> scale = d3.scale_identity()
>>> scale(3)
3
>>> scale("a")
'a'

class detroit.scale.identity.Identity(domain=None)¶

Build a new identity scale with the specified range (and by extension, domain).

__call__(x: T) → T¶

Returns same value if valid type

Parameters:: x (T) – Input value
Returns:: Input value if valid type
Return type:: T

invert(x: T) → T¶

Returns same value if valid type

Parameters:: x (T) – Input value
Returns:: Input value if valid type
Return type:: T

set_domain(domain: list[T]) → Identity¶

Sets the scale’s domain

Parameters:: domain (list[T]) – Domain
Returns:: Itself
Return type:: Identity

set_range(range_vals: list[T]) → Identity¶

Sets the scale’s range

Parameters:: range_vals (list[T]) – Range values
Returns:: Itself
Return type:: Identity

set_unknown(unknown: Any) → Identity¶

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

Parameters:: unknown (Any) – Unknown value
Returns:: Itself
Return type:: Identity

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]¶

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

detroit.scale_radial() → ScaleRadial¶

detroit.scale_radial(range_vals: list[int | float]) → ScaleRadial

detroit.scale_radial(domain: list[int | float], range_vals: list[int | float]) → ScaleRadial

Builds a new radial scale with the specified domain and range.

Parameters:

domain (list[Number]) – Array of numbers
range_vals (list[Number]) – Array of values

Returns:

Scale object

Return type:

ScaleRadial

Examples

>>> scale = d3.scale_radial([100, 200], [0, 480])
>>> for x in range(11):
...     x = 100 + x * 10
...     print(x, scale(x))
...
...
100 0.0
110 151.7893276880822
120 214.66252583997982
130 262.9068276024797
140 303.5786553761644
150 339.4112549695428
160 371.806401235912
170 401.59681273635624
180 429.32505167995964
190 455.36798306424663
200 480.0

class detroit.scale.radial.ScaleRadial(t: ~collections.abc.Callable[[float], float] = <function identity>, u: ~collections.abc.Callable[[float], float] = <function identity>)¶

Radial scales are a variant of linear scales where the range is internally squared so that an input value corresponds linearly to the squared output value. These scales are useful when you want the input value to correspond to the area of a graphical mark and the mark is specified by radius, as in a radial bar chart. Radial scales do not support interpolate.

Parameters:

t (Callable[[float], float]) – Tranform function
u (Callable[[float], float]) – Untranform function

__call__(x: int | float) → int | 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:: Number

invert(y: int | float) → int | float¶

Given a value from the range, returns the corresponding value from the domain. Inversion is useful for interaction, say to determine the data value corresponding to the position of the mouse.

Parameters:: y (Number) – Input value
Returns:: Corresponding value from the domain
Return type:: Number

set_range(range_vals: list[int | float]) → ScaleRadial¶

Sets the scale’s range to the specified array of values

Parameters:: range_vals (list[Number]) – Range values
Returns:: Itself
Return type:: ScaleRadial

set_range_round(range_vals: list[int | float]) → ScaleRadial¶

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

Parameters:: range_vals (list[Number]) – Range values
Returns:: Itself
Return type:: ScaleRadial

set_round(round_val: bool) → ScaleRadial¶

Enables or disables rounding accordingly

Parameters:: round_val (bool) – Round value
Returns:: Itself
Return type:: ScaleRadial

detroit.tick_format(start: T, stop: T, count: int, specifier: str | None = None) → Callable[[T], 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, as determined by d3.tickStep.

Parameters:

start (T) – Start value
stop (T) – Stop value
count (int) – Count value
specifier (str | None) – Specifier allows a custom format where the precision of the format is automatically set by the scale as appropriate for the tick interval.