Fude.Channel (Fude v0.4.0)

Copy Markdown View Source

What a channel of a chart shows: the field of the data it reads, and how. x, y, color and size are channels.

A channel is given in a short form or in full:

Fude.bar(sales, x: :region, y: :revenue)
Fude.bar(sales, x: :region, y: {:sum, :revenue})
Fude.line(visits, x: {:month, :day}, y: {:count, :id})
Fude.histogram(orders, x: {:bin, :total})
Fude.bar(sales, x: :region, y: [field: :revenue, aggregate: :sum, format: :compact])
Fude.rule(y: 1000)
  • an atom or a string is a field;
  • {aggregate, field} aggregates the field: :count, :sum, :mean, :median, :min, :max or :distinct;
  • {unit, field} takes a unit of a time: :year, :quarter, :month, :week, :day, :hour or :minute;
  • {:bin, field} puts the numbers of a field in bins;
  • a number is a constant, as the height of a rule;
  • a keyword list is the full form, with the keys below.

Keys

  • :field - the field of the data.
  • :type - :number, :time, :category or :ordinal; learned from the data when not given.
  • :aggregate - see above.
  • :time - a unit of a time, see above.
  • :bin - true, or a keyword list with :count (about how many bins) or :step (the width of a bin).
  • :sort - the order of a field's categories: :ascending, :descending, :x, :y, :"-x" or :"-y" (by another channel, the minus for descending), or a list of the categories in order.
  • :format - how the browser writes the values: :number, :integer, :percent, :compact, {:currency, "EUR"}, :bytes, or a unit of a time for times.
  • :digits - how many decimals the values are written with, from 0 to 20, for :number, :compact, :percent and currencies: [field: :revenue, format: :number, digits: 0] writes 6,893,914. Not given, :number keeps a value's decimals up to 2, :compact and :percent write up to 1, and a currency 2 under 1,000 and none from there. An axis's ticks take the decimals their step needs.
  • :scheme - the colors of a color channel, by name: sequential :blue (the default), :green, :orange, :purple, :gray, :viridis; diverging :red_blue, :red_green (around :mid); categorical :categorical (the default) and :okabe_ito. Or a list of colors (["#0b6e4f", "#f2c14e", "#d1495b"]): a ramp for numbers, a color for each category, in order.
  • :mid - the value at the middle of a diverging scheme: 0 when not given.
  • :title - the title of the axis or the legend; the field's name when not given, false for none.
  • :scale - a keyword list: :type (:linear, :log, :sqrt), :domain ([min, max], or the categories), :zero (whether a number scale starts at zero), :nice.
  • :stack - :zero (the default of bars and areas with a color), :normalize (to 100%), :center or false.
  • :value - a constant instead of a field.
  • :axis - :right for a y of its own scale, on an axis at the right of the plot: a layer of other units over another, as a line of revenue over bars of orders (Fude.layers/3). :left is the default.

Summary

Types

aggregate()
t()
time_unit()
type()

Functions

field?(channel)

Whether the channel reads a field (and not a constant).

new(name, channel)

A channel from its short form or its full form (see above). Raises an ArgumentError that names the channel and the value when it is neither.

title(channel)

The title of the channel's axis or legend: its own, or its field's name.

Types

aggregate()

@type aggregate() :: :count | :sum | :mean | :median | :min | :max | :distinct

t()

@type t() :: %Fude.Channel{
  aggregate: aggregate() | nil,
  axis: :left | :right | nil,
  bin: boolean() | map() | nil,
  digits: non_neg_integer() | nil,
  field: String.t() | nil,
  format: atom() | {atom(), String.t()} | nil,
  mid: number() | nil,
  scale: map() | nil,
  scheme: atom() | [String.t()] | nil,
  sort: atom() | [term()] | nil,
  stack: atom() | false | nil,
  time: time_unit() | nil,
  title: String.t() | false | nil,
  type: type() | nil,
  value: term()
}

time_unit()

@type time_unit() :: :year | :quarter | :month | :week | :day | :hour | :minute

type()

@type type() :: :number | :time | :category | :ordinal

Functions

field?(channel)

@spec field?(t()) :: boolean()

Whether the channel reads a field (and not a constant).

new(name, channel)

@spec new(atom(), term()) :: t()

A channel from its short form or its full form (see above). Raises an ArgumentError that names the channel and the value when it is neither.

title(channel)

@spec title(t()) :: String.t() | nil

The title of the channel's axis or legend: its own, or its field's name.