Module Vz.Scale'


Scales map data values to visual values.

A scale represents a function from a given domain to a given range. It keeps additional metadata about the map which can be used for example to represent them as axes in visual depictions.

type 'a set = [
  1. | `Discrete of 'a list
  2. | `Continuous of 'a list

The type for representing sets of values.


type ('a, 'b) t

The type for scales mapping values from a domain of type 'a to a range of 'b.

val dom : ('a, 'b) t -> 'a set

dom s is the (possibly niced) domain of s.

val dom_unniced : ('a, 'b) t -> 'a set

dom_unniced s is the unniced domain of s. This is the same as dom if niced is false.

val range : ('a, 'b) t -> 'b set

range s is the range of s.

val clamp : ('a, 'b) t -> bool

clamp s is true if the map of s first clamps values to the scale domain before mapping them (ensures the map returns only values in the range).

val niced : ('a, 'b) t -> bool

niced s is true if the domain of s was niced.

Maps and invert map

val map : ('a, 'b) t -> 'a -> 'b

map s is the mapping function of s.

Warning. On ordinal scales the mapping function raises Invalid_argument on undefined arguments. Use partial_map to apply to unknown values.

val partial_map : ('a, 'b) t -> 'a -> 'b option

partial_map s is like map s except on ordinal scales it returns None on undefined argument.

val fold_ticks : ?bounds:bool -> int -> ('a -> int -> float -> 'a) -> 'a -> (float, 'b) t -> 'a

fold_ticks bounds n f acc scale folds f over approximatevely n uniformly spaced values taken in scale's domain using Nice.step to determine the step value. See Nice.step_fold. If bounds is true ensures that the bounds of the domain are folded over.

Continuous scales

val linear : ?clamp:bool -> ?nice:bool -> (float * float) -> (float * float) -> (float, float) t

linear ?clamp ?nice (x0, x1) (y0, y1) is the map that linearly transforms x0 on y0 and x1 on y1. If the map is undefined (x0 = x1 and y0 <> y1) the map always returns y0.

  • If clamp is false (default), the scale maps values outside the domain (x0, x1) according to the specified linear transformation. If true values outside the domain are clamped to the nearest domain bounds.
  • If nice if true the given domain (x0, x1) is first expanded to fall on round numbers (x0', x1') which are used to define the linear map. The precision of these round numbers is one order of magnitude less than the extent of the domain that is: 10(round (log10 abs_float (x1 - x0)) - 1). Defaults to false.

Ordinal scales

Ordinal scales maps a discrete orderable domain to a range.

val ordinal : ?cmp:('a -> 'a -> int) -> 'a list -> 'b list -> ('a, 'b) t

ordinal cmp dom range maps the value domi to the value rangei mod max with max = List.length range - 1. cmp is the order on the domain, defaults to

Generating discrete ranges

val range_pts : ?rpad:float -> min:float -> max:float -> int -> float list
val range_bands : ?rpad:float -> ?pad:float -> min:float -> max:float -> int -> float list