Giggly.Scale.Binned (giggly v0.1.0)

Copy Markdown View Source

A binned scale: a colour or fill scale that cuts its continuous values into bins at its breaks and gives every value in a bin the same colour. Its fields:

  • range: the range of the finite numbers it has seen, or :none before it has seen any.
  • palette: what gives each bin its colour: {:binned, palette}, a discrete palette of Scales.Palette's, such as {:binned, {:brewer, %{palette: "Blues", direction: -1}}}, its colours for as many levels as there are bins, the first for the lowest; or a continuous palette, such as {:gradient, colors}, or any other of Scales.Palette's, the colour at the middle of each bin's place in the limits.
  • rescaler: how a value's place in the limits is found: :rescale, its distance from the low end over the limits' width; or {:mid, midpoint}, its distance from the midpoint over twice the further end's, so the midpoint is at the middle and the further end at 0 or 1.
  • na_value: what a missing value, one not a finite number, or one oob leaves outside the limits maps to: grey, "#7F7F7F", or :none, no colour.
  • guide: the guide that draws it: :colorsteps, a bar of one block of colour for each bin; :legend, a key for each break; or :none for none.
  • name: its guide's title, :none for none, or :default for the title its mapping gives.
  • limits: {low, high}, the values it spans whatever the data, nil at an end the data decides. A value outside them is handled as oob says. With neither end given and its breaks the default, the limits are the data's range widened so the end bins are as wide as their neighbours: from the lowest break inside the range less the step to the next, to the highest plus the step from the one before; with one break inside, so it is the middle, from it less its distance to the further end of the range to it plus the same; with none inside, not widened, its ends its breaks, and a range of one value widened by 0.05 either side first.
  • oob: what happens to a value outside the limits before it is binned, as a continuous scale's oob says: :squish, a finite number moved onto the nearer limit, so it takes the colour of the bin at that end; any other of Giggly.Scale.Continuous's; a value still outside, or missing, maps to na_value.
  • breaks: the values its bins are cut at, beside the limits: a list, those inside the limits kept, in the order given; a function handed the limits, {low, high}, and for one of two arguments [n: n_breaks] too, that returns them, or {value, label} pairs, a pair's label the break's unless labels says otherwise, kept as a list's are, the limits not widened; :none for one bin; or :default for about n_breaks, chosen as nice_breaks says on the limits, those at either end of the data's range left out where the limits are widened.
  • n_breaks: how many default breaks are wanted, or a breaks function of two arguments is asked for, 5 unless given; nice breaks may number a few more or fewer.
  • nice_breaks: true for default breaks chosen to be round numbers, as a continuous scale's are, n_breaks of them wanted, 2 or more; false for n_breaks breaks spaced evenly between the ends of the limits, 1 or more.
  • labels: a label for each break: a list, one for each of its given breaks, or of its default ones, a break left out taking its label with it, nil for a missing one; a function handed every break kept, that returns their labels, each a string, a power (Scales.Labels.log/2) or nil; :none for none; or :default, each written as a continuous scale writes a number.
  • right: where a value on a break falls: true in the bin below it, false in the bin above; the lowest value is in the lowest bin, and the highest in the highest.
  • show_limits: true to have colour steps label the ends of the bar with the limits, written by its labels as its breaks are, unless a break is already there; false for the breaks alone. A legend shows the breaks alone either way.

Summary

Types

t()

@type t() :: %Giggly.Scale.Binned{
  breaks:
    :default
    | :none
    | [number()]
    | ({float(), float()} -> list())
    | ({float(), float()}, keyword() -> list()),
  guide: :colorsteps | :legend | :none,
  labels:
    :default
    | :none
    | [String.t() | nil]
    | ([float()] -> [Scales.Labels.power_label()]),
  limits: {number() | nil, number() | nil},
  n_breaks: pos_integer(),
  na_value: String.t() | :none,
  name: :default | :none | String.t(),
  nice_breaks: boolean(),
  oob: Giggly.Scale.Continuous.oob(),
  palette: {:binned, Scales.Palette.t()} | Scales.Palette.t(),
  range: :none | {number(), number()},
  rescaler: :rescale | {:mid, number()},
  right: boolean(),
  show_limits: boolean()
}