Giggly.Scale.Continuous (giggly v0.1.0)

Copy Markdown View Source

A continuous scale. Giggly.Plot.scale_x_continuous/2, Giggly.Plot.scale_x_date/2, Giggly.Plot.scale_x_datetime/2 and Giggly.Plot.scale_x_time/2 record one with the options they are given and no range, and Giggly.panel_scales/2 returns an axis's trained. Its fields:

  • range: the range of the finite numbers it has seen, or :none before it has seen any.
  • transform: the transformation its values are put through before it sees them, so its range is in transformed space: :identity for numbers; :date for dates, which it sees as days since 1970-01-01; {:datetime, zone, database} for date-times, which it sees as seconds since 1970-01-01 00:00 UTC, a naive one as though its clock were UTC's, zone being the time zone its breaks are laid and written in, :default until its first column gives it one, or :naive for naive date-times, and database the Calendar.TimeZoneDatabase that reads it; :time for times of day, which it sees as seconds since midnight; or any other transformation of numbers Scales.Transform names, :log10, :reverse (each value negated), a composition or one of a user's own among them, as a plot's scale names one, on an axis or on any other aesthetic.
  • palette: what turns a value's place in its limits into its aesthetic's value: :identity for a position, left for the coordinate system to place; {:rescale, {low, high}} for an aesthetic such as alpha or line width, each place, from 0 to 1, rescaled onto low to high; and {:gradient, colors} for colour and fill, the colour that far along a gradient through colors, spaced evenly, blended in Lab*, or {:gradient, colors, values}, spaced at values; and for size, {:area, {low, high}}, each place's square root rescaled onto low to high, so a value's area grows with it, or {:abs_area, max}, the square root of the place's size rescaled onto 0 to max; or any other of Scales.Palette's, such as {:brewer, %{palette: "Blues", direction: 1}}, a discrete one taken as a gradient through its colours.
  • rescaler: how a value's place in the limits is found: :rescale, its distance from the low end over the limits' width; {:mid, midpoint}, its distance from the midpoint, in transformed space, over twice the further end's, so the midpoint is at the middle and the further end at 0 or 1; or :max, the value over the high end, so 0 is at 0.
  • na_value: what a value the palette gives nothing for maps to, a missing one, one oob leaves missing, or for a colour one left outside the limits or infinite, while an alpha, size or line width is an infinity for an infinite value: nil for a position, alpha, line width and size, grey, "#7F7F7F", for colour and fill, or :none, no colour.
  • guide: the guide that draws it: :axis for a position, :legend for alpha, line width, size and :colorbar for colour and fill unless a scale function chooses :legend or :colorsteps, :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: {low, high}, the values it spans whatever the data, in data units, nil at an end the data decides; once transformed, the two are sorted. A value outside them is handled as oob says.
  • oob: what happens to a value outside the limits, in transformed space, before it is placed, and for a position again once the stat and position have moved it: :censor, a finite number outside made missing, so a position's row is not drawn and another aesthetic's value takes na_value; :censor_any, an infinity too; :squish, a finite number moved onto the nearer limit; :squish_any, an infinity too; :squish_infinite, an infinity alone moved onto its limit; :keep, every value kept, a position drawn past the panel's edge and a colour taking na_value, as its palette gives none there, while an opacity or a size runs on past its range; or a function handed one column's values and the limits, {low, high}, that returns a value for each, a number, :infinity, :neg_infinity, nil or :nan, R's NaN, which is missing.
  • breaks and minor_breaks: the values an axis marks, in data units; on a date axis, {:width, [week: 1]} for a break every step, one of :day, :week, :month and :year and how many of it, on a date-time axis :second, :minute and :hour too, and on a time axis :second, :minute and :hour alone; a function, handed the limits, {low, high} in data units, a date axis's rounded out to whole days, and for breaks of two arguments [n: n_breaks] too, or [] where n_breaks is the default, and for minor breaks of two arguments the breaks drawn, that returns the values, or {value, label} pairs, a pair's label the break's unless labels says otherwise; :none for none; or :default for those its transformation chooses.
  • n_breaks: how many breaks its transformation, or a breaks function of two arguments, is asked for, or :default for as many as it chooses.
  • labels: a label for each break, nil for a missing one; a function handed every break drawn, in data units, a time axis's as times of day wrapped past midnight, that returns their labels, each a string, a power (Scales.Labels.log/2) or nil; on a date, date-time or time axis, {:format, format}, each break written in format by Calendar.strftime/3, a time's wrapped past midnight; :none for none; or :default for its transformation's.
  • expand: how far an axis reaches beyond its limits, [mult: {low, high}, add: {low, high}]: at each end, that multiple of the limits' width plus that constant.

Summary

Types

A date, date-time or time axis's step between breaks: one unit and how many of it, [week: 1], a date-time's or a time's [hour: 6].

What a scale does with a value outside its limits: one of R's oob_* functions by name, or a function of one column's values and the limits that returns a value for each.

t()

A value a date, date-time or time axis places.

Types

date_step()

@type date_step() :: [
  {:second | :minute | :hour | :day | :week | :month | :year, pos_integer()}
]

A date, date-time or time axis's step between breaks: one unit and how many of it, [week: 1], a date-time's or a time's [hour: 6].

oob()

@type oob() ::
  :censor
  | :censor_any
  | :squish
  | :squish_any
  | :squish_infinite
  | :keep
  | (list(), {number(), number()} -> list())

What a scale does with a value outside its limits: one of R's oob_* functions by name, or a function of one column's values and the limits that returns a value for each.

t()

@type t() :: %Giggly.Scale.Continuous{
  breaks:
    :default
    | :none
    | [number() | time_value()]
    | {:width, date_step()}
    | ({term(), term()} -> list())
    | ({term(), term()}, keyword() -> list()),
  expand: [mult: {number(), number()}, add: {number(), number()}],
  guide: :axis | :legend | :colorbar | :colorsteps | :none | struct(),
  labels:
    :default
    | :none
    | [String.t() | nil]
    | ([number() | time_value()] -> [Scales.Labels.power_label()])
    | {:format, String.t()},
  limits: {number() | time_value() | nil, number() | time_value() | nil},
  minor_breaks:
    :default
    | :none
    | [number() | time_value()]
    | {:width, date_step()}
    | ({term(), term()} -> list())
    | ({term(), term()}, list() -> list()),
  n_breaks: :default | pos_integer(),
  na_value: nil | number() | String.t() | :none,
  name: :default | :none | String.t(),
  oob: oob(),
  palette: Scales.Palette.t(),
  range: :none | {number(), number()},
  rescaler: :rescale | {:mid, number()} | :max,
  transform: Scales.Transform.name()
}

time_value()

@type time_value() :: Date.t() | DateTime.t() | NaiveDateTime.t() | Time.t()

A value a date, date-time or time axis places.