Giggly.Scale.Discrete (giggly v0.1.0)

Copy Markdown View Source

A discrete scale. Giggly.Plot.scale_x_discrete/2 records one with the options it is given and no levels, and Giggly.panel_scales/2 returns an axis's trained. Its fields:

  • levels: the distinct values it has seen, in level order: a factor's in its levels' order, those it lacks after them, and values with no levels of their own sorted, a missing value last, but where factor keeps them in the order they came.
  • factor: whether the first values it was trained on were a factor's, whose levels have an order of their own: true keeps its levels in the order they came, each new value after them; false sorts them again whenever values with no levels of their own come, a factor's levels first until then; :none before it has seen any.
  • continuous_range: the range of the positions it has been handed since its levels were placed, such as a bar's edges, which can widen the axis past its levels; :none before any.
  • palette: what turns a value into its aesthetic's value: :identity for a position, each value at its place counting from 1; {:sequence, {low, high}} for an aesthetic such as alpha or line width, the values spread evenly from low to high in order; and, for colour and fill, {:hue, %{hue: {low, high}, chroma: chroma, luminance: luminance, direction: direction}}, a colour for each value, their hues spaced evenly from low to high round the circle, handed out in reverse for a direction of -1; {:gray, {start, finish}}, greys from the level start to finish, 0 black and 1 white; or {:manual, colors}, the colours of a list in order, or those of a map from value to colour by value, or {:manual, colors, breaks}, the colours of a list each given to the break at its place; for size, {:area_sequence, {low, high}}, sizes from low to high whose squares, and so areas, are spread evenly; for shape, {:shape, :solid} or {:shape, :open}, six shapes by name in order, solid or open, or {:manual, shapes}, a list's or a map's, as a colour's; and for line type, :linetype, 13 line types in order, each as its dash pattern, {} for a solid line, or {:manual, line_types}, as a colour's; or any other of Scales.Palette's, such as {:brewer, %{palette: "Set1", direction: 1}}, a ColorBrewer palette's colours in order, a continuous one's taken at places spread evenly over it.
  • na_value: what a missing value, or one not among the limits, maps to: nil for alpha, line type, line width, shape and size, grey, "#7F7F7F", for colour and fill, :none, no colour, shape or line, or the shape, line type or width a plot's scale gives. A missing value takes no share of the palette; a position scale puts it at its last level, and its na_value is nil.
  • guide: the guide that draws it: :axis for a position and :legend for an aesthetic such as alpha or colour, :none for none, or a legend Giggly.Plot.guide_legend/1 makes.
  • name: its guide's title, :none for none, or :default for the title its mapping gives.
  • limits: the values it shows, in the order shown, whatever the data, or :default for its levels, those a manual palette's map has a value for where it is one. A value not among them is missing, so its mark is not drawn on an axis and takes the na_value elsewhere; nil among them places the missing value. A number names the value equal to it, so 2 names a level of 2.0.
  • breaks: the values an axis marks, in the order given, those not among its limits left out; a function handed the limits that returns them, or {value, label} pairs, a pair's label the break's unless labels says otherwise; :none for none, or :default for every one of its limits.
  • minor_breaks: the positions an axis draws a minor grid line at, its values at 1, 2, 3 and on: a list; a function handed the axis's extent, {low, high}, and for one of two arguments the breaks' positions too, that returns them; or :default or :none for none.
  • labels: the breaks' labels: a list, one for each break; a map from a value to its label, a value it does not hold keeping its own, either's nil a missing one; a function handed every break drawn, which returns their labels, each a string, a power or nil; :none for none; or :default, each value written as text.
  • expand: how far an axis reaches beyond its first and last values, [mult: {low, high}, add: {low, high}]: at each end, that multiple of the distance between them plus that constant.

Summary

Types

t()

@type t() :: %Giggly.Scale.Discrete{
  breaks: :default | :none | [term()] | (list() -> list()),
  continuous_range: :none | {number(), number()},
  expand: [mult: {number(), number()}, add: {number(), number()}],
  factor: :none | boolean(),
  guide: :axis | :legend | :none | struct(),
  labels:
    :default
    | :none
    | [String.t() | nil]
    | %{required(term()) => String.t() | nil}
    | (list() -> list()),
  levels: list(),
  limits: :default | [term()],
  minor_breaks:
    :default
    | :none
    | [number()]
    | ({number(), number()} -> [number()])
    | ({number(), number()}, [number()] -> [number()]),
  na_value: nil | number() | String.t() | atom() | tuple(),
  name: :default | :none | String.t(),
  palette:
    Scales.Palette.t()
    | {:sequence, {number(), number()}}
    | {:manual, %{required(term()) => String.t() | atom() | tuple()}}
    | {:manual, [String.t() | atom() | tuple()], [term()]}
    | {:area_sequence, {number(), number()}}
}