# `Expresso.Element.Chart.Encoding`
[🔗](https://github.com/rellen/expresso/blob/main/lib/expresso/element/chart/encoding.ex#L1)

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.

# `categories`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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]

---

*Consult [api-reference.md](api-reference.md) for complete listing*