Visualize.Scale.Behaviour behaviour (Visualize v0.2.35)

Copy Markdown View Source

The protocol every scale module implements (spec/03 §1.3).

Visualize.Scale dispatches each of these operations to the module named by the scale struct (scale.__struct__). A module that declares this behaviour and omits a callback fails to compile under --warnings-as-errors, which is what keeps the facade total: no scale reaches Visualize.Scale.apply/2 without an apply/2 of its own.

Operations that do not apply to a scale kind are still defined and behave as identity (nice/1, padding/2, clamp/2), return nil (invert/2), or return 0 (bandwidth/1). The discretising scales (Quantile, Quantize, Threshold) return their thresholds from ticks/2.

Summary

Types

scale()

Any scale struct.

Callbacks

apply(scale, term)

Maps a domain value to a range value.

bandwidth(scale)

The band width; 0 for every scale but Band.

clamp(scale, boolean)

Enables or disables clamping; identity where the scale never extrapolates.

domain(scale, term)

Sets the input domain; the argument shape is the module's own.

invert(scale, term)

Maps a range value back to the domain; nil where the scale is not invertible.

nice(scale)

Extends the domain outward to round values; identity where that has no meaning.

padding(scale, number)

Sets band padding; identity for every scale but Band.

range(scale, term)

Sets the output range; the argument shape is the module's own.

ticks(scale, integer)

Representative domain values; count is a hint, never a guarantee.

Functions

normalize(value, a, b)

The position of value between a and b as a fraction, 0.5 when a == b.

Types

scale()

@type scale() :: struct()

Any scale struct.

Callbacks

apply(scale, term)

@callback apply(scale(), term()) :: term()

Maps a domain value to a range value.

bandwidth(scale)

@callback bandwidth(scale()) :: number()

The band width; 0 for every scale but Band.

clamp(scale, boolean)

@callback clamp(scale(), boolean()) :: scale()

Enables or disables clamping; identity where the scale never extrapolates.

domain(scale, term)

@callback domain(scale(), term()) :: scale()

Sets the input domain; the argument shape is the module's own.

invert(scale, term)

@callback invert(scale(), term()) :: term() | nil

Maps a range value back to the domain; nil where the scale is not invertible.

nice(scale)

@callback nice(scale()) :: scale()

Extends the domain outward to round values; identity where that has no meaning.

padding(scale, number)

@callback padding(scale(), number()) :: scale()

Sets band padding; identity for every scale but Band.

range(scale, term)

@callback range(scale(), term()) :: scale()

Sets the output range; the argument shape is the module's own.

ticks(scale, integer)

@callback ticks(scale(), integer()) :: [term()]

Representative domain values; count is a hint, never a guarantee.

Functions

normalize(value, a, b)

@spec normalize(number(), number(), number()) :: float()

The position of value between a and b as a fraction, 0.5 when a == b.

d3-scale's normalize: a collapsed domain maps every value to the middle of the range and a collapsed range inverts to the middle of the domain, instead of dividing by zero (D-49). Every continuous scale's apply/2 and invert/2 go through it.