Visualize.Scale (Visualize v0.2.35)

Copy Markdown View Source

Scale functions that map from a data domain to a visual range.

Scales are the fundamental building blocks for encoding data visually. They map abstract data values (the domain) to visual variables (the range) such as position, length, or color.

Scale Types

Continuous

  • linear/0 - Continuous linear mapping
  • log/0 - Logarithmic scale
  • power/0 - Power/polynomial scale
  • sqrt/0 - Square root scale (power with exponent 0.5)
  • symlog/0 - Symmetric log (handles zero and negatives)
  • time/0 - DateTime scale
  • radial/0 - Angle scale for cyclic quantities (bearing, hour of day)

Discrete

  • ordinal/0 - Discrete categorical mapping
  • band/0 - Discrete with bandwidth (for bar charts)
  • quantize/0 - Continuous to discrete (uniform buckets)
  • quantile/0 - Continuous to discrete (equal-count buckets)
  • threshold/0 - Continuous to discrete (explicit breakpoints)

Colour

The protocol

Every scale module implements Visualize.Scale.Behaviour, so each operation below dispatches to scale.__struct__ and is total over every scale this module constructs. Operations that have no meaning for a scale kind are identity (nice/1, padding/2, clamp/2), nil (invert/2), or 0 (bandwidth/1); the discretising scales return their thresholds from ticks/2.

Examples

# Linear scale
scale = Visualize.Scale.linear()
  |> Visualize.Scale.domain([0, 100])
  |> Visualize.Scale.range([0, 500])

Visualize.Scale.apply(scale, 50)  # => 250.0

# Band scale for bar charts
scale = Visualize.Scale.band()
  |> Visualize.Scale.domain(["A", "B", "C"])
  |> Visualize.Scale.range([0, 300])
  |> Visualize.Scale.padding(0.1)

Visualize.Scale.apply(scale, "B")  # => 105.0
Visualize.Scale.bandwidth(scale)   # => 90.0

Summary

Functions

apply(scale, value)

Applies the scale to transform a domain value to a range value.

band()

Creates a band scale

bandwidth(scale)

Returns the bandwidth for band scales; 0 for every other scale.

clamp(scale, clamp?)

Clamps output to the range bounds.

diverging(interpolator)

Creates a diverging color scale

domain(scale, domain_values)

Sets the input domain for the scale.

invert(scale, value)

Inverts the scale to get a domain value from a range value.

linear()

Creates a linear scale

log(base \\ 10)

Creates a logarithmic scale

nice(scale)

Extends the domain to nice round values.

ordinal()

Creates an ordinal scale

padding(scale, padding)

Sets padding for band scales; identity for every other scale.

power()

Creates a power scale

quantile()

Creates a quantile scale (continuous to discrete, equal-count buckets)

quantize()

Creates a quantize scale (continuous to discrete, uniform buckets)

radial()

Creates a radial (angle) scale: domain to [0, 2π] by default

range(scale, range_values)

Sets the output range for the scale.

sequential(interpolator)

Creates a sequential color scale

sqrt()

Creates a square root scale (power with exponent 0.5)

symlog()

Creates a symmetric log scale (handles zero and negatives)

threshold()

Creates a threshold scale (continuous to discrete, explicit breakpoints)

ticks(scale, count \\ 10)

Returns representative domain values: nice round ticks for continuous scales, the domain for discrete scales, the thresholds for discretising scales. count is a hint.

time()

Creates a time scale

zone(scale, zone)

Sets a time scale's display zone, an IANA name or nil for UTC (spec/03 §7.4); see Visualize.Scale.Time.zone/2. Not part of the protocol: a zone means something only to a time scale, so any other scale is a FunctionClauseError.

Functions

apply(scale, value)

@spec apply(struct(), any()) :: any()

Applies the scale to transform a domain value to a range value.

band()

Creates a band scale

bandwidth(scale)

@spec bandwidth(struct()) :: number()

Returns the bandwidth for band scales; 0 for every other scale.

clamp(scale, clamp?)

@spec clamp(struct(), boolean()) :: struct()

Clamps output to the range bounds.

diverging(interpolator)

Creates a diverging color scale

domain(scale, domain_values)

@spec domain(struct(), [any()]) :: struct()

Sets the input domain for the scale.

For continuous scales, domain is [min, max]. For ordinal/band scales, domain is a list of categories.

invert(scale, value)

@spec invert(struct(), number()) :: any()

Inverts the scale to get a domain value from a range value.

Continuous scales only; every other scale returns nil.

linear()

Creates a linear scale

log(base \\ 10)

Creates a logarithmic scale

nice(scale)

@spec nice(struct()) :: struct()

Extends the domain to nice round values.

ordinal()

Creates an ordinal scale

padding(scale, padding)

@spec padding(struct(), number()) :: struct()

Sets padding for band scales; identity for every other scale.

power()

Creates a power scale

quantile()

Creates a quantile scale (continuous to discrete, equal-count buckets)

quantize()

Creates a quantize scale (continuous to discrete, uniform buckets)

radial()

Creates a radial (angle) scale: domain to [0, 2π] by default

range(scale, range_values)

@spec range(struct(), [any()]) :: struct()

Sets the output range for the scale.

For position scales, typically [0, width] or [height, 0]. For color scales, a list of colors.

sequential(interpolator)

Creates a sequential color scale

sqrt()

Creates a square root scale (power with exponent 0.5)

symlog()

Creates a symmetric log scale (handles zero and negatives)

threshold()

Creates a threshold scale (continuous to discrete, explicit breakpoints)

ticks(scale, count \\ 10)

@spec ticks(struct(), integer()) :: [any()]

Returns representative domain values: nice round ticks for continuous scales, the domain for discrete scales, the thresholds for discretising scales. count is a hint.

time()

Creates a time scale

zone(scale, zone)

@spec zone(Visualize.Scale.Time.t(), Calendar.time_zone() | nil) ::
  Visualize.Scale.Time.t()

Sets a time scale's display zone, an IANA name or nil for UTC (spec/03 §7.4); see Visualize.Scale.Time.zone/2. Not part of the protocol: a zone means something only to a time scale, so any other scale is a FunctionClauseError.