Expresso.Element.Chart.Encoding (expresso v0.1.0)

The symbol, the color and the size of a mark of a scatter plot

A point gives each of the three as a category, such as "EU", or as a value: a symbol by its name, such as :square, a color by a role of the theme, such as :chart_3 or :accent, and a size as a number. A category of the symbol takes the symbols in the order of symbols/0, and a category of the color takes --chart-1 to --chart-8, each in the order of the first point of the category.

Each symbol is a path of radius 1 at the origin. The symbols have approximately the area of a circle of radius 1, so a mark of one size looks as large with each symbol. The size of a point gives the area of its mark, so a size two times larger gives two times the area.

A number as the color takes a place on the scale of the color_scale option: scale/1 gives the color of the scale, and scale_place/4 the place of a number on it.

Summary

Functions

categories(values)

Return the categories of a list of values: each string, one time, in the order of its first value

color(role, categories, default)

Return the CSS color of a value: the color of its category, the role that it names, or a default

jitter(value)

Check the jitter option: a number from 0 to 0.2

legend_sizes(largest)

Return the three sizes of the legend of the sizes: round numbers at approximately the largest size, a quarter of it and a sixteenth of it

opacity(value)

Check the opacity option: a number from 0 to 1

path(symbol)

Return the path of a symbol of radius 1 at the origin

radius(size, largest, most)

Return the radius of a mark from its size, the largest size of the chart and the radius of the largest mark

role(role)

Return the CSS color of a role of the theme

roles()

Return each role that the color of a point takes: :chart_1 to :chart_8 and the roles of Expresso.Element.Icon.colors/0

scale(arg1)

Return the CSS color of a scale of the color_scale option

scale_place(value, arg, arg3, mid)

Return the place of a value on a scale of colors, from the lowest and the highest value of the chart

symbol(symbol, categories)

Return the symbol of a value: the symbol of its category, the symbol that it names, or a circle

symbols()

Return each symbol, in the order that the categories take them

Functions

categories(values)

@spec categories([term()]) :: [String.t()]

Return the categories of a list of values: each string, one time, in the order of its first value

iex> Expresso.Element.Chart.Encoding.categories(["EU", nil, :square, "US", "EU"])
["EU", "US"]

color(role, categories, default)

@spec color(String.t() | atom() | nil, [String.t()], String.t() | nil) ::
  String.t() | nil

Return the CSS color of a value: the color of its category, the role that it names, or a default

iex> Expresso.Element.Chart.Encoding.color("US", ["EU", "US"], "var(--chart-1)")
"var(--chart-2)"
iex> Expresso.Element.Chart.Encoding.color(:chart_5, [], "var(--chart-1)")
"var(--chart-5)"
iex> Expresso.Element.Chart.Encoding.color(:accent, [], "var(--chart-1)")
"var(--accent)"
iex> Expresso.Element.Chart.Encoding.color(nil, [], "var(--muted)")
"var(--muted)"

jitter(value)

@spec jitter(term()) :: {:ok, number()} | {:error, String.t()}

Check the jitter option: a number from 0 to 0.2

iex> Expresso.Element.Chart.Encoding.jitter(0.02)
{:ok, 0.02}
iex> Expresso.Element.Chart.Encoding.jitter(0.5)
{:error, "the jitter is a part of the range of an axis from 0 to 0.2, such as 0.02"}

legend_sizes(largest)

@spec legend_sizes(number()) :: [number()]

Return the three sizes of the legend of the sizes: round numbers at approximately the largest size, a quarter of it and a sixteenth of it

iex> Expresso.Element.Chart.Encoding.legend_sizes(120_000)
[100000, 20000, 5000]
iex> Expresso.Element.Chart.Encoding.legend_sizes(3)
[2, 0.5, 0.1]

opacity(value)

@spec opacity(term()) :: {:ok, number()} | {:error, String.t()}

Check the opacity option: a number from 0 to 1

iex> Expresso.Element.Chart.Encoding.opacity(0.6)
{:ok, 0.6}
iex> Expresso.Element.Chart.Encoding.opacity(2)
{:error, "the opacity of a mark is a number from 0 to 1, such as 0.6"}

path(symbol)

@spec path(atom()) :: String.t()

Return the path of a symbol of radius 1 at the origin

iex> Expresso.Element.Chart.Encoding.path(:diamond)
"M0 -1.253L1.253 0L0 1.253L-1.253 0Z"

radius(size, largest, most)

@spec radius(number(), number(), number()) :: float()

Return the radius of a mark from its size, the largest size of the chart and the radius of the largest mark

iex> Expresso.Element.Chart.Encoding.radius(25, 100, 30)
15.0

role(role)

@spec role(atom()) :: String.t()

Return the CSS color of a role of the theme

iex> Expresso.Element.Chart.Encoding.role(:chart_2)
"var(--chart-2)"

roles()

@spec roles() :: [atom()]

Return each role that the color of a point takes: :chart_1 to :chart_8 and the roles of Expresso.Element.Icon.colors/0

scale(arg1)

@spec scale(:sequential | :diverging | {atom(), atom()}) :: String.t()

Return the CSS color of a scale of the color_scale option

The color reads --chart-h, the place of the value of a mark on the scale. A sequential scale and a scale of two roles go from 0 to 1, and a diverging scale goes from -1 through 0 to 1.

iex> Expresso.Element.Chart.Encoding.scale({:chart_1, :chart_4})
"color-mix(in oklab, var(--chart-4) calc(var(--chart-h) * 100%), var(--chart-1))"

scale_place(value, arg, arg3, mid)

@spec scale_place(number(), {number(), number()}, atom() | tuple(), number() | nil) ::
  float()

Return the place of a value on a scale of colors, from the lowest and the highest value of the chart

The place goes from 0 to 1, or from -1 to 1 on a diverging scale. The middle of a diverging scale is 0 at mid, and each side reaches 1 at the value furthest from mid, so the colors of the two sides compare.

iex> Expresso.Element.Chart.Encoding.scale_place(15, {10, 30}, :sequential, nil)
0.25
iex> Expresso.Element.Chart.Encoding.scale_place(-5, {-10, 20}, :diverging, 0)
-0.25

symbol(symbol, categories)

@spec symbol(String.t() | atom() | nil, [String.t()]) :: atom()

Return the symbol of a value: the symbol of its category, the symbol that it names, or a circle

iex> Expresso.Element.Chart.Encoding.symbol("US", ["EU", "US"])
:square
iex> Expresso.Element.Chart.Encoding.symbol(:star, ["EU", "US"])
:star
iex> Expresso.Element.Chart.Encoding.symbol(nil, [])
:circle

symbols()

@spec symbols() :: [atom()]

Return each symbol, in the order that the categories take them

iex> Expresso.Element.Chart.Encoding.symbols()
[:circle, :square, :triangle, :diamond, :cross, :star]