# `Giggly.Plot`
[🔗](https://github.com/giggleton/giggly/blob/v0.1.0/lib/giggly/plot.ex#L1)

Describes a plot: its data, a mapping from aesthetics to columns, and layers added with a pipe.

    rows
    |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    |> Giggly.Plot.geom_point()

A plot is a value and draws nothing itself: `Giggly.to_svg/2` draws it, and
`Giggly.layer_data/2` shows the table a layer computes.

## Data

The data is anything implementing `Table.Reader`: a list of maps, a map of columns, an Explorer
data frame. `new/2` reads it once, into a `Giggly.DataFrame`. A layer can draw a table of its
own instead, given by its `data:` option; under a facet, a table lacking the faceting columns
is drawn in every panel:

    iex> mtcars = %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "cyl" => [6, 4, 8]}
    iex> frame =
    ...>   mtcars
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_point(data: %{"wt" => [3.0], "mpg" => [20.0]}, colour: "#D9D9D9")
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.facet_wrap(:cyl)
    ...>   |> Giggly.layer_data(0)
    iex> Giggly.DataFrame.pull(frame, :panel)
    [1, 2, 3]

## Mapping and setting aesthetics

Every layer function takes a mapping, a map, and options, a keyword list, either or both. A map
maps an aesthetic to a column, `%{x: :wt}`, or to an expression or a constant, as
`Giggly.Mapping` describes; a keyword list sets it to one value for every mark, `alpha: 0.4`.
The plot's mapping applies to every layer, and a layer's own mapping is laid over it.

A misspelt column, or an aesthetic a layer cannot use, raises from the function that names it.
An aesthetic the plot maps that a layer cannot use is ignored by that layer, so a plot can map
`:label` for its text and still draw points. Whether a column's type suits an axis is checked
when the plot is run.

## Positions

A layer's `position:` says where its marks move once its stat has run: a position by name,
`position: :dodge`, or by name in a tuple with its options, `position: {:dodge, width: 0.9}`.
Each layer function's `position:` names the positions it takes and its default. A position
given to several layers moves their marks alike, so one bound to a name, `dodge = {:dodge,
width: 0.9}`, lines labels up with the bars they label.

A layer takes every position that can move its marks. Marks with a width of their own, such as
bars, tiles and error bars, take them all. Marks with none, such as points, lines, text, line
ranges and areas, are dodged, either way, only within a width given, `{:dodge, width: 0.9}` or
`{:dodge2, width: 0.5}`, since without one neither would move them. Box plots and rectangles are
neither stacked, filled nor jittered, beside dodging or not, and a horizontal or vertical line is
only nudged; a diagonal line takes no position.

Stacking and dodging move marks along x, and horizontal marks along y: those the layer makes
horizontal, such as bars counted along `y` or a line range from `xmin` to `xmax`, and those whose
one discrete axis is `y`, such as points or labels over a continuous x and a discrete y.

A position a layer's marks do not take raises from the layer function given it, saying why, and
so do an option the position does not take, or one that would change nothing for those marks,
and a value it cannot use, naming the position.

### Leaving marks where they are: `:identity`

Every mark stays where its stat put it. It takes no options.

### Piling marks up: `:stack`

Marks that share an `x` are piled on one another, the highest group at the bottom, so the pile
matches the legend's order, or the lowest given `reverse: true`; those reaching below zero pile
downward from it. Each mark takes the stretch of its pile as long as its `y`, and its `y` moves
to the stretch's top, or as far up it as `vjust:` says, so `vjust: 0.5` sets a label in the
middle of the bar it labels. Bars and areas pile this way by default.

* `:vjust` - Where in its stretch of the pile each mark's `y` moves, any number: 0 its bottom, 0.5 its middle, 1 its top. The default value is `1.0`.

* `:reverse` (`t:boolean/0`) - Whether the pile runs from the lowest group at the bottom to the highest. The default value is `false`.

    iex> frame =
    ...>   %{"x" => ["a", "a"], "y" => [2.0, 3.0], "g" => ["p", "q"]}
    ...>   |> Giggly.Plot.new(%{x: :x, y: :y, label: :g, colour: :g})
    ...>   |> Giggly.Plot.geom_text(position: {:stack, vjust: 0.5})
    ...>   |> Giggly.layer_data()
    iex> Giggly.DataFrame.pull(frame, :y)
    [4.0, 1.5]

### Piling marks to one height: `:fill`

Marks are piled as `:stack` piles them, then each pile is scaled to reach 1, so the marks at an
`x` show their shares of its total; a pile below zero reaches -1. A pile whose total is 0 is
left as it is, and one holding both infinities, whose total is no number, is not drawn. It
takes stacking's options.

    iex> frame =
    ...>   %{"x" => ["a", "a", "b"], "y" => [1.0, 3.0, 2.0], "g" => ["p", "q", "p"]}
    ...>   |> Giggly.Plot.new(%{x: :x, y: :y, fill: :g})
    ...>   |> Giggly.Plot.geom_col(position: :fill)
    ...>   |> Giggly.layer_data()
    iex> Giggly.DataFrame.pull(frame, :ymax)
    [1.0, 0.75, 1.0]

### Setting marks side by side: `:dodge`

The marks of different groups at one position are set side by side. The groups share a width,
each centred in its share, lowest group first, and each mark keeps its own width over the number
of groups. Given no `width:`, they share the width of the panel's first mark, so a bar dodges
bars, but marks of different widths drawn over them, such as narrower error bars, are dodged
within their own width and miss the bars; give each layer the same `width:`, the bars' width,
so they line up. A mark with no width of its own, a line range or a point range, is dodged only
within a `width:` given. A position with one group keeps its mark where it is, unless
`preserve: :single`, where each mark takes the share it would among the most groups any one
position holds, in any panel, the first share first, so a position with fewer leaves room after
them. `reverse: true` sets the highest group first. Marks that do not say which way they run,
such as points over two continuous axes, are dodged along y given `orientation: :y`; a layer
whose marks always say so, bars, box plots, ranges, lines and areas, takes no `orientation:`.

* `:width` - How wide the space is that the marks at one position share, in the units of the axis they are dodged along, any number; the panel's first mark's width when not given, so marks with no width of their own, such as line ranges, are not moved.

* `:preserve` - Whether the marks at a position share the whole width (`:total`), or each takes the share it would among the most groups any one position holds, the first share first, so a position with fewer leaves room after them (`:single`). The default value is `:total`.

* `:orientation` - The axis the marks are dodged along where neither the layer nor its data says which way they run: points or text over two continuous axes, say, which `:y` dodges up the panel. Marks whose one discrete axis is `y` are dodged along y whatever this says, and a layer whose marks always say which way they run, bars, box plots, ranges, lines and areas, takes none. The default value is `:x`.

* `:reverse` (`t:boolean/0`) - Whether the marks at a position run from the highest group to the lowest. The default value is `false`.

    iex> frame =
    ...>   %{"x" => ["a", "a"], "y" => [2.0, 3.0], "g" => ["p", "q"]}
    ...>   |> Giggly.Plot.new(%{x: :x, y: :y, color: :g})
    ...>   |> Giggly.Plot.geom_linerange(%{ymin: :y, ymax: :y}, position: {:dodge, width: 0.9})
    ...>   |> Giggly.layer_data()
    iex> Giggly.DataFrame.pull(frame, :x)
    [0.775, 1.225]

With `preserve: :single`, a bar alone at its position is as wide as each of a pair, in the
first of their places:

    iex> frame =
    ...>   %{"x" => ["a", "a", "b"], "y" => [1.0, 2.0, 3.0], "g" => ["p", "q", "p"]}
    ...>   |> Giggly.Plot.new(%{x: :x, y: :y, fill: :g})
    ...>   |> Giggly.Plot.geom_col(position: {:dodge, preserve: :single})
    ...>   |> Giggly.layer_data()
    iex> Giggly.DataFrame.pull(frame, :xmax)
    [1.0, 1.4500000000000002, 2.0]

### Setting bars side by side by their spans: `:dodge2`

Bars whose spans overlap or meet are dodged together, whatever their groups and widths: each
takes its share of their widths, its own width over their number, and they are laid side by
side in order of group, centred on the middle of the span they covered, each bar's `x` moving
to its middle. In a panel where some position holds two bars or more, every bar is then
narrowed by `padding:`, so neighbours stand apart. The layer's rows come out in that order: by
panel, then by `x`, then by group. A mark with no edges of its own, a point or a line range, is
dodged as a bar `width:` wide, each row side by side with those it overlaps, whatever their
groups; marks with edges, bars, box plots and error bars, take no `width:`.

* `:width` - How wide each mark with no width of its own, such as a point or a line range, is taken to be, in the units of the axis it is dodged along, any number, so each is set side by side with the marks it overlaps, whatever their groups; a layer whose marks have widths of their own, bars, box plots and error bars, takes none.

* `:preserve` - Whether the bars at a position share their whole width (`:total`), or each takes its width over the most bars any one position holds, so a position with fewer leaves room (`:single`). The default value is `:total`.

* `:padding` - How much of its share each bar leaves as a gap, a fraction from 0 to 1, in every panel where some position holds two bars or more. The default value is `0.1`.

* `:reverse` (`t:boolean/0`) - Whether the bars at a position run from the highest group to the lowest. The default value is `false`.

    iex> plot =
    ...>   %{"x" => ["a", "a", "b"], "y" => [1.0, 2.0, 3.0], "g" => ["p", "q", "p"]}
    ...>   |> Giggly.Plot.new(%{x: :x, y: :y, fill: :g})
    ...>   |> Giggly.Plot.geom_col(position: {:dodge2, preserve: :single})
    iex> frame = Giggly.layer_data(plot)
    iex> Giggly.DataFrame.pull(frame, :xmin)
    [0.5725, 1.0225000000000002, 1.7974999999999999]

    iex> frame =
    ...>   %{"x" => [1.0, 1.0], "y" => [2.0, 3.0], "g" => ["p", "q"]}
    ...>   |> Giggly.Plot.new(%{x: :x, y: :y, color: :g})
    ...>   |> Giggly.Plot.geom_point(position: {:dodge2, width: 0.5})
    ...>   |> Giggly.layer_data()
    iex> Giggly.DataFrame.pull(frame, :x)
    [0.875, 1.125]

### Nudging marks: `:nudge`

Every position a mark has along x moves by its `nudge_x` and every one along y by its
`nudge_y`, in the units of each axis: set for every mark by the layer's `nudge_x:` and
`nudge_y:`, which every layer function but `geom_abline/3` takes, a reference line only along
its own axis, or mapped from a column, each mark its own way, a value set winning over one
mapped. A mark given neither stays where it is, and one whose nudge is missing is not drawn.
Text and labels are nudged unless `position:` says otherwise. A nudge set or mapped beside
another position raises, which would move nothing, and so does a mapped one that is not numbers,
when the plot is run. It takes no options.

    iex> plot =
    ...>   %{"x" => [1.0, 2.0], "y" => [1.0, 2.0], "shift" => [0.5, -0.5]}
    ...>   |> Giggly.Plot.new(%{x: :x, y: :y})
    ...>   |> Giggly.Plot.geom_point(%{nudge_x: :shift}, position: :nudge)
    iex> Giggly.DataFrame.pull(Giggly.layer_data(plot), :x)
    [1.5, 1.5]

### Moving marks a random distance: `:jitter`

Each mark moves by a distance drawn evenly from minus `width:` to `width:` across and from minus
`height:` to `height:` up, in the units of each axis; one not given is 0.4 of the closest
spacing of each panel's positions along that axis, 0.4 on a discrete axis, whose levels are 1
apart. The distances are drawn from `seed:`, each panel's afresh, so the same seed moves the
same rows the same way: a plot draws the same points every time it is drawn, and layers given
one position move rows alike. Every position the layer has along an axis moves by its row's
distance along it; a missing position stays missing, and an infinite one where it is.

* `:width` - How far each point moves at most to either side, in the units of the x axis, 0 or more; 0.4 of the closest spacing of each panel's `x` positions when not given, 0.4 on a discrete axis.

* `:height` - How far each point moves at most up or down, in the units of the y axis, 0 or more; 0.4 of the closest spacing of each panel's `y` positions when not given.

* `:seed` (`t:integer/0`) - The seed the random distances are drawn from, any integer: the same seed moves the same rows the same way, so another seed draws other distances. The default value is `0`.

    iex> jitter = {:jitter, width: 0.1, height: 0.1, seed: 7}
    iex> plot =
    ...>   %{"am" => [0, 1], "vs" => [1, 0]}
    ...>   |> Giggly.Plot.new(%{x: :am, y: :vs})
    ...>   |> Giggly.Plot.geom_point(position: jitter)
    ...>   |> Giggly.Plot.geom_point(position: jitter, colour: "red")
    iex> plot |> Giggly.layer_data(0) |> Giggly.DataFrame.pull(:x)
    [0.0673789719000282, 1.0819934130875033]
    iex> plot |> Giggly.layer_data(1) |> Giggly.DataFrame.pull(:x)
    [0.0673789719000282, 1.0819934130875033]

### Setting marks side by side, then moving them a random distance: `:jitterdodge`

The marks of different groups at one position are set side by side within `dodge_width:`, as
`{:dodge, width: dodge_width}` sets them, then each moves by a distance drawn evenly from minus
to plus its amount to either side, and up and down by up to `jitter_height:`, 0 unless given, so
points drawn over box plots dodged by the same groups spread across their own group's box. The
sideways amount is `jitter_width:`, else 0.4 of the closest spacing of the layer's positions,
over every panel, divided by the most groups at one position in any panel plus 2, so the points
of each group keep to their share; the distances are drawn as `:jitter` draws them, from
`seed:`. Marks with no width of their own are dodged within `dodge_width:` too, and so are
marks whose one discrete axis is `y`, along y. A layer jittered this way needs both `x` and
`y`, as `:jitter` does.

* `:jitter_width` - How far each mark moves at most to either side of its share, in the units of the axis it is dodged along, 0 or more, before it is divided by the most groups at one position in any panel plus 2; 0.4 of the closest spacing of the layer's positions along that axis, over every panel, when not given, 0.4 on a discrete axis.

* `:jitter_height` - How far each mark moves at most along the other axis, up or down for marks dodged along x, in that axis's units, 0 or more, so marks move only to the side unless given. The default value is `0.0`.

* `:dodge_width` - How wide the space is that the groups at one position share, in the units of the axis they are dodged along, any number. The default value is `0.75`.

* `:seed` (`t:integer/0`) - The seed the random distances are drawn from, any integer: the same seed moves the same rows the same way, so another seed draws other distances. The default value is `0`.

    iex> plot =
    ...>   %{"cut" => ["a", "a", "a", "a"], "carat" => [1.0, 2.0, 3.0, 4.0]}
    ...>   |> Map.put("clarity", ["p", "q", "p", "q"])
    ...>   |> Giggly.Plot.new(%{x: :cut, y: :carat, fill: :clarity})
    ...>   |> Giggly.Plot.geom_boxplot()
    ...>   |> Giggly.Plot.geom_point(position: :jitterdodge)
    iex> plot |> Giggly.layer_data(0) |> Giggly.DataFrame.pull(:x)
    [0.8125, 1.1875]
    iex> plot |> Giggly.layer_data(1) |> Giggly.DataFrame.pull(:x)
    [0.8086663925491824, 1.2857778162399303, 0.7413202475792124, 1.1838679705192539]

## Colours

A colour is a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or
`"#4682B480"` with an alpha of its own, or `"transparent"`, white with no alpha as R's is, where
CSS's is black; `:none` draws nothing. A name CSS does not define raises. An alpha, set or
mapped, replaces a colour's own, so `"transparent"` at an alpha of 0.5 draws half-white.

A discrete column mapped to `:color` (or `:colour`) or `:fill` gives each of its values a hue,
evenly spaced round the colour wheel, so three values are `#F8766D`, `#00BA38` and `#619CFF`; a
missing value is grey, `#7F7F7F`, and its key in the legend comes last, labelled `NA`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.875, 2.32], "mpg" => [21.0, 22.8, 22.8], "cyl" => ["6", "4", nil]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, colour: :cyl})
    ...>   |> Giggly.Plot.geom_point()
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:color)
    ["#00BFC4", "#F8766D", "#7F7F7F"]

A column of numbers mapped to colour or fill gives each value a colour as far along a gradient
from `#132B43` to `#56B1F7` as the value is through the column's range; a missing value is grey
here too. Its guide is a colour bar.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.875, 2.32], "mpg" => [21.0, 22.8, 22.8], "hp" => [110, 93, nil]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, colour: :hp})
    ...>   |> Giggly.Plot.geom_point()
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:color)
    ["#56B1F7", "#132B43", "#7F7F7F"]

A legend, colour bar or colour steps are drawn for each mapped aesthetic, stacked down the right
of the panels unless the theme puts them elsewhere (`theme/2`'s `legend_position:`), in the
order of the aesthetics' names (`alpha`, `color`, `fill`, `shape`, `size`). Two with the same
title and labels, such as a colour and a fill mapped to one column, are drawn as one.

## Guides

A guide reads a scale back: a legend, a key for each break, or, for a continuous colour or fill,
a colour bar, or colour steps, a bar of one block of colour for each bin between its breaks.
Each scale function's `guide:` chooses its scale's, `:legend`, `:colorbar`, `:colorsteps`,
`:none` for none, or a legend `guide_legend/1` makes, whose keys may run in reverse; `guides/2`
chooses them by aesthetic over whatever the scales say.

## Scales

Each axis gets a scale from the type of what is mapped to it: a continuous scale for numbers, a
discrete one for text, booleans and factors, a date one for dates, a date-time one for
`DateTime`s and `NaiveDateTime`s, and a time one for `Time`s. `scale_x_continuous/2`,
`scale_x_discrete/2`, `scale_x_date/2`, `scale_x_datetime/2` and `scale_x_time/2`, and their y
twins, set an axis's title, limits, breaks, labels and how far it reaches, and a date-time
axis's time zone; `xlim/3`, `ylim/3` and `lims/2` set its limits alone, two ends for a
continuous, a date or a date-time axis and, with `xlim/2` and `ylim/2`, a list of values for a
discrete one; a time axis's are its scale's `limits:`. A value outside the limits is missing, so
its mark is not drawn, unless the scale's `oob:` says otherwise. A continuous scale given a column of dates places each at its days since
1970-01-01, one of date-times each at its seconds since 1970-01-01 00:00 UTC, and one of times
each at its seconds since midnight.

A label on an axis or a legend breaks over lines where it holds `"
"`, and a missing one,
`nil`, is drawn `NA`. A labels function may return powers, as `Scales.Labels.log/2` does, drawn
as a base with a smaller exponent raised after it, a sign before it in the symbol font; where
any label of an axis or a colour bar is a power, its strings are placed as powers are and a
missing one is drawn as nothing; a legend draws each key's label alone, a string as text and a
missing one `NA`.

A colour, fill, alpha, shape or size scale chooses how values become colours, opacities, shapes or
sizes, and sets its legend's title, limits, breaks and labels: `scale_color_manual/2` names each
value's colour, `scale_color_hue/2` spaces hues round the colour wheel, `scale_color_gray/2`
greys, `scale_color_discrete/2` either, and `scale_color_viridis_d/2` takes colours from a
viridis palette, as an ordered factor gets by default, and `scale_color_brewer/2` from a
ColorBrewer palette; `scale_color_gradient/2`, `scale_color_gradient2/2`,
`scale_color_gradientn/2` and `scale_color_continuous/2` blend a gradient through two, three or
any number of colours, `scale_color_viridis_c/2` through a viridis palette and
`scale_color_distiller/2` through a ColorBrewer palette; each has a `scale_fill_` twin, and
`scale_alpha_continuous/2` and `scale_alpha_discrete/2` set opacities. `scale_size_continuous/2`
and `scale_size_area/2` size points by area, the second from 0, `scale_radius/2` by width, and
`scale_size_discrete/2` a discrete column's values in order. `scale_shape_discrete/2` gives a
discrete column's values six shapes, solid or open, and `scale_shape_manual/2` names each value's
shape; shapes have no order, so a continuous column cannot be mapped to `:shape`. `lims/2` sets
their limits alone. A value outside a colour scale's limits takes its `na_value:`, as a missing
one does, unless its `oob:` says otherwise; a binned scale's takes the colour of the nearer end
bin.

## Labels

Each axis and legend is titled by what is mapped to it, as `Giggly.Mapping` describes. `labs/2`
titles them otherwise, and gives the plot a title, a subtitle, a caption and a tag; a scale's
name titles its axis over both.

## Theme

Everything but the marks is drawn in ggplot2's default theme, a grey panel with white grid lines,
unless a complete theme replaces it: `theme_bw/2`, `theme_linedraw/2`, `theme_light/2`,
`theme_dark/2`, `theme_minimal/2`, `theme_classic/2` or `theme_void/2`, or `theme_gray/2`, the
default, each at a base size of its own. `theme/2` changes any element of it by name, each
inheriting what it leaves unset from its parent in ggplot2's tree, so setting
`text: [size: 14]` makes every label bigger, and `axis_text_x: [color: "red"]` reddens only the
x axis's labels. An element set to `:none` is removed, with everything that inherits from it.
`legend_position:` puts the legends left, right, above or below the panels, inside them, or
nowhere (`:none`).

# `aesthetic`

```elixir
@type aesthetic() :: atom()
```

An aesthetic's name, such as `:x`, `:y` or `:color`.

# `axis_end`

```elixir
@type axis_end() :: number() | Date.t() | DateTime.t() | NaiveDateTime.t() | nil
```

An end of an axis's limits: a number, a date or a date-time, or `nil` for the data's.

# `column_reference`

```elixir
@type column_reference() :: atom() | String.t()
```

A column of a table as written: its name as an atom or a string.

# `coord`

```elixir
@type coord() :: struct()
```

How positions are placed in each panel: a coordinate system's struct.

# `facet`

```elixir
@type facet() :: struct()
```

How the plot's rows are split into panels: a facet's struct.

# `guide`

```elixir
@type guide() :: :none | :legend | :colorbar | :colorsteps | struct()
```

The guide that reads an aesthetic's scale back: `:legend`, `:colorbar`, `:colorsteps`, `:none`
for none, or a legend `guide_legend/1` makes.

# `guides`

```elixir
@type guides() :: %{optional(aesthetic()) => guide()}
```

The guides `guides/2` sets, by aesthetic, each winning over its scale's own.

# `labels`

```elixir
@type labels() :: %{optional(atom()) => String.t() | :none}
```

The labels `labs/2` sets, by what each titles: an aesthetic's guide, or the plot's `:title`,
`:subtitle`, `:caption` or `:tag`; each its text, or `:none` for none.

# `mapping`

```elixir
@type mapping() :: Giggly.Mapping.t()
```

A mapping as stored: aesthetic to its value resolved, each column it reads named as a string, in
the table the layer draws.

# `mapping_argument`

```elixir
@type mapping_argument() :: %{optional(aesthetic()) => Giggly.Mapping.value()}
```

A mapping as written: aesthetic to a column, an expression or a constant.

# `scales`

```elixir
@type scales() :: %{optional(aesthetic()) => struct()}
```

The scales the plot sets, by aesthetic: each a scale's struct, as yet untrained.

# `t`

```elixir
@type t() :: %Giggly.Plot{
  coord: coord(),
  data: Giggly.DataFrame.t(),
  facet: facet(),
  guides: guides(),
  labels: labels(),
  mapping: mapping(),
  reversed_layers: [struct()],
  scales: scales(),
  theme: theme()
}
```

A plot: its data, its mapping, its facet, coordinate system, scales, the guides `guides/2`
sets, its theme, the labels `labs/2` sets, and its layers newest first (each function adds one at the front; they are
assembled in the order they were added).

# `theme`

```elixir
@type theme() :: %{
  complete:
    %{
      name:
        :gray | :bw | :linedraw | :light | :dark | :minimal | :classic | :void,
      base_size: float(),
      base_line_size: float(),
      base_rect_size: float(),
      base_family: String.t(),
      header_family: String.t() | :none
    }
    | :none,
  settings: %{optional(atom()) => term()}
}
```

The look everything but the marks is drawn in: the complete theme a `theme_*` function chose,
by name with its base sizes and families, `:none` for a header family not given, or `:none`
for none, which draws the plot in `theme_gray/2`'s at its defaults, and the settings `theme/2`
has laid over it, by element.

# `annotate`

```elixir
@spec annotate(t(), atom(), keyword()) :: t()
```

Adds an annotation: a layer drawn from values given here rather than from the data's columns,
for a label, a shaded rectangle or a line placed by hand. `geom` names what draws it: `:point`,
`:col` or `:bar`, `:path`, `:line`, `:segment`, `:rug`, `:linerange`, `:pointrange`,
`:errorbar`, `:crossbar`, `:text`, `:label` or `:rect`.

An annotation's positions widen the axes as the data's do. It takes nothing from the plot's
mapping, titles no axis, is in no legend, and under a facet is drawn in every panel. It is drawn
where it is placed: text and labels are not nudged, and bars at one `x` are not stacked.

Each option takes one value, or a list of them, one per annotation: every list holds as many
values as the others, and a single value is used for every annotation, so
`x: [2, 3, 4, 5], y: 25` places four. A position is a number, `:infinity` or `:neg_infinity`,
which reach the panel's edge, `nil` for none, a string on a discrete axis, `true` or `false`, or
a date, a date-time or a time on such an axis. Of the other options, `label:`, `colour:`,
`alpha:` and `fill:` each take a list, its values of one type, and so do a point's or a point
range's `shape:`, `size:` and `stroke:`, a bar's, a segment's, a rug's, a range's, a label's or
a rectangle's `linewidth:` and `linetype:`, whose list holds line types, a dash pattern among
them a tuple, and a path's or a line's `linewidth:`, a line whose width changes along it drawn a segment from each annotation
to the next; the rest take one value, a label's `label_padding:` one for every label however
many sides it gives. Under a facet that makes more than one panel, an annotation given such a
list raises when the plot is run.

Each geom takes the positions it draws at and the options its own function takes but `data:`
and `position:`, and `geom_text/3`'s nudging:

  * `:point`: `x:`, `y:`, `alpha:`, `colour:`, `fill:`, `shape:`, `size:` and `stroke:`;
  * `:col` and `:bar`, each a bar from 0 to its `y` as `geom_col/3` draws one: `x:`, `y:`,
    `alpha:`, `colour:`, `fill:`, `linewidth:`, `linetype:`, `width:` and `just:`;
  * `:path`: `x:`, `y:`, `alpha:`, `colour:`, `linewidth:`, `linetype:`, `lineend:`, `linejoin:`
    and `linemitre:`, and `:line` those and `orientation:`;
  * `:segment`: `x:`, `y:`, `xend:`, `yend:`, `alpha:`, `colour:`, `linewidth:`, `linetype:`,
    `lineend:` and `linejoin:`;
  * `:rug`: `x:`, `y:`, `alpha:`, `colour:`, `linewidth:`, `linetype:`, `sides:`, `length:`,
    `outside:` and `lineend:`;
  * `:linerange`: `x:`, `y:`, `xmin:`, `xmax:`, `ymin:`, `ymax:`, `orientation:`, `alpha:`,
    `colour:`, `linewidth:`, `linetype:` and `lineend:`, and `:pointrange` those and `fill:`,
    `shape:`, `size:` and `stroke:`;
  * `:errorbar`: a line range's options and `width:`, one value or a list;
  * `:crossbar`: `x:`, `y:`, `xmin:`, `xmax:`, `ymin:`, `ymax:`, `orientation:`, `width:`,
    `alpha:`, `colour:`, `fill:`, `linewidth:`, `linetype:`, `lineend:`, `linejoin:` and the
    `middle_` and `box_` looks, its `width:` one value or a list;
  * `:text`: `x:`, `y:`, `label:`, `check_overlap:`, `alpha:`, `colour:`, `size:`, `angle:`,
    `hjust:`, `vjust:` and `family:`;
  * `:label`: `x:`, `y:`, `label:`, `alpha:`, `colour:`, `fill:`, `linewidth:`, `linetype:`,
    `size:`, `angle:`, `hjust:`, `vjust:`, `family:`, `label_padding:`, `label_r:`,
    `border_colour:` and `text_colour:`;
  * `:rect`: `xmin:`, `xmax:`, `ymin:`, `ymax:`, `alpha:`, `colour:`, `fill:`, `linewidth:` and
    `linetype:`.

The reference lines are not among them: each annotates on its own, given its lines as values
(`geom_hline/3`, `geom_vline/3`, `geom_abline/3`).

Raises `ArgumentError` for a geom it does not draw with, for lists of different lengths, for a
list whose values are not of one type, and for an aesthetic the geom needs and is not given, a
range's three positions among them, as `geom_linerange/3` refuses them;
`NimbleOptions.ValidationError` for an option the geom does not take, or a value it cannot draw.

    iex> frame =
    ...>   %{"wt" => [2.62, 3.44], "mpg" => [21.0, 18.7]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.annotate(:text, x: [2.0, 3.0], y: 25.0, label: ["my label", "label 2"])
    ...>   |> Giggly.layer_data(1)
    iex> {Giggly.DataFrame.pull(frame, :y), Giggly.DataFrame.pull(frame, :label)}
    {[25.0, 25.0], ["my label", "label 2"]}

# `coord_cartesian`

```elixir
@spec coord_cartesian(t(), keyword()) :: t()
```

Draws the plot in cartesian coordinates, x across each panel and y up it, replacing any
coordinate system the plot had. A plot is cartesian until another is chosen, each panel cut off
at its edges; with `clip: :off` what is drawn may run past them, as rugs drawn outside the
panel do.

## Options

* `:clip` - Whether what is drawn in each panel is cut off at its edges (`:on`), or may run past them (`:off`). The default value is `:on`.

Clipped, the panel's cell has a clip path of its own beside the plot's background's; unclipped,
the background's alone:

    iex> plot =
    ...>   %{"wt" => [2.32, 2.62, 3.44], "mpg" => [22.8, 21.0, 18.7]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_rug(outside: true)
    iex> Enum.map([:on, :off], fn clip ->
    ...>   svg =
    ...>     plot
    ...>     |> Giggly.Plot.coord_cartesian(clip: clip)
    ...>     |> Giggly.to_svg()
    ...>     |> IO.iodata_to_binary()
    ...>
    ...>   ~r/<clipPath/ |> Regex.scan(svg) |> length()
    ...> end)
    [2, 1]

# `coord_radial`

```elixir
@spec coord_radial(t()) :: t()
```

Draws the plot in radial coordinates: x is the angle, running clockwise round a full circle from
12 o'clock, and y the radius, out from the centre. A plot is cartesian until this is called.

The scales are expanded as cartesian ones are, so the marks keep clear of the circle's edge and
centre, and the first and last positions on x are a gap apart at 12 o'clock. Each panel is
square, its grid a circle at each of y's breaks and a spoke at each of x's, on a disc; x's axis
is drawn round the circle inside the panel, and y's to its left, up the radius at 12 o'clock.
Nothing is clipped at the panel's edges.

    iex> svg =
    ...>   %{"wt" => [2.32, 2.62, 3.44], "mpg" => [22.8, 21.0, 18.7]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.coord_radial()
    ...>   |> Giggly.to_svg()
    ...>   |> IO.iodata_to_binary()
    iex> svg =~ "<polygon"
    true

# `facet_grid`

```elixir
@spec facet_grid(t(), keyword()) :: t()
```

Splits the plot into a grid of panels: a row of panels for each combination of values of the
`rows:` columns that occurs in the data, and a column of panels for each of the `cols:`
columns', each given as a column or a list of columns named as a mapping names one:
`facet_grid(plot, rows: :drv, cols: :cyl)`. Leaving one out gives a single column or a single
row of panels.

Each layer's rows are drawn in the panel of their values. The rows' values and the columns' are
each those the plot's data and every layer's own table make together, and every row is crossed
with every column, so a pair of values no table holds still has a panel, drawn empty. A table
lacking some of the columns is drawn in every panel of the values it has, so one lacking them
all is drawn in every panel. The rows, and the columns, are ordered by their first column's
values, then the next's, as an axis orders its levels, with a missing value (`nil`) last.

Each column of panels is labelled by strips above the first row, and each row by strips right of
the last column, turned to read downward unless the theme says otherwise (`strip_text_y`): a
strip for each column split on, the first outermost, labelled with its value unless
`labeller:` says otherwise.

The panels share each axis's scale, and an axis is drawn only at the grid's outer edges. Free
scales give each column of panels an x scale of its own and each row a y scale, trained on its
panels' rows alone; the axes stay at the edges, each column's below it and each row's left of
it.

## Options

* `:rows` - The column, or list of columns, whose values give the rows of panels, each named as a mapping names one. The default value is `[]`.

* `:cols` - The column, or list of columns, whose values give the columns of panels, each named as a mapping names one. The default value is `[]`.

* `:scales` - Whether the panels share each axis's scale (`:fixed`), or each column of panels has its own x scale (`:free_x`), each row its own y scale (`:free_y`), or both (`:free`). The default value is `:fixed`.

* `:labeller` - How each strip is labelled from its panel's values: `:value`, `:both`, `:context`, `:wrap`, one of them with its options, a function, a map, or a keyword list labelling each side or column apart, as "Labelling the strips" says. The default value is `:value`.

Raises `ArgumentError` when neither `rows:` nor `cols:` names a column, a column is named twice,
in one of them or in both, or the labeller's `columns:` names a column of a side its `rows:` or
`cols:` labels, and `NimbleOptions.ValidationError` for an option it does not take, a value that
is not a column reference, or a labeller it cannot use. When the plot is run, since a layer added
later may bring a column, it raises `ArgumentError` unless the plot's data or some layer's own
table holds every column of `rows:`, and likewise of `cols:`, and when no table has a row to
make a panel from.

    iex> plot =
    ...>   %{
    ...>     "wt" => [2.32, 2.62, 3.44, 2.2],
    ...>     "mpg" => [22.8, 21.0, 18.7, 32.4],
    ...>     "am" => [1, 1, 0, 1],
    ...>     "cyl" => [4, 6, 8, 4]
    ...>   }
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.facet_grid(rows: :am, cols: :cyl)
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:panel)
    [4, 5, 3, 4]

## Labelling the strips

Each strip is labelled from its panel's values by `labeller:`, the value alone unless it says
otherwise:

  * `:value`, the value alone, as a table writes it: `4` for a whole float, `TRUE`;
  * `:both`, the column's name and the value, `cyl: 4`;
  * `:context`, the value alone where a side's strips are for one column, and both where they
    are for several;
  * `:wrap`, the value alone broken between its words into lines shorter than 25 columns, a
    word wider than that on a line of its own, as `Scales.Labels.wrap/2` breaks it (a Chinese,
    Japanese or Korean character or an emoji takes two columns): the whitespace between words
    becomes one space, or two after a sentence's end that two or more followed, and a line
    holding only whitespace starts a paragraph, an empty line before it;
  * one of these with its options, such as `{:both, sep: "=", multi_line: false}`: `sep:` goes
    between the name and the value (`": "`), `width:` sets how many columns `:wrap` keeps a
    line under (`{:wrap, width: 10}`), and `multi_line: false` puts a panel's labels in
    one strip, joined by `", "`, in place of a strip for each column (`4, f`, or under
    `:both` `cyl, drv: 4, f`, and under `:wrap` the labels joined and then broken);
  * a function, handed each label as `:value` writes it and returning the label to show;
  * a map of labels to the labels to show, `%{"0" => "Zero", "1" => "One"}`, a label it lacks
    shown as `NA`.

A missing value is shown as `NA`, and is never handed to a function or looked up. A label
holding a line break, whichever labeller writes it, is drawn in a strip of several lines,
spaced by the strip text's `lineheight:`.

A keyword list labels the sides, or the columns, apart:

  * `rows:` and `cols:`, the labeller of every strip of the rows or of the columns of panels;
    a wrap's strips are one side, labelled by either;
  * `columns:`, a keyword list or a map of a labeller for each column it names, by the column.
    A column the facet does not split on is passed over, so one list can label several plots.
    A label a column's own labeller leaves missing, as a map does one it lacks, is the
    default's;
  * `default:`, the labeller of every other column (`:value`), which also writes the labels a
    function or a map gives: under `[columns: [vore: &String.upcase/1], default: :both]` the
    strip of `"carni"` shows `vore: CARNI`;
  * `multi_line:`, whether each column's label is a strip of its own (`true`), or one strip
    joins them, `cyl: 4, drv: f`.

In the list a labeller takes its options but not `multi_line:`, which is the list's. A side
whose strips have a labeller of their own cannot also have its columns labelled apart.

# `facet_wrap`

```elixir
@spec facet_wrap(t(), column_reference() | [column_reference()], keyword()) :: t()
```

Splits the plot into panels, one for each combination of values of the `facets` columns that
occurs in the data, laid out in rows. `facets` is a column, or a list of columns, each named as
a mapping names one: `facet_wrap(plot, :class)` or `facet_wrap(plot, [:cyl, :drv])`.

Each layer's rows are drawn in the panel of their values. The panels are those the plot's data
and every layer's own table make together; a table lacking some of the columns is drawn in every
panel of the values it has, so one lacking them all is drawn in every panel. The panels are
ordered by the first column's values, then the next's, as an axis orders its levels, with a
missing value (`nil`) last, and fill the rows left to right. With neither `nrow:` nor `ncol:`,
up to three panels make one row, up to six two rows, up to twelve three, and more a square or
nearly one; given one of the two, the other is as many as the panels need.

The panels share each axis's scale, and an axis is drawn only at the panels' outer edges. Free
scales give each panel a scale of its own, trained on its rows alone, and its own axis.

Each panel has a strip above it for each column, in the order given, labelled with its value
unless `labeller:` says otherwise.

## Options

* `:nrow` (`t:pos_integer/0`) - How many rows to lay the panels out in.

* `:ncol` (`t:pos_integer/0`) - How many columns to lay the panels out in.

* `:scales` - Whether the panels share each axis's scale (`:fixed`), or each panel has its own x scale (`:free_x`), y scale (`:free_y`) or both (`:free`), and draws its own axis for each. The default value is `:fixed`.

* `:labeller` - How each strip is labelled from its panel's values: `:value`, `:both`, `:context`, `:wrap`, one of them with its options, a function, a map, or a keyword list labelling each side or column apart, as "Labelling the strips" says. The default value is `:value`.

Raises `ArgumentError` for a column named twice or none at all, a value that is not a column
reference, or a labeller whose `columns:` names a column when `rows:` or `cols:` labels every
strip, and `NimbleOptions.ValidationError` for an option it does not take, a count that is not a
positive whole number, or a labeller it cannot use, `rows:` and `cols:` together among them. When
the plot is run, since a layer added later may bring a column,
it raises `ArgumentError` unless the plot's data or some layer's own table holds every column,
when `nrow:` and `ncol:` together hold fewer panels than there are, and when no table has a row
to make a panel from.

    iex> plot =
    ...>   %{"wt" => [2.32, 2.62, 3.44, 2.2], "mpg" => [22.8, 21.0, 18.7, 32.4], "cyl" => [4, 6, 8, 4]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.facet_wrap(:cyl)
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:panel)
    [1, 2, 3, 1]

Under `labeller: :both` each strip shows the column's name beside its value:

    iex> svg =
    ...>   %{"wt" => [2.32, 2.62], "mpg" => [22.8, 21.0], "cyl" => [4, 6]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.facet_wrap(:cyl, labeller: :both)
    ...>   |> Giggly.to_svg()
    ...>   |> IO.iodata_to_binary()
    iex> Enum.map(["cyl: 4", "cyl: 6"], fn label -> svg =~ ">" <> label <> "</text>" end)
    [true, true]

## Labelling the strips

Each strip is labelled from its panel's values by `labeller:`, the value alone unless it says
otherwise:

  * `:value`, the value alone, as a table writes it: `4` for a whole float, `TRUE`;
  * `:both`, the column's name and the value, `cyl: 4`;
  * `:context`, the value alone where a side's strips are for one column, and both where they
    are for several;
  * `:wrap`, the value alone broken between its words into lines shorter than 25 columns, a
    word wider than that on a line of its own, as `Scales.Labels.wrap/2` breaks it (a Chinese,
    Japanese or Korean character or an emoji takes two columns): the whitespace between words
    becomes one space, or two after a sentence's end that two or more followed, and a line
    holding only whitespace starts a paragraph, an empty line before it;
  * one of these with its options, such as `{:both, sep: "=", multi_line: false}`: `sep:` goes
    between the name and the value (`": "`), `width:` sets how many columns `:wrap` keeps a
    line under (`{:wrap, width: 10}`), and `multi_line: false` puts a panel's labels in
    one strip, joined by `", "`, in place of a strip for each column (`4, f`, or under
    `:both` `cyl, drv: 4, f`, and under `:wrap` the labels joined and then broken);
  * a function, handed each label as `:value` writes it and returning the label to show;
  * a map of labels to the labels to show, `%{"0" => "Zero", "1" => "One"}`, a label it lacks
    shown as `NA`.

A missing value is shown as `NA`, and is never handed to a function or looked up. A label
holding a line break, whichever labeller writes it, is drawn in a strip of several lines,
spaced by the strip text's `lineheight:`.

A keyword list labels the sides, or the columns, apart:

  * `rows:` and `cols:`, the labeller of every strip of the rows or of the columns of panels;
    a wrap's strips are one side, labelled by either;
  * `columns:`, a keyword list or a map of a labeller for each column it names, by the column.
    A column the facet does not split on is passed over, so one list can label several plots.
    A label a column's own labeller leaves missing, as a map does one it lacks, is the
    default's;
  * `default:`, the labeller of every other column (`:value`), which also writes the labels a
    function or a map gives: under `[columns: [vore: &String.upcase/1], default: :both]` the
    strip of `"carni"` shows `vore: CARNI`;
  * `multi_line:`, whether each column's label is a strip of its own (`true`), or one strip
    joins them, `cyl: 4, drv: f`.

In the list a labeller takes its options but not `multi_line:`, which is the list's. A side
whose strips have a labeller of their own cannot also have its columns labelled apart.

# `geom_abline`

```elixir
@spec geom_abline(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer of diagonal reference lines: a line across the whole panel for each `intercept`
and `slope`, `y = intercept + slope * x`, for a line of equality, a fitted line worked out
elsewhere, or a rule of thumb drawn over the data.

The lines are given in one of two ways. `intercept:` and `slope:` give them as values, a line
for each, drawn in every panel and in no legend; given neither, nor a mapping, the layer draws
the line `y = x`. Or the layer maps both `:intercept` and `:slope` from a table, its own
`data:` or the plot's, so the lines can differ from panel to panel under a facet and map a
colour, alpha, width or line type into a legend. Either way the layer takes nothing from the
plot's mapping, and titles no axis.

Diagonal lines use `:intercept`, `:slope`, `:group`, `:alpha`, `:color`, `:linetype` and
`:linewidth`, and need `:intercept` and `:slope`, numbers in the axes' positions, the units
their scales transform into, so under `scale_y_log10/2` an intercept of 1 crosses at 10; on a
discrete axis the levels sit at 1, 2, 3 and on. Neither widens an axis or goes through a
scale. A line repeated in a panel is drawn once. Beside `intercept:` or `slope:`, each look
option takes one value or a list, one per line, every list as long as the others. A line
missing its intercept or slope draws nothing, and so do an infinite one, a colour of `:none`
and the line type `:blank`. A line that misses the panel is still drawn, beyond its edges:
hidden where the panel is clipped, but under `coord_cartesian(clip: :off)` and
`coord_radial/1`, which never clips, it may show outside the panel, a spiral under radial
coordinates. A flat line exactly on the edge of such a panel draws nothing.

Raises `ArgumentError` for `intercept:` or `slope:` beside a mapping or `data:`, for `data:`
without a mapping, for a list of looks without `intercept:` or `slope:`, for lists of
different lengths, and for a mapped intercept or slope that is not a number.

## Options

* `:data` (`t:term/0`) - A table for the layer's mapping to draw from instead of the plot's data, anything implementing `Table.Reader`; refused beside the options giving lines as values, which draw lines of their own. Under a facet, a table lacking a faceting column is drawn in every panel.

* `:intercept` - Where each line crosses x = 0, in the y axis's positions, the units its scale transforms into: a number, or a list of them, a line for each, drawn in every panel; 0 when only `slope:` is given. Given, the layer takes no mapping and no `data:`.

* `:slope` - How far each line rises along y for each unit along x, in the axes' positions: a number, or a list of them, a line for each; 1 when only `intercept:` is given. Given, the layer takes no mapping and no `data:`.

* `:alpha` - How opaque each line is, from 0, invisible, to 1, opaque.

* `:color` - The colour of each line, written `colour:` or `color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; black when not given.

* `:linewidth` - How wide each line is, in millimetres; the theme's `base_line_size` when not given, 0.5 at its default sizes.

* `:linetype` - The line type of each line: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; `:solid` when not given.

* `:lineend` - How a line's ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half the line's width beyond it (`:square`). The default value is `:butt`.

    iex> frame =
    ...>   %{"wt" => [2.62, 3.44], "mpg" => [21.0, 18.7]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.geom_abline(intercept: 37, slope: [-5, -4], colour: "red")
    ...>   |> Giggly.layer_data(1)
    iex> {Giggly.DataFrame.pull(frame, :intercept), Giggly.DataFrame.pull(frame, :slope)}
    {[37.0, 37.0], [-5.0, -4.0]}

A line for each panel, mapped from a table of its own:

    iex> frame =
    ...>   %{"wt" => [2.62, 3.44], "mpg" => [21.0, 18.7], "cyl" => [4, 8]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.geom_abline(%{intercept: :intercept, slope: :slope},
    ...>     data: %{"cyl" => [4, 8], "intercept" => [40.0, 20.0], "slope" => [-5.0, -1.0]}
    ...>   )
    ...>   |> Giggly.Plot.facet_wrap(:cyl)
    ...>   |> Giggly.layer_data(1)
    iex> {Giggly.DataFrame.pull(frame, :slope), Giggly.DataFrame.pull(frame, :panel)}
    {[-5.0, -1.0], [1, 2]}

# `geom_area`

```elixir
@spec geom_area(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer of areas: the band from 0 to each group's `y` along its `x`, for how much a series
holds over time, or from 0 to its `x` up its `y` with `orientation: :y`.

Areas use `:x`, `:y`, `:group`, `:alpha`, `:fill`, `:color`, `:linetype` and `:linewidth`, and
need `:x` and `:y`. Each group is an area of its own, its rows in order along it, and areas at
one `x` are piled on one another, the first group on top, unless `position: :identity` draws
each where it is. So that groups whose rows sit at different places pile into one another, each
group with more than one row is first worked out at every `x` the panel's groups have, and
wherever a group crosses 0, along a straight line between its own rows, and at its ends drops to
0 a hair beyond them. A row missing `x` or `y` is left out. An area is filled, at its alpha, and
its upper edge outlined only where a colour is mapped or set, taking no alpha but its colour's
own; its look cannot change along it, as a ribbon's cannot (`geom_ribbon/3`).

## Options

* `:data` (`t:term/0`) - A table for the layer to draw instead of the plot's data, anything implementing `Table.Reader`. The plot's mapping applies to it, so it must hold each column the plot's mapping names for an aesthetic the layer neither maps nor sets. Under a facet, a table lacking a faceting column is drawn in every panel of that column's values.

* `:position` - Where the marks are moved once the stat has run: left at their positions (`:identity`), piled on one another (`:stack`), piled to the same height (`:fill`), set side by side within the width given, `{:dodge, width: width}`, or each taken as that wide and set side by side with the marks it overlaps, `{:dodge2, width: width}`, having no width of their own to share, each moved a small random distance (`:jitter`), set side by side and then each moved a small random distance (`:jitterdodge`), or nudged (`:nudge`), each alone or with its options, as [Positions](#module-positions) says. The default value is `:stack`.

* `:orientation` - The axis each area runs along: `:x`, from 0 up to its `y`, or `:y`, from 0 across to its `x`, for areas that run up the panel. The default value is `:x`.

* `:outline_type` - Which of each band's edges its outline draws: the upper and the lower, each a line (`:both`), the upper alone (`:upper`), the lower alone (`:lower`), or the band's whole border (`:full`). The default value is `:upper`.

* `:alpha` - How opaque every band's fill is, from 0, invisible, to 1, opaque; its outline keeps its colour's own alpha.

* `:color` - The colour of every band's outline, written `colour:` or `color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; no outline when not given.

* `:fill` - The colour every band is filled with: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; when not given, the theme's ink mixed 20% toward its paper, `#333333`, or `#000000CC` under `theme_void/2`, whose paper is clear.

* `:linewidth` - How wide every band's outline is, in millimetres; the theme's `base_line_size` when not given, 0.5 at its default sizes.

* `:linetype` - The line type of every band's outline: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; `:solid` when not given.

* `:lineend` - How a line's ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half the line's width beyond it (`:square`). The default value is `:butt`.

* `:linejoin` - How a line turns a corner: rounded (`:round`), pointed (`:mitre`) or cut off (`:bevel`). The default value is `:round`.

* `:linemitre` - How far a pointed corner may reach, in widths of the line, before it is cut off; 1 or more. The default value is `10.0`.

* `:nudge_x` - How far every mark moves along x from its place, in the units of the x axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

* `:nudge_y` - How far every mark moves along y from its place, in the units of the y axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

    iex> frame =
    ...>   %{"t" => [1, 2, 1, 2], "g" => ["a", "a", "b", "b"], "v" => [1.0, 1.0, 2.0, 2.0]}
    ...>   |> Giggly.Plot.new(%{x: :t, y: :v, fill: :g})
    ...>   |> Giggly.Plot.geom_area()
    ...>   |> Giggly.layer_data()
    iex> Giggly.DataFrame.pull(frame, :ymax)
    [0.0, 3.0, 3.0, 3.0, 3.0, 0.0, 0.0, 2.0, 2.0, 2.0, 2.0, 0.0]

# `geom_bar`

```elixir
@spec geom_bar(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer of bars counting the rows at each `x`. Each bar runs from 0 to the number of rows at
its `x`, or, where `:weight` is mapped, to the sum of their weights, and the y axis is titled
`count`. A row missing its `x` is not counted. The bars are drawn as `geom_col/3` draws them.

Counting uses `:x` or `:y`, `:weight` and `:group`, and needs exactly one of `:x` and `:y`: it
counts along the one mapped, so mapping `:y` alone draws horizontal bars. A `:weight` column must
hold numbers. The bars also take `:alpha`, `:fill`, `:color`, `:linetype` and `:linewidth`; one
reaches a bar only where it is the same in every row the bar counts, so a discrete one groups the
rows and gives each group its own bar. Each bar is 0.9 times the closest spacing of the `x`
positions wide, counting from zero, 0.9 on a discrete axis, unless `width:` says otherwise; counting gives every bar its
width, so `:width` is not mapped. `just:` places each bar against its `x`.

Counting computes `count` and `prop`, the count's share of its group's total, which a mapping
reads with an after_stat (`Giggly.Mapping`): `%{x: :class, y: {:after_stat, [:prop]}, group: 1}`
draws each class's share of all the rows.

## Options

* `:data` (`t:term/0`) - A table for the layer to draw instead of the plot's data, anything implementing `Table.Reader`. The plot's mapping applies to it, so it must hold each column the plot's mapping names for an aesthetic the layer neither maps nor sets. Under a facet, a table lacking a faceting column is drawn in every panel of that column's values.

* `:position` - Where the marks are moved once the stat has run: left at their positions (`:identity`), piled on one another (`:stack`), piled to the same height (`:fill`), set side by side within the width one mark takes or the width given (`:dodge`), set side by side, each its share of their widths, with a gap between them (`:dodge2`), each moved a small random distance (`:jitter`), set side by side and then each moved a small random distance (`:jitterdodge`), or nudged (`:nudge`), each alone or with its options, as [Positions](#module-positions) says. The default value is `:stack`.

* `:orientation` - The axis the layer runs along, `:x` or `:y`, which must be the one of `:x` and `:y` mapped; it runs along that one when this is not given.

* `:width` - How wide every bar is, in the units of the axis it stands on, any number; it replaces the width the bars would take otherwise, and a mapped `:width`.

* `:just` - Where each bar sits against its position, a number from 0 to 1: 0 puts its lower edge there, 1 its upper edge, and 0.5 centres it. The default value is `0.5`.

* `:alpha` - How opaque every mark is, from 0, invisible, to 1, opaque.

* `:color` - The colour of every bar's border, written `colour:` or `color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; no border when not given. A border takes no alpha but its colour's own.

* `:fill` - The colour every bar is filled with: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; when not given, the theme's ink mixed 35% toward its paper, `#595959`, or `#000000A6` under `theme_void/2`, whose paper is clear.

* `:linewidth` - How wide every bar's border is, in millimetres; the theme's `base_line_size` when not given, 0.5 at its default sizes.

* `:linetype` - The line type of every bar's border: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; `:solid` when not given.

* `:nudge_x` - How far every mark moves along x from its place, in the units of the x axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

* `:nudge_y` - How far every mark moves along y from its place, in the units of the y axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

    iex> plot =
    ...>   %{"class" => ["suv", "compact", "suv"]}
    ...>   |> Giggly.Plot.new(%{x: :class})
    ...>   |> Giggly.Plot.geom_bar()
    iex> frame = Giggly.layer_data(plot)
    iex> Giggly.DataFrame.pull(frame, :count)
    [1.0, 2.0]

# `geom_boxplot`

```elixir
@spec geom_boxplot(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer of box plots, a box for each group summarising its `y`: from its lower quartile to
its upper, a line across it at its median, and whiskers out to the least and greatest `y` within
`coef:` heights of the box beyond it, every value further out drawn as a point, an outlier. The
quartiles are R's default (type 7). Each box stands at the middle of its group's `x` values,
0.75 times the closest spacing of the `x` positions wide, counting from zero, 0.75 on a
discrete axis, or 0.9 of the
range of its group's `x` values where they are several, or as wide as its group's first mapped
`:width`, a number, or as `width:` says. A row missing its `x` or `y`, or at an infinite one, is
left out.

Boxes stand along the discrete one of `x` and `y`, so mapping a discrete `y` beside a numeric `x`
draws horizontal boxes summarising `x`; mapping one of them alone summarises it, a single box at
0; where both are continuous, they stand along the axis on which every group holds one value,
or else along `x`, each group a box, so a numeric `x` takes a `:group` to draw more than one.
`orientation:` says which. Boxes sharing a position are set side by side, as `position:` says.
Raises `ArgumentError` for `varwidth: true` beside a position other than `:dodge2`, or beside
`{:dodge2, preserve: :total}`, since each box keeps its own width.

Box plots use `:x`, `:y`, `:group`, `:width`, `:alpha`, `:color`, `:fill`, `:linetype` and
`:linewidth`, and `:shape` and `:size`, which the outliers take, and need `:x` or `:y`. A look
reaches a box only where it is the same in every row of its group, so a discrete one groups the
rows and gives each group its own box. A box plot is not weighted, so a `:weight` the plot's
mapping gives is refused. The whiskers, staples, median and box's border each take a look of
their own (`whisker_color:` and the like), and the outliers theirs (`outlier_color:` and the
like), else the box's.

## Options

* `:data` (`t:term/0`) - A table for the layer to draw instead of the plot's data, anything implementing `Table.Reader`. The plot's mapping applies to it, so it must hold each column the plot's mapping names for an aesthetic the layer neither maps nor sets. Under a facet, a table lacking a faceting column is drawn in every panel of that column's values.

* `:position` - Where the boxes are moved once the stat has run: set side by side, each its share of their widths, with a gap between them (`:dodge2`), set side by side within the width one box takes or the width given (`:dodge`), left at their positions (`:identity`), or nudged (`:nudge`), each alone or with its options, as [Positions](#module-positions) says. With `varwidth: true`, every box keeps its own width, which only `:dodge2` lays side by side, and so it is the only position taken, its `preserve:` `:single`. The default value is `:dodge2`.

* `:coef` - How far the whiskers may reach past the box, in heights of the box; a value further out is an outlier. The default value is `1.5`.

* `:width` - How wide a box is, in the units of the axis it stands on, any number; it replaces a mapped `:width`, and gives way to 0.9 of the range of a group spanning several positions. 0.75 times the closest spacing of the positions, counting from zero, when not given.

* `:orientation` - The axis the boxes stand along, `:x` or `:y`, summarising the other. Where one of `:x` and `:y` is mapped, the boxes summarise it, so this must name the other; where both are, it chooses, and when not given the boxes stand along the discrete one, or else along the axis on which every group holds one value, or else along x.

* `:outliers` (`t:boolean/0`) - Whether to keep the outliers, drawing them and fitting the axes to them; `false` leaves them out, the axes fitting the whiskers. `outlier_shape: :none` hides them and keeps the axes. The default value is `true`.

* `:outlier_color` - The outliers' colour, written `outlier_colour:` or `outlier_color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; the box's when not given.

* `:outlier_fill` - The colour outliers of a shape with a fill of their own are filled with: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; the box's fill when not given.

* `:outlier_shape` - The shape the outliers are drawn in, by name or number, as `geom_point/3` takes one, or `:none` for none; the box's `:shape` when not given.

* `:outlier_size` - How big the outliers are, in millimetres; the box's `:size`, the theme's points' size unless the layer sets one, when not given.

* `:outlier_stroke` - How heavy the outliers' outlines are, in millimetres, or `:none` for none. The default value is `0.5`.

* `:outlier_alpha` - How opaque the outliers are, from 0 to 1; the box's alpha when not given.

* `:whisker_color` - The colour of the whiskers, written `whisker_colour:` or `whisker_color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; the box's colour when not given.

* `:whisker_linetype` - The line type of the whiskers: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; the box's when not given.

* `:whisker_linewidth` - How wide the whiskers is drawn, in millimetres; the box's line width when not given.

* `:staple_color` - The colour of the staples, written `staple_colour:` or `staple_color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; the box's colour when not given.

* `:staple_linetype` - The line type of the staples: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; the box's when not given.

* `:staple_linewidth` - How wide the staples is drawn, in millimetres; the box's line width when not given.

* `:median_color` - The colour of the median, written `median_colour:` or `median_color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; the box's colour when not given.

* `:median_linetype` - The line type of the median: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; the box's when not given.

* `:median_linewidth` - How wide the median is drawn, in millimetres; the box's line width when not given, doubled.

* `:box_color` - The colour of the box's border, written `box_colour:` or `box_color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; the box's colour when not given.

* `:box_linetype` - The line type of the box's border: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; the box's when not given.

* `:box_linewidth` - How wide the box's border is drawn, in millimetres; the box's line width when not given.

* `:notch` (`t:boolean/0`) - Whether to notch each box at its median, the notches reaching 1.58 heights of the box over the square root of its rows either side, so boxes whose notches do not overlap have medians that differ. The default value is `false`.

* `:notchwidth` - How wide a notched box is at its median, a share of its width. The default value is `0.5`.

* `:staplewidth` - How wide the staples across the whiskers' ends are, a share of the box's width; 0 draws none. The default value is `0.0`.

* `:varwidth` (`t:boolean/0`) - Whether to draw each box as wide as the square root of its rows makes it beside the widest. The default value is `false`.

* `:alpha` - How opaque every box's fill and outliers are, from 0 to 1; its lines take none.

* `:color` - The colour of every box's lines and outliers, written `colour:` or `color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; when not given, the theme's ink mixed 20% toward its paper, `#333333`, or `#000000CC` under `theme_void/2`.

* `:fill` - The colour every box is filled with: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; the theme's paper when not given, white, or clear under `theme_void/2`.

* `:linewidth` - How wide every box's lines are, in millimetres; the theme's `base_line_size` when not given, 0.5 at its default sizes.

* `:linetype` - The line type of every box's lines: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; `:solid` when not given.

* `:shape` - The shape every box's outliers are drawn in, as `outlier_shape:` takes one, which wins over it.

* `:size` - How big every box's outliers are, in millimetres, as `outlier_size:` takes it, which wins over it.

* `:nudge_x` - How far every mark moves along x from its place, in the units of the x axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

* `:nudge_y` - How far every mark moves along y from its place, in the units of the y axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

    iex> plot =
    ...>   %{"g" => ["a", "a", "a", "a", "a"], "y" => [1.0, 2.0, 3.0, 4.0, 20.0]}
    ...>   |> Giggly.Plot.new(%{x: :g, y: :y})
    ...>   |> Giggly.Plot.geom_boxplot()
    iex> frame = Giggly.layer_data(plot)
    iex> {Giggly.DataFrame.pull(frame, :middle), Giggly.DataFrame.pull(frame, :outliers)}
    {[3.0], [[20.0]]}

# `geom_col`

```elixir
@spec geom_col(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer of bars, one per row, each from 0 to its `y` and centred on its `x` unless `just:`
says otherwise, for bars whose heights are in the data. Bars at the same `x` are stacked, those
below zero downward, the highest group at the bottom; with `position: :dodge` they are set side
by side within one bar's width, an `x` with one group keeping its whole width; with `position:
:dodge2`, alone or with its options, bars whose spans overlap are set side by side, each its
share of their widths, with a gap between them.

Each bar is 0.9 times the closest spacing of the `x` positions wide: 0.9 on a discrete axis
whose neighbouring levels the layer holds, and 1.8 where it skips one, and on a continuous one
0.9 times the closest gap, a column of integers spaced as any numbers are; or as
wide as its mapped `:width`, a number, or as `width:` makes every bar, which wins over a mapped
one. `just:` places each bar against its `x`, its lower edge there at 0 and its upper at 1. Bars
of different widths at one `x` are dodged together only by `:dodge2`. The `y` axis reaches 0.

Bars use `:x`, `:y`, `:group`, `:alpha`, `:fill`, `:color`, `:linetype`, `:linewidth` and
`:width`, and need `:x` and `:y`. `:fill` fills a bar and takes its alpha; `:color` borders it,
and bars have no border unless it is mapped or set; `:linewidth` and `:linetype` say how wide
the border is and how it is dashed. With a discrete `y` and a continuous `x`, the bars are
horizontal.

## Options

* `:data` (`t:term/0`) - A table for the layer to draw instead of the plot's data, anything implementing `Table.Reader`. The plot's mapping applies to it, so it must hold each column the plot's mapping names for an aesthetic the layer neither maps nor sets. Under a facet, a table lacking a faceting column is drawn in every panel of that column's values.

* `:position` - Where the marks are moved once the stat has run: left at their positions (`:identity`), piled on one another (`:stack`), piled to the same height (`:fill`), set side by side within the width one mark takes or the width given (`:dodge`), set side by side, each its share of their widths, with a gap between them (`:dodge2`), each moved a small random distance (`:jitter`), set side by side and then each moved a small random distance (`:jitterdodge`), or nudged (`:nudge`), each alone or with its options, as [Positions](#module-positions) says. The default value is `:stack`.

* `:width` - How wide every bar is, in the units of the axis it stands on, any number; it replaces the width the bars would take otherwise, and a mapped `:width`.

* `:just` - Where each bar sits against its position, a number from 0 to 1: 0 puts its lower edge there, 1 its upper edge, and 0.5 centres it. The default value is `0.5`.

* `:alpha` - How opaque every mark is, from 0, invisible, to 1, opaque.

* `:color` - The colour of every bar's border, written `colour:` or `color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; no border when not given. A border takes no alpha but its colour's own.

* `:fill` - The colour every bar is filled with: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; when not given, the theme's ink mixed 35% toward its paper, `#595959`, or `#000000A6` under `theme_void/2`, whose paper is clear.

* `:linewidth` - How wide every bar's border is, in millimetres; the theme's `base_line_size` when not given, 0.5 at its default sizes.

* `:linetype` - The line type of every bar's border: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; `:solid` when not given.

* `:nudge_x` - How far every mark moves along x from its place, in the units of the x axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

* `:nudge_y` - How far every mark moves along y from its place, in the units of the y axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

    iex> plot =
    ...>   %{"trt" => ["a", "b", "c"], "outcome" => [2.3, 1.9, 3.2]}
    ...>   |> Giggly.Plot.new(%{x: :trt, y: :outcome})
    ...>   |> Giggly.Plot.geom_col()
    iex> frame = Giggly.layer_data(plot)
    iex> Giggly.DataFrame.pull(frame, :ymin)
    [0.0, 0.0, 0.0]
    iex> Giggly.DataFrame.pull(frame, :ymax)
    [2.3, 1.9, 3.2]

Dodged, the two groups at `a` share its width, and `b`'s one group keeps all of it:

    iex> plot =
    ...>   %{"x" => ["a", "a", "b"], "y" => [1.0, 2.0, 3.0], "g" => ["p", "q", "p"]}
    ...>   |> Giggly.Plot.new(%{x: :x, y: :y, group: :g})
    ...>   |> Giggly.Plot.geom_col(position: :dodge)
    iex> frame = Giggly.layer_data(plot)
    iex> Giggly.DataFrame.pull(frame, :xmin)
    [0.55, 1.0, 1.55]

# `geom_count`

```elixir
@spec geom_count(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer of points counting the rows at each place: one point for each combination of `x`,
`y` and the layer's other aesthetics that its rows hold, sized by how many rows hold it, or,
where `:weight` is mapped, by the sum of their weights, and the size legend titled `n`. The
points are drawn as `geom_point/3` draws them.

Counting uses `:x`, `:y`, `:weight` and `:group`, and needs `:x` and `:y`. A `:weight` column must
hold numbers, and a missing weight leaves its place's count missing, so no point is drawn there.
The points also take `:alpha`, `:color`, `:fill`, `:shape` and `:size`; each is counted over, as
`:group` is, so a discrete colour gives each of its values at a place a point of its own, and a
mapped `:size` sizes the points by its column instead of the count. A row missing its `x` or `y`
is not counted.

Counting computes `n` and `prop`, the count's share of its group's total in its panel, which a
mapping reads with an after_stat (`Giggly.Mapping`): `%{size: {:after_stat, [:prop]}, group: 1}`
sizes each point by its share of all the rows.

## Options

* `:data` (`t:term/0`) - A table for the layer to draw instead of the plot's data, anything implementing `Table.Reader`. The plot's mapping applies to it, so it must hold each column the plot's mapping names for an aesthetic the layer neither maps nor sets. Under a facet, a table lacking a faceting column is drawn in every panel of that column's values.

* `:position` - Where the marks are moved once the stat has run: left at their positions (`:identity`), piled on one another (`:stack`), piled to the same height (`:fill`), set side by side within the width given, `{:dodge, width: width}`, or each taken as that wide and set side by side with the marks it overlaps, `{:dodge2, width: width}`, having no width of their own to share, each moved a small random distance (`:jitter`), set side by side and then each moved a small random distance (`:jitterdodge`), or nudged (`:nudge`), each alone or with its options, as [Positions](#module-positions) says. The default value is `:identity`.

* `:alpha` - How opaque every mark is, from 0, invisible, to 1, opaque.

* `:color` - The colour of every point, written `colour:` or `color:`, which outlines its shape and fills the shapes filled in it: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; black when not given.

* `:fill` - The colour every point of a shape with a fill of its own is filled with: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; none when not given.

* `:shape` - The shape every point is drawn in, by its name or its number, as listed above, or `:none` for no point; `:circle` when not given.

* `:size` - How big every point is, in millimetres; 1.5 times the theme's `base_size` over 11 when not given, 1.5 at its default sizes.

* `:stroke` - How heavy every point's outline is, in millimetres, or `:none` for no outline and no lines; the theme's `base_line_size` when not given, 0.5 at its default sizes. The outline is drawn half that wide, and a heavier stroke makes the shape bigger too.

* `:nudge_x` - How far every mark moves along x from its place, in the units of the x axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

* `:nudge_y` - How far every mark moves along y from its place, in the units of the y axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

    iex> plot =
    ...>   %{"cty" => [18, 18, 21], "hwy" => [29, 29, 29]}
    ...>   |> Giggly.Plot.new(%{x: :cty, y: :hwy})
    ...>   |> Giggly.Plot.geom_count()
    iex> frame = Giggly.layer_data(plot)
    iex> Giggly.DataFrame.pull(frame, :n)
    [2.0, 1.0]
    iex> Giggly.DataFrame.pull(frame, :size)
    [6.0, 1.0]

# `geom_crossbar`

```elixir
@spec geom_crossbar(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer of crossbars: a box for each row from its `ymin` to its `ymax`, with a line across
it at its `y`, for a value and the interval round it, or, turned, a box from its `xmin` to its
`xmax` with a line up it at its `x`.

Crossbars use a line range's aesthetics, `:fill` and `:width`, and need `:x` and `:y` and the
range a line range runs along, as `geom_linerange/3` takes it. Each box is as wide as the row's
`width`, as `geom_errorbar/3` sizes its whiskers. Every box is drawn before every line across,
which is 2.5 times as wide as the box's border unless `middle_linewidth:` says otherwise; the
box's fill takes the row's alpha, its border and line across their colour's own. The
`middle_` and `box_` options give the line across and the box's border a look of their own.

Raises `ArgumentError` where the layer lacks one of the three positions its boxes run along, and
where a mapped `:width` is not a number.

## Options

* `:data` (`t:term/0`) - A table for the layer to draw instead of the plot's data, anything implementing `Table.Reader`. The plot's mapping applies to it, so it must hold each column the plot's mapping names for an aesthetic the layer neither maps nor sets. Under a facet, a table lacking a faceting column is drawn in every panel of that column's values.

* `:position` - Where the marks are moved once the stat has run: left at their positions (`:identity`), piled on one another (`:stack`), piled to the same height (`:fill`), set side by side within the width one mark takes or the width given (`:dodge`), set side by side, each its share of their widths, with a gap between them (`:dodge2`), each moved a small random distance (`:jitter`), set side by side and then each moved a small random distance (`:jitterdodge`), or nudged (`:nudge`), each alone or with its options, as [Positions](#module-positions) says. The default value is `:identity`.

* `:orientation` - Which way each range runs: `:x`, up the panel from `ymin` to `ymax` at each `x`, or `:y`, across it from `xmin` to `xmax` at each `y`; when not given, `:y` where the layer is given neither `:ymin` nor `:ymax`, and `:x` otherwise.

* `:width` - How wide every mark is, in the units of the axis it is placed along, x, or y for one that runs across the panel, any number; 0.9 of the closest spacing of the positions there when not given, 0.9 on a discrete axis. It replaces a mapped `:width`.

* `:alpha` - How opaque every box's fill is, from 0, invisible, to 1, opaque; its lines keep their colour's own alpha.

* `:color` - The colour of every box's border and line across, written `colour:` or `color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; black when not given.

* `:fill` - The colour every box is filled with: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; none when not given.

* `:linewidth` - How wide every box's border is, in millimetres, its line across 2.5 times as wide; the theme's `base_line_size` when not given, 0.5 at its default sizes.

* `:linetype` - The line type of every box's border and line across: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; `:solid` when not given.

* `:middle_color` - The colour of the line across each box, written `middle_colour:` or `middle_color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; the crossbar's colour when not given.

* `:middle_linetype` - The line type of the line across each box: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; the crossbar's when not given.

* `:middle_linewidth` - How wide the line across each box is drawn, in millimetres; the crossbar's line width when not given, times 2.5.

* `:box_color` - The colour of the box's border, written `box_colour:` or `box_color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; the crossbar's colour when not given.

* `:box_linetype` - The line type of the box's border: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; the crossbar's when not given.

* `:box_linewidth` - How wide the box's border is drawn, in millimetres; the crossbar's line width when not given.

* `:lineend` - How a line's ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half the line's width beyond it (`:square`). The default value is `:butt`.

* `:linejoin` - How a box's border turns a corner: pointed (`:mitre`), rounded (`:round`) or cut off (`:bevel`). The default value is `:mitre`.

* `:nudge_x` - How far every mark moves along x from its place, in the units of the x axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

* `:nudge_y` - How far every mark moves along y from its place, in the units of the y axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

    iex> frame =
    ...>   %{"trt" => [1, 2], "resp" => [1.0, 3.0], "lower" => [0.8, 2.4], "upper" => [1.1, 3.3]}
    ...>   |> Giggly.Plot.new(%{x: :trt, y: :resp})
    ...>   |> Giggly.Plot.geom_crossbar(%{ymin: :lower, ymax: :upper}, middle_colour: "red")
    ...>   |> Giggly.layer_data()
    iex> {Giggly.DataFrame.pull(frame, :xmin), Giggly.DataFrame.pull(frame, :xmax)}
    {[0.55, 1.55], [1.45, 2.45]}

# `geom_density`

```elixir
@spec geom_density(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer of densities: for each group, a smoothed estimate of how its rows are distributed
along `x`, a smoothed histogram drawn as a curve over the area beneath it, for a variable that
comes from a smooth distribution.

Each curve is a kernel density estimate: a kernel, a normal curve unless `kernel:` says
otherwise, put at each row and summed, its spread the bandwidth, `bw:` times `adjust:`, so a
narrower one follows the rows more closely. Each row weighs as its `:weight` where one is mapped,
the weights taking their share of their group's total. A curve spans the whole x axis, short of
its widening, at `n:` evenly spaced places, so curves of different groups share their places,
unless `trim: true` keeps each to its own group's extent. With `bounds:`, rows outside them are
left out, and the part of a curve beyond a finite bound is folded back inside it.

Densities use `:x` or `:y`, `:weight`, `:group`, `:alpha`, `:fill`, `:color`, `:linetype` and
`:linewidth`, and need exactly one of `:x` and `:y`: the curve runs along the one mapped, so
mapping `:y` alone draws curves that run up the panel. A `:weight` column must hold numbers. Each
curve is outlined along its top in the theme's ink and left unfilled unless a fill is mapped or
set; curves are drawn over one another unless `position: :stack` piles them. A row missing its
`x`, or at an infinite one, is left out. A group of fewer than two rows is a single row of
missing values, drawn as nothing. A panel where some group's weight is missing, infinite or
below 0, or adds up to 0, or where a rule gives no bandwidth above 0, as for rows all at one
`x`, is drawn nothing.

A density computes each place's `density`; `count`, the density times the group's rows, whose
curves add up when stacked; `wdensity`, the density times the group's total weight; `scaled` and
`ndensity`, the density over the group's greatest; and `n`, the group's rows, which a mapping
reads with an after_stat (`Giggly.Mapping`): `%{x: :carat, y: {:after_stat, [:count]}, fill:
:cut}` with `position: :stack` piles each cut's curve to the density of every diamond. The y
axis is titled `density` unless something else is mapped there.

## Options

* `:data` (`t:term/0`) - A table for the layer to draw instead of the plot's data, anything implementing `Table.Reader`. The plot's mapping applies to it, so it must hold each column the plot's mapping names for an aesthetic the layer neither maps nor sets. Under a facet, a table lacking a faceting column is drawn in every panel of that column's values.

* `:position` - Where the marks are moved once the stat has run: left at their positions (`:identity`), piled on one another (`:stack`), piled to the same height (`:fill`), set side by side within the width given, `{:dodge, width: width}`, or each taken as that wide and set side by side with the marks it overlaps, `{:dodge2, width: width}`, having no width of their own to share, each moved a small random distance (`:jitter`), set side by side and then each moved a small random distance (`:jitterdodge`), or nudged (`:nudge`), each alone or with its options, as [Positions](#module-positions) says. The default value is `:identity`.

* `:outline_type` - Which of each band's edges its outline draws: the upper and the lower, each a line (`:both`), the upper alone (`:upper`), the lower alone (`:lower`), or the band's whole border (`:full`). The default value is `:upper`.

* `:bw` - How smooth each curve is, its bandwidth, the kernel's standard deviation in the axis's transformed units: a number above 0, or a rule worked out from each group's rows, taking no weight: Silverman's rule of thumb (`:nrd0`), 0.9 times the lesser of the rows' standard deviation and their interquartile range over 1.34, times the rows to the power -0.2, or Scott's variation of it (`:nrd`), 1.06 times the lesser. The default value is `:nrd0`.

* `:adjust` - A multiple of the bandwidth, above 0: `adjust: 0.5` halves it, for a curve that follows the rows more closely, and `adjust: 2` doubles it, for a smoother one. The default value is `1.0`.

* `:kernel` - The shape put at each row and summed, scaled so its standard deviation is the bandwidth: a normal curve (`:gaussian`), a parabola (`:epanechnikov`), a block (`:rectangular`), a tent (`:triangular`), a parabola squared (`:biweight`), or a cosine's hump (`:cosine`) or a narrower one (`:optcosine`). The default value is `:gaussian`.

* `:n` (`t:pos_integer/0`) - How many evenly spaced places each curve is worked out at, twice as many with one finite bound and three times with two. The default value is `512`.

* `:trim` (`t:boolean/0`) - Whether each curve spans only its own group's extent rather than the panel's axis, short of its widening; trimmed curves no longer share their places, so they do not stack. The default value is `false`.

* `:bounds` - Limits the rows are known to lie within, `{low, high}`, the low a number or `:neg_infinity`, the high a number or `:infinity`, not below the low: the rows outside them are left out, and each curve's part beyond a finite one is folded back inside it, so the curve does not spill past a limit the data cannot. The default value is `{:neg_infinity, :infinity}`.

* `:orientation` - The axis the layer runs along, `:x` or `:y`, which must be the one of `:x` and `:y` mapped; it runs along that one when this is not given.

* `:alpha` - How opaque every curve's fill is, from 0, invisible, to 1, opaque; its outline keeps its colour's own alpha.

* `:color` - The colour of every curve's outline, written `colour:` or `color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; the theme's ink, black, when not given.

* `:fill` - The colour every curve is filled with down to 0: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; none when not given.

* `:linewidth` - How wide every curve's outline is, in millimetres; the theme's `base_line_size` when not given, 0.5 at its default sizes.

* `:linetype` - The line type of every curve's outline: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; `:solid` when not given.

* `:lineend` - How a line's ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half the line's width beyond it (`:square`). The default value is `:butt`.

* `:linejoin` - How a line turns a corner: rounded (`:round`), pointed (`:mitre`) or cut off (`:bevel`). The default value is `:round`.

* `:linemitre` - How far a pointed corner may reach, in widths of the line, before it is cut off; 1 or more. The default value is `10.0`.

* `:nudge_x` - How far every mark moves along x from its place, in the units of the x axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

* `:nudge_y` - How far every mark moves along y from its place, in the units of the y axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

    iex> frame =
    ...>   %{"x" => [1.0, 2.0, 4.0, 4.0]}
    ...>   |> Giggly.Plot.new(%{x: :x})
    ...>   |> Giggly.Plot.geom_density(n: 3)
    ...>   |> Giggly.layer_data()
    iex> {Giggly.DataFrame.pull(frame, :x), Giggly.DataFrame.pull(frame, :n)}
    {[1.0, 2.5, 4.0], [4, 4, 4]}

# `geom_errorbar`

```elixir
@spec geom_errorbar(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer of error bars: a vertical line for each row from its `ymin` to its `ymax` at its
`x`, with a whisker across each end, for an interval round a value, or, turned, a horizontal
one from its `xmin` to its `xmax` at its `y`.

Error bars use a line range's aesthetics and `:width`, and run up or across the panel as
`geom_linerange/3`'s ranges do. Each whisker is as wide as the row's `width`, mapped or set, or
else 0.9 of the closest spacing of the positions along the axis the bars are placed on, so bars
at neighbouring positions never meet. A row missing a position draws none of its lines that
need it, and each bar takes its own row's colour, alpha, width and line type.

Raises `ArgumentError` where the layer lacks one of the three positions its bars run along, and
where a mapped `:width` is not a number.

## Options

* `:data` (`t:term/0`) - A table for the layer to draw instead of the plot's data, anything implementing `Table.Reader`. The plot's mapping applies to it, so it must hold each column the plot's mapping names for an aesthetic the layer neither maps nor sets. Under a facet, a table lacking a faceting column is drawn in every panel of that column's values.

* `:position` - Where the marks are moved once the stat has run: left at their positions (`:identity`), piled on one another (`:stack`), piled to the same height (`:fill`), set side by side within the width one mark takes or the width given (`:dodge`), set side by side, each its share of their widths, with a gap between them (`:dodge2`), each moved a small random distance (`:jitter`), set side by side and then each moved a small random distance (`:jitterdodge`), or nudged (`:nudge`), each alone or with its options, as [Positions](#module-positions) says. The default value is `:identity`.

* `:orientation` - Which way each range runs: `:x`, up the panel from `ymin` to `ymax` at each `x`, or `:y`, across it from `xmin` to `xmax` at each `y`; when not given, `:y` where the layer is given neither `:ymin` nor `:ymax`, and `:x` otherwise.

* `:width` - How wide every mark is, in the units of the axis it is placed along, x, or y for one that runs across the panel, any number; 0.9 of the closest spacing of the positions there when not given, 0.9 on a discrete axis. It replaces a mapped `:width`.

* `:alpha` - How opaque every mark is, from 0, invisible, to 1, opaque.

* `:color` - The colour of every line, written `colour:` or `color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; black when not given.

* `:linewidth` - How wide every line is, in millimetres; the theme's `base_line_size` when not given, 0.5 at its default sizes.

* `:linetype` - The line type of every line: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; `:solid` when not given.

* `:lineend` - How a line's ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half the line's width beyond it (`:square`). The default value is `:butt`.

* `:nudge_x` - How far every mark moves along x from its place, in the units of the x axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

* `:nudge_y` - How far every mark moves along y from its place, in the units of the y axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

    iex> frame =
    ...>   %{"trt" => [1, 2], "resp" => [1.0, 3.0], "lower" => [0.8, 2.4], "upper" => [1.1, 3.3]}
    ...>   |> Giggly.Plot.new(%{x: :trt, y: :resp})
    ...>   |> Giggly.Plot.geom_errorbar(%{ymin: :lower, ymax: :upper}, width: 0.2)
    ...>   |> Giggly.layer_data()
    iex> {Giggly.DataFrame.pull(frame, :xmin), Giggly.DataFrame.pull(frame, :xmax)}
    {[0.9, 1.9], [1.1, 2.1]}

# `geom_freqpoly`

```elixir
@spec geom_freqpoly(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer of frequency polygons: the `x` axis cut into bins, as `geom_histogram/3` cuts it,
and for each group a line through the middle of each bin at the number of rows in it, or, where
`:weight` is mapped, the sum of their weights. A bin of no rows is added at each end, so every
line starts and ends at 0. The y axis is titled `count`. The lines of different groups are drawn
over one another, not stacked, so a discrete colour compares the groups' distributions. A row
missing its `x`, or outside the breaks given, is not counted. The lines are drawn as
`geom_path/3` draws paths.

Binning uses `:x` or `:y`, `:weight` and `:group`, and needs exactly one of `:x` and `:y`, on a
continuous axis: it bins along the one mapped, so mapping `:y` alone draws lines that run up the
panel. A `:weight` column must hold numbers, and a missing weight adds nothing. The lines also
take `:alpha`, `:color`, `:linetype` and `:linewidth`; one reaches a line only where it is the
same in every row of its group, so a discrete one groups the rows and gives each group its line.

Binning computes what `geom_histogram/3` lists, which a mapping reads with an after_stat
(`Giggly.Mapping`): `%{x: :price, y: {:after_stat, [:density]}, color: :cut}` draws each cut's
density, comparable however many rows each cut has.

## Options

* `:data` (`t:term/0`) - A table for the layer to draw instead of the plot's data, anything implementing `Table.Reader`. The plot's mapping applies to it, so it must hold each column the plot's mapping names for an aesthetic the layer neither maps nor sets. Under a facet, a table lacking a faceting column is drawn in every panel of that column's values.

* `:position` - Where the marks are moved once the stat has run: left at their positions (`:identity`), piled on one another (`:stack`), piled to the same height (`:fill`), set side by side within the width one mark takes or the width given (`:dodge`), set side by side, each its share of their widths, with a gap between them (`:dodge2`), each moved a small random distance (`:jitter`), set side by side and then each moved a small random distance (`:jitterdodge`), or nudged (`:nudge`), each alone or with its options, as [Positions](#module-positions) says. The default value is `:identity`.

* `:bins` (`t:pos_integer/0`) - How many bins span the axis, when neither `binwidth:` nor `breaks:` is given. The default value is `30`.

* `:binwidth` - How wide each bin is, a number above 0 in the axis's transformed units, which takes the place of `bins:`.

* `:center` - Where one bin's middle falls, which places them all; not with `boundary:`.

* `:boundary` - Where two bins meet, which places them all; not with `center:`. Without either, the outermost bins are centred on the axis's limits, or bins `binwidth:` wide meet half a width from 0.

* `:breaks` - Where the bins meet, a list of two or more distinct numbers in the data's units, put through the axis's transformation, which takes the place of `bins:`, `binwidth:`, `center:` and `boundary:`; a row outside them is not counted.

* `:closed` - Which end of a bin a value on its edge belongs to: the right end (`:right`), or the left (`:left`); the outermost bins hold their outer ends too. The default value is `:right`.

* `:drop` - Which bins of no rows to leave out: none (`:none`), every one (`:all`), or those before the first bin with rows and after the last (`:extremes`). The default value is `:none`.

* `:orientation` - The axis the layer runs along, `:x` or `:y`, which must be the one of `:x` and `:y` mapped; it runs along that one when this is not given.

* `:alpha` - How opaque every mark is, from 0, invisible, to 1, opaque.

* `:color` - The colour of every line, written `colour:` or `color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; black when not given.

* `:linewidth` - How wide every line is, in millimetres; the theme's `base_line_size` when not given, 0.5 at its default sizes.

* `:linetype` - The line type of every line: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; `:solid` when not given.

* `:arrow` - An arrowhead on each line: `true` for the defaults, or a keyword list of its options, `angle:` (30), `length:` (`{0.25, :in}`, in `:pt`, `:cm`, `:mm` or `:in`), `ends:` (`:last`, `:first` or `:both`), `type:` (`:open` or `:closed`) and `fill:`, a closed head's, a colour, `:none`, or `:color`, the line's colour and the default; none when not given.

* `:lineend` - How a line's ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half the line's width beyond it (`:square`). The default value is `:butt`.

* `:linejoin` - How a line turns a corner: rounded (`:round`), pointed (`:mitre`) or cut off (`:bevel`). The default value is `:round`.

* `:linemitre` - How far a pointed corner may reach, in widths of the line, before it is cut off; 1 or more. The default value is `10.0`.

* `:nudge_x` - How far every mark moves along x from its place, in the units of the x axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

* `:nudge_y` - How far every mark moves along y from its place, in the units of the y axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

    iex> plot =
    ...>   %{"x" => [1.0, 1.5, 2.5, 4.0]}
    ...>   |> Giggly.Plot.new(%{x: :x})
    ...>   |> Giggly.Plot.geom_freqpoly(binwidth: 1, boundary: 0)
    iex> frame = Giggly.layer_data(plot)
    iex> Giggly.DataFrame.pull(frame, :x)
    [0.5, 1.5, 2.5, 3.5, 4.5]
    iex> Giggly.DataFrame.pull(frame, :count)
    [0.0, 2.0, 1.0, 1.0, 0.0]

# `geom_hex`

```elixir
@spec geom_hex(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer of hexagons counting the rows in each, hexagonal binning: the plane cut into
hexagons, each standing on a point, and for each group one hexagon wherever a row falls, filled
by how many rows fall in it, or, where `:weight` is mapped, by the sum of their weights. A
heatmap of two continuous variables, it shows where many rows overlap, as points drawn over
one another cannot.

The hexagons are 30 across each panel's x and y axes unless `bins:` or `binwidth:` says
otherwise; each group's hexagons start from its own rows, so groups are binned apart. A row
falls in the hexagon whose centre is nearest. A row missing its `x` or `y`, or at an infinite
one, is not counted. A panel where an axis has no extent, as for rows all at one `x`, is drawn
nothing.

Hexagonal binning uses `:x`, `:y`, `:weight` and `:group`, and needs `:x` and `:y`. A `:weight`
column must hold numbers. The hexagons also take `:alpha`, `:fill`, `:color`, `:linetype` and
`:linewidth`; one reaches a hexagon only where it is the same in every row of its group, so a
discrete one groups the rows. Each is filled by its count through the fill scale, which titles
the legend `count`, unless a fill is mapped or set, and drawn without a border unless a colour
is mapped or set.

Hexagonal binning computes, for each hexagon, `count`; `density`, the count over the group's
total; and `ncount` and `ndensity`, the count and the density over the group's largest. A
mapping reads them with an after_stat (`Giggly.Mapping`): `%{x: :carat, y: :price, fill:
{:after_stat, [:density]}}` fills each hexagon by its share of the rows.

## Options

* `:data` (`t:term/0`) - A table for the layer to draw instead of the plot's data, anything implementing `Table.Reader`. The plot's mapping applies to it, so it must hold each column the plot's mapping names for an aesthetic the layer neither maps nor sets. Under a facet, a table lacking a faceting column is drawn in every panel of that column's values.

* `:position` - Where the marks are moved once the stat has run: left at their positions (`:identity`), piled on one another (`:stack`), piled to the same height (`:fill`), set side by side within the width given, `{:dodge, width: width}`, or each taken as that wide and set side by side with the marks it overlaps, `{:dodge2, width: width}`, having no width of their own to share, each moved a small random distance (`:jitter`), set side by side and then each moved a small random distance (`:jitterdodge`), or nudged (`:nudge`), each alone or with its options, as [Positions](#module-positions) says. The default value is `:identity`.

* `:bins` - How many hexagons span each axis, when `binwidth:` is not given: a whole number above 0 for both, or `{x_bins, y_bins}`. The default value is `30`.

* `:binwidth` - How wide and how high each hexagon is, in the axes' transformed units, which takes the place of `bins:`: a number above 0 for both, or `{width, height}`.

* `:alpha` - How opaque every hexagon's fill is, from 0, invisible, to 1, opaque; its border keeps its colour's own alpha.

* `:color` - The colour of every hexagon's border, written `colour:` or `color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; no border when not given.

* `:fill` - The colour every hexagon is filled with: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; when not given, each hexagon is filled by its count, through the fill scale.

* `:linewidth` - How wide every hexagon's border is, in millimetres; the theme's `base_line_size` when not given, 0.5 at its default sizes.

* `:linetype` - The line type of every hexagon's border: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; `:solid` when not given.

* `:lineend` - How a line's ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half the line's width beyond it (`:square`). The default value is `:butt`.

* `:linejoin` - How a border turns a corner: pointed (`:mitre`), rounded (`:round`) or cut off (`:bevel`). The default value is `:mitre`.

* `:linemitre` - How far a pointed corner may reach, in widths of the line, before it is cut off; 1 or more. The default value is `10.0`.

* `:nudge_x` - How far every mark moves along x from its place, in the units of the x axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

* `:nudge_y` - How far every mark moves along y from its place, in the units of the y axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

    iex> frame =
    ...>   %{"x" => [0.0, 0.1, 1.0, 2.0], "y" => [0.0, 0.1, 1.0, 2.0]}
    ...>   |> Giggly.Plot.new(%{x: :x, y: :y})
    ...>   |> Giggly.Plot.geom_hex(binwidth: 1)
    ...>   |> Giggly.layer_data()
    iex> Giggly.DataFrame.pull(frame, :count)
    [2.0, 1.0, 1.0]

# `geom_histogram`

```elixir
@spec geom_histogram(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer of bars counting the rows in each bin, a histogram: the `x` axis cut into bins, and
for each group one bar per bin, from 0 to the number of rows in it, or, where `:weight` is
mapped, to the sum of their weights, a bin with no rows counting 0. The y axis is titled `count`.
The bins are 30 spanning each panel's x axis unless `bins:`, `binwidth:` or `breaks:` says
otherwise; bars of different groups in one bin are stacked. A row missing its `x`, or outside the
breaks given, is not counted. The bars are drawn as `geom_col/3` draws them.

Binning uses `:x` or `:y`, `:weight` and `:group`, and needs exactly one of `:x` and `:y`, on a
continuous axis: it bins along the one mapped, so mapping `:y` alone draws horizontal bars. A
`:weight` column must hold numbers, and a missing weight adds nothing. The bars also take
`:alpha`, `:fill`, `:color`, `:linetype` and `:linewidth`; one reaches a bar only where it is the
same in every row of its group, so a discrete one groups the rows and gives each group its bars.

Binning computes, for each bin, `count`; `density`, the count over the bin's width over the
group's total, so a group's bars cover an area of 1; `ncount` and `ndensity`, the count and the
density over the group's largest; and `width`. A mapping reads them with an after_stat
(`Giggly.Mapping`): `%{x: :hwy, y: {:after_stat, [:density]}}` draws the density.

## Options

* `:data` (`t:term/0`) - A table for the layer to draw instead of the plot's data, anything implementing `Table.Reader`. The plot's mapping applies to it, so it must hold each column the plot's mapping names for an aesthetic the layer neither maps nor sets. Under a facet, a table lacking a faceting column is drawn in every panel of that column's values.

* `:position` - Where the marks are moved once the stat has run: left at their positions (`:identity`), piled on one another (`:stack`), piled to the same height (`:fill`), set side by side within the width one mark takes or the width given (`:dodge`), set side by side, each its share of their widths, with a gap between them (`:dodge2`), each moved a small random distance (`:jitter`), set side by side and then each moved a small random distance (`:jitterdodge`), or nudged (`:nudge`), each alone or with its options, as [Positions](#module-positions) says. The default value is `:stack`.

* `:bins` (`t:pos_integer/0`) - How many bins span the axis, when neither `binwidth:` nor `breaks:` is given. The default value is `30`.

* `:binwidth` - How wide each bin is, a number above 0 in the axis's transformed units, which takes the place of `bins:`.

* `:center` - Where one bin's middle falls, which places them all; not with `boundary:`.

* `:boundary` - Where two bins meet, which places them all; not with `center:`. Without either, the outermost bins are centred on the axis's limits, or bins `binwidth:` wide meet half a width from 0.

* `:breaks` - Where the bins meet, a list of two or more distinct numbers in the data's units, put through the axis's transformation, which takes the place of `bins:`, `binwidth:`, `center:` and `boundary:`; a row outside them is not counted.

* `:closed` - Which end of a bin a value on its edge belongs to: the right end (`:right`), or the left (`:left`); the outermost bins hold their outer ends too. The default value is `:right`.

* `:pad` (`t:boolean/0`) - Whether to add a bin of no rows at each end. The default value is `false`.

* `:drop` - Which bins of no rows to leave out: none (`:none`), every one (`:all`), or those before the first bin with rows and after the last (`:extremes`). The default value is `:none`.

* `:orientation` - The axis the layer runs along, `:x` or `:y`, which must be the one of `:x` and `:y` mapped; it runs along that one when this is not given.

* `:alpha` - How opaque every mark is, from 0, invisible, to 1, opaque.

* `:color` - The colour of every bar's border, written `colour:` or `color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; no border when not given. A border takes no alpha but its colour's own.

* `:fill` - The colour every bar is filled with: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; when not given, the theme's ink mixed 35% toward its paper, `#595959`, or `#000000A6` under `theme_void/2`, whose paper is clear.

* `:linewidth` - How wide every bar's border is, in millimetres; the theme's `base_line_size` when not given, 0.5 at its default sizes.

* `:linetype` - The line type of every bar's border: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; `:solid` when not given.

* `:nudge_x` - How far every mark moves along x from its place, in the units of the x axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

* `:nudge_y` - How far every mark moves along y from its place, in the units of the y axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

    iex> plot =
    ...>   %{"x" => [1.0, 1.5, 2.5, 4.0]}
    ...>   |> Giggly.Plot.new(%{x: :x})
    ...>   |> Giggly.Plot.geom_histogram(binwidth: 1, boundary: 0)
    iex> frame = Giggly.layer_data(plot)
    iex> Giggly.DataFrame.pull(frame, :count)
    [2.0, 1.0, 1.0]
    iex> Giggly.DataFrame.pull(frame, :x)
    [1.5, 2.5, 3.5]

# `geom_hline`

```elixir
@spec geom_hline(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer of horizontal reference lines: a line across the whole panel at each `yintercept`,
for a threshold, a target or a mean drawn over the data.

The lines are given in one of two ways. `yintercept:` gives them as values, a line for each,
drawn in every panel and in no legend. Or the layer maps `:yintercept` from a table, its own
`data:` or the plot's, so the lines can differ from panel to panel under a facet and map a
colour, alpha, width or line type into a legend. Either way the layer takes nothing from the
plot's mapping, and titles no axis.

Horizontal lines use `:yintercept`, `:group`, `:alpha`, `:color`, `:linetype` and `:linewidth`,
and need `:yintercept`, which the y axis widens to show and puts through its scale as it does
`y`: a number on a continuous axis, a string on a discrete one, a date, a date-time or a time
on such an axis, and `:infinity` or `:neg_infinity` at the panel's edge. A line repeated in a
panel is drawn once. Beside `yintercept:`, each look option takes one value or a list, one per
line, every list as long as the others. A line missing its `yintercept`, as a scale's limits
leave it, draws nothing, and so do a colour of `:none` and the line type `:blank`. Under
`coord_radial/1` each line is a circle.

Raises `ArgumentError` for `yintercept:` beside a mapping or `data:`, for a list of looks
without `yintercept:`, and for lists of different lengths.

## Options

* `:data` (`t:term/0`) - A table for the layer's mapping to draw from instead of the plot's data, anything implementing `Table.Reader`; refused beside the options giving lines as values, which draw lines of their own. Under a facet, a table lacking a faceting column is drawn in every panel.

* `:position` - Where the lines are moved: left where they cross the axis (`:identity`), or nudged (`:nudge`), as [Positions](#module-positions) says. The default value is `:identity`.

* `:yintercept` - Where each line crosses the y axis, in its units: a value, or a list of them, a line for each, drawn in every panel. Given, the layer takes no mapping and no `data:`.

* `:nudge_y` - How far every mark moves along y from its place, in the units of the y axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

* `:alpha` - How opaque each line is, from 0, invisible, to 1, opaque.

* `:color` - The colour of each line, written `colour:` or `color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; black when not given.

* `:linewidth` - How wide each line is, in millimetres; the theme's `base_line_size` when not given, 0.5 at its default sizes.

* `:linetype` - The line type of each line: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; `:solid` when not given.

* `:lineend` - How a line's ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half the line's width beyond it (`:square`). The default value is `:butt`.

    iex> frame =
    ...>   %{"wt" => [2.62, 3.44], "mpg" => [21.0, 18.7]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.geom_hline(yintercept: [20, 25], colour: ["red", "blue"])
    ...>   |> Giggly.layer_data(1)
    iex> {Giggly.DataFrame.pull(frame, :yintercept), Giggly.DataFrame.pull(frame, :color)}
    {[20.0, 25.0], ["#FF0000", "#0000FF"]}

A line for each panel, mapped from a table of its own:

    iex> frame =
    ...>   %{"wt" => [2.62, 3.44], "mpg" => [21.0, 18.7], "cyl" => [4, 8]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.geom_hline(%{yintercept: :mean},
    ...>     data: %{"cyl" => [4, 8], "mean" => [26.7, 15.1]}
    ...>   )
    ...>   |> Giggly.Plot.facet_wrap(:cyl)
    ...>   |> Giggly.layer_data(1)
    iex> {Giggly.DataFrame.pull(frame, :yintercept), Giggly.DataFrame.pull(frame, :panel)}
    {[26.7, 15.1], [1, 2]}

# `geom_jitter`

```elixir
@spec geom_jitter(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer of points, as `geom_point/3` adds, each moved a small random distance across and up
from its place, so that points sharing a place stand apart: by up to 0.4 of the closest spacing
of each panel's positions either way, 0.4 on a discrete axis, whose levels are 1 apart, unless
`width:` and `height:` say how far. The axes widen to hold the points where they land.

The distances are drawn from a seed, so a plot draws the same points every time it is drawn, and
two layers of the same rows move them alike; `position: {:jitter, seed: seed}` draws
others. Each panel draws its distances afresh from the seed.

Points use the aesthetics `geom_point/3`'s use, and need `:x` and `:y`. Raises `ArgumentError`
when `position:` is given beside `width:` or `height:`.

## Options

* `:data` (`t:term/0`) - A table for the layer to draw instead of the plot's data, anything implementing `Table.Reader`. The plot's mapping applies to it, so it must hold each column the plot's mapping names for an aesthetic the layer neither maps nor sets. Under a facet, a table lacking a faceting column is drawn in every panel of that column's values.

* `:width` - How far each point moves at most to either side, in the units of the x axis, 0 or more; 0.4 of the closest spacing of each panel's `x` positions when not given, 0.4 on a discrete axis.

* `:height` - How far each point moves at most up or down, in the units of the y axis, 0 or more; 0.4 of the closest spacing of each panel's `y` positions when not given.

* `:position` - Where the points are moved: any position the points of `geom_point/3` take, as [Positions](#module-positions) says; refused beside `width:` or `height:`. They move as `width:` and `height:` say when not given.

* `:alpha` - How opaque every mark is, from 0, invisible, to 1, opaque.

* `:color` - The colour of every point, written `colour:` or `color:`, which outlines its shape and fills the shapes filled in it: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; black when not given.

* `:fill` - The colour every point of a shape with a fill of its own is filled with: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; none when not given.

* `:shape` - The shape every point is drawn in, by its name or its number, as listed above, or `:none` for no point; `:circle` when not given.

* `:size` - How big every point is, in millimetres; 1.5 times the theme's `base_size` over 11 when not given, 1.5 at its default sizes.

* `:stroke` - How heavy every point's outline is, in millimetres, or `:none` for no outline and no lines; the theme's `base_line_size` when not given, 0.5 at its default sizes. The outline is drawn half that wide, and a heavier stroke makes the shape bigger too.

* `:nudge_x` - How far every mark moves along x from its place, in the units of the x axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

* `:nudge_y` - How far every mark moves along y from its place, in the units of the y axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

    iex> plot =
    ...>   %{"cyl" => [4, 4, 6], "hwy" => [29, 29, 26]}
    ...>   |> Giggly.Plot.new(%{x: :cyl, y: :hwy})
    ...>   |> Giggly.Plot.geom_jitter(height: 0)
    iex> frame = Giggly.layer_data(plot)
    iex> Giggly.DataFrame.pull(frame, :x)
    [3.969331140393459, 4.786222529919443, 5.4305619806336995]
    iex> Giggly.DataFrame.pull(frame, :y)
    [29.0, 29.0, 26.0]

# `geom_label`

```elixir
@spec geom_label(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer of labels: each row's `label` at its `x` and `y`, as `geom_text/3` writes it, on a
box with rounded corners, so it reads over what lies beneath.

Each label is written and justified as `geom_text/3`'s are, its box placed and turned with its
text, padded round it by a quarter of a line of the text on every side and its corners rounded
to 0.15 of a line. A box is white with a black border 0.25 millimetres wide, and its text black
and 11 points tall, unless the options say otherwise; `alpha:` makes the box see-through, but
neither the text nor the border. Labels are drawn in the order of their rows, each box and then
its text, so a later label covers an earlier one. A row missing its `x`, `y` or label draws
nothing.

Labels use `:x`, `:y`, `:label`, `:group`, `:alpha`, `:color`, `:fill`, `:linetype` and
`:linewidth`, and need `:x`, `:y` and `:label`; a label never groups the rows. `nudge_x:` and
`nudge_y:` move every label, in the units of each axis, and a mapped `:nudge_x` or `:nudge_y`
each its own way, as its position, `:nudge` unless `position:` says otherwise, reads them, and
the axes reach each label's place, though not its box. Raises `ArgumentError` for a nudge
beside another position, which moves no label by it.

## Options

* `:data` (`t:term/0`) - A table for the layer to draw instead of the plot's data, anything implementing `Table.Reader`. The plot's mapping applies to it, so it must hold each column the plot's mapping names for an aesthetic the layer neither maps nor sets. Under a facet, a table lacking a faceting column is drawn in every panel of that column's values.

* `:position` - Where the marks are moved once the stat has run: left at their positions (`:identity`), piled on one another (`:stack`), piled to the same height (`:fill`), set side by side within the width given, `{:dodge, width: width}`, or each taken as that wide and set side by side with the marks it overlaps, `{:dodge2, width: width}`, having no width of their own to share, each moved a small random distance (`:jitter`), set side by side and then each moved a small random distance (`:jitterdodge`), or nudged (`:nudge`), each alone or with its options, as [Positions](#module-positions) says. The default value is `:nudge`.

* `:alpha` - How opaque every label's box is, from 0, invisible, to 1, opaque; its text and border keep their colour's own.

* `:color` - The colour of every label's text and border, written `colour:` or `color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; black when not given. Neither takes `alpha:`, only its colour's own.

* `:fill` - The colour every label's box is filled with: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; the theme's paper, white, when not given.

* `:linewidth` - How wide every label's border is, in millimetres, 0 for none; half the theme's `base_line_size` when not given, 0.25 at its default sizes.

* `:linetype` - The line type of every label's border: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; `:solid` when not given.

* `:size` - How big every label is, in millimetres, each 2.85 points; the theme's `base_size` when not given, 11 points at its default sizes.

* `:angle` - How far every label is turned, in degrees anticlockwise; 0 when not given.

* `:hjust` - Where along its baseline every label is anchored on its place, 0 its start and 1 its end: a number from 0 to 1, or one of the words `:left`, `:center` and `:right`, `:bottom`, `:middle` and `:top`, or `:inward` and `:outward`, which justify each label toward or away from the middle of the panel by where it falls; 0.5 when not given.

* `:vjust` - Where up its height every label is anchored on its place, 0 its baseline and 1 the top of a capital letter: a number from 0 to 1, or one of the words `:left`, `:center` and `:right`, `:bottom`, `:middle` and `:top`, or `:inward` and `:outward`, which justify each label toward or away from the middle of the panel by where it falls; 0.5 when not given.

* `:family` (`t:String.t/0`) - The font every label is drawn in, by name, such as `"Times New Roman"`, or one of the generic families `"sans"`, `"serif"` and `"mono"`; the theme's `base_family` when not given, the default sans-serif at its default. How a label is measured and drawn in it: the [fonts guide](fonts.md).

* `:label_padding` - The room round every label's text inside its box: one length for every side, or a keyword list of `:top`, `:right`, `:bottom` and `:left`, a side left out 0; each a number of points or `{amount, unit}` with a unit of `:pt`, `:cm`, `:mm`, `:in` or `:lines`, lines of the label's own text. The text sits the bottom's padding above the box's bottom, its descent within it, and the top's is at least the descent. The default value is `{0.25, :lines}`.

* `:label_r` - The radius of every label's box's corners, a length as `label_padding:` takes one; 0 for square corners. The default value is `{0.15, :lines}`.

* `:border_color` - The colour of every label's border apart from its text, written `border_colour:` or `border_color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none, or `:color`, the label's own colour, when not given. The default value is `:color`.

* `:text_color` - The colour of every label's text apart from its border, written `text_colour:` or `text_color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none, or `:color`, the label's own colour, when not given. The default value is `:color`.

* `:nudge_x` - How far every mark moves along x from its place, in the units of the x axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

* `:nudge_y` - How far every mark moves along y from its place, in the units of the y axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

    iex> frame =
    ...>   %{"wt" => [2.62, 2.32], "mpg" => [21.0, 22.8], "model" => ["Mazda RX4", "Datsun 710"]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, label: :model})
    ...>   |> Giggly.Plot.geom_label(fill: "lightyellow")
    ...>   |> Giggly.layer_data()
    iex> {Giggly.DataFrame.pull(frame, :fill), Giggly.DataFrame.pull(frame, :linewidth)}
    {["#FFFFE0", "#FFFFE0"], [0.25, 0.25]}

A label is drawn as its box and its text, here padded 4 points either side, on square corners:

    iex> svg =
    ...>   %{"x" => [1.0], "y" => [1.0], "name" => ["a"]}
    ...>   |> Giggly.Plot.new(%{x: :x, y: :y, label: :name})
    ...>   |> Giggly.Plot.geom_label(label_padding: [left: 4, right: 4], label_r: 0)
    ...>   |> Giggly.to_svg()
    ...>   |> IO.iodata_to_binary()
    iex> {svg =~ "<polygon points=", svg =~ ">a</text>"}
    {true, true}

# `geom_line`

```elixir
@spec geom_line(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer of lines: a line through each group's rows in order of their `x`, as a series over
time is drawn, or of their `y` with `orientation: :y`. Rows that share a position keep the order
the data gives them. Lines are drawn as `geom_path/3` draws paths and take the same aesthetics.

## Options

* `:data` (`t:term/0`) - A table for the layer to draw instead of the plot's data, anything implementing `Table.Reader`. The plot's mapping applies to it, so it must hold each column the plot's mapping names for an aesthetic the layer neither maps nor sets. Under a facet, a table lacking a faceting column is drawn in every panel of that column's values.

* `:position` - Where the marks are moved once the stat has run: left at their positions (`:identity`), piled on one another (`:stack`), piled to the same height (`:fill`), set side by side within the width given, `{:dodge, width: width}`, or each taken as that wide and set side by side with the marks it overlaps, `{:dodge2, width: width}`, having no width of their own to share, each moved a small random distance (`:jitter`), set side by side and then each moved a small random distance (`:jitterdodge`), or nudged (`:nudge`), each alone or with its options, as [Positions](#module-positions) says. The default value is `:identity`.

* `:orientation` - Which position the rows are put in order of: `x`, or `y` for a line that runs up the panel. The default value is `:x`.

* `:alpha` - How opaque every mark is, from 0, invisible, to 1, opaque.

* `:color` - The colour of every line, written `colour:` or `color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; black when not given.

* `:linewidth` - How wide every line is, in millimetres; the theme's `base_line_size` when not given, 0.5 at its default sizes.

* `:linetype` - The line type of every line: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; `:solid` when not given.

* `:arrow` - An arrowhead on each line: `true` for the defaults, or a keyword list of its options, `angle:` (30), `length:` (`{0.25, :in}`, in `:pt`, `:cm`, `:mm` or `:in`), `ends:` (`:last`, `:first` or `:both`), `type:` (`:open` or `:closed`) and `fill:`, a closed head's, a colour, `:none`, or `:color`, the line's colour and the default; none when not given.

* `:lineend` - How a line's ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half the line's width beyond it (`:square`). The default value is `:butt`.

* `:linejoin` - How a line turns a corner: rounded (`:round`), pointed (`:mitre`) or cut off (`:bevel`). The default value is `:round`.

* `:linemitre` - How far a pointed corner may reach, in widths of the line, before it is cut off; 1 or more. The default value is `10.0`.

* `:nudge_x` - How far every mark moves along x from its place, in the units of the x axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

* `:nudge_y` - How far every mark moves along y from its place, in the units of the y axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

    iex> plot =
    ...>   %{"x" => [1.0, 3.0, 2.0], "y" => [1.0, 2.0, 4.0]}
    ...>   |> Giggly.Plot.new(%{x: :x, y: :y})
    ...>   |> Giggly.Plot.geom_line()
    iex> frame = Giggly.layer_data(plot)
    iex> Giggly.DataFrame.pull(frame, :x)
    [1.0, 2.0, 3.0]
    iex> Giggly.DataFrame.pull(frame, :y)
    [1.0, 4.0, 2.0]

# `geom_linerange`

```elixir
@spec geom_linerange(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer of line ranges: a vertical line for each row from its `ymin` to its `ymax` at its
`x`, for an interval round a value, or a horizontal one from its `xmin` to its `xmax` at its
`y`.

Line ranges use `:x`, `:y`, `:xmin`, `:xmax`, `:ymin`, `:ymax`, `:group`, `:alpha`, `:color`,
`:linetype` and `:linewidth`. A layer given `:ymin` or `:ymax` runs up the panel and needs `:x`,
`:ymin` and `:ymax`; one given neither runs across it and needs `:y`, `:xmin` and `:xmax`; and
`orientation:` chooses either way. A row missing a position, its width or its line type draws no
line, and an infinite end reaches the panel's edge. Each line takes its own row's colour, alpha,
width and line type; a colour of `:none` draws none, and so does the line type `:blank`. Under
`coord_radial/1` a line follows the panel's curves.

Raises `ArgumentError` where the layer lacks one of the three positions its lines run along.

## Options

* `:data` (`t:term/0`) - A table for the layer to draw instead of the plot's data, anything implementing `Table.Reader`. The plot's mapping applies to it, so it must hold each column the plot's mapping names for an aesthetic the layer neither maps nor sets. Under a facet, a table lacking a faceting column is drawn in every panel of that column's values.

* `:position` - Where the marks are moved once the stat has run: left at their positions (`:identity`), piled on one another (`:stack`), piled to the same height (`:fill`), set side by side within the width given, `{:dodge, width: width}`, or each taken as that wide and set side by side with the marks it overlaps, `{:dodge2, width: width}`, having no width of their own to share, each moved a small random distance (`:jitter`), set side by side and then each moved a small random distance (`:jitterdodge`), or nudged (`:nudge`), each alone or with its options, as [Positions](#module-positions) says. The default value is `:identity`.

* `:orientation` - Which way each range runs: `:x`, up the panel from `ymin` to `ymax` at each `x`, or `:y`, across it from `xmin` to `xmax` at each `y`; when not given, `:y` where the layer is given neither `:ymin` nor `:ymax`, and `:x` otherwise.

* `:alpha` - How opaque every mark is, from 0, invisible, to 1, opaque.

* `:color` - The colour of every line, written `colour:` or `color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; black when not given.

* `:linewidth` - How wide every line is, in millimetres; the theme's `base_line_size` when not given, 0.5 at its default sizes.

* `:linetype` - The line type of every line: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; `:solid` when not given.

* `:lineend` - How a line's ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half the line's width beyond it (`:square`). The default value is `:butt`.

* `:nudge_x` - How far every mark moves along x from its place, in the units of the x axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

* `:nudge_y` - How far every mark moves along y from its place, in the units of the y axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

    iex> frame =
    ...>   %{"trt" => [1, 2], "resp" => [1.0, 3.0], "lower" => [0.8, 2.4], "upper" => [1.1, 3.3]}
    ...>   |> Giggly.Plot.new(%{x: :trt, y: :resp})
    ...>   |> Giggly.Plot.geom_linerange(%{ymin: :lower, ymax: :upper})
    ...>   |> Giggly.layer_data()
    iex> {Giggly.DataFrame.pull(frame, :ymin), Giggly.DataFrame.pull(frame, :ymax)}
    {[0.8, 2.4], [1.1, 3.3]}

Ranges given `:xmin` and `:xmax` run across the panel:

    iex> frame =
    ...>   %{"trt" => [1, 2], "lower" => [0.8, 2.4], "upper" => [1.1, 3.3]}
    ...>   |> Giggly.Plot.new(%{y: :trt, xmin: :lower, xmax: :upper})
    ...>   |> Giggly.Plot.geom_linerange()
    ...>   |> Giggly.layer_data()
    iex> Giggly.DataFrame.pull(frame, :flipped_aes)
    [true, true]

# `geom_path`

```elixir
@spec geom_path(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer of paths: a line through each group's rows in the order the data gives them, for a
line that may double back. `geom_line/3` puts the rows in order first.

Paths use `:x`, `:y`, `:group`, `:alpha`, `:color`, `:linetype` and `:linewidth`, and need `:x`
and `:y`. Each group is a line of its own, and a discrete colour, line type or width groups the
rows. A row missing `x` or `y` breaks its line; a group of one row draws nothing. Where colour,
alpha or width changes along a line, each segment takes the colour, alpha and width of the row
it starts from, and a missing width leaves its segment out; a line type cannot change along a
line, and while any line is dashed, dotted or blank, drawing one whose colour, alpha or width
changes raises `ArgumentError`. A colour of `:none` draws no line, and so does the line type
`:blank`.

`arrow:` puts an arrowhead at a line's ends, in the line's colour, width and line type, its arms
the same length however the panel is sized; a line broken by a missing position has its heads at
the line's own first and last rows, and one drawn as segments only at those ends too.

## Options

* `:data` (`t:term/0`) - A table for the layer to draw instead of the plot's data, anything implementing `Table.Reader`. The plot's mapping applies to it, so it must hold each column the plot's mapping names for an aesthetic the layer neither maps nor sets. Under a facet, a table lacking a faceting column is drawn in every panel of that column's values.

* `:position` - Where the marks are moved once the stat has run: left at their positions (`:identity`), piled on one another (`:stack`), piled to the same height (`:fill`), set side by side within the width given, `{:dodge, width: width}`, or each taken as that wide and set side by side with the marks it overlaps, `{:dodge2, width: width}`, having no width of their own to share, each moved a small random distance (`:jitter`), set side by side and then each moved a small random distance (`:jitterdodge`), or nudged (`:nudge`), each alone or with its options, as [Positions](#module-positions) says. The default value is `:identity`.

* `:alpha` - How opaque every mark is, from 0, invisible, to 1, opaque.

* `:color` - The colour of every line, written `colour:` or `color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; black when not given.

* `:linewidth` - How wide every line is, in millimetres; the theme's `base_line_size` when not given, 0.5 at its default sizes.

* `:linetype` - The line type of every line: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; `:solid` when not given.

* `:arrow` - An arrowhead on each line: `true` for the defaults, or a keyword list of its options, `angle:` (30), `length:` (`{0.25, :in}`, in `:pt`, `:cm`, `:mm` or `:in`), `ends:` (`:last`, `:first` or `:both`), `type:` (`:open` or `:closed`) and `fill:`, a closed head's, a colour, `:none`, or `:color`, the line's colour and the default; none when not given.

* `:lineend` - How a line's ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half the line's width beyond it (`:square`). The default value is `:butt`.

* `:linejoin` - How a line turns a corner: rounded (`:round`), pointed (`:mitre`) or cut off (`:bevel`). The default value is `:round`.

* `:linemitre` - How far a pointed corner may reach, in widths of the line, before it is cut off; 1 or more. The default value is `10.0`.

* `:nudge_x` - How far every mark moves along x from its place, in the units of the x axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

* `:nudge_y` - How far every mark moves along y from its place, in the units of the y axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

    iex> plot =
    ...>   %{"unemploy" => [2.9, 4.1, 3.4], "psavert" => [12.6, 9.4, 11.1]}
    ...>   |> Giggly.Plot.new(%{x: :unemploy, y: :psavert})
    ...>   |> Giggly.Plot.geom_path(linewidth: 2)
    iex> frame = Giggly.layer_data(plot)
    iex> Giggly.DataFrame.pull(frame, :x)
    [2.9, 4.1, 3.4]
    iex> Giggly.DataFrame.pull(frame, :linewidth)
    [2.0, 2.0, 2.0]

A line type is held as its dash pattern, whichever way it is written:

    iex> frame =
    ...>   %{"unemploy" => [2.9, 4.1], "psavert" => [12.6, 9.4]}
    ...>   |> Giggly.Plot.new(%{x: :unemploy, y: :psavert})
    ...>   |> Giggly.Plot.geom_path(linetype: 2)
    ...>   |> Giggly.layer_data()
    iex> Giggly.DataFrame.pull(frame, :linetype)
    [{4, 4}, {4, 4}]

# `geom_point`

```elixir
@spec geom_point(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer of points, one per row, at `x` and `y`, or each moved a small random distance from
there with `position: :jitter`, as `geom_jitter/3` moves them.

Points use `:x`, `:y`, `:group`, `:alpha`, `:color`, `:fill`, `:shape` and `:size`, and need
`:x` and `:y`. A point's alpha applies to its colour and its fill alike; a colour or shape of
`:none`, or a missing size or shape, draws no point.

A point is drawn in one of 26 shapes, each named, and numbered 0 to 25:

  * outlined in the point's colour: `:square_open` (0), `:circle_open` (1), `:triangle_open`
    (2), `:plus` (3), `:cross` (4), `:diamond_open` (5), `:triangle_down_open` (6),
    `:square_cross` (7), `:asterisk` (8), `:diamond_plus` (9), `:circle_plus` (10), `:star`
    (11), `:square_plus` (12), `:circle_cross` (13) and `:square_triangle` (14);
  * filled with its colour: `:square` (15), `:circle_small` (16), `:triangle` (17) and
    `:diamond` (18), with no outline, and `:circle` (19) and the smaller `:bullet` (20),
    outlined in it too;
  * outlined in its colour and filled with its fill: `:circle_filled` (21), `:square_filled`
    (22), `:diamond_filled` (23), `:triangle_filled` (24) and `:triangle_down_filled` (25).

## Options

* `:data` (`t:term/0`) - A table for the layer to draw instead of the plot's data, anything implementing `Table.Reader`. The plot's mapping applies to it, so it must hold each column the plot's mapping names for an aesthetic the layer neither maps nor sets. Under a facet, a table lacking a faceting column is drawn in every panel of that column's values.

* `:position` - Where the marks are moved once the stat has run: left at their positions (`:identity`), piled on one another (`:stack`), piled to the same height (`:fill`), set side by side within the width given, `{:dodge, width: width}`, or each taken as that wide and set side by side with the marks it overlaps, `{:dodge2, width: width}`, having no width of their own to share, each moved a small random distance (`:jitter`), set side by side and then each moved a small random distance (`:jitterdodge`), or nudged (`:nudge`), each alone or with its options, as [Positions](#module-positions) says. The default value is `:identity`.

* `:alpha` - How opaque every mark is, from 0, invisible, to 1, opaque.

* `:color` - The colour of every point, written `colour:` or `color:`, which outlines its shape and fills the shapes filled in it: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; black when not given.

* `:fill` - The colour every point of a shape with a fill of its own is filled with: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; none when not given.

* `:shape` - The shape every point is drawn in, by its name or its number, as listed above, or `:none` for no point; `:circle` when not given.

* `:size` - How big every point is, in millimetres; 1.5 times the theme's `base_size` over 11 when not given, 1.5 at its default sizes.

* `:stroke` - How heavy every point's outline is, in millimetres, or `:none` for no outline and no lines; the theme's `base_line_size` when not given, 0.5 at its default sizes. The outline is drawn half that wide, and a heavier stroke makes the shape bigger too.

* `:nudge_x` - How far every mark moves along x from its place, in the units of the x axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

* `:nudge_y` - How far every mark moves along y from its place, in the units of the y axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.875], "mpg" => [21.0, 22.8], "cyl" => ["6", "4"]}
    ...>   |> Giggly.Plot.new()
    ...>   |> Giggly.Plot.geom_point(%{x: :wt, y: :mpg, group: :cyl})
    iex> frame = Giggly.layer_data(plot)
    iex> Giggly.DataFrame.pull(frame, :x)
    [2.62, 2.875]
    iex> Giggly.DataFrame.pull(frame, :group)
    [2, 1]

A value set for every point is in every row of the layer's table:

    iex> plot =
    ...>   %{"wt" => [2.62, 2.875], "mpg" => [21.0, 22.8]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_point(alpha: 0.4)
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:alpha)
    [0.4, 0.4]

A colour is kept as the hex it names:

    iex> plot =
    ...>   %{"wt" => [2.62, 2.875], "mpg" => [21.0, 22.8]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_point(colour: "steelblue")
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:color)
    ["#4682B4", "#4682B4"]

A shape given by its number is kept as its name:

    iex> plot =
    ...>   %{"wt" => [2.62, 2.875], "mpg" => [21.0, 22.8]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_point(shape: 21, fill: "white", size: 5, stroke: 2)
    iex> frame = Giggly.layer_data(plot)
    iex> {Giggly.DataFrame.pull(frame, :shape), Giggly.DataFrame.pull(frame, :fill)}
    {[:circle_filled, :circle_filled], ["#FFFFFF", "#FFFFFF"]}

# `geom_pointrange`

```elixir
@spec geom_pointrange(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer of point ranges: a line range for each row, as `geom_linerange/3` draws one, with
a point at its `x` and `y` on it, for a value and the interval round it, such as a mean and its
standard error.

Point ranges use a line range's aesthetics and a point's `:fill`, `:shape`, `:size` and
`:stroke`, and need `:x` and `:y` and the range a line range runs along: `:ymin` and `:ymax`
up the panel, or `:xmin` and `:xmax` across it, as `orientation:` or the range given says. Every
line is drawn before every point, each point four times its `size`, so a small size makes a
plain dot on the line. Each line and point takes its own row's look; a row missing a position
draws no line, and one missing `x` or `y` no point.

Raises `ArgumentError` where the layer lacks one of the three positions its lines run along.

## Options

* `:data` (`t:term/0`) - A table for the layer to draw instead of the plot's data, anything implementing `Table.Reader`. The plot's mapping applies to it, so it must hold each column the plot's mapping names for an aesthetic the layer neither maps nor sets. Under a facet, a table lacking a faceting column is drawn in every panel of that column's values.

* `:position` - Where the marks are moved once the stat has run: left at their positions (`:identity`), piled on one another (`:stack`), piled to the same height (`:fill`), set side by side within the width given, `{:dodge, width: width}`, or each taken as that wide and set side by side with the marks it overlaps, `{:dodge2, width: width}`, having no width of their own to share, each moved a small random distance (`:jitter`), set side by side and then each moved a small random distance (`:jitterdodge`), or nudged (`:nudge`), each alone or with its options, as [Positions](#module-positions) says. The default value is `:identity`.

* `:orientation` - Which way each range runs: `:x`, up the panel from `ymin` to `ymax` at each `x`, or `:y`, across it from `xmin` to `xmax` at each `y`; when not given, `:y` where the layer is given neither `:ymin` nor `:ymax`, and `:x` otherwise.

* `:alpha` - How opaque every mark is, from 0, invisible, to 1, opaque.

* `:linewidth` - How wide every line is, in millimetres; the theme's `base_line_size` when not given, 0.5 at its default sizes.

* `:linetype` - The line type of every line: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; `:solid` when not given.

* `:lineend` - How a line's ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half the line's width beyond it (`:square`). The default value is `:butt`.

* `:color` - The colour of every line and point, written `colour:` or `color:`, which outlines the point's shape and fills the shapes filled in it: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; black when not given.

* `:fill` - The colour every point of a shape with a fill of its own is filled with: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; none when not given.

* `:shape` - The shape every point is drawn in, by its name or its number, as listed above, or `:none` for no point; `:circle` when not given.

* `:size` - How big every point is, in millimetres, each drawn four times as big; a third of the theme's points' size when not given, 0.5 at its default sizes.

* `:stroke` - How heavy every point's outline is, in millimetres, or `:none` for no outline and no lines; twice the theme's `base_line_size` when not given, 1 at its default sizes. The outline is drawn half that wide, and a heavier stroke makes the shape bigger too.

* `:nudge_x` - How far every mark moves along x from its place, in the units of the x axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

* `:nudge_y` - How far every mark moves along y from its place, in the units of the y axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

    iex> frame =
    ...>   %{"trt" => [1, 2], "resp" => [1.0, 3.0], "lower" => [0.8, 2.4], "upper" => [1.1, 3.3]}
    ...>   |> Giggly.Plot.new(%{x: :trt, y: :resp})
    ...>   |> Giggly.Plot.geom_pointrange(%{ymin: :lower, ymax: :upper}, colour: "red")
    ...>   |> Giggly.layer_data()
    iex> {Giggly.DataFrame.pull(frame, :size), Giggly.DataFrame.pull(frame, :stroke)}
    {[0.5, 0.5], [1.0, 1.0]}

# `geom_raster`

```elixir
@spec geom_raster(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer of equal cells on a regular grid, one per row, drawn as one image: a faster,
smaller tile for a surface of values, such as a density over two variables.

Every cell is as wide as the gap between the `x` positions and as tall as the gap between the
`y` positions, the smallest where the gaps differ. Positions may skip places, a grid with
holes, but each must be a whole number of cells from the least, or the plot raises when run;
`geom_tile/3` draws cells at uneven positions. `hjust:` and `vjust:` place each cell against
its position. A row missing its `x` or `y` draws nothing, and a place no row fills is left
clear. In radial coordinates the cells are drawn as tiles.

Rasters use `:x`, `:y`, `:group`, `:alpha` and `:fill`, and need `:x` and `:y`. `:fill` fills a
cell and takes its alpha; a raster has no border.

## Options

* `:data` (`t:term/0`) - A table for the layer to draw instead of the plot's data, anything implementing `Table.Reader`. The plot's mapping applies to it, so it must hold each column the plot's mapping names for an aesthetic the layer neither maps nor sets. Under a facet, a table lacking a faceting column is drawn in every panel of that column's values.

* `:position` - Where the marks are moved once the stat has run: left at their positions (`:identity`), piled on one another (`:stack`), piled to the same height (`:fill`), set side by side within the width one mark takes or the width given (`:dodge`), set side by side, each its share of their widths, with a gap between them (`:dodge2`), each moved a small random distance (`:jitter`), set side by side and then each moved a small random distance (`:jitterdodge`), or nudged (`:nudge`), each alone or with its options, as [Positions](#module-positions) says. The default value is `:identity`.

* `:alpha` - How opaque every mark is, from 0, invisible, to 1, opaque.

* `:fill` - The colour every cell is filled with: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; when not given, the theme's ink mixed 20% toward its paper, `#333333`, or `#000000CC` under `theme_void/2`, whose paper is clear.

* `:hjust` - Where each cell sits across against its `x`, a number from 0 to 1: 0 puts the cell's right or top edge there, 1 its left or bottom edge, and 0.5 centres it. The default value is `0.5`.

* `:vjust` - Where each cell sits up against its `y`, a number from 0 to 1: 0 puts the cell's right or top edge there, 1 its left or bottom edge, and 0.5 centres it. The default value is `0.5`.

* `:interpolate` (`t:boolean/0`) - Whether a viewer blends neighbouring cells' colours, smoothing the image, rather than drawing each cell as a block of its colour. The default value is `false`.

* `:nudge_x` - How far every mark moves along x from its place, in the units of the x axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

* `:nudge_y` - How far every mark moves along y from its place, in the units of the y axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

    iex> frame =
    ...>   %{"x" => [1.0, 2.0, 4.0], "y" => [1.0, 1.0, 1.0]}
    ...>   |> Giggly.Plot.new(%{x: :x, y: :y})
    ...>   |> Giggly.Plot.geom_raster(hjust: 0)
    ...>   |> Giggly.layer_data()
    iex> {Giggly.DataFrame.pull(frame, :xmin), Giggly.DataFrame.pull(frame, :xmax)}
    {[0.0, 1.0, 3.0], [1.0, 2.0, 4.0]}

# `geom_rect`

```elixir
@spec geom_rect(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer of rectangles, one per row, each from its `xmin` to its `xmax` and its `ymin` to its
`ymax`.

Each corner is mapped to a column, or set for every rectangle by the option of its name, in the
units of its axis; a set corner widens the axes as a mapped one does. `:infinity` and
`:neg_infinity` reach the panel's edge, so a band can shade the whole panel. A row missing a
corner draws nothing.

Rectangles use `:xmin`, `:xmax`, `:ymin`, `:ymax`, `:group`, `:alpha`, `:fill`, `:color`,
`:linetype` and `:linewidth`, and need all four corners, each mapped or set. They look as
`geom_col/3`'s bars do, their borders as wide and dashed as `:linewidth` and `:linetype` say.

## Options

* `:data` (`t:term/0`) - A table for the layer to draw instead of the plot's data, anything implementing `Table.Reader`. The plot's mapping applies to it, so it must hold each column the plot's mapping names for an aesthetic the layer neither maps nor sets. Under a facet, a table lacking a faceting column is drawn in every panel of that column's values.

* `:position` - Where the rectangles are moved: left at their positions (`:identity`), set side by side within the width one takes or the width given (`:dodge`), set side by side, each its share of their widths, with a gap between them (`:dodge2`), or nudged (`:nudge`), each alone or with its options, as [Positions](#module-positions) says. The default value is `:identity`.

* `:alpha` - How opaque every mark is, from 0, invisible, to 1, opaque.

* `:color` - The colour of every rectangle's border, written `colour:` or `color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; no border when not given. A border takes no alpha but its colour's own.

* `:fill` - The colour every rectangle is filled with: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; when not given, the theme's ink mixed 35% toward its paper, `#595959`, or `#000000A6` under `theme_void/2`, whose paper is clear.

* `:linewidth` - How wide every rectangle's border is, in millimetres; the theme's `base_line_size` when not given, 0.5 at its default sizes.

* `:linetype` - The line type of every rectangle's border: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; `:solid` when not given.

* `:xmin` - Every rectangle's `xmin`, in the units of the x axis: a number, or `:infinity` or `:neg_infinity`, which reach the panel's edge.

* `:xmax` - Every rectangle's `xmax`, as `xmin:` sets one.

* `:ymin` - Every rectangle's `ymin`, in the units of the y axis, as `xmin:` sets an `xmin`.

* `:ymax` - Every rectangle's `ymax`, as `ymin:` sets one.

* `:nudge_x` - How far every mark moves along x from its place, in the units of the x axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

* `:nudge_y` - How far every mark moves along y from its place, in the units of the y axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

    iex> frame =
    ...>   %{"start" => [1.0, 3.0], "end" => [2.0, 5.0], "low" => [0.0, 1.0], "high" => [4.0, 2.0]}
    ...>   |> Giggly.Plot.new(%{xmin: :start, xmax: :end, ymin: :low, ymax: :high})
    ...>   |> Giggly.Plot.geom_rect()
    ...>   |> Giggly.layer_data()
    iex> {Giggly.DataFrame.pull(frame, :xmin), Giggly.DataFrame.pull(frame, :ymax)}
    {[1.0, 3.0], [4.0, 2.0]}

Corners set for every rectangle shade one band behind every row:

    iex> frame =
    ...>   %{"start" => [1.0, 3.0], "end" => [2.0, 5.0]}
    ...>   |> Giggly.Plot.new(%{xmin: :start, xmax: :end})
    ...>   |> Giggly.Plot.geom_rect(ymin: 0, ymax: :infinity)
    ...>   |> Giggly.layer_data()
    iex> {Giggly.DataFrame.pull(frame, :ymin), Giggly.DataFrame.pull(frame, :ymax)}
    {[0.0, 0.0], [:infinity, :infinity]}

# `geom_ribbon`

```elixir
@spec geom_ribbon(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer of ribbons: the band between each group's `ymin` and `ymax` along its `x`, for a
range around a line, or between its `xmin` and `xmax` up its `y`.

Ribbons use `:x`, `:y`, `:xmin`, `:xmax`, `:ymin`, `:ymax`, `:group`, `:alpha`, `:fill`,
`:color`, `:linetype` and `:linewidth`, and need one of `:x` and `:y`, one of `:ymin` and
`:xmin`, and one of `:ymax` and `:xmax`. A band runs along x, or along y where it is given
neither `:ymin` nor `:ymax`, or as `orientation:` says. Each group is a band of its own, its rows
in order along it, and a row missing a position breaks its band there. A band is filled, at its
alpha, and outlined only where a colour is mapped or set, its outline taking no alpha but its
colour's own; its look cannot change along it: a colour, fill, alpha, width or line type that
changes within a group raises `ArgumentError` when the plot is drawn.

## Options

* `:data` (`t:term/0`) - A table for the layer to draw instead of the plot's data, anything implementing `Table.Reader`. The plot's mapping applies to it, so it must hold each column the plot's mapping names for an aesthetic the layer neither maps nor sets. Under a facet, a table lacking a faceting column is drawn in every panel of that column's values.

* `:position` - Where the marks are moved once the stat has run: left at their positions (`:identity`), piled on one another (`:stack`), piled to the same height (`:fill`), set side by side within the width given, `{:dodge, width: width}`, or each taken as that wide and set side by side with the marks it overlaps, `{:dodge2, width: width}`, having no width of their own to share, each moved a small random distance (`:jitter`), set side by side and then each moved a small random distance (`:jitterdodge`), or nudged (`:nudge`), each alone or with its options, as [Positions](#module-positions) says. The default value is `:identity`.

* `:orientation` - The axis each band runs along, `:x` or `:y`; when not given, along y where the layer is given neither `:ymin` nor `:ymax`, and along x otherwise. A band along x needs `:ymin` or `:ymax`, and one along y `:xmin` or `:xmax`.

* `:outline_type` - Which of each band's edges its outline draws: the upper and the lower, each a line (`:both`), the upper alone (`:upper`), the lower alone (`:lower`), or the band's whole border (`:full`). The default value is `:both`.

* `:alpha` - How opaque every band's fill is, from 0, invisible, to 1, opaque; its outline keeps its colour's own alpha.

* `:color` - The colour of every band's outline, written `colour:` or `color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; no outline when not given.

* `:fill` - The colour every band is filled with: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; when not given, the theme's ink mixed 20% toward its paper, `#333333`, or `#000000CC` under `theme_void/2`, whose paper is clear.

* `:linewidth` - How wide every band's outline is, in millimetres; the theme's `base_line_size` when not given, 0.5 at its default sizes.

* `:linetype` - The line type of every band's outline: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; `:solid` when not given.

* `:lineend` - How a line's ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half the line's width beyond it (`:square`). The default value is `:butt`.

* `:linejoin` - How a line turns a corner: rounded (`:round`), pointed (`:mitre`) or cut off (`:bevel`). The default value is `:round`.

* `:linemitre` - How far a pointed corner may reach, in widths of the line, before it is cut off; 1 or more. The default value is `10.0`.

* `:nudge_x` - How far every mark moves along x from its place, in the units of the x axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

* `:nudge_y` - How far every mark moves along y from its place, in the units of the y axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

    iex> frame =
    ...>   %{"x" => [2, 1, 3], "low" => [1.0, 0.5, 2.0], "high" => [3.0, 2.0, 4.0]}
    ...>   |> Giggly.Plot.new(%{x: :x, ymin: :low, ymax: :high})
    ...>   |> Giggly.Plot.geom_ribbon()
    ...>   |> Giggly.layer_data()
    iex> {Giggly.DataFrame.pull(frame, :x), Giggly.DataFrame.pull(frame, :ymin)}
    {[1, 2, 3], [0.5, 1.0, 2.0]}

A band given `:xmin` and `:xmax` runs up the panel:

    iex> frame =
    ...>   %{"y" => [1, 2], "low" => [1.0, 0.5], "high" => [3.0, 2.0]}
    ...>   |> Giggly.Plot.new(%{y: :y, xmin: :low, xmax: :high})
    ...>   |> Giggly.Plot.geom_ribbon(colour: "black")
    ...>   |> Giggly.layer_data()
    iex> Giggly.DataFrame.pull(frame, :flipped_aes)
    [true, true]

# `geom_rug`

```elixir
@spec geom_rug(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer of rugs: a short line at the panel's edge for each row, at its `x` along the
bottom and at its `y` along the left, so the margins show how each axis's values are spread,
beside a scatter plot of the same rows. Every row is drawn, so rugs suit small tables.

Rugs use `:x`, `:y`, `:group`, `:alpha`, `:color`, `:linetype` and `:linewidth`, and need one
of `:x` and `:y`; a side whose axis is not mapped draws nothing. `sides:` says which sides are
drawn, in any order. Each line runs in from the panel's edge as far as `length:` says, by
default 3% of the panel, which the 5% of room the axes leave at each end keeps clear of the
data; with `outside: true` it runs out from the edge instead, which shows only where
`coord_cartesian/2` leaves the panel unclipped. A row missing its place draws no line along
that axis's sides, and an infinite one is at the panel's corner. Where the rugs run along both
axes, a row repeated in every column is drawn once on each side, as ggplot2 draws it. Each line
takes its own row's colour, alpha, width and line type; a colour of `:none` draws none, and so
does the line type `:blank`. Under `coord_radial/1` the lines are straight all the same, along
the panel's square edges at each row's place, and a rug needs both `:x` and `:y` there.

With `position: :jitter` each row moves as `geom_jitter/3` moves the points of the same rows,
so a rug beside them marks each point; it needs both `:x` and `:y`.

## Options

* `:data` (`t:term/0`) - A table for the layer to draw instead of the plot's data, anything implementing `Table.Reader`. The plot's mapping applies to it, so it must hold each column the plot's mapping names for an aesthetic the layer neither maps nor sets. Under a facet, a table lacking a faceting column is drawn in every panel of that column's values.

* `:position` - Where the marks are moved once the stat has run: left at their positions (`:identity`), piled on one another (`:stack`), piled to the same height (`:fill`), set side by side within the width given, `{:dodge, width: width}`, or each taken as that wide and set side by side with the marks it overlaps, `{:dodge2, width: width}`, having no width of their own to share, each moved a small random distance (`:jitter`), set side by side and then each moved a small random distance (`:jitterdodge`), or nudged (`:nudge`), each alone or with its options, as [Positions](#module-positions) says. Jittering needs both `:x` and `:y`. The default value is `:identity`.

* `:alpha` - How opaque every mark is, from 0, invisible, to 1, opaque.

* `:color` - The colour of every line, written `colour:` or `color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; black when not given.

* `:linewidth` - How wide every line is, in millimetres; the theme's `base_line_size` when not given, 0.5 at its default sizes.

* `:linetype` - The line type of every line: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; `:solid` when not given.

* `:sides` - The sides of the panel the rugs are drawn along, a list of `:top`, `:right`, `:bottom` and `:left`, each given once: an `x` along the bottom and top, a `y` along the left and right. The default value is `[:bottom, :left]`.

* `:length` - How long each line is, `{amount, unit}`: a share of the panel (`:npc`), or a length in `:pt`, `:cm`, `:mm` or `:in`. The default value is `{0.03, :npc}`.

* `:outside` (`t:boolean/0`) - Whether each line runs out from the panel's edge rather than in, which shows only where the panel is not clipped (`coord_cartesian/2`'s `clip: :off`). The default value is `false`.

* `:lineend` - How a line's ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half the line's width beyond it (`:square`). The default value is `:butt`.

* `:nudge_x` - How far every mark moves along x from its place, in the units of the x axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

* `:nudge_y` - How far every mark moves along y from its place, in the units of the y axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

    iex> frame =
    ...>   %{"wt" => [2.62, 2.875], "mpg" => [21.0, 22.8]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_rug(sides: [:bottom, :right], length: {2, :mm})
    ...>   |> Giggly.layer_data()
    iex> {Giggly.DataFrame.pull(frame, :x), Giggly.DataFrame.pull(frame, :y)}
    {[2.62, 2.875], [21.0, 22.8]}

Rows repeated in every column are drawn once on each side where the rugs run along both axes,
so these three rows draw two lines along the bottom and two along the left:

    iex> svg =
    ...>   %{"x" => [1.0, 1.0, 2.0], "y" => [5.0, 5.0, 6.0]}
    ...>   |> Giggly.Plot.new(%{x: :x, y: :y})
    ...>   |> Giggly.Plot.geom_rug()
    ...>   |> Giggly.Plot.theme_void()
    ...>   |> Giggly.to_svg()
    ...>   |> IO.iodata_to_binary()
    iex> ~r/<line / |> Regex.scan(svg) |> length()
    4

# `geom_segment`

```elixir
@spec geom_segment(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer of segments: a straight line for each row, from its `x` and `y` to its `xend` and
`yend`, for a line joining two points the data names apart, such as a span of time or a spike
down to an axis.

Segments use `:x`, `:y`, `:xend`, `:yend`, `:group`, `:alpha`, `:color`, `:linetype` and
`:linewidth`, and need `:x`, `:y` and one of `:xend` and `:yend`: a segment given only `:xend`
ends at its own `y`, and one given only `:yend` at its own `x`. A row missing a position, its
width or its line type draws no segment, and an infinite position reaches the panel's edge. Each
segment takes its own row's colour, alpha, width and line type; a colour of `:none` draws none,
and so does the line type `:blank`. Under `coord_radial/1` a segment follows the panel's curves,
as a path from its start to its end does.

`arrow:` puts an arrowhead on each segment, in its colour, width and line type, a closed one
filled with its colour or the arrow's `fill:` at its alpha; under `coord_radial/1` a closed head
is filled with its segment's colour whatever the `fill:`.

## Options

* `:data` (`t:term/0`) - A table for the layer to draw instead of the plot's data, anything implementing `Table.Reader`. The plot's mapping applies to it, so it must hold each column the plot's mapping names for an aesthetic the layer neither maps nor sets. Under a facet, a table lacking a faceting column is drawn in every panel of that column's values.

* `:position` - Where the marks are moved once the stat has run: left at their positions (`:identity`), piled on one another (`:stack`), piled to the same height (`:fill`), set side by side within the width given, `{:dodge, width: width}`, or each taken as that wide and set side by side with the marks it overlaps, `{:dodge2, width: width}`, having no width of their own to share, each moved a small random distance (`:jitter`), set side by side and then each moved a small random distance (`:jitterdodge`), or nudged (`:nudge`), each alone or with its options, as [Positions](#module-positions) says. The default value is `:identity`.

* `:alpha` - How opaque every mark is, from 0, invisible, to 1, opaque.

* `:color` - The colour of every line, written `colour:` or `color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; black when not given.

* `:linewidth` - How wide every line is, in millimetres; the theme's `base_line_size` when not given, 0.5 at its default sizes.

* `:linetype` - The line type of every line: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; `:solid` when not given.

* `:arrow` - An arrowhead on each line: `true` for the defaults, or a keyword list of its options, `angle:` (30), `length:` (`{0.25, :in}`, in `:pt`, `:cm`, `:mm` or `:in`), `ends:` (`:last`, `:first` or `:both`), `type:` (`:open` or `:closed`) and `fill:`, a closed head's, a colour, `:none`, or `:color`, the line's colour and the default; none when not given.

* `:lineend` - How a line's ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half the line's width beyond it (`:square`). The default value is `:butt`.

* `:linejoin` - How a line turns a corner: rounded (`:round`), pointed (`:mitre`) or cut off (`:bevel`). The default value is `:round`.

* `:nudge_x` - How far every mark moves along x from its place, in the units of the x axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

* `:nudge_y` - How far every mark moves along y from its place, in the units of the y axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

    iex> frame =
    ...>   %{"start" => [1.0, 2.0], "finish" => [3.0, 5.0], "row" => [1.0, 2.0]}
    ...>   |> Giggly.Plot.new(%{x: :start, xend: :finish, y: :row})
    ...>   |> Giggly.Plot.geom_segment(lineend: :round)
    ...>   |> Giggly.layer_data()
    iex> {Giggly.DataFrame.pull(frame, :x), Giggly.DataFrame.pull(frame, :xend)}
    {[1.0, 2.0], [3.0, 5.0]}

A closed head filled white:

    iex> svg =
    ...>   %{"x" => [1.0], "y" => [1.0], "xend" => [2.0], "yend" => [3.0]}
    ...>   |> Giggly.Plot.new(%{x: :x, y: :y, xend: :xend, yend: :yend})
    ...>   |> Giggly.Plot.geom_segment(arrow: [type: :closed, fill: "white"])
    ...>   |> Giggly.to_svg()
    ...>   |> IO.iodata_to_binary()
    iex> svg =~ "fill: #FFFFFF;"
    true

# `geom_smooth`

```elixir
@spec geom_smooth(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer of smooths: a curve fitted to each group's rows, for the trend through a cloud of
points, drawn over its band, the confidence interval around it.

Each curve is worked out at `n:` evenly spaced places from the group's least `x` to its
greatest, or across the whole x axis with `fullrange: true`, and drawn over its band, its
standard error times a quantile at `level:` either side of it, the t distribution's for lm and
loess and the normal distribution's for gam. Each row is
weighted by its `:weight` where one is mapped; a row missing `x` or `y`, or at an infinite one,
or missing its weight, is left out, and a group holding fewer than two distinct `x`, or a weight
below 0 or infinite, is drawn nothing.

With `method: :lm` each curve is a straight line by least squares, `y` fitted to `x`; a row
weighted 0 is left out, a group whose weighted rows hold one `x` is drawn flat at their weighted
mean, and where the line meets every row, as through two, no band is drawn.

With `method: :loess`, each place's value is a quadratic fitted by least squares to the share
`span:` of the group's rows nearest it, nearer rows weighing more, so the curve follows the rows'
trend wherever it bends. It is drawn only across the group's rows, even with `fullrange: true`; a
row weighted 0 leaves the band out; and a group too small for its span to hold three distinct `x`
round each place, as one of five rows at the default span, is drawn nothing.

With `method: :gam`, each curve is a smoothing spline: a cubic curve through ten knots spread
evenly through the group's distinct `x`, its wiggliness penalised by as much as the rows bear
out, chosen by restricted maximum likelihood, and straight beyond the outermost knots, as
`fullrange: true` shows. A row weighted 0 still places the knots but adds nothing to the fit,
and a group of fewer than ten distinct `x`, or whose rows weighted above 0 share one `y`, is
drawn nothing.

A smooth given no method fits loess where the largest group in any panel holds under 1,000 rows,
and gam from there.

Smooths use `:x`, `:y`, `:weight`, `:group`, `:alpha`, `:fill`, `:color`, `:linetype` and
`:linewidth`, and need `:x` and `:y`; a `:weight` column must hold numbers. A curve's line is
drawn in its colour's own alpha, and `:alpha` fills its band.

## Options

* `:data` (`t:term/0`) - A table for the layer to draw instead of the plot's data, anything implementing `Table.Reader`. The plot's mapping applies to it, so it must hold each column the plot's mapping names for an aesthetic the layer neither maps nor sets. Under a facet, a table lacking a faceting column is drawn in every panel of that column's values.

* `:position` - Where the marks are moved once the stat has run: left at their positions (`:identity`), piled on one another (`:stack`), piled to the same height (`:fill`), set side by side within the width given, `{:dodge, width: width}`, or each taken as that wide and set side by side with the marks it overlaps, `{:dodge2, width: width}`, having no width of their own to share, each moved a small random distance (`:jitter`), set side by side and then each moved a small random distance (`:jitterdodge`), or nudged (`:nudge`), each alone or with its options, as [Positions](#module-positions) says. The default value is `:identity`.

* `:method` - How each curve is fitted: `:lm`, a straight line by least squares; `:loess`, at each place a quadratic fitted to the nearest rows, nearer ones weighing more; or `:gam`, a smoothing spline, its wiggliness chosen from the rows; each row weighted too by its `:weight` where one is mapped. When not given, loess where the largest group in any panel holds under 1,000 rows, and gam from there.

* `:se` (`t:boolean/0`) - Whether each curve is drawn over its band, the confidence interval around it at `level:`. The default value is `true`.

* `:level` - How confident each band is, above 0 and below 1. The default value is `0.95`.

* `:n` (`t:pos_integer/0`) - How many evenly spaced places along x each curve is worked out at. The default value is `80`.

* `:span` - How much of a group each loess fit reads, above 0: the share of its rows nearest each place, so a smaller span follows the rows more closely; only loess reads it. The default value is `0.75`.

* `:fullrange` (`t:boolean/0`) - Whether each curve spans the panel's axis it runs along, short of its widening, rather than its own group's extent along it. The default value is `false`.

* `:orientation` - The axis each curve runs along: `:x`, y fitted to x, or `:y`, x fitted to y, for a curve that runs up the panel. The default value is `:x`.

* `:alpha` - How opaque every band's fill is, from 0, invisible, to 1, opaque; 0.4 when not given. The line keeps its colour's own alpha.

* `:color` - The colour of every curve's line, written `colour:` or `color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; the theme's accent, `#3366FF`, when not given.

* `:fill` - The colour every band is filled with: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; when not given, the theme's ink mixed 60% toward its paper, `#999999`, or `#00000066` under `theme_void/2`, whose paper is clear.

* `:linewidth` - How wide every curve's line is, in millimetres; twice the theme's `base_line_size` when not given, 1 at its default sizes.

* `:linetype` - The line type of every line: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; `:solid` when not given.

* `:lineend` - How a line's ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half the line's width beyond it (`:square`). The default value is `:butt`.

* `:linejoin` - How a line turns a corner: rounded (`:round`), pointed (`:mitre`) or cut off (`:bevel`). The default value is `:round`.

* `:linemitre` - How far a pointed corner may reach, in widths of the line, before it is cut off; 1 or more. The default value is `10.0`.

* `:nudge_x` - How far every mark moves along x from its place, in the units of the x axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

* `:nudge_y` - How far every mark moves along y from its place, in the units of the y axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

    iex> frame =
    ...>   %{"x" => [1.0, 2.0, 3.0, 4.0], "y" => [1.0, 3.0, 2.0, 4.0]}
    ...>   |> Giggly.Plot.new(%{x: :x, y: :y})
    ...>   |> Giggly.Plot.geom_smooth(method: :lm, n: 3)
    ...>   |> Giggly.layer_data()
    iex> {Giggly.DataFrame.pull(frame, :x), Giggly.DataFrame.pull(frame, :y)}
    {[1.0, 2.5, 4.0], [1.2999999999999998, 2.5, 3.7]}

Without its band, a curve carries no standard error:

    iex> frame =
    ...>   %{"x" => [1.0, 2.0, 3.0, 4.0], "y" => [1.0, 3.0, 2.0, 4.0]}
    ...>   |> Giggly.Plot.new(%{x: :x, y: :y})
    ...>   |> Giggly.Plot.geom_smooth(method: :lm, se: false, n: 3)
    ...>   |> Giggly.layer_data()
    iex> :se in Giggly.DataFrame.names(frame)
    false

# `geom_text`

```elixir
@spec geom_text(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer of text: each row's `label` at its `x` and `y`.

Text is written as it is; a whole number has no decimal point (`21`, not `21.0`), any other
number up to 15 significant digits, in scientific notation when that is shorter (`1e+05`), and a
boolean is `TRUE` or `FALSE`. Each label is centred on its place, black and 11 points tall,
unless the options say otherwise. A row missing its `x`, `y` or label draws nothing.

Text uses `:x`, `:y`, `:label`, `:group`, `:alpha` and `:color`, and needs `:x`, `:y` and
`:label`; a label never groups the rows. `nudge_x:` and `nudge_y:` move every label, in the
units of each axis, and a mapped `:nudge_x` or `:nudge_y` each its own way, as its position,
`:nudge` unless `position:` says otherwise, reads them, and the axes reach the labels where they
are drawn. Raises `ArgumentError` for a nudge beside another position, which moves no label by
it.

## Options

* `:data` (`t:term/0`) - A table for the layer to draw instead of the plot's data, anything implementing `Table.Reader`. The plot's mapping applies to it, so it must hold each column the plot's mapping names for an aesthetic the layer neither maps nor sets. Under a facet, a table lacking a faceting column is drawn in every panel of that column's values.

* `:position` - Where the marks are moved once the stat has run: left at their positions (`:identity`), piled on one another (`:stack`), piled to the same height (`:fill`), set side by side within the width given, `{:dodge, width: width}`, or each taken as that wide and set side by side with the marks it overlaps, `{:dodge2, width: width}`, having no width of their own to share, each moved a small random distance (`:jitter`), set side by side and then each moved a small random distance (`:jitterdodge`), or nudged (`:nudge`), each alone or with its options, as [Positions](#module-positions) says. The default value is `:nudge`.

* `:check_overlap` (`t:boolean/0`) - Whether to leave out each label that would cross one drawn before it, the rows taken in order. The default value is `false`.

* `:alpha` - How opaque every mark is, from 0, invisible, to 1, opaque.

* `:color` - The colour of every label, written `colour:` or `color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; black when not given.

* `:size` - How big every label is, in millimetres, each 2.85 points; the theme's `base_size` when not given, 11 points at its default sizes.

* `:angle` - How far every label is turned, in degrees anticlockwise; 0 when not given.

* `:hjust` - Where along its baseline every label is anchored on its place, 0 its start and 1 its end: a number from 0 to 1, or one of the words `:left`, `:center` and `:right`, `:bottom`, `:middle` and `:top`, or `:inward` and `:outward`, which justify each label toward or away from the middle of the panel by where it falls; 0.5 when not given.

* `:vjust` - Where up its height every label is anchored on its place, 0 its baseline and 1 the top of a capital letter: a number from 0 to 1, or one of the words `:left`, `:center` and `:right`, `:bottom`, `:middle` and `:top`, or `:inward` and `:outward`, which justify each label toward or away from the middle of the panel by where it falls; 0.5 when not given.

* `:family` (`t:String.t/0`) - The font every label is drawn in, by name, such as `"Times New Roman"`, or one of the generic families `"sans"`, `"serif"` and `"mono"`; the theme's `base_family` when not given, the default sans-serif at its default. How a label is measured and drawn in it: the [fonts guide](fonts.md).

* `:nudge_x` - How far every mark moves along x from its place, in the units of the x axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

* `:nudge_y` - How far every mark moves along y from its place, in the units of the y axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32], "mpg" => [21.0, 22.8], "model" => ["Mazda RX4", "Datsun 710"]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, label: :model})
    ...>   |> Giggly.Plot.geom_text(hjust: :inward, size: 5)
    iex> frame = Giggly.layer_data(plot)
    iex> Giggly.DataFrame.pull(frame, :label)
    ["Mazda RX4", "Datsun 710"]
    iex> Giggly.DataFrame.pull(frame, :hjust)
    [:inward, :inward]

A whole number is labelled without a decimal point, and a large one in scientific notation:

    iex> svg =
    ...>   %{"x" => [1.0, 2.0], "y" => [1.0, 2.0], "count" => [21.0, 100_000.0]}
    ...>   |> Giggly.Plot.new(%{x: :x, y: :y, label: :count})
    ...>   |> Giggly.Plot.geom_text()
    ...>   |> Giggly.to_svg()
    ...>   |> IO.iodata_to_binary()
    iex> {svg =~ ">21</text>", svg =~ ">1e+05</text>"}
    {true, true}

Nudged labels sit off the points they name:

    iex> frame =
    ...>   %{"x" => [1.0, 2.0, 3.0], "y" => [1.0, 4.0, 2.0], "name" => ["a", "b", "c"]}
    ...>   |> Giggly.Plot.new(%{x: :x, y: :y, label: :name})
    ...>   |> Giggly.Plot.geom_text(nudge_x: 0.1, nudge_y: -0.2)
    ...>   |> Giggly.layer_data()
    iex> {Giggly.DataFrame.pull(frame, :x), Giggly.DataFrame.pull(frame, :y)}
    {[1.1, 2.1, 3.1], [0.8, 3.8, 1.8]}

# `geom_tile`

```elixir
@spec geom_tile(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer of tiles, one per row, each a rectangle centred on its `x` and `y`, for a surface
or a grid of values drawn as colours.

Each tile is as wide as the closest spacing of the `x` positions in its panel and as tall as
that of the `y` positions, 1 on a discrete axis, and on a continuous one the closest gap, a
column of integers spaced as any numbers are; or as wide as its mapped `:width` and as tall as its
mapped `:height`, numbers, or as `width:` and `height:` make every tile, which win over mapped
ones. A row missing its `x` or `y` draws nothing.

Tiles use `:x`, `:y`, `:group`, `:alpha`, `:fill`, `:color`, `:linetype`, `:linewidth`,
`:width` and `:height`, and need `:x` and `:y`. `:fill` fills a tile and takes its alpha;
`:color` borders it, and tiles have no border unless it is mapped or set; `:linewidth` and
`:linetype` say how wide the border is and how it is dashed.

## Options

* `:data` (`t:term/0`) - A table for the layer to draw instead of the plot's data, anything implementing `Table.Reader`. The plot's mapping applies to it, so it must hold each column the plot's mapping names for an aesthetic the layer neither maps nor sets. Under a facet, a table lacking a faceting column is drawn in every panel of that column's values.

* `:position` - Where the marks are moved once the stat has run: left at their positions (`:identity`), piled on one another (`:stack`), piled to the same height (`:fill`), set side by side within the width one mark takes or the width given (`:dodge`), set side by side, each its share of their widths, with a gap between them (`:dodge2`), each moved a small random distance (`:jitter`), set side by side and then each moved a small random distance (`:jitterdodge`), or nudged (`:nudge`), each alone or with its options, as [Positions](#module-positions) says. The default value is `:identity`.

* `:alpha` - How opaque every mark is, from 0, invisible, to 1, opaque.

* `:color` - The colour of every tile's border, written `colour:` or `color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; no border when not given. A border takes no alpha but its colour's own.

* `:fill` - The colour every tile is filled with: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; when not given, the theme's ink mixed 20% toward its paper, `#333333`, or `#000000CC` under `theme_void/2`, whose paper is clear.

* `:linewidth` - How wide every tile's border is, in millimetres; 0.4 times the theme's `base_line_size` when not given, 0.2 at its default sizes.

* `:linetype` - The line type of every tile's border: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; `:solid` when not given.

* `:width` - How wide every tile is, in the units of the x axis, any number; it replaces the width the tiles would take otherwise, and a mapped `:width`.

* `:height` - How tall every tile is, in the units of the y axis, as `width:` sets a width.

* `:nudge_x` - How far every mark moves along x from its place, in the units of the x axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

* `:nudge_y` - How far every mark moves along y from its place, in the units of the y axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

    iex> frame =
    ...>   %{"x" => [2.0, 5.0, 7.0, 9.0, 12.0], "y" => [1.0, 1.0, 1.0, 1.0, 1.0]}
    ...>   |> Giggly.Plot.new(%{x: :x, y: :y})
    ...>   |> Giggly.Plot.geom_tile()
    ...>   |> Giggly.layer_data()
    iex> {Giggly.DataFrame.pull(frame, :xmin), Giggly.DataFrame.pull(frame, :xmax)}
    {[1.0, 4.0, 6.0, 8.0, 11.0], [3.0, 6.0, 8.0, 10.0, 13.0]}

Mapped widths make tiles of different sizes, here meeting edge to edge:

    iex> frame =
    ...>   %{"x" => [2.0, 5.0, 7.0, 9.0, 12.0], "y" => [1.0, 1.0, 1.0, 1.0, 1.0],
    ...>     "w" => [4.0, 2.0, 2.0, 2.0, 4.0]}
    ...>   |> Giggly.Plot.new(%{x: :x, y: :y, width: :w})
    ...>   |> Giggly.Plot.geom_tile()
    ...>   |> Giggly.layer_data()
    iex> {Giggly.DataFrame.pull(frame, :xmin), Giggly.DataFrame.pull(frame, :xmax)}
    {[0.0, 4.0, 6.0, 8.0, 10.0], [4.0, 6.0, 8.0, 10.0, 14.0]}

# `geom_violin`

```elixir
@spec geom_violin(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer of violins: for each group, a density of its `y` mirrored about its `x`, a compact
view of its distribution, drawn where a box plot would draw its box.

Each violin's outline is a kernel density estimate of its group's `y`, worked out as
`geom_density/3` works one out, its bandwidth from every row of the group: a kernel, a normal
curve unless `kernel:` says otherwise, put at each row and summed, its spread `bw:` times
`adjust:`, each row weighing as its `:weight` where one is mapped. A violin spans its own group's
extent, at 512 evenly spaced places, unless `trim: false` lets its tails reach three bandwidths
past it, and `bounds:` folds back what lies beyond a finite bound. Each violin is as wide at a
place as its density there makes it beside the panel's greatest, so every violin has the same
area, unless `scale:` says otherwise; it stands at its group's `x`, or the middle of its group's
`x` values where they are several, in a room 0.9 times the closest spacing of the `x` positions
wide, counting from zero, or 0.9 of the range of those values, or as wide as its group's mapped
`:width`, or as `width:` says. A row missing its `x`, `y` or weight, or at an infinite one, is
left out; a group of fewer than two rows is left out too, unless `drop: false` keeps it as room
for a position. A panel where some group's weight is below 0 is drawn nothing.

Violins stand along the discrete one of `x` and `y`, so mapping a discrete `y` beside a numeric
`x` draws horizontal violins; where both are continuous they stand along the axis on which every
group holds one value, or else along `x`, each group a violin. `orientation:` says which.
Violins sharing a position are set side by side, as `position:` says.

Violins use `:x`, `:y`, `:group`, `:weight`, `:width`, `:alpha`, `:color`, `:fill`,
`:linetype` and `:linewidth`, and need `:x` and `:y`. A look reaches a violin from its group's
first row, so a discrete one groups the rows and gives each group its own violin. Each is
bordered in the theme's ink mixed 20% toward its paper and filled with its paper unless a look
is mapped or set.

Given a `quantile_linetype:`, each violin is drawn with a line across it at each of the
quantiles of its group's `y` its densities mark (`quantiles:`, its quartiles unless given), side
to side at the violin's width there, from its lowest to its highest; each line in its quantile's
row's colour, at its alpha, and width unless `quantile_color:` and `quantile_linewidth:` give
them. Every border and line is drawn with butt ends and round corners; `lineend:` and
`linejoin:` draw the legend's keys.

Each group's densities compute each place's `density`; `scaled`, the density over the group's
greatest; `count`, the density times its rows; `violinwidth`, how wide the violin is there;
`n`, its rows; `width`, its room's width where the stat gives one; and `quantile`, which the
rows marking `quantiles:` hold, which a mapping reads with an after_stat (`Giggly.Mapping`).

## Options

* `:data` (`t:term/0`) - A table for the layer to draw instead of the plot's data, anything implementing `Table.Reader`. The plot's mapping applies to it, so it must hold each column the plot's mapping names for an aesthetic the layer neither maps nor sets. Under a facet, a table lacking a faceting column is drawn in every panel of that column's values.

* `:position` - Where the marks are moved once the stat has run: left at their positions (`:identity`), piled on one another (`:stack`), piled to the same height (`:fill`), set side by side within the width one mark takes or the width given (`:dodge`), set side by side, each its share of their widths, with a gap between them (`:dodge2`), each moved a small random distance (`:jitter`), set side by side and then each moved a small random distance (`:jitterdodge`), or nudged (`:nudge`), each alone or with its options, as [Positions](#module-positions) says. The default value is `:dodge`.

* `:bw` - How smooth each curve is, its bandwidth, the kernel's standard deviation in the axis's transformed units: a number above 0, or a rule worked out from each group's rows, taking no weight: Silverman's rule of thumb (`:nrd0`), 0.9 times the lesser of the rows' standard deviation and their interquartile range over 1.34, times the rows to the power -0.2, or Scott's variation of it (`:nrd`), 1.06 times the lesser. The default value is `:nrd0`.

* `:adjust` - A multiple of the bandwidth, above 0: `adjust: 0.5` halves it, for a curve that follows the rows more closely, and `adjust: 2` doubles it, for a smoother one. The default value is `1.0`.

* `:kernel` - The shape put at each row and summed, scaled so its standard deviation is the bandwidth: a normal curve (`:gaussian`), a parabola (`:epanechnikov`), a block (`:rectangular`), a tent (`:triangular`), a parabola squared (`:biweight`), or a cosine's hump (`:cosine`) or a narrower one (`:optcosine`). The default value is `:gaussian`.

* `:trim` (`t:boolean/0`) - Whether each violin spans only its own group's extent; `false` reaches three of the rule's bandwidths, before `adjust:`, past it either end, so its tails show. The default value is `true`.

* `:bounds` - Limits the rows are known to lie within, `{low, high}`, the low a number or `:neg_infinity`, the high a number or `:infinity`, not below the low: the rows outside them are left out, and each curve's part beyond a finite one is folded back inside it, so the curve does not spill past a limit the data cannot. The default value is `{:neg_infinity, :infinity}`.

* `:scale` - How the violins are sized beside one another: each the same area (`:area`), as wide as its density makes it beside the panel's greatest; that times its rows over the panel's most, so a violin of more rows is bigger (`:count`); or each as wide at its widest (`:width`). The default value is `:area`.

* `:quantiles` - The quantiles of each group's `y` the densities mark, each a row of its own whose `quantile` is its probability, a list of numbers from 0 to 1, or `:none` for no `quantile` column at all. The default value is `[0.25, 0.5, 0.75]`.

* `:drop` (`t:boolean/0`) - Whether to leave out a group of fewer than two rows, or, `false`, keep it as one row of missing densities, so a position makes room for it. The default value is `true`.

* `:width` - How wide a violin's room is, in the units of the axis it stands on, any number; it replaces a mapped `:width`, and gives way to 0.9 of the range of a group spanning several positions. 0.9 times the closest spacing of the positions, counting from zero, when not given.

* `:orientation` - The axis the violins stand along, `:x` or `:y`, estimating the other; when not given they stand along the discrete one, or else along the axis on which every group holds one value, or else along x.

* `:alpha` - How opaque every violin's fill and quantile lines are, from 0, invisible, to 1, opaque; its border keeps its colour's own alpha.

* `:color` - The colour of every violin's border, written `colour:` or `color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; when not given, the theme's ink mixed 20% toward its paper, `#333333`, or `#000000CC` under `theme_void/2`.

* `:fill` - The colour every violin is filled with: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; the theme's paper when not given, white, or clear under `theme_void/2`.

* `:linewidth` - How wide every violin's border is, in millimetres; the theme's `base_line_size` when not given, 0.5 at its default sizes.

* `:linetype` - The line type of every violin's border: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; `:solid` when not given.

* `:quantile_color` - The colour of the lines across each violin at the quantiles its densities mark, written `quantile_colour:` or `quantile_color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; its violin's border colour when not given.

* `:quantile_linetype` - The line type of the lines across each violin at the quantiles its densities mark (`quantiles:`): `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; `:blank`, drawing none, when not given. The default value is `:blank`.

* `:quantile_linewidth` - How wide the quantile lines are, in millimetres; their violin's border width when not given.

* `:lineend` - How the borders of the legend's keys end: cut square at the end (`:butt`), rounded (`:round`), or cut square half the line's width beyond it (`:square`); the violins' own borders are always cut square at the end. The default value is `:butt`.

* `:linejoin` - How the borders of the legend's keys turn a corner: pointed (`:mitre`), rounded (`:round`) or cut off (`:bevel`); the violins' own borders always turn rounded. The default value is `:mitre`.

* `:nudge_x` - How far every mark moves along x from its place, in the units of the x axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

* `:nudge_y` - How far every mark moves along y from its place, in the units of the y axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

    iex> frame =
    ...>   %{"g" => ["a", "a", "a"], "y" => [1.0, 2.0, 4.0]}
    ...>   |> Giggly.Plot.new(%{x: :g, y: :y})
    ...>   |> Giggly.Plot.geom_violin(quantiles: [0.5])
    ...>   |> Giggly.layer_data()
    iex> {Giggly.DataFrame.row_count(frame), Enum.at(Giggly.DataFrame.pull(frame, :y), -1)}
    {513, 2.0}

# `geom_vline`

```elixir
@spec geom_vline(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer of vertical reference lines: a line up the whole panel at each `xintercept`, for
a date to mark, a threshold or a mean drawn over the data.

The lines are given in one of two ways. `xintercept:` gives them as values, a line for each,
drawn in every panel and in no legend. Or the layer maps `:xintercept` from a table, its own
`data:` or the plot's, so the lines can differ from panel to panel under a facet and map a
colour, alpha, width or line type into a legend. Either way the layer takes nothing from the
plot's mapping, and titles no axis.

Vertical lines use `:xintercept`, `:group`, `:alpha`, `:color`, `:linetype` and `:linewidth`,
and need `:xintercept`, which the x axis widens to show and puts through its scale as it does
`x`: a number on a continuous axis, a string on a discrete one, a date, a date-time or a time
on such an axis, and `:infinity` or `:neg_infinity` at the panel's edge. A line repeated in a
panel is drawn once. Beside `xintercept:`, each look option takes one value or a list, one per
line, every list as long as the others. A line missing its `xintercept`, as a scale's limits
leave it, draws nothing, and so do a colour of `:none` and the line type `:blank`. Under
`coord_radial/1` each line is a spoke from the centre.

Raises `ArgumentError` for `xintercept:` beside a mapping or `data:`, for a list of looks
without `xintercept:`, and for lists of different lengths.

## Options

* `:data` (`t:term/0`) - A table for the layer's mapping to draw from instead of the plot's data, anything implementing `Table.Reader`; refused beside the options giving lines as values, which draw lines of their own. Under a facet, a table lacking a faceting column is drawn in every panel.

* `:position` - Where the lines are moved: left where they cross the axis (`:identity`), or nudged (`:nudge`), as [Positions](#module-positions) says. The default value is `:identity`.

* `:xintercept` - Where each line crosses the x axis, in its units: a value, or a list of them, a line for each, drawn in every panel. Given, the layer takes no mapping and no `data:`.

* `:nudge_x` - How far every mark moves along x from its place, in the units of the x axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

* `:alpha` - How opaque each line is, from 0, invisible, to 1, opaque.

* `:color` - The colour of each line, written `colour:` or `color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; black when not given.

* `:linewidth` - How wide each line is, in millimetres; the theme's `base_line_size` when not given, 0.5 at its default sizes.

* `:linetype` - The line type of each line: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; `:solid` when not given.

* `:lineend` - How a line's ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half the line's width beyond it (`:square`). The default value is `:butt`.

    iex> frame =
    ...>   %{"wt" => [2.62, 3.44], "mpg" => [21.0, 18.7]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.geom_vline(xintercept: [3, 5], linetype: :dashed)
    ...>   |> Giggly.layer_data(1)
    iex> Giggly.DataFrame.pull(frame, :xintercept)
    [3.0, 5.0]

# `guide_legend`

```elixir
@spec guide_legend(keyword()) :: struct()
```

A legend for a scale's `guide:` or for `guides/2`, with options: a key for each of the scale's
breaks, labelled, as `:legend` draws, its keys in the order the options choose.

Raises `NimbleOptions.ValidationError` for an option it does not take or a value it cannot use.

## Options

* `:reverse` (`t:boolean/0`) - Whether the keys run from the last break down to the first, the key of a missing value first. The default value is `false`.

    iex> svg =
    ...>   %{"wt" => [2.62, 2.875, 2.32], "mpg" => [21.0, 22.8, 22.8], "drv" => ["f", "r", "4"]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, colour: :drv})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.guides(color: Giggly.Plot.guide_legend(reverse: true))
    ...>   |> Giggly.to_svg()
    ...>   |> IO.iodata_to_binary()
    iex> Regex.scan(~r{>([fr4])</text>}, svg, capture: :all_but_first)
    [["r"], ["f"], ["4"]]

# `guides`

```elixir
@spec guides(t(), keyword()) :: t()
```

Sets the guide that reads each aesthetic's scale back: `:legend`, a key for each break;
`:colorbar`, a bar a continuous colour or fill scale's colours run up; `:colorsteps`, a bar of
one block of colour for each bin between a colour or fill scale's breaks, all as long whatever
the bins' widths, each break's label at its edge; a legend `guide_legend/1` makes; or `:none`
for none.

A guide set here wins over the one its scale's `guide:` chooses, before or after the scale is
given. Each call sets only the guides it is given, keeping the rest. A colour bar or colour
steps for alpha, shape or size raise here; either for a colour or fill scale that is discrete,
or a colour bar for a binned one, raises when the plot is run. A guide for an aesthetic no layer
maps reads nothing.

## Options

* `:color` - The colour scale's guide (`colour:` too), as `scale_color_continuous/2`'s `guide:` takes it; a colour bar for a continuous scale alone, colour steps for a binned or continuous one.

* `:fill` - The fill scale's guide, as `scale_fill_continuous/2`'s `guide:` takes it; a colour bar for a continuous scale alone, colour steps for a binned or continuous one.

* `:alpha` - The alpha scale's guide, as `scale_alpha_continuous/2`'s `guide:` takes it.

* `:shape` - The shape scale's guide, as `scale_shape_discrete/2`'s `guide:` takes it.

* `:size` - The size scale's guide, as `scale_size_continuous/2`'s `guide:` takes it.

* `:linetype` - The line type scale's guide, as `scale_linetype_discrete/2`'s `guide:` takes it.

* `:linewidth` - The line width scale's guide, as `scale_linewidth_continuous/2`'s `guide:` takes it.

    iex> svg =
    ...>   %{"wt" => [2.62, 2.875], "mpg" => [21.0, 22.8], "cyl" => ["6", "4"]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, colour: :cyl})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.guides(color: :none)
    ...>   |> Giggly.to_svg()
    ...>   |> IO.iodata_to_binary()
    iex> svg =~ ">cyl</text>"
    false

# `labs`

```elixir
@spec labs(t(), keyword()) :: t()
```

Sets the plot's labels: the title of an axis or a legend, named by its aesthetic, and the plot's
title, subtitle, caption and tag.

An axis or legend is otherwise titled by what is mapped to it (`Giggly.Mapping`); a label set
here replaces that title, whether the layer was added before or after. A label of `:none`
removes the title and the room it took, and `""` keeps the room and draws nothing. A label for an
aesthetic no layer maps titles nothing. Each call sets only the labels it is given, keeping the
rest. A label breaking over several lines (`"Fuel\neconomy"`) is drawn a line at a time.

The title and subtitle are drawn above the panels, from their left edge; the caption below them,
to their right edge; and the tag at the plot's top left.

## Options

* `:x` - The x axis's title.

* `:y` - The y axis's title.

* `:color` - The colour legend's or colour bar's title (`colour:` too).

* `:fill` - The fill legend's or colour bar's title.

* `:alpha` - The alpha legend's title.

* `:shape` - The shape legend's title.

* `:size` - The size legend's title.

* `:linetype` - The line type legend's title.

* `:linewidth` - The line width legend's title.

* `:title` - The plot's title, above the panels.

* `:subtitle` - The plot's subtitle, below its title.

* `:caption` - The plot's caption, below the panels.

* `:tag` - The plot's tag, at its top left.

    iex> svg =
    ...>   %{"wt" => [2.62, 2.875], "mpg" => [21.0, 22.8]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.labs(x: "Weight (1000 lbs)", y: :none, title: "Fuel economy")
    ...>   |> Giggly.to_svg()
    ...>   |> IO.iodata_to_binary()
    iex> {svg =~ ">Weight (1000 lbs)</text>", svg =~ ">mpg</text>", svg =~ ">Fuel economy</text>"}
    {true, false, true}

# `lims`

```elixir
@spec lims(t(), keyword()) :: t()
```

Gives the plot a scale with the given limits for each axis named, replacing any scale it had for
it, as `xlim/3`, `xlim/2`, `ylim/3` and `ylim/2` do: `{low, high}` for a continuous or a date
scale, a list of values for a discrete one.

## Options

* `:x` - The x axis's limits, as `xlim/3` or `xlim/2` takes them.

* `:y` - The y axis's limits, as `ylim/3` or `ylim/2` takes them.

* `:color` - The colour scale's limits (`colour:` too): `{low, high}` for a continuous scale, as `scale_color_continuous/2` takes them, two numbers high to low running it from high to low, as `transform: :reverse` runs it, or a list of values for a discrete one, as `scale_color_discrete/2` does.

* `:fill` - The fill scale's limits, as `scale_fill_continuous/2` or `scale_fill_discrete/2` takes them.

* `:alpha` - The alpha scale's limits, as `scale_alpha_continuous/2` or `scale_alpha_discrete/2` takes them.

* `:shape` - The shape scale's limits, a list of values, as `scale_shape_discrete/2` takes them.

* `:size` - The size scale's limits, as `scale_size_continuous/2` or `scale_size_discrete/2` takes them.

* `:linetype` - The line type scale's limits, a list of values, as `scale_linetype_discrete/2` takes them.

* `:linewidth` - The line width scale's limits, as `scale_linewidth_continuous/2` or `scale_linewidth_discrete/2` takes them.

    iex> plot =
    ...>   %{"wt" => [1.5, 2.6, 3.4], "mpg" => [30.4, 21.0, 18.7]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.lims(x: {2, 4}, y: {15, 25})
    iex> frame = Giggly.layer_data(plot)
    iex> {Giggly.DataFrame.pull(frame, :x), Giggly.DataFrame.pull(frame, :y)}
    {[nil, 2.6, 3.4], [nil, 21.0, 18.7]}

# `new`

```elixir
@spec new(Table.Reader.t(), mapping_argument()) :: t()
```

A plot of `data`, with `mapping` applying to every layer.

The mapping's columns are checked by the layers that use them, so a misspelt column is reported
by the first layer function to take it. Raises `ArgumentError` for a value that is not a column,
an expression or a constant (`Giggly.Mapping`).

    iex> plot =
    ...>   Giggly.Plot.new(
    ...>     %{"wt" => [2.62, 2.875], "mpg" => [21.0, 22.8], "cyl" => ["6", "4"]},
    ...>     %{x: :wt, y: "mpg", colour: :cyl}
    ...>   )
    iex> plot.mapping
    %{x: "wt", y: "mpg", color: "cyl"}

# `scale_alpha_continuous`

```elixir
@spec scale_alpha_continuous(t(), keyword()) :: t()
```

Gives the plot a continuous alpha scale, replacing any alpha scale it had.

Each value is drawn as opaque as it is far from the first of `range:` to the second through the
limits; its guide is a legend unless `guide:` says otherwise. Raises
`NimbleOptions.ValidationError` for an option it does not take or a value it cannot use, an
opacity outside 0 to 1 or a `guide:` of `:colorbar` or `:colorsteps`, and `ArgumentError` for a
list of labels without a list of breaks as long; a column that is not numbers is refused when the
plot is run.

## Options

* `:range` - `{low, high}`: the opacities the values run between, each from 0 to 1. The default value is `{0.1, 1.0}`.

* `:na_value` - The opacity of a missing value, or of one outside the limits, from 0 to 1; its colour's own when not given.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the scale spans whatever the data, `nil` for an end the data decides; either order names the same scale. A value outside them takes `na_value:`, unless `oob:` says otherwise where the scale takes it.

* `:breaks` - The values the legend or colour bar marks, a list of numbers, those outside the limits left out; a function that returns them, or `{break, label}` pairs, handed the limits, `{low, high}`, and, taking two arguments, `[n: n]` as `n_breaks:` asks, `[]` when not given; or `:none` for no guide; chosen from the limits when not given.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted, 2 or more, of the breaks chosen when `breaks:` is not given, or of a `breaks:` function of two arguments; not beside `breaks:` a list, `:none` or a function of one argument, which wants no number.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break, a list of numbers, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do; or `:none` for no labels. A pair's label when a `breaks:` function returns pairs.

* `:transform` - What each value is put through before the scale sees it, a transformation of `Scales.Transform`'s: `:identity`, `:log`, `:log2`, `:log10`, `{:log, base}`, `:log1p`, `:exp`, `{:exp, base}`, `:asinh`, `:pseudo_log`, `{:pseudo_log, sigma: sigma, base: base}`, `:sqrt`, `:reverse`, `:reciprocal`, `:asn`, `:atanh`, `:logit`, `:probit`, `{:probability, :normal, mean: mean, sd: sd}`, `{:probability, :logistic, location: location, scale: scale}`, `{:boxcox, exponent}`, `{:boxcox, exponent, offset: offset}`, `{:modulus, exponent}`, `{:modulus, exponent, offset: offset}`, `{:yj, exponent}`, `:timespan`, `{:timespan, unit}`, a composition `{:compose, [part, ...]}` or one `Scales.Transform.new/2` makes; `:identity` when not given. The scale trains, breaks and places in transformed space, its limits and breaks given in data units, and labels its breaks in data units.

* `:oob` - What happens to a value outside the limits: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. A value left outside, or left missing, takes `na_value:`, but an opacity or a size kept outside runs on past its range. `:censor` when not given.

* `:guide` - What reads the scale back: `:legend`, a key for each break, or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:legend`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "hp" => [1, 2, 3]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, alpha: :hp})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_alpha_continuous(range: {0, 1})
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:alpha)
    [0.0, 0.5, 1.0]

# `scale_alpha_discrete`

```elixir
@spec scale_alpha_discrete(t(), keyword()) :: t()
```

Gives the plot a discrete alpha scale, replacing any alpha scale it had.

The values' opacities are spaced evenly from the first of `range:` to the second, in order; its
guide is a legend unless `guide:` says otherwise. Raises `NimbleOptions.ValidationError` for an
option it does not take or a value it cannot use, an opacity outside 0 to 1 or a `guide:` of
`:colorbar` or `:colorsteps`, and `ArgumentError` for a list of labels not one for each break or
limit given; a column of numbers is refused when the plot is run.

## Options

* `:range` - `{low, high}`: the opacities the values run between, each from 0 to 1. The default value is `{0.1, 1.0}`.

* `:na_value` - The opacity of a missing value, or of one outside the limits, from 0 to 1; its colour's own when not given.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - The values the scale shows, a list in the order shown, whatever the data; each value as the column holds it, `nil` for the missing value, a number naming the value equal to it. A value not among them takes `na_value:`. Every value the data holds, in order, when not given.

* `:breaks` - The values the legend shows a key for, a list in the order given, those not among the limits left out; a function of one argument handed the limits that returns them, or `{value, label}` pairs, a pair's label its key's; or `:none` for no legend; every one of the limits when not given.

* `:labels` - The keys' labels: a list of strings, `nil` drawn `NA`, one for each break, or for each limit when no breaks are given; a map from a value to its label, a value it does not hold keeping its own; a function handed every break, a list of values, that returns a label for each, a string, a power or `nil`; or `:none` for keys with no labels. Each value written as text when not given.

* `:guide` - What reads the scale back: `:legend`, a key for each break, or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:legend`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "cyl" => ["6", "4", "8"]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, alpha: :cyl})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_alpha_discrete(range: {0.25, 0.75})
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:alpha)
    [0.5, 0.25, 0.75]

# `scale_color_binned`

```elixir
@spec scale_color_binned(t(), keyword()) :: t()
```

Gives the plot a binned colour scale, replacing any colour scale it had: the values are cut into
bins at its breaks and every value in a bin takes one colour, by default the colour at the
bin's middle of a gradient from `#132B43` to `#56B1F7`, or a colour each of `palette:`, a
palette's name or a list, given to the bins in order.

Values outside the limits take the colour of the nearer end bin, unless `oob:` says otherwise;
with neither limits nor
breaks given, the limits are the data's range widened so the end bins are as wide as their
neighbours. Its guide is colour steps, a bar of one block of colour for each bin, unless
`guide:` names another.
Raises `NimbleOptions.ValidationError` for an option it does not take or a value it cannot use,
and `ArgumentError` for a list of labels without a list of breaks as long, `show_limits: true`
beside a list of labels, or `n_breaks: 1` for nice breaks; a column that is not numbers is
refused when the plot is run.

## Options

* `:palette` - A palette's name, one of scales' in any case (`Scales.Palette.named/1`), such as `"Blues"` or `"viridis"`, its colours for as many bins as there are given to them in order, or a list of colours, given to the bins in order, at least one for each; a gradient from `#132B43` to `#56B1F7`, each bin the colour at its middle, when not given.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `"#7F7F7F"`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the bins span whatever the data, `nil` for an end the data decides; either order names the same scale. A value outside them takes the colour of the bin at the nearer end, unless `oob:` says otherwise. The data's range, widened so the end bins are as wide as their neighbours, when neither this nor `breaks:` is given.

* `:oob` - What happens to a value outside the limits before it is binned: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. A value left outside, or left missing, takes `na_value:`. `:squish` when not given, so a value outside takes the colour of the bin at the nearer end.

* `:breaks` - The values the bins are cut at, a list of numbers, those outside the limits left out; a function that returns them, or `{break, label}` pairs, handed the limits, `{low, high}`, and, taking two arguments, `[n: n_breaks]`; or `:none` for one bin and no guide; chosen from the limits as `n_breaks:` and `nice_breaks:` say when not given.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break, a list of numbers, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do, and handed the limits too where `show_limits:` shows them; or `:none` for no labels. A pair's label when a `breaks:` function returns pairs.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted when `breaks:` is not given: 2 or more for nice breaks, which may number a few more or fewer, 1 or more otherwise; or of a `breaks:` function of two arguments. When given, not beside `breaks:` a list, `:none` or a function of one argument, which wants no number. The default value is `5`.

* `:nice_breaks` (`t:boolean/0`) - Whether breaks not given are round numbers, chosen as a continuous scale's are, or `n_breaks:` spaced evenly between the ends of the limits. The default value is `true`.

* `:right` (`t:boolean/0`) - Where a value on a break falls: `true` in the bin below it, `false` in the bin above. The default value is `true`.

* `:show_limits` (`t:boolean/0`) - Whether colour steps label the ends of the bar with the limits, unless a break is already there; not beside a list of `labels:`, which labels the breaks alone. The default value is `false`.

* `:guide` - What reads the scale back: `:colorsteps`, a bar of one block of colour for each bin; `:legend`, a key for each break; or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:colorsteps`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "hp" => [110, 93, 175]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, colour: :hp})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_color_binned()
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:color)
    ["#265075", "#193753", "#4FA2E3"]

# `scale_color_brewer`

```elixir
@spec scale_color_brewer(t(), keyword()) :: t()
```

Gives the plot a discrete colour scale from a ColorBrewer palette, replacing any colour scale it
had.

The palette is `palette:`, by name or by its number among the palettes of `type:`, its colours
given to the values in order, or in reverse for `direction: -1`; each palette has a set of
colours for each count from 3 to its largest, chosen to be told apart, sequential palettes for
ordered values, diverging for values either side of a middle and qualitative for values with no
order. A missing value takes no colour unless `na_value:` gives one. Raises
`NimbleOptions.ValidationError` for an option it does not take, a name ColorBrewer does not
spell so or a number below 1, and `ArgumentError` for a number past the last of its type's or a
list of labels not one for each break or limit given; a column of numbers, or more values than
the palette's largest set has colours, is refused when the plot is run.

## Options

* `:type` - The palettes a number in `palette:` counts among: `:seq`, sequential; `:div`, diverging; or `:qual`, qualitative. A name is not counted, so this is not read beside one. The default value is `:seq`.

* `:palette` - The ColorBrewer palette: its name, spelled as `Scales.Palette.brewer_palettes/1` spells it, or its number among the palettes of `type:`, counting from 1. The default value is `1`.

* `:direction` - 1 to give the palette's colours to the values in order, -1 in reverse. The default value is `1`.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `:none`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - The values the scale shows, a list in the order shown, whatever the data; each value as the column holds it, `nil` for the missing value, a number naming the value equal to it. A value not among them takes `na_value:`. Every value the data holds, in order, when not given.

* `:breaks` - The values the legend shows a key for, a list in the order given, those not among the limits left out; a function of one argument handed the limits that returns them, or `{value, label}` pairs, a pair's label its key's; or `:none` for no legend; every one of the limits when not given.

* `:labels` - The keys' labels: a list of strings, `nil` drawn `NA`, one for each break, or for each limit when no breaks are given; a map from a value to its label, a value it does not hold keeping its own; a function handed every break, a list of values, that returns a label for each, a string, a power or `nil`; or `:none` for keys with no labels. Each value written as text when not given.

* `:guide` - What reads the scale back: `:legend`, a key for each break, or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:legend`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "cyl" => ["6", "4", "8"]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, colour: :cyl})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_color_brewer(palette: "Set1")
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:color)
    ["#377EB8", "#E41A1C", "#4DAF4A"]

# `scale_color_continuous`

```elixir
@spec scale_color_continuous(t(), keyword()) :: t()
```

Gives the plot a continuous colour scale, replacing any colour scale it had: a gradient from
`#132B43` to `#56B1F7`, as a column of numbers gets by default, or through the colours of
`palette:`, a palette's name or a list, spaced evenly over the limits.

Raises `NimbleOptions.ValidationError` for an option it does not take, a palette's name scales
does not know, a colour CSS does not define or one with an alpha of its own, and `ArgumentError`
for a list of labels without a list of breaks as long; a column that is not numbers is refused
when the plot is run.

## Options

* `:palette` - A palette's name, one of scales' in any case (`Scales.Palette.named/1`), such as `"Blues"` or `"viridis"`, its colours blended in order, or a list of colours, spaced evenly from the low end of the limits to the high; a gradient from `#132B43` to `#56B1F7` when not given.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `"#7F7F7F"`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the scale spans whatever the data, `nil` for an end the data decides; either order names the same scale. A value outside them takes `na_value:`, unless `oob:` says otherwise where the scale takes it.

* `:breaks` - The values the legend or colour bar marks, a list of numbers, those outside the limits left out; a function that returns them, or `{break, label}` pairs, handed the limits, `{low, high}`, and, taking two arguments, `[n: n]` as `n_breaks:` asks, `[]` when not given; or `:none` for no guide; chosen from the limits when not given.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted, 2 or more, of the breaks chosen when `breaks:` is not given, or of a `breaks:` function of two arguments; not beside `breaks:` a list, `:none` or a function of one argument, which wants no number.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break, a list of numbers, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do; or `:none` for no labels. A pair's label when a `breaks:` function returns pairs.

* `:transform` - What each value is put through before the scale sees it, a transformation of `Scales.Transform`'s: `:identity`, `:log`, `:log2`, `:log10`, `{:log, base}`, `:log1p`, `:exp`, `{:exp, base}`, `:asinh`, `:pseudo_log`, `{:pseudo_log, sigma: sigma, base: base}`, `:sqrt`, `:reverse`, `:reciprocal`, `:asn`, `:atanh`, `:logit`, `:probit`, `{:probability, :normal, mean: mean, sd: sd}`, `{:probability, :logistic, location: location, scale: scale}`, `{:boxcox, exponent}`, `{:boxcox, exponent, offset: offset}`, `{:modulus, exponent}`, `{:modulus, exponent, offset: offset}`, `{:yj, exponent}`, `:timespan`, `{:timespan, unit}`, a composition `{:compose, [part, ...]}` or one `Scales.Transform.new/2` makes; `:identity` when not given. The scale trains, breaks and places in transformed space, its limits and breaks given in data units, and labels its breaks in data units.

* `:oob` - What happens to a value outside the limits: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. A value left outside, or left missing, takes `na_value:`, but an opacity or a size kept outside runs on past its range. `:censor` when not given.

* `:guide` - What reads the scale back: `:colorbar`, a bar the colours run up; `:colorsteps`, a bar of one block of colour between each break and the next; `:legend`, a key for each break; or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:colorbar`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "hp" => [5, 12, 0]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, colour: :hp})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_color_continuous(limits: {0, 10})
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:color)
    ["#336A98", "#7F7F7F", "#132B43"]

# `scale_color_discrete`

```elixir
@spec scale_color_discrete(t(), keyword()) :: t()
```

Gives the plot a discrete colour scale, replacing any colour scale it had: hues spaced evenly
round the colour wheel, as a discrete column gets by default, or the colours of `palette:`, a
palette's name or a list, in order.

Raises `NimbleOptions.ValidationError` for an option it does not take, a palette's name scales
does not know or a colour CSS does not define, and `ArgumentError` for a list of labels not one
for each break or limit given; a column of numbers, or more values than a list or a ColorBrewer
palette has colours, is refused when the plot is run.

## Options

* `:palette` - A palette's name, one of scales' in any case (`Scales.Palette.named/1`), such as `"Set1"` or `"viridis"`, or a list of colours, its colours given to the values in order; hues spaced evenly round the colour wheel when not given.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `"#7F7F7F"`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - The values the scale shows, a list in the order shown, whatever the data; each value as the column holds it, `nil` for the missing value, a number naming the value equal to it. A value not among them takes `na_value:`. Every value the data holds, in order, when not given.

* `:breaks` - The values the legend shows a key for, a list in the order given, those not among the limits left out; a function of one argument handed the limits that returns them, or `{value, label}` pairs, a pair's label its key's; or `:none` for no legend; every one of the limits when not given.

* `:labels` - The keys' labels: a list of strings, `nil` drawn `NA`, one for each break, or for each limit when no breaks are given; a map from a value to its label, a value it does not hold keeping its own; a function handed every break, a list of values, that returns a label for each, a string, a power or `nil`; or `:none` for keys with no labels. Each value written as text when not given.

* `:guide` - What reads the scale back: `:legend`, a key for each break, or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:legend`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "cyl" => ["6", "4", "8"]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, colour: :cyl})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_color_discrete(palette: ["steelblue", "orange", "red"])
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:color)
    ["#FFA500", "#4682B4", "#FF0000"]

# `scale_color_distiller`

```elixir
@spec scale_color_distiller(t(), keyword()) :: t()
```

Gives the plot a continuous colour scale, a gradient through a ColorBrewer palette, replacing any
colour scale it had.

The gradient runs through seven colours of the palette `palette:`, by name or by its number
among the palettes of `type:`, spaced evenly over the limits unless `values:` places them, from
its last at the low end to its first at the high, or the other way for `direction: 1`, blended
in CIE L*a*b* between neighbours, as `scale_color_gradientn/2` blends its colours; its guide is a
colour bar unless `guide:` names another. A qualitative palette is taken too, though its colours
have no order to blend along. Raises `NimbleOptions.ValidationError` for an option it does not
take, a name ColorBrewer does not spell so or a number below 1, and `ArgumentError` for a number
past the last of its type's or a list of labels without a list of breaks as long; a column that
is not numbers is refused when the plot is run.

## Options

* `:type` - The palettes a number in `palette:` counts among: `:seq`, sequential; `:div`, diverging; or `:qual`, qualitative. A name is not counted, so this is not read beside one. The default value is `:seq`.

* `:palette` - The ColorBrewer palette: its name, spelled as `Scales.Palette.brewer_palettes/1` spells it, or its number among the palettes of `type:`, counting from 1. The default value is `1`.

* `:direction` - -1 to blend the palette's colours from its last at the low end of the limits to its first at the high, 1 the other way. The default value is `-1`.

* `:values` - Where the colours sit: places from 0, the low end of the limits, to 1, the high, one for each colour, so each colour sits at its place and those between are blended; of another count, the colours are spread over them evenly. A value beyond the first or last place takes `na_value:`. The colours are spaced evenly when not given.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `"#7F7F7F"`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the scale spans whatever the data, `nil` for an end the data decides; either order names the same scale. A value outside them takes `na_value:`, unless `oob:` says otherwise where the scale takes it.

* `:breaks` - The values the legend or colour bar marks, a list of numbers, those outside the limits left out; a function that returns them, or `{break, label}` pairs, handed the limits, `{low, high}`, and, taking two arguments, `[n: n]` as `n_breaks:` asks, `[]` when not given; or `:none` for no guide; chosen from the limits when not given.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted, 2 or more, of the breaks chosen when `breaks:` is not given, or of a `breaks:` function of two arguments; not beside `breaks:` a list, `:none` or a function of one argument, which wants no number.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break, a list of numbers, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do; or `:none` for no labels. A pair's label when a `breaks:` function returns pairs.

* `:transform` - What each value is put through before the scale sees it, a transformation of `Scales.Transform`'s: `:identity`, `:log`, `:log2`, `:log10`, `{:log, base}`, `:log1p`, `:exp`, `{:exp, base}`, `:asinh`, `:pseudo_log`, `{:pseudo_log, sigma: sigma, base: base}`, `:sqrt`, `:reverse`, `:reciprocal`, `:asn`, `:atanh`, `:logit`, `:probit`, `{:probability, :normal, mean: mean, sd: sd}`, `{:probability, :logistic, location: location, scale: scale}`, `{:boxcox, exponent}`, `{:boxcox, exponent, offset: offset}`, `{:modulus, exponent}`, `{:modulus, exponent, offset: offset}`, `{:yj, exponent}`, `:timespan`, `{:timespan, unit}`, a composition `{:compose, [part, ...]}` or one `Scales.Transform.new/2` makes; `:identity` when not given. The scale trains, breaks and places in transformed space, its limits and breaks given in data units, and labels its breaks in data units.

* `:oob` - What happens to a value outside the limits: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. A value left outside, or left missing, takes `na_value:`, but an opacity or a size kept outside runs on past its range. `:censor` when not given.

* `:guide` - What reads the scale back: `:colorbar`, a bar the colours run up; `:colorsteps`, a bar of one block of colour between each break and the next; `:legend`, a key for each break; or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:colorbar`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "hp" => [0, 5, 10]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, colour: :hp})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_color_distiller()
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:color)
    ["#084594", "#6BAED6", "#EFF3FF"]

# `scale_color_fermenter`

```elixir
@spec scale_color_fermenter(t(), keyword()) :: t()
```

Gives the plot a binned colour scale from a ColorBrewer palette, replacing any colour scale it
had.

The values are cut into bins at its breaks, as `scale_color_binned/2` cuts them, and the bins
take the colours of the palette `palette:`'s set for as many, by name or by its number among
the palettes of `type:`, from its last at the lowest bin to its first at the highest, or the
other way for `direction: 1`. Raises `NimbleOptions.ValidationError` for an option it does not
take, a name ColorBrewer does not spell so or a number below 1, and `ArgumentError` for a
number past the last of its type's, a list of labels without a list of breaks as long,
`show_limits: true` beside a list of labels, or `n_breaks: 1` for nice breaks; a column that is
not numbers, or more bins than the palette's largest set has colours, is refused when the plot
is run.

## Options

* `:type` - The palettes a number in `palette:` counts among: `:seq`, sequential; `:div`, diverging; or `:qual`, qualitative. A name is not counted, so this is not read beside one. The default value is `:seq`.

* `:palette` - The ColorBrewer palette: its name, spelled as `Scales.Palette.brewer_palettes/1` spells it, or its number among the palettes of `type:`, counting from 1. The default value is `1`.

* `:direction` - -1 to give the palette's colours to the bins from its last at the lowest to its first at the highest, 1 the other way. The default value is `-1`.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `"#7F7F7F"`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the bins span whatever the data, `nil` for an end the data decides; either order names the same scale. A value outside them takes the colour of the bin at the nearer end, unless `oob:` says otherwise. The data's range, widened so the end bins are as wide as their neighbours, when neither this nor `breaks:` is given.

* `:oob` - What happens to a value outside the limits before it is binned: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. A value left outside, or left missing, takes `na_value:`. `:squish` when not given, so a value outside takes the colour of the bin at the nearer end.

* `:breaks` - The values the bins are cut at, a list of numbers, those outside the limits left out; a function that returns them, or `{break, label}` pairs, handed the limits, `{low, high}`, and, taking two arguments, `[n: n_breaks]`; or `:none` for one bin and no guide; chosen from the limits as `n_breaks:` and `nice_breaks:` say when not given.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break, a list of numbers, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do, and handed the limits too where `show_limits:` shows them; or `:none` for no labels. A pair's label when a `breaks:` function returns pairs.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted when `breaks:` is not given: 2 or more for nice breaks, which may number a few more or fewer, 1 or more otherwise; or of a `breaks:` function of two arguments. When given, not beside `breaks:` a list, `:none` or a function of one argument, which wants no number. The default value is `5`.

* `:nice_breaks` (`t:boolean/0`) - Whether breaks not given are round numbers, chosen as a continuous scale's are, or `n_breaks:` spaced evenly between the ends of the limits. The default value is `true`.

* `:right` (`t:boolean/0`) - Where a value on a break falls: `true` in the bin below it, `false` in the bin above. The default value is `true`.

* `:show_limits` (`t:boolean/0`) - Whether colour steps label the ends of the bar with the limits, unless a break is already there; not beside a list of `labels:`, which labels the breaks alone. The default value is `false`.

* `:guide` - What reads the scale back: `:colorsteps`, a bar of one block of colour for each bin; `:legend`, a key for each break; or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:colorsteps`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "hp" => [110, 93, 175]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, colour: :hp})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_color_fermenter()
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:color)
    ["#3182BD", "#08519C", "#EFF3FF"]

# `scale_color_gradient2`

```elixir
@spec scale_color_gradient2(t(), keyword()) :: t()
```

Gives the plot a continuous colour scale diverging from `mid:` at `midpoint:`, toward `low:`
below it and `high:` above, replacing any colour scale it had.

A value's colour is as far toward its side's end as the value is from the midpoint, the end of
the limits further from the midpoint taking its colour in full and the nearer only as far as it
reaches; its guide is a colour bar unless `guide:` names another. Raises
`NimbleOptions.ValidationError` for an option it does not take, a colour CSS does not define or
one with an alpha of its own, and `ArgumentError` for a list of labels without a list of breaks
as long; a column that is not numbers is refused when the plot is run.

## Options

* `:low` - The colour the low side runs to, a dark red when not given. The default value is `"#832424"`.

* `:mid` - The colour at the midpoint, white when not given. The default value is `"#FFFFFF"`.

* `:high` - The colour the high side runs to, a dark blue when not given. The default value is `"#3A3A98"`.

* `:midpoint` - The value the middle colour stands at. The default value is `0.0`.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `"#7F7F7F"`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the scale spans whatever the data, `nil` for an end the data decides; either order names the same scale. A value outside them takes `na_value:`, unless `oob:` says otherwise where the scale takes it.

* `:breaks` - The values the legend or colour bar marks, a list of numbers, those outside the limits left out; a function that returns them, or `{break, label}` pairs, handed the limits, `{low, high}`, and, taking two arguments, `[n: n]` as `n_breaks:` asks, `[]` when not given; or `:none` for no guide; chosen from the limits when not given.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted, 2 or more, of the breaks chosen when `breaks:` is not given, or of a `breaks:` function of two arguments; not beside `breaks:` a list, `:none` or a function of one argument, which wants no number.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break, a list of numbers, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do; or `:none` for no labels. A pair's label when a `breaks:` function returns pairs.

* `:transform` - What each value is put through before the scale sees it, a transformation of `Scales.Transform`'s: `:identity`, `:log`, `:log2`, `:log10`, `{:log, base}`, `:log1p`, `:exp`, `{:exp, base}`, `:asinh`, `:pseudo_log`, `{:pseudo_log, sigma: sigma, base: base}`, `:sqrt`, `:reverse`, `:reciprocal`, `:asn`, `:atanh`, `:logit`, `:probit`, `{:probability, :normal, mean: mean, sd: sd}`, `{:probability, :logistic, location: location, scale: scale}`, `{:boxcox, exponent}`, `{:boxcox, exponent, offset: offset}`, `{:modulus, exponent}`, `{:modulus, exponent, offset: offset}`, `{:yj, exponent}`, `:timespan`, `{:timespan, unit}`, a composition `{:compose, [part, ...]}` or one `Scales.Transform.new/2` makes; `:identity` when not given. The scale trains, breaks and places in transformed space, its limits and breaks given in data units, and labels its breaks in data units.

* `:oob` - What happens to a value outside the limits: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. A value left outside, or left missing, takes `na_value:`, but an opacity or a size kept outside runs on past its range. `:censor` when not given.

* `:guide` - What reads the scale back: `:colorbar`, a bar the colours run up; `:colorsteps`, a bar of one block of colour between each break and the next; `:legend`, a key for each break; or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:colorbar`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "change" => [-2, 0, 1]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, colour: :change})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_color_gradient2()
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:color)
    ["#832424", "#FFFFFF", "#A197CC"]

# `scale_color_gradient`

```elixir
@spec scale_color_gradient(t(), keyword()) :: t()
```

Gives the plot a continuous colour scale, a gradient from `low:` to `high:`, replacing any colour
scale it had.

Each value takes the colour as far along the gradient as the value is through the limits,
blended in CIE L*a*b*, which spaces colours evenly to the eye; its guide is a colour bar unless
`guide:` names another. Raises `NimbleOptions.ValidationError` for an option it does not take, a
colour CSS does not define or one with an alpha of its own, and `ArgumentError` for a list of
labels without a list of breaks as long; a column that is not numbers is refused when the plot is
run.

## Options

* `:low` - The colour at the low end of the limits. The default value is `"#132B43"`.

* `:high` - The colour at the high end of the limits. The default value is `"#56B1F7"`.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `"#7F7F7F"`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the scale spans whatever the data, `nil` for an end the data decides; either order names the same scale. A value outside them takes `na_value:`, unless `oob:` says otherwise where the scale takes it.

* `:breaks` - The values the legend or colour bar marks, a list of numbers, those outside the limits left out; a function that returns them, or `{break, label}` pairs, handed the limits, `{low, high}`, and, taking two arguments, `[n: n]` as `n_breaks:` asks, `[]` when not given; or `:none` for no guide; chosen from the limits when not given.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted, 2 or more, of the breaks chosen when `breaks:` is not given, or of a `breaks:` function of two arguments; not beside `breaks:` a list, `:none` or a function of one argument, which wants no number.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break, a list of numbers, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do; or `:none` for no labels. A pair's label when a `breaks:` function returns pairs.

* `:transform` - What each value is put through before the scale sees it, a transformation of `Scales.Transform`'s: `:identity`, `:log`, `:log2`, `:log10`, `{:log, base}`, `:log1p`, `:exp`, `{:exp, base}`, `:asinh`, `:pseudo_log`, `{:pseudo_log, sigma: sigma, base: base}`, `:sqrt`, `:reverse`, `:reciprocal`, `:asn`, `:atanh`, `:logit`, `:probit`, `{:probability, :normal, mean: mean, sd: sd}`, `{:probability, :logistic, location: location, scale: scale}`, `{:boxcox, exponent}`, `{:boxcox, exponent, offset: offset}`, `{:modulus, exponent}`, `{:modulus, exponent, offset: offset}`, `{:yj, exponent}`, `:timespan`, `{:timespan, unit}`, a composition `{:compose, [part, ...]}` or one `Scales.Transform.new/2` makes; `:identity` when not given. The scale trains, breaks and places in transformed space, its limits and breaks given in data units, and labels its breaks in data units.

* `:oob` - What happens to a value outside the limits: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. A value left outside, or left missing, takes `na_value:`, but an opacity or a size kept outside runs on past its range. `:censor` when not given.

* `:guide` - What reads the scale back: `:colorbar`, a bar the colours run up; `:colorsteps`, a bar of one block of colour between each break and the next; `:legend`, a key for each break; or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:colorbar`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "hp" => [1, 2, 3]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, colour: :hp})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_color_gradient(low: "white", high: "black")
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:color)
    ["#FFFFFF", "#777777", "#000000"]

# `scale_color_gradientn`

```elixir
@spec scale_color_gradientn(t(), keyword()) :: t()
```

Gives the plot a continuous colour scale, a gradient through the colours of `colors:`, replacing
any colour scale it had.

The colours are spaced evenly over the limits, the first at the low end and the last at the high,
unless `values:` places them, and blended in CIE L*a*b* between neighbours; its guide is a colour
bar unless `guide:` names another. Raises `NimbleOptions.ValidationError` for an option it does
not take, a colour CSS does not define or one with an alpha of its own, and `ArgumentError` for
a list of labels without a list of breaks as long; a column that is not numbers is refused when
the plot is run.

## Options

* `:colors` - Required. The colours, a list, spaced evenly from the low end of the limits to the high unless `values:` places them.

* `:values` - Where the colours sit: places from 0, the low end of the limits, to 1, the high, one for each colour, so each colour sits at its place and those between are blended; of another count, the colours are spread over them evenly. A value beyond the first or last place takes `na_value:`. The colours are spaced evenly when not given.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `"#7F7F7F"`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the scale spans whatever the data, `nil` for an end the data decides; either order names the same scale. A value outside them takes `na_value:`, unless `oob:` says otherwise where the scale takes it.

* `:breaks` - The values the legend or colour bar marks, a list of numbers, those outside the limits left out; a function that returns them, or `{break, label}` pairs, handed the limits, `{low, high}`, and, taking two arguments, `[n: n]` as `n_breaks:` asks, `[]` when not given; or `:none` for no guide; chosen from the limits when not given.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted, 2 or more, of the breaks chosen when `breaks:` is not given, or of a `breaks:` function of two arguments; not beside `breaks:` a list, `:none` or a function of one argument, which wants no number.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break, a list of numbers, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do; or `:none` for no labels. A pair's label when a `breaks:` function returns pairs.

* `:transform` - What each value is put through before the scale sees it, a transformation of `Scales.Transform`'s: `:identity`, `:log`, `:log2`, `:log10`, `{:log, base}`, `:log1p`, `:exp`, `{:exp, base}`, `:asinh`, `:pseudo_log`, `{:pseudo_log, sigma: sigma, base: base}`, `:sqrt`, `:reverse`, `:reciprocal`, `:asn`, `:atanh`, `:logit`, `:probit`, `{:probability, :normal, mean: mean, sd: sd}`, `{:probability, :logistic, location: location, scale: scale}`, `{:boxcox, exponent}`, `{:boxcox, exponent, offset: offset}`, `{:modulus, exponent}`, `{:modulus, exponent, offset: offset}`, `{:yj, exponent}`, `:timespan`, `{:timespan, unit}`, a composition `{:compose, [part, ...]}` or one `Scales.Transform.new/2` makes; `:identity` when not given. The scale trains, breaks and places in transformed space, its limits and breaks given in data units, and labels its breaks in data units.

* `:oob` - What happens to a value outside the limits: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. A value left outside, or left missing, takes `na_value:`, but an opacity or a size kept outside runs on past its range. `:censor` when not given.

* `:guide` - What reads the scale back: `:colorbar`, a bar the colours run up; `:colorsteps`, a bar of one block of colour between each break and the next; `:legend`, a key for each break; or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:colorbar`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "hp" => [0, 5, 10]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, colour: :hp})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_color_gradientn(colors: ["red", "yellow", "blue"])
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:color)
    ["#FF0000", "#FFFF00", "#0000FF"]

# `scale_color_gray`

```elixir
@spec scale_color_gray(t(), keyword()) :: t()
```

Gives the plot a discrete colour scale of greys, replacing any colour scale it had.

The greys run from `start:` to `end:`, spaced evenly to the eye; a missing value is red.
Raises `NimbleOptions.ValidationError` for an option it does not take or a grey's level outside
0 to 1, and `ArgumentError` for a list of labels not one for each break or limit given; a column
of numbers is refused when the plot is run.

## Options

* `:start` - The first value's grey, from 0, black, to 1, white. The default value is `0.2`.

* `:end` - The last value's grey, from 0, black, to 1, white. The default value is `0.8`.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `"#FF0000"`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - The values the scale shows, a list in the order shown, whatever the data; each value as the column holds it, `nil` for the missing value, a number naming the value equal to it. A value not among them takes `na_value:`. Every value the data holds, in order, when not given.

* `:breaks` - The values the legend shows a key for, a list in the order given, those not among the limits left out; a function of one argument handed the limits that returns them, or `{value, label}` pairs, a pair's label its key's; or `:none` for no legend; every one of the limits when not given.

* `:labels` - The keys' labels: a list of strings, `nil` drawn `NA`, one for each break, or for each limit when no breaks are given; a map from a value to its label, a value it does not hold keeping its own; a function handed every break, a list of values, that returns a label for each, a string, a power or `nil`; or `:none` for keys with no labels. Each value written as text when not given.

* `:guide` - What reads the scale back: `:legend`, a key for each break, or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:legend`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "cyl" => ["6", "4", "8"]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, colour: :cyl})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_color_gray()
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:color)
    ["#989898", "#333333", "#CCCCCC"]

# `scale_color_hue`

```elixir
@spec scale_color_hue(t(), keyword()) :: t()
```

Gives the plot a discrete colour scale of hues spaced evenly round the colour wheel, all of one
chroma and luminance, replacing any colour scale it had.

A discrete column mapped to colour gets these hues by default; the options choose others.
Raises `NimbleOptions.ValidationError` for an option it does not take or a value it cannot use,
and `ArgumentError` for a list of labels not one for each break or limit given; a column of
numbers is refused when the plot is run.

## Options

* `:hue` - `{first, last}`: the hues the colours are spaced between, in degrees round the colour wheel. A range spanning the whole circle leaves its last share off, so the first and last colours differ. The default value is `{15.0, 375.0}`.

* `:chroma` - How vivid the colours are, from 0, grey. The default value is `100.0`.

* `:luminance` - How light the colours are, from 0, black, to 100, white. The default value is `65.0`.

* `:direction` - 1 to give the colours to the values in order, -1 in reverse. The default value is `1`.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `"#7F7F7F"`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - The values the scale shows, a list in the order shown, whatever the data; each value as the column holds it, `nil` for the missing value, a number naming the value equal to it. A value not among them takes `na_value:`. Every value the data holds, in order, when not given.

* `:breaks` - The values the legend shows a key for, a list in the order given, those not among the limits left out; a function of one argument handed the limits that returns them, or `{value, label}` pairs, a pair's label its key's; or `:none` for no legend; every one of the limits when not given.

* `:labels` - The keys' labels: a list of strings, `nil` drawn `NA`, one for each break, or for each limit when no breaks are given; a map from a value to its label, a value it does not hold keeping its own; a function handed every break, a list of values, that returns a label for each, a string, a power or `nil`; or `:none` for keys with no labels. Each value written as text when not given.

* `:guide` - What reads the scale back: `:legend`, a key for each break, or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:legend`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "cyl" => ["6", "4", "8"]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, colour: :cyl})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_color_hue(luminance: 40, chroma: 30)
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:color)
    ["#3A6845", "#7F5351", "#515E7F"]

# `scale_color_manual`

```elixir
@spec scale_color_manual(t(), keyword()) :: t()
```

Gives the plot a discrete colour scale of the colours given, replacing any colour scale it had.

`values:` gives the colours, a list handed to the values in order, or a map from a value to its
colour. The legend shows a key for each value the scale shows, labelled. Raises
`NimbleOptions.ValidationError` for an option it does not take or a colour CSS does not define,
and `ArgumentError` for a list of labels not one for each break or limit given; a column of
numbers, or more values than a list has colours, is refused when the plot is run.

## Options

* `:values` - Required. The colours: a list, given to the values in order, or to `breaks:` in order where they are a list; or a map from a value, as the column holds it, to its colour, whose scale shows only the values the data holds that it names, unless `limits:` gives others. A value with no colour takes `na_value:`.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `"#7F7F7F"`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - The values the scale shows, a list in the order shown, whatever the data; each value as the column holds it, `nil` for the missing value, a number naming the value equal to it. A value not among them takes `na_value:`. Every value the data holds, in order, when not given.

* `:breaks` - The values the legend shows a key for, a list in the order given, those not among the limits left out; a function of one argument handed the limits that returns them, or `{value, label}` pairs, a pair's label its key's; or `:none` for no legend; every one of the limits when not given.

* `:labels` - The keys' labels: a list of strings, `nil` drawn `NA`, one for each break, or for each limit when no breaks are given; a map from a value to its label, a value it does not hold keeping its own; a function handed every break, a list of values, that returns a label for each, a string, a power or `nil`; or `:none` for keys with no labels. Each value written as text when not given.

* `:guide` - What reads the scale back: `:legend`, a key for each break, or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:legend`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "cyl" => ["6", "4", "8"]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, colour: :cyl})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_color_manual(values: %{"4" => "steelblue", "6" => "orange", "8" => "red"})
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:color)
    ["#FFA500", "#4682B4", "#FF0000"]

# `scale_color_steps2`

```elixir
@spec scale_color_steps2(t(), keyword()) :: t()
```

Gives the plot a binned colour scale diverging from `mid:` at `midpoint:`, toward `low:` below
it and `high:` above, cut into steps, replacing any colour scale it had.

The values are cut into bins at its breaks, as `scale_color_binned/2` cuts them, and every value
in a bin takes the colour `scale_color_gradient2/2` gives the bin's middle.
Raises `NimbleOptions.ValidationError` for an option it does not take or a value it cannot use,
and `ArgumentError` for a list of labels without a list of breaks as long, `show_limits: true`
beside a list of labels, or `n_breaks: 1` for nice breaks; a column that is not numbers is
refused when the plot is run.

## Options

* `:low` - The colour the low side runs to, a dark red when not given. The default value is `"#832424"`.

* `:mid` - The colour at the midpoint, white when not given. The default value is `"#FFFFFF"`.

* `:high` - The colour the high side runs to, a dark blue when not given. The default value is `"#3A3A98"`.

* `:midpoint` - The value the middle colour stands at. The default value is `0.0`.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `"#7F7F7F"`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the bins span whatever the data, `nil` for an end the data decides; either order names the same scale. A value outside them takes the colour of the bin at the nearer end, unless `oob:` says otherwise. The data's range, widened so the end bins are as wide as their neighbours, when neither this nor `breaks:` is given.

* `:oob` - What happens to a value outside the limits before it is binned: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. A value left outside, or left missing, takes `na_value:`. `:squish` when not given, so a value outside takes the colour of the bin at the nearer end.

* `:breaks` - The values the bins are cut at, a list of numbers, those outside the limits left out; a function that returns them, or `{break, label}` pairs, handed the limits, `{low, high}`, and, taking two arguments, `[n: n_breaks]`; or `:none` for one bin and no guide; chosen from the limits as `n_breaks:` and `nice_breaks:` say when not given.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break, a list of numbers, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do, and handed the limits too where `show_limits:` shows them; or `:none` for no labels. A pair's label when a `breaks:` function returns pairs.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted when `breaks:` is not given: 2 or more for nice breaks, which may number a few more or fewer, 1 or more otherwise; or of a `breaks:` function of two arguments. When given, not beside `breaks:` a list, `:none` or a function of one argument, which wants no number. The default value is `5`.

* `:nice_breaks` (`t:boolean/0`) - Whether breaks not given are round numbers, chosen as a continuous scale's are, or `n_breaks:` spaced evenly between the ends of the limits. The default value is `true`.

* `:right` (`t:boolean/0`) - Where a value on a break falls: `true` in the bin below it, `false` in the bin above. The default value is `true`.

* `:show_limits` (`t:boolean/0`) - Whether colour steps label the ends of the bar with the limits, unless a break is already there; not beside a list of `labels:`, which labels the breaks alone. The default value is `false`.

* `:guide` - What reads the scale back: `:colorsteps`, a bar of one block of colour for each bin; `:legend`, a key for each break; or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:colorsteps`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "hp" => [110, 93, 175]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, colour: :hp})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_color_steps2(midpoint: 120)
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:color)
    ["#EED9D6", "#C89089", "#6057A9"]

# `scale_color_steps`

```elixir
@spec scale_color_steps(t(), keyword()) :: t()
```

Gives the plot a binned colour scale, a gradient from `low:` to `high:` cut into steps, replacing
any colour scale it had.

The values are cut into bins at its breaks, as `scale_color_binned/2` cuts them, and every value
in a bin takes the colour of the gradient at the bin's middle, blended in CIE L*a*b*.
Raises `NimbleOptions.ValidationError` for an option it does not take or a value it cannot use,
and `ArgumentError` for a list of labels without a list of breaks as long, `show_limits: true`
beside a list of labels, or `n_breaks: 1` for nice breaks; a column that is not numbers is
refused when the plot is run.

## Options

* `:low` - The colour at the low end of the limits. The default value is `"#132B43"`.

* `:high` - The colour at the high end of the limits. The default value is `"#56B1F7"`.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `"#7F7F7F"`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the bins span whatever the data, `nil` for an end the data decides; either order names the same scale. A value outside them takes the colour of the bin at the nearer end, unless `oob:` says otherwise. The data's range, widened so the end bins are as wide as their neighbours, when neither this nor `breaks:` is given.

* `:oob` - What happens to a value outside the limits before it is binned: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. A value left outside, or left missing, takes `na_value:`. `:squish` when not given, so a value outside takes the colour of the bin at the nearer end.

* `:breaks` - The values the bins are cut at, a list of numbers, those outside the limits left out; a function that returns them, or `{break, label}` pairs, handed the limits, `{low, high}`, and, taking two arguments, `[n: n_breaks]`; or `:none` for one bin and no guide; chosen from the limits as `n_breaks:` and `nice_breaks:` say when not given.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break, a list of numbers, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do, and handed the limits too where `show_limits:` shows them; or `:none` for no labels. A pair's label when a `breaks:` function returns pairs.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted when `breaks:` is not given: 2 or more for nice breaks, which may number a few more or fewer, 1 or more otherwise; or of a `breaks:` function of two arguments. When given, not beside `breaks:` a list, `:none` or a function of one argument, which wants no number. The default value is `5`.

* `:nice_breaks` (`t:boolean/0`) - Whether breaks not given are round numbers, chosen as a continuous scale's are, or `n_breaks:` spaced evenly between the ends of the limits. The default value is `true`.

* `:right` (`t:boolean/0`) - Where a value on a break falls: `true` in the bin below it, `false` in the bin above. The default value is `true`.

* `:show_limits` (`t:boolean/0`) - Whether colour steps label the ends of the bar with the limits, unless a break is already there; not beside a list of `labels:`, which labels the breaks alone. The default value is `false`.

* `:guide` - What reads the scale back: `:colorsteps`, a bar of one block of colour for each bin; `:legend`, a key for each break; or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:colorsteps`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "hp" => [110, 93, 175]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, colour: :hp})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_color_steps(low: "white", high: "black")
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:color)
    ["#ABABAB", "#E2E2E2", "#1B1B1B"]

# `scale_color_stepsn`

```elixir
@spec scale_color_stepsn(t(), keyword()) :: t()
```

Gives the plot a binned colour scale, a gradient through the colours of `colors:` cut into steps,
replacing any colour scale it had.

The values are cut into bins at its breaks, as `scale_color_binned/2` cuts them, and every value
in a bin takes the colour `scale_color_gradientn/2` gives the bin's middle.
Raises `NimbleOptions.ValidationError` for an option it does not take or a value it cannot use,
and `ArgumentError` for a list of labels without a list of breaks as long, `show_limits: true`
beside a list of labels, or `n_breaks: 1` for nice breaks; a column that is not numbers is
refused when the plot is run.

## Options

* `:colors` - Required. The colours, a list, spaced evenly from the low end of the limits to the high unless `values:` places them.

* `:values` - Where the colours sit: places from 0, the low end of the limits, to 1, the high, one for each colour, so each colour sits at its place and those between are blended; of another count, the colours are spread over them evenly. A value beyond the first or last place takes `na_value:`. The colours are spaced evenly when not given.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `"#7F7F7F"`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the bins span whatever the data, `nil` for an end the data decides; either order names the same scale. A value outside them takes the colour of the bin at the nearer end, unless `oob:` says otherwise. The data's range, widened so the end bins are as wide as their neighbours, when neither this nor `breaks:` is given.

* `:oob` - What happens to a value outside the limits before it is binned: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. A value left outside, or left missing, takes `na_value:`. `:squish` when not given, so a value outside takes the colour of the bin at the nearer end.

* `:breaks` - The values the bins are cut at, a list of numbers, those outside the limits left out; a function that returns them, or `{break, label}` pairs, handed the limits, `{low, high}`, and, taking two arguments, `[n: n_breaks]`; or `:none` for one bin and no guide; chosen from the limits as `n_breaks:` and `nice_breaks:` say when not given.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break, a list of numbers, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do, and handed the limits too where `show_limits:` shows them; or `:none` for no labels. A pair's label when a `breaks:` function returns pairs.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted when `breaks:` is not given: 2 or more for nice breaks, which may number a few more or fewer, 1 or more otherwise; or of a `breaks:` function of two arguments. When given, not beside `breaks:` a list, `:none` or a function of one argument, which wants no number. The default value is `5`.

* `:nice_breaks` (`t:boolean/0`) - Whether breaks not given are round numbers, chosen as a continuous scale's are, or `n_breaks:` spaced evenly between the ends of the limits. The default value is `true`.

* `:right` (`t:boolean/0`) - Where a value on a break falls: `true` in the bin below it, `false` in the bin above. The default value is `true`.

* `:show_limits` (`t:boolean/0`) - Whether colour steps label the ends of the bar with the limits, unless a break is already there; not beside a list of `labels:`, which labels the breaks alone. The default value is `false`.

* `:guide` - What reads the scale back: `:colorsteps`, a bar of one block of colour for each bin; `:legend`, a key for each break; or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:colorsteps`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "hp" => [110, 93, 175]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, colour: :hp})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_color_stepsn(colors: ["red", "yellow", "blue"])
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:color)
    ["#FFB500", "#FF5F00", "#8A44DE"]

# `scale_color_viridis_b`

```elixir
@spec scale_color_viridis_b(t(), keyword()) :: t()
```

Gives the plot a binned colour scale from a viridis palette, replacing any colour scale it had.

The values are cut into bins at its breaks, as `scale_color_binned/2` cuts them, and the bins
take the colours `scale_color_viridis_d/2` would give as many values, in order, from `begin:`
to `end:` of the palette `option:`.
Raises `NimbleOptions.ValidationError` for an option it does not take or a value it cannot use,
and `ArgumentError` for a list of labels without a list of breaks as long, `show_limits: true`
beside a list of labels, or `n_breaks: 1` for nice breaks; a column that is not numbers is
refused when the plot is run.

## Options

* `:option` - The palette: `:viridis`, `:magma`, `:inferno`, `:plasma`, `:cividis`, `:rocket`, `:mako` or `:turbo`. The default value is `:viridis`.

* `:begin` - Where in the palette the colours begin, from 0, its start, to 1, its end. The default value is `0.0`.

* `:end` - Where in the palette the colours end, from 0, its start, to 1, its end. The default value is `1.0`.

* `:direction` - 1 to take the colours from `begin:` to `end:`, -1 from `end:` to `begin:`. The default value is `1`.

* `:alpha` - The colours' opacity, from 0 to 1. The default value is `1.0`.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `"#7F7F7F"`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the bins span whatever the data, `nil` for an end the data decides; either order names the same scale. A value outside them takes the colour of the bin at the nearer end, unless `oob:` says otherwise. The data's range, widened so the end bins are as wide as their neighbours, when neither this nor `breaks:` is given.

* `:oob` - What happens to a value outside the limits before it is binned: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. A value left outside, or left missing, takes `na_value:`. `:squish` when not given, so a value outside takes the colour of the bin at the nearer end.

* `:breaks` - The values the bins are cut at, a list of numbers, those outside the limits left out; a function that returns them, or `{break, label}` pairs, handed the limits, `{low, high}`, and, taking two arguments, `[n: n_breaks]`; or `:none` for one bin and no guide; chosen from the limits as `n_breaks:` and `nice_breaks:` say when not given.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break, a list of numbers, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do, and handed the limits too where `show_limits:` shows them; or `:none` for no labels. A pair's label when a `breaks:` function returns pairs.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted when `breaks:` is not given: 2 or more for nice breaks, which may number a few more or fewer, 1 or more otherwise; or of a `breaks:` function of two arguments. When given, not beside `breaks:` a list, `:none` or a function of one argument, which wants no number. The default value is `5`.

* `:nice_breaks` (`t:boolean/0`) - Whether breaks not given are round numbers, chosen as a continuous scale's are, or `n_breaks:` spaced evenly between the ends of the limits. The default value is `true`.

* `:right` (`t:boolean/0`) - Where a value on a break falls: `true` in the bin below it, `false` in the bin above. The default value is `true`.

* `:show_limits` (`t:boolean/0`) - Whether colour steps label the ends of the bar with the limits, unless a break is already there; not beside a list of `labels:`, which labels the breaks alone. The default value is `false`.

* `:guide` - What reads the scale back: `:colorsteps`, a bar of one block of colour for each bin; `:legend`, a key for each break; or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:colorsteps`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "hp" => [110, 93, 175]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, colour: :hp})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_color_viridis_b()
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:color)
    ["#3B528B", "#440154", "#FDE725"]

# `scale_color_viridis_c`

```elixir
@spec scale_color_viridis_c(t(), keyword()) :: t()
```

Gives the plot a continuous colour scale, a gradient through a viridis palette, replacing any
colour scale it had.

The gradient runs through six colours spaced evenly from `begin:` to `end:` of the palette
`option:`, blended in CIE L*a*b* between neighbours, as `scale_color_gradientn/2` blends its
colours; its guide is a colour bar unless `guide:` names another. Raises
`NimbleOptions.ValidationError` for an option it does not take or a value it cannot use, and
`ArgumentError` for a list of labels without a list of breaks as long; a column that is not
numbers is refused when the plot is run.

## Options

* `:option` - The palette: `:viridis`, `:magma`, `:inferno`, `:plasma`, `:cividis`, `:rocket`, `:mako` or `:turbo`. The default value is `:viridis`.

* `:begin` - Where in the palette the colours begin, from 0, its start, to 1, its end. The default value is `0.0`.

* `:end` - Where in the palette the colours end, from 0, its start, to 1, its end. The default value is `1.0`.

* `:direction` - 1 to take the colours from `begin:` to `end:`, -1 from `end:` to `begin:`. The default value is `1`.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `"#7F7F7F"`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the scale spans whatever the data, `nil` for an end the data decides; either order names the same scale. A value outside them takes `na_value:`, unless `oob:` says otherwise where the scale takes it.

* `:breaks` - The values the legend or colour bar marks, a list of numbers, those outside the limits left out; a function that returns them, or `{break, label}` pairs, handed the limits, `{low, high}`, and, taking two arguments, `[n: n]` as `n_breaks:` asks, `[]` when not given; or `:none` for no guide; chosen from the limits when not given.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted, 2 or more, of the breaks chosen when `breaks:` is not given, or of a `breaks:` function of two arguments; not beside `breaks:` a list, `:none` or a function of one argument, which wants no number.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break, a list of numbers, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do; or `:none` for no labels. A pair's label when a `breaks:` function returns pairs.

* `:transform` - What each value is put through before the scale sees it, a transformation of `Scales.Transform`'s: `:identity`, `:log`, `:log2`, `:log10`, `{:log, base}`, `:log1p`, `:exp`, `{:exp, base}`, `:asinh`, `:pseudo_log`, `{:pseudo_log, sigma: sigma, base: base}`, `:sqrt`, `:reverse`, `:reciprocal`, `:asn`, `:atanh`, `:logit`, `:probit`, `{:probability, :normal, mean: mean, sd: sd}`, `{:probability, :logistic, location: location, scale: scale}`, `{:boxcox, exponent}`, `{:boxcox, exponent, offset: offset}`, `{:modulus, exponent}`, `{:modulus, exponent, offset: offset}`, `{:yj, exponent}`, `:timespan`, `{:timespan, unit}`, a composition `{:compose, [part, ...]}` or one `Scales.Transform.new/2` makes; `:identity` when not given. The scale trains, breaks and places in transformed space, its limits and breaks given in data units, and labels its breaks in data units.

* `:oob` - What happens to a value outside the limits: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. A value left outside, or left missing, takes `na_value:`, but an opacity or a size kept outside runs on past its range. `:censor` when not given.

* `:guide` - What reads the scale back: `:colorbar`, a bar the colours run up; `:colorsteps`, a bar of one block of colour between each break and the next; `:legend`, a key for each break; or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:colorbar`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "hp" => [0, 5, 10]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, colour: :hp})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_color_viridis_c()
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:color)
    ["#440154", "#2B9089", "#FDE725"]

# `scale_color_viridis_d`

```elixir
@spec scale_color_viridis_d(t(), keyword()) :: t()
```

Gives the plot a discrete colour scale from a viridis palette, replacing any colour scale it had.

The palettes change evenly to the eye, in colour and in grey, and are made to be read by people
with the common forms of colour blindness. The values take colours spaced evenly from `begin:`
to `end:` of the palette `option:`, in order. An ordered factor mapped to colour gets
this scale by default; a missing value has no colour, so its mark is not drawn, unless
`na_value:` gives one. Raises `NimbleOptions.ValidationError` for an option it does not take or
a value it cannot use, and `ArgumentError` for a list of labels not one for each break or limit
given; a column of numbers is refused when the plot is run.

## Options

* `:option` - The palette: `:viridis`, `:magma`, `:inferno`, `:plasma`, `:cividis`, `:rocket`, `:mako` or `:turbo`. The default value is `:viridis`.

* `:begin` - Where in the palette the colours begin, from 0, its start, to 1, its end. The default value is `0.0`.

* `:end` - Where in the palette the colours end, from 0, its start, to 1, its end. The default value is `1.0`.

* `:direction` - 1 to take the colours from `begin:` to `end:`, -1 from `end:` to `begin:`. The default value is `1`.

* `:alpha` - The colours' opacity, from 0 to 1. The default value is `1.0`.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `:none`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - The values the scale shows, a list in the order shown, whatever the data; each value as the column holds it, `nil` for the missing value, a number naming the value equal to it. A value not among them takes `na_value:`. Every value the data holds, in order, when not given.

* `:breaks` - The values the legend shows a key for, a list in the order given, those not among the limits left out; a function of one argument handed the limits that returns them, or `{value, label}` pairs, a pair's label its key's; or `:none` for no legend; every one of the limits when not given.

* `:labels` - The keys' labels: a list of strings, `nil` drawn `NA`, one for each break, or for each limit when no breaks are given; a map from a value to its label, a value it does not hold keeping its own; a function handed every break, a list of values, that returns a label for each, a string, a power or `nil`; or `:none` for keys with no labels. Each value written as text when not given.

* `:guide` - What reads the scale back: `:legend`, a key for each break, or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:legend`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "cyl" => ["6", "4", "8"]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, colour: :cyl})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_color_viridis_d(option: :magma)
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:color)
    ["#B63679", "#000004", "#FCFDBF"]

# `scale_fill_binned`

```elixir
@spec scale_fill_binned(t(), keyword()) :: t()
```

Gives the plot a binned fill scale, replacing any fill scale it had, as `scale_color_binned/2`
gives a colour scale.

## Options

* `:palette` - A palette's name, one of scales' in any case (`Scales.Palette.named/1`), such as `"Blues"` or `"viridis"`, its colours for as many bins as there are given to them in order, or a list of colours, given to the bins in order, at least one for each; a gradient from `#132B43` to `#56B1F7`, each bin the colour at its middle, when not given.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `"#7F7F7F"`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the bins span whatever the data, `nil` for an end the data decides; either order names the same scale. A value outside them takes the colour of the bin at the nearer end, unless `oob:` says otherwise. The data's range, widened so the end bins are as wide as their neighbours, when neither this nor `breaks:` is given.

* `:oob` - What happens to a value outside the limits before it is binned: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. A value left outside, or left missing, takes `na_value:`. `:squish` when not given, so a value outside takes the colour of the bin at the nearer end.

* `:breaks` - The values the bins are cut at, a list of numbers, those outside the limits left out; a function that returns them, or `{break, label}` pairs, handed the limits, `{low, high}`, and, taking two arguments, `[n: n_breaks]`; or `:none` for one bin and no guide; chosen from the limits as `n_breaks:` and `nice_breaks:` say when not given.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break, a list of numbers, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do, and handed the limits too where `show_limits:` shows them; or `:none` for no labels. A pair's label when a `breaks:` function returns pairs.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted when `breaks:` is not given: 2 or more for nice breaks, which may number a few more or fewer, 1 or more otherwise; or of a `breaks:` function of two arguments. When given, not beside `breaks:` a list, `:none` or a function of one argument, which wants no number. The default value is `5`.

* `:nice_breaks` (`t:boolean/0`) - Whether breaks not given are round numbers, chosen as a continuous scale's are, or `n_breaks:` spaced evenly between the ends of the limits. The default value is `true`.

* `:right` (`t:boolean/0`) - Where a value on a break falls: `true` in the bin below it, `false` in the bin above. The default value is `true`.

* `:show_limits` (`t:boolean/0`) - Whether colour steps label the ends of the bar with the limits, unless a break is already there; not beside a list of `labels:`, which labels the breaks alone. The default value is `false`.

* `:guide` - What reads the scale back: `:colorsteps`, a bar of one block of colour for each bin; `:legend`, a key for each break; or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:colorsteps`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "hp" => [0, 5, 10]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, fill: :hp})
    ...>   |> Giggly.Plot.geom_col()
    ...>   |> Giggly.Plot.scale_fill_binned(palette: "Blues")
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:fill)
    ["#EFF3FF", "#BDD7E7", "#2171B5"]

# `scale_fill_brewer`

```elixir
@spec scale_fill_brewer(t(), keyword()) :: t()
```

Gives the plot a discrete fill scale from a ColorBrewer palette, replacing any fill scale it had,
as `scale_color_brewer/2` gives a colour scale.

## Options

* `:type` - The palettes a number in `palette:` counts among: `:seq`, sequential; `:div`, diverging; or `:qual`, qualitative. A name is not counted, so this is not read beside one. The default value is `:seq`.

* `:palette` - The ColorBrewer palette: its name, spelled as `Scales.Palette.brewer_palettes/1` spells it, or its number among the palettes of `type:`, counting from 1. The default value is `1`.

* `:direction` - 1 to give the palette's colours to the values in order, -1 in reverse. The default value is `1`.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `:none`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - The values the scale shows, a list in the order shown, whatever the data; each value as the column holds it, `nil` for the missing value, a number naming the value equal to it. A value not among them takes `na_value:`. Every value the data holds, in order, when not given.

* `:breaks` - The values the legend shows a key for, a list in the order given, those not among the limits left out; a function of one argument handed the limits that returns them, or `{value, label}` pairs, a pair's label its key's; or `:none` for no legend; every one of the limits when not given.

* `:labels` - The keys' labels: a list of strings, `nil` drawn `NA`, one for each break, or for each limit when no breaks are given; a map from a value to its label, a value it does not hold keeping its own; a function handed every break, a list of values, that returns a label for each, a string, a power or `nil`; or `:none` for keys with no labels. Each value written as text when not given.

* `:guide` - What reads the scale back: `:legend`, a key for each break, or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:legend`.

    iex> plot =
    ...>   %{"drv" => ["f", "r", "4"], "hwy" => [28, 19, 20]}
    ...>   |> Giggly.Plot.new(%{x: :drv, y: :hwy, fill: :drv})
    ...>   |> Giggly.Plot.geom_col()
    ...>   |> Giggly.Plot.scale_fill_brewer(type: :qual, palette: 2)
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:fill)
    ["#D95F02", "#7570B3", "#1B9E77"]

# `scale_fill_continuous`

```elixir
@spec scale_fill_continuous(t(), keyword()) :: t()
```

Gives the plot a continuous fill scale, replacing any fill scale it had, as
`scale_color_continuous/2` gives a colour scale.

## Options

* `:palette` - A palette's name, one of scales' in any case (`Scales.Palette.named/1`), such as `"Blues"` or `"viridis"`, its colours blended in order, or a list of colours, spaced evenly from the low end of the limits to the high; a gradient from `#132B43` to `#56B1F7` when not given.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `"#7F7F7F"`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the scale spans whatever the data, `nil` for an end the data decides; either order names the same scale. A value outside them takes `na_value:`, unless `oob:` says otherwise where the scale takes it.

* `:breaks` - The values the legend or colour bar marks, a list of numbers, those outside the limits left out; a function that returns them, or `{break, label}` pairs, handed the limits, `{low, high}`, and, taking two arguments, `[n: n]` as `n_breaks:` asks, `[]` when not given; or `:none` for no guide; chosen from the limits when not given.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted, 2 or more, of the breaks chosen when `breaks:` is not given, or of a `breaks:` function of two arguments; not beside `breaks:` a list, `:none` or a function of one argument, which wants no number.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break, a list of numbers, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do; or `:none` for no labels. A pair's label when a `breaks:` function returns pairs.

* `:transform` - What each value is put through before the scale sees it, a transformation of `Scales.Transform`'s: `:identity`, `:log`, `:log2`, `:log10`, `{:log, base}`, `:log1p`, `:exp`, `{:exp, base}`, `:asinh`, `:pseudo_log`, `{:pseudo_log, sigma: sigma, base: base}`, `:sqrt`, `:reverse`, `:reciprocal`, `:asn`, `:atanh`, `:logit`, `:probit`, `{:probability, :normal, mean: mean, sd: sd}`, `{:probability, :logistic, location: location, scale: scale}`, `{:boxcox, exponent}`, `{:boxcox, exponent, offset: offset}`, `{:modulus, exponent}`, `{:modulus, exponent, offset: offset}`, `{:yj, exponent}`, `:timespan`, `{:timespan, unit}`, a composition `{:compose, [part, ...]}` or one `Scales.Transform.new/2` makes; `:identity` when not given. The scale trains, breaks and places in transformed space, its limits and breaks given in data units, and labels its breaks in data units.

* `:oob` - What happens to a value outside the limits: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. A value left outside, or left missing, takes `na_value:`, but an opacity or a size kept outside runs on past its range. `:censor` when not given.

* `:guide` - What reads the scale back: `:colorbar`, a bar the colours run up; `:colorsteps`, a bar of one block of colour between each break and the next; `:legend`, a key for each break; or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:colorbar`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "hp" => [0, 5, 10]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, fill: :hp})
    ...>   |> Giggly.Plot.geom_col()
    ...>   |> Giggly.Plot.scale_fill_continuous(palette: ["#FEE0D2", "#FC9272", "#DE2D26"])
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:fill)
    ["#FEE0D2", "#FC9272", "#DE2D26"]

# `scale_fill_discrete`

```elixir
@spec scale_fill_discrete(t(), keyword()) :: t()
```

Gives the plot a discrete fill scale, replacing any fill scale it had, as
`scale_color_discrete/2` gives a colour scale.

## Options

* `:palette` - A palette's name, one of scales' in any case (`Scales.Palette.named/1`), such as `"Set1"` or `"viridis"`, or a list of colours, its colours given to the values in order; hues spaced evenly round the colour wheel when not given.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `"#7F7F7F"`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - The values the scale shows, a list in the order shown, whatever the data; each value as the column holds it, `nil` for the missing value, a number naming the value equal to it. A value not among them takes `na_value:`. Every value the data holds, in order, when not given.

* `:breaks` - The values the legend shows a key for, a list in the order given, those not among the limits left out; a function of one argument handed the limits that returns them, or `{value, label}` pairs, a pair's label its key's; or `:none` for no legend; every one of the limits when not given.

* `:labels` - The keys' labels: a list of strings, `nil` drawn `NA`, one for each break, or for each limit when no breaks are given; a map from a value to its label, a value it does not hold keeping its own; a function handed every break, a list of values, that returns a label for each, a string, a power or `nil`; or `:none` for keys with no labels. Each value written as text when not given.

* `:guide` - What reads the scale back: `:legend`, a key for each break, or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:legend`.

    iex> plot =
    ...>   %{"drv" => ["f", "r", "4"], "hwy" => [28, 19, 20]}
    ...>   |> Giggly.Plot.new(%{x: :drv, y: :hwy, fill: :drv})
    ...>   |> Giggly.Plot.geom_col()
    ...>   |> Giggly.Plot.scale_fill_discrete(limits: ["f", "r"])
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:fill)
    ["#F8766D", "#00BFC4", "#7F7F7F"]

# `scale_fill_distiller`

```elixir
@spec scale_fill_distiller(t(), keyword()) :: t()
```

Gives the plot a continuous fill scale, a gradient through a ColorBrewer palette, replacing any
fill scale it had, as `scale_color_distiller/2` gives a colour scale.

## Options

* `:type` - The palettes a number in `palette:` counts among: `:seq`, sequential; `:div`, diverging; or `:qual`, qualitative. A name is not counted, so this is not read beside one. The default value is `:seq`.

* `:palette` - The ColorBrewer palette: its name, spelled as `Scales.Palette.brewer_palettes/1` spells it, or its number among the palettes of `type:`, counting from 1. The default value is `1`.

* `:direction` - -1 to blend the palette's colours from its last at the low end of the limits to its first at the high, 1 the other way. The default value is `-1`.

* `:values` - Where the colours sit: places from 0, the low end of the limits, to 1, the high, one for each colour, so each colour sits at its place and those between are blended; of another count, the colours are spread over them evenly. A value beyond the first or last place takes `na_value:`. The colours are spaced evenly when not given.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `"#7F7F7F"`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the scale spans whatever the data, `nil` for an end the data decides; either order names the same scale. A value outside them takes `na_value:`, unless `oob:` says otherwise where the scale takes it.

* `:breaks` - The values the legend or colour bar marks, a list of numbers, those outside the limits left out; a function that returns them, or `{break, label}` pairs, handed the limits, `{low, high}`, and, taking two arguments, `[n: n]` as `n_breaks:` asks, `[]` when not given; or `:none` for no guide; chosen from the limits when not given.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted, 2 or more, of the breaks chosen when `breaks:` is not given, or of a `breaks:` function of two arguments; not beside `breaks:` a list, `:none` or a function of one argument, which wants no number.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break, a list of numbers, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do; or `:none` for no labels. A pair's label when a `breaks:` function returns pairs.

* `:transform` - What each value is put through before the scale sees it, a transformation of `Scales.Transform`'s: `:identity`, `:log`, `:log2`, `:log10`, `{:log, base}`, `:log1p`, `:exp`, `{:exp, base}`, `:asinh`, `:pseudo_log`, `{:pseudo_log, sigma: sigma, base: base}`, `:sqrt`, `:reverse`, `:reciprocal`, `:asn`, `:atanh`, `:logit`, `:probit`, `{:probability, :normal, mean: mean, sd: sd}`, `{:probability, :logistic, location: location, scale: scale}`, `{:boxcox, exponent}`, `{:boxcox, exponent, offset: offset}`, `{:modulus, exponent}`, `{:modulus, exponent, offset: offset}`, `{:yj, exponent}`, `:timespan`, `{:timespan, unit}`, a composition `{:compose, [part, ...]}` or one `Scales.Transform.new/2` makes; `:identity` when not given. The scale trains, breaks and places in transformed space, its limits and breaks given in data units, and labels its breaks in data units.

* `:oob` - What happens to a value outside the limits: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. A value left outside, or left missing, takes `na_value:`, but an opacity or a size kept outside runs on past its range. `:censor` when not given.

* `:guide` - What reads the scale back: `:colorbar`, a bar the colours run up; `:colorsteps`, a bar of one block of colour between each break and the next; `:legend`, a key for each break; or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:colorbar`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "hp" => [0, 5, 10]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, fill: :hp})
    ...>   |> Giggly.Plot.geom_col()
    ...>   |> Giggly.Plot.scale_fill_distiller(palette: "YlGn")
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:fill)
    ["#005A32", "#78C679", "#FFFFCC"]

# `scale_fill_fermenter`

```elixir
@spec scale_fill_fermenter(t(), keyword()) :: t()
```

Gives the plot a binned fill scale, from a ColorBrewer palette, replacing any fill scale it had, as
`scale_color_fermenter/2` gives a colour scale.

## Options

* `:type` - The palettes a number in `palette:` counts among: `:seq`, sequential; `:div`, diverging; or `:qual`, qualitative. A name is not counted, so this is not read beside one. The default value is `:seq`.

* `:palette` - The ColorBrewer palette: its name, spelled as `Scales.Palette.brewer_palettes/1` spells it, or its number among the palettes of `type:`, counting from 1. The default value is `1`.

* `:direction` - -1 to give the palette's colours to the bins from its last at the lowest to its first at the highest, 1 the other way. The default value is `-1`.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `"#7F7F7F"`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the bins span whatever the data, `nil` for an end the data decides; either order names the same scale. A value outside them takes the colour of the bin at the nearer end, unless `oob:` says otherwise. The data's range, widened so the end bins are as wide as their neighbours, when neither this nor `breaks:` is given.

* `:oob` - What happens to a value outside the limits before it is binned: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. A value left outside, or left missing, takes `na_value:`. `:squish` when not given, so a value outside takes the colour of the bin at the nearer end.

* `:breaks` - The values the bins are cut at, a list of numbers, those outside the limits left out; a function that returns them, or `{break, label}` pairs, handed the limits, `{low, high}`, and, taking two arguments, `[n: n_breaks]`; or `:none` for one bin and no guide; chosen from the limits as `n_breaks:` and `nice_breaks:` say when not given.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break, a list of numbers, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do, and handed the limits too where `show_limits:` shows them; or `:none` for no labels. A pair's label when a `breaks:` function returns pairs.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted when `breaks:` is not given: 2 or more for nice breaks, which may number a few more or fewer, 1 or more otherwise; or of a `breaks:` function of two arguments. When given, not beside `breaks:` a list, `:none` or a function of one argument, which wants no number. The default value is `5`.

* `:nice_breaks` (`t:boolean/0`) - Whether breaks not given are round numbers, chosen as a continuous scale's are, or `n_breaks:` spaced evenly between the ends of the limits. The default value is `true`.

* `:right` (`t:boolean/0`) - Where a value on a break falls: `true` in the bin below it, `false` in the bin above. The default value is `true`.

* `:show_limits` (`t:boolean/0`) - Whether colour steps label the ends of the bar with the limits, unless a break is already there; not beside a list of `labels:`, which labels the breaks alone. The default value is `false`.

* `:guide` - What reads the scale back: `:colorsteps`, a bar of one block of colour for each bin; `:legend`, a key for each break; or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:colorsteps`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "hp" => [0, 5, 10]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, fill: :hp})
    ...>   |> Giggly.Plot.geom_col()
    ...>   |> Giggly.Plot.scale_fill_fermenter(palette: "YlGn")
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:fill)
    ["#238443", "#78C679", "#FFFFCC"]

# `scale_fill_gradient2`

```elixir
@spec scale_fill_gradient2(t(), keyword()) :: t()
```

Gives the plot a continuous fill scale diverging from `mid:` at `midpoint:`, replacing any fill
scale it had, as `scale_color_gradient2/2` gives a colour scale.

## Options

* `:low` - The colour the low side runs to, a dark red when not given. The default value is `"#832424"`.

* `:mid` - The colour at the midpoint, white when not given. The default value is `"#FFFFFF"`.

* `:high` - The colour the high side runs to, a dark blue when not given. The default value is `"#3A3A98"`.

* `:midpoint` - The value the middle colour stands at. The default value is `0.0`.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `"#7F7F7F"`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the scale spans whatever the data, `nil` for an end the data decides; either order names the same scale. A value outside them takes `na_value:`, unless `oob:` says otherwise where the scale takes it.

* `:breaks` - The values the legend or colour bar marks, a list of numbers, those outside the limits left out; a function that returns them, or `{break, label}` pairs, handed the limits, `{low, high}`, and, taking two arguments, `[n: n]` as `n_breaks:` asks, `[]` when not given; or `:none` for no guide; chosen from the limits when not given.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted, 2 or more, of the breaks chosen when `breaks:` is not given, or of a `breaks:` function of two arguments; not beside `breaks:` a list, `:none` or a function of one argument, which wants no number.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break, a list of numbers, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do; or `:none` for no labels. A pair's label when a `breaks:` function returns pairs.

* `:transform` - What each value is put through before the scale sees it, a transformation of `Scales.Transform`'s: `:identity`, `:log`, `:log2`, `:log10`, `{:log, base}`, `:log1p`, `:exp`, `{:exp, base}`, `:asinh`, `:pseudo_log`, `{:pseudo_log, sigma: sigma, base: base}`, `:sqrt`, `:reverse`, `:reciprocal`, `:asn`, `:atanh`, `:logit`, `:probit`, `{:probability, :normal, mean: mean, sd: sd}`, `{:probability, :logistic, location: location, scale: scale}`, `{:boxcox, exponent}`, `{:boxcox, exponent, offset: offset}`, `{:modulus, exponent}`, `{:modulus, exponent, offset: offset}`, `{:yj, exponent}`, `:timespan`, `{:timespan, unit}`, a composition `{:compose, [part, ...]}` or one `Scales.Transform.new/2` makes; `:identity` when not given. The scale trains, breaks and places in transformed space, its limits and breaks given in data units, and labels its breaks in data units.

* `:oob` - What happens to a value outside the limits: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. A value left outside, or left missing, takes `na_value:`, but an opacity or a size kept outside runs on past its range. `:censor` when not given.

* `:guide` - What reads the scale back: `:colorbar`, a bar the colours run up; `:colorsteps`, a bar of one block of colour between each break and the next; `:legend`, a key for each break; or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:colorbar`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "hp" => [0, 5, 10]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, fill: :hp})
    ...>   |> Giggly.Plot.geom_col()
    ...>   |> Giggly.Plot.scale_fill_gradient2(midpoint: 4)
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:fill)
    ["#B26D65", "#E0DBEE", "#3A3A98"]

# `scale_fill_gradient`

```elixir
@spec scale_fill_gradient(t(), keyword()) :: t()
```

Gives the plot a continuous fill scale, a gradient from `low:` to `high:`, replacing any fill
scale it had, as `scale_color_gradient/2` gives a colour scale.

## Options

* `:low` - The colour at the low end of the limits. The default value is `"#132B43"`.

* `:high` - The colour at the high end of the limits. The default value is `"#56B1F7"`.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `"#7F7F7F"`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the scale spans whatever the data, `nil` for an end the data decides; either order names the same scale. A value outside them takes `na_value:`, unless `oob:` says otherwise where the scale takes it.

* `:breaks` - The values the legend or colour bar marks, a list of numbers, those outside the limits left out; a function that returns them, or `{break, label}` pairs, handed the limits, `{low, high}`, and, taking two arguments, `[n: n]` as `n_breaks:` asks, `[]` when not given; or `:none` for no guide; chosen from the limits when not given.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted, 2 or more, of the breaks chosen when `breaks:` is not given, or of a `breaks:` function of two arguments; not beside `breaks:` a list, `:none` or a function of one argument, which wants no number.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break, a list of numbers, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do; or `:none` for no labels. A pair's label when a `breaks:` function returns pairs.

* `:transform` - What each value is put through before the scale sees it, a transformation of `Scales.Transform`'s: `:identity`, `:log`, `:log2`, `:log10`, `{:log, base}`, `:log1p`, `:exp`, `{:exp, base}`, `:asinh`, `:pseudo_log`, `{:pseudo_log, sigma: sigma, base: base}`, `:sqrt`, `:reverse`, `:reciprocal`, `:asn`, `:atanh`, `:logit`, `:probit`, `{:probability, :normal, mean: mean, sd: sd}`, `{:probability, :logistic, location: location, scale: scale}`, `{:boxcox, exponent}`, `{:boxcox, exponent, offset: offset}`, `{:modulus, exponent}`, `{:modulus, exponent, offset: offset}`, `{:yj, exponent}`, `:timespan`, `{:timespan, unit}`, a composition `{:compose, [part, ...]}` or one `Scales.Transform.new/2` makes; `:identity` when not given. The scale trains, breaks and places in transformed space, its limits and breaks given in data units, and labels its breaks in data units.

* `:oob` - What happens to a value outside the limits: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. A value left outside, or left missing, takes `na_value:`, but an opacity or a size kept outside runs on past its range. `:censor` when not given.

* `:guide` - What reads the scale back: `:colorbar`, a bar the colours run up; `:colorsteps`, a bar of one block of colour between each break and the next; `:legend`, a key for each break; or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:colorbar`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "hp" => [0, 5, 10]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, fill: :hp})
    ...>   |> Giggly.Plot.geom_col()
    ...>   |> Giggly.Plot.scale_fill_gradient(low: "white", high: "steelblue")
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:fill)
    ["#FFFFFF", "#A7BED9", "#4682B4"]

# `scale_fill_gradientn`

```elixir
@spec scale_fill_gradientn(t(), keyword()) :: t()
```

Gives the plot a continuous fill scale, a gradient through the colours of `colors:`, replacing
any fill scale it had, as `scale_color_gradientn/2` gives a colour scale.

## Options

* `:colors` - Required. The colours, a list, spaced evenly from the low end of the limits to the high unless `values:` places them.

* `:values` - Where the colours sit: places from 0, the low end of the limits, to 1, the high, one for each colour, so each colour sits at its place and those between are blended; of another count, the colours are spread over them evenly. A value beyond the first or last place takes `na_value:`. The colours are spaced evenly when not given.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `"#7F7F7F"`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the scale spans whatever the data, `nil` for an end the data decides; either order names the same scale. A value outside them takes `na_value:`, unless `oob:` says otherwise where the scale takes it.

* `:breaks` - The values the legend or colour bar marks, a list of numbers, those outside the limits left out; a function that returns them, or `{break, label}` pairs, handed the limits, `{low, high}`, and, taking two arguments, `[n: n]` as `n_breaks:` asks, `[]` when not given; or `:none` for no guide; chosen from the limits when not given.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted, 2 or more, of the breaks chosen when `breaks:` is not given, or of a `breaks:` function of two arguments; not beside `breaks:` a list, `:none` or a function of one argument, which wants no number.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break, a list of numbers, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do; or `:none` for no labels. A pair's label when a `breaks:` function returns pairs.

* `:transform` - What each value is put through before the scale sees it, a transformation of `Scales.Transform`'s: `:identity`, `:log`, `:log2`, `:log10`, `{:log, base}`, `:log1p`, `:exp`, `{:exp, base}`, `:asinh`, `:pseudo_log`, `{:pseudo_log, sigma: sigma, base: base}`, `:sqrt`, `:reverse`, `:reciprocal`, `:asn`, `:atanh`, `:logit`, `:probit`, `{:probability, :normal, mean: mean, sd: sd}`, `{:probability, :logistic, location: location, scale: scale}`, `{:boxcox, exponent}`, `{:boxcox, exponent, offset: offset}`, `{:modulus, exponent}`, `{:modulus, exponent, offset: offset}`, `{:yj, exponent}`, `:timespan`, `{:timespan, unit}`, a composition `{:compose, [part, ...]}` or one `Scales.Transform.new/2` makes; `:identity` when not given. The scale trains, breaks and places in transformed space, its limits and breaks given in data units, and labels its breaks in data units.

* `:oob` - What happens to a value outside the limits: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. A value left outside, or left missing, takes `na_value:`, but an opacity or a size kept outside runs on past its range. `:censor` when not given.

* `:guide` - What reads the scale back: `:colorbar`, a bar the colours run up; `:colorsteps`, a bar of one block of colour between each break and the next; `:legend`, a key for each break; or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:colorbar`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "hp" => [0, 5, 10]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, fill: :hp})
    ...>   |> Giggly.Plot.geom_col()
    ...>   |> Giggly.Plot.scale_fill_gradientn(colors: ["#FEE0D2", "#FC9272", "#DE2D26"])
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:fill)
    ["#FEE0D2", "#FC9272", "#DE2D26"]

# `scale_fill_gray`

```elixir
@spec scale_fill_gray(t(), keyword()) :: t()
```

Gives the plot a discrete fill scale of greys, replacing any fill scale it had, as
`scale_color_gray/2` gives a colour scale.

## Options

* `:start` - The first value's grey, from 0, black, to 1, white. The default value is `0.2`.

* `:end` - The last value's grey, from 0, black, to 1, white. The default value is `0.8`.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `"#FF0000"`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - The values the scale shows, a list in the order shown, whatever the data; each value as the column holds it, `nil` for the missing value, a number naming the value equal to it. A value not among them takes `na_value:`. Every value the data holds, in order, when not given.

* `:breaks` - The values the legend shows a key for, a list in the order given, those not among the limits left out; a function of one argument handed the limits that returns them, or `{value, label}` pairs, a pair's label its key's; or `:none` for no legend; every one of the limits when not given.

* `:labels` - The keys' labels: a list of strings, `nil` drawn `NA`, one for each break, or for each limit when no breaks are given; a map from a value to its label, a value it does not hold keeping its own; a function handed every break, a list of values, that returns a label for each, a string, a power or `nil`; or `:none` for keys with no labels. Each value written as text when not given.

* `:guide` - What reads the scale back: `:legend`, a key for each break, or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:legend`.

    iex> plot =
    ...>   %{"drv" => ["f", "r"], "hwy" => [28, 19]}
    ...>   |> Giggly.Plot.new(%{x: :drv, y: :hwy, fill: :drv})
    ...>   |> Giggly.Plot.geom_col()
    ...>   |> Giggly.Plot.scale_fill_gray(start: 0, end: 1)
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:fill)
    ["#000000", "#FFFFFF"]

# `scale_fill_hue`

```elixir
@spec scale_fill_hue(t(), keyword()) :: t()
```

Gives the plot a discrete fill scale of hues spaced evenly round the colour wheel, replacing any
fill scale it had, as `scale_color_hue/2` gives a colour scale.

## Options

* `:hue` - `{first, last}`: the hues the colours are spaced between, in degrees round the colour wheel. A range spanning the whole circle leaves its last share off, so the first and last colours differ. The default value is `{15.0, 375.0}`.

* `:chroma` - How vivid the colours are, from 0, grey. The default value is `100.0`.

* `:luminance` - How light the colours are, from 0, black, to 100, white. The default value is `65.0`.

* `:direction` - 1 to give the colours to the values in order, -1 in reverse. The default value is `1`.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `"#7F7F7F"`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - The values the scale shows, a list in the order shown, whatever the data; each value as the column holds it, `nil` for the missing value, a number naming the value equal to it. A value not among them takes `na_value:`. Every value the data holds, in order, when not given.

* `:breaks` - The values the legend shows a key for, a list in the order given, those not among the limits left out; a function of one argument handed the limits that returns them, or `{value, label}` pairs, a pair's label its key's; or `:none` for no legend; every one of the limits when not given.

* `:labels` - The keys' labels: a list of strings, `nil` drawn `NA`, one for each break, or for each limit when no breaks are given; a map from a value to its label, a value it does not hold keeping its own; a function handed every break, a list of values, that returns a label for each, a string, a power or `nil`; or `:none` for keys with no labels. Each value written as text when not given.

* `:guide` - What reads the scale back: `:legend`, a key for each break, or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:legend`.

    iex> plot =
    ...>   %{"cyl" => ["6", "4", "8"], "mpg" => [19.7, 26.7, 15.1]}
    ...>   |> Giggly.Plot.new(%{x: :cyl, y: :mpg, fill: :cyl})
    ...>   |> Giggly.Plot.geom_col()
    ...>   |> Giggly.Plot.scale_fill_hue(direction: -1)
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:fill)
    ["#00BA38", "#619CFF", "#F8766D"]

# `scale_fill_manual`

```elixir
@spec scale_fill_manual(t(), keyword()) :: t()
```

Gives the plot a discrete fill scale of the colours given, replacing any fill scale it had, as
`scale_color_manual/2` gives a colour scale.

## Options

* `:values` - Required. The colours: a list, given to the values in order, or to `breaks:` in order where they are a list; or a map from a value, as the column holds it, to its colour, whose scale shows only the values the data holds that it names, unless `limits:` gives others. A value with no colour takes `na_value:`.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `"#7F7F7F"`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - The values the scale shows, a list in the order shown, whatever the data; each value as the column holds it, `nil` for the missing value, a number naming the value equal to it. A value not among them takes `na_value:`. Every value the data holds, in order, when not given.

* `:breaks` - The values the legend shows a key for, a list in the order given, those not among the limits left out; a function of one argument handed the limits that returns them, or `{value, label}` pairs, a pair's label its key's; or `:none` for no legend; every one of the limits when not given.

* `:labels` - The keys' labels: a list of strings, `nil` drawn `NA`, one for each break, or for each limit when no breaks are given; a map from a value to its label, a value it does not hold keeping its own; a function handed every break, a list of values, that returns a label for each, a string, a power or `nil`; or `:none` for keys with no labels. Each value written as text when not given.

* `:guide` - What reads the scale back: `:legend`, a key for each break, or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:legend`.

    iex> plot =
    ...>   %{"drv" => ["f", "r"], "hwy" => [28, 19]}
    ...>   |> Giggly.Plot.new(%{x: :drv, y: :hwy, fill: :drv})
    ...>   |> Giggly.Plot.geom_col()
    ...>   |> Giggly.Plot.scale_fill_manual(values: ["steelblue", "orange"])
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:fill)
    ["#4682B4", "#FFA500"]

# `scale_fill_steps2`

```elixir
@spec scale_fill_steps2(t(), keyword()) :: t()
```

Gives the plot a binned fill scale, diverging from `mid:` at `midpoint:`, cut into steps, replacing any fill scale it had, as
`scale_color_steps2/2` gives a colour scale.

## Options

* `:low` - The colour the low side runs to, a dark red when not given. The default value is `"#832424"`.

* `:mid` - The colour at the midpoint, white when not given. The default value is `"#FFFFFF"`.

* `:high` - The colour the high side runs to, a dark blue when not given. The default value is `"#3A3A98"`.

* `:midpoint` - The value the middle colour stands at. The default value is `0.0`.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `"#7F7F7F"`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the bins span whatever the data, `nil` for an end the data decides; either order names the same scale. A value outside them takes the colour of the bin at the nearer end, unless `oob:` says otherwise. The data's range, widened so the end bins are as wide as their neighbours, when neither this nor `breaks:` is given.

* `:oob` - What happens to a value outside the limits before it is binned: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. A value left outside, or left missing, takes `na_value:`. `:squish` when not given, so a value outside takes the colour of the bin at the nearer end.

* `:breaks` - The values the bins are cut at, a list of numbers, those outside the limits left out; a function that returns them, or `{break, label}` pairs, handed the limits, `{low, high}`, and, taking two arguments, `[n: n_breaks]`; or `:none` for one bin and no guide; chosen from the limits as `n_breaks:` and `nice_breaks:` say when not given.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break, a list of numbers, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do, and handed the limits too where `show_limits:` shows them; or `:none` for no labels. A pair's label when a `breaks:` function returns pairs.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted when `breaks:` is not given: 2 or more for nice breaks, which may number a few more or fewer, 1 or more otherwise; or of a `breaks:` function of two arguments. When given, not beside `breaks:` a list, `:none` or a function of one argument, which wants no number. The default value is `5`.

* `:nice_breaks` (`t:boolean/0`) - Whether breaks not given are round numbers, chosen as a continuous scale's are, or `n_breaks:` spaced evenly between the ends of the limits. The default value is `true`.

* `:right` (`t:boolean/0`) - Where a value on a break falls: `true` in the bin below it, `false` in the bin above. The default value is `true`.

* `:show_limits` (`t:boolean/0`) - Whether colour steps label the ends of the bar with the limits, unless a break is already there; not beside a list of `labels:`, which labels the breaks alone. The default value is `false`.

* `:guide` - What reads the scale back: `:colorsteps`, a bar of one block of colour for each bin; `:legend`, a key for each break; or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:colorsteps`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "hp" => [0, 5, 10]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, fill: :hp})
    ...>   |> Giggly.Plot.geom_col()
    ...>   |> Giggly.Plot.scale_fill_steps2(midpoint: 4)
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:fill)
    ["#CD9993", "#FBF5F5", "#685FAE"]

# `scale_fill_steps`

```elixir
@spec scale_fill_steps(t(), keyword()) :: t()
```

Gives the plot a binned fill scale, a gradient cut into steps, replacing any fill scale it had, as
`scale_color_steps/2` gives a colour scale.

## Options

* `:low` - The colour at the low end of the limits. The default value is `"#132B43"`.

* `:high` - The colour at the high end of the limits. The default value is `"#56B1F7"`.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `"#7F7F7F"`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the bins span whatever the data, `nil` for an end the data decides; either order names the same scale. A value outside them takes the colour of the bin at the nearer end, unless `oob:` says otherwise. The data's range, widened so the end bins are as wide as their neighbours, when neither this nor `breaks:` is given.

* `:oob` - What happens to a value outside the limits before it is binned: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. A value left outside, or left missing, takes `na_value:`. `:squish` when not given, so a value outside takes the colour of the bin at the nearer end.

* `:breaks` - The values the bins are cut at, a list of numbers, those outside the limits left out; a function that returns them, or `{break, label}` pairs, handed the limits, `{low, high}`, and, taking two arguments, `[n: n_breaks]`; or `:none` for one bin and no guide; chosen from the limits as `n_breaks:` and `nice_breaks:` say when not given.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break, a list of numbers, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do, and handed the limits too where `show_limits:` shows them; or `:none` for no labels. A pair's label when a `breaks:` function returns pairs.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted when `breaks:` is not given: 2 or more for nice breaks, which may number a few more or fewer, 1 or more otherwise; or of a `breaks:` function of two arguments. When given, not beside `breaks:` a list, `:none` or a function of one argument, which wants no number. The default value is `5`.

* `:nice_breaks` (`t:boolean/0`) - Whether breaks not given are round numbers, chosen as a continuous scale's are, or `n_breaks:` spaced evenly between the ends of the limits. The default value is `true`.

* `:right` (`t:boolean/0`) - Where a value on a break falls: `true` in the bin below it, `false` in the bin above. The default value is `true`.

* `:show_limits` (`t:boolean/0`) - Whether colour steps label the ends of the bar with the limits, unless a break is already there; not beside a list of `labels:`, which labels the breaks alone. The default value is `false`.

* `:guide` - What reads the scale back: `:colorsteps`, a bar of one block of colour for each bin; `:legend`, a key for each break; or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:colorsteps`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "hp" => [0, 5, 10]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, fill: :hp})
    ...>   |> Giggly.Plot.geom_col()
    ...>   |> Giggly.Plot.scale_fill_steps(n_breaks: 3)
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:fill)
    ["#22496C", "#22496C", "#448DC6"]

# `scale_fill_stepsn`

```elixir
@spec scale_fill_stepsn(t(), keyword()) :: t()
```

Gives the plot a binned fill scale, a gradient through `colors:` cut into steps, replacing any fill scale it had, as
`scale_color_stepsn/2` gives a colour scale.

## Options

* `:colors` - Required. The colours, a list, spaced evenly from the low end of the limits to the high unless `values:` places them.

* `:values` - Where the colours sit: places from 0, the low end of the limits, to 1, the high, one for each colour, so each colour sits at its place and those between are blended; of another count, the colours are spread over them evenly. A value beyond the first or last place takes `na_value:`. The colours are spaced evenly when not given.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `"#7F7F7F"`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the bins span whatever the data, `nil` for an end the data decides; either order names the same scale. A value outside them takes the colour of the bin at the nearer end, unless `oob:` says otherwise. The data's range, widened so the end bins are as wide as their neighbours, when neither this nor `breaks:` is given.

* `:oob` - What happens to a value outside the limits before it is binned: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. A value left outside, or left missing, takes `na_value:`. `:squish` when not given, so a value outside takes the colour of the bin at the nearer end.

* `:breaks` - The values the bins are cut at, a list of numbers, those outside the limits left out; a function that returns them, or `{break, label}` pairs, handed the limits, `{low, high}`, and, taking two arguments, `[n: n_breaks]`; or `:none` for one bin and no guide; chosen from the limits as `n_breaks:` and `nice_breaks:` say when not given.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break, a list of numbers, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do, and handed the limits too where `show_limits:` shows them; or `:none` for no labels. A pair's label when a `breaks:` function returns pairs.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted when `breaks:` is not given: 2 or more for nice breaks, which may number a few more or fewer, 1 or more otherwise; or of a `breaks:` function of two arguments. When given, not beside `breaks:` a list, `:none` or a function of one argument, which wants no number. The default value is `5`.

* `:nice_breaks` (`t:boolean/0`) - Whether breaks not given are round numbers, chosen as a continuous scale's are, or `n_breaks:` spaced evenly between the ends of the limits. The default value is `true`.

* `:right` (`t:boolean/0`) - Where a value on a break falls: `true` in the bin below it, `false` in the bin above. The default value is `true`.

* `:show_limits` (`t:boolean/0`) - Whether colour steps label the ends of the bar with the limits, unless a break is already there; not beside a list of `labels:`, which labels the breaks alone. The default value is `false`.

* `:guide` - What reads the scale back: `:colorsteps`, a bar of one block of colour for each bin; `:legend`, a key for each break; or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:colorsteps`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "hp" => [0, 5, 10]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, fill: :hp})
    ...>   |> Giggly.Plot.geom_col()
    ...>   |> Giggly.Plot.scale_fill_stepsn(
    ...>     colors: ["#FEE0D2", "#FC9272", "#DE2D26"],
    ...>     nice_breaks: false
    ...>   )
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:fill)
    ["#FFD3C1", "#FE9F81", "#E44332"]

# `scale_fill_viridis_b`

```elixir
@spec scale_fill_viridis_b(t(), keyword()) :: t()
```

Gives the plot a binned fill scale, from a viridis palette, replacing any fill scale it had, as
`scale_color_viridis_b/2` gives a colour scale.

## Options

* `:option` - The palette: `:viridis`, `:magma`, `:inferno`, `:plasma`, `:cividis`, `:rocket`, `:mako` or `:turbo`. The default value is `:viridis`.

* `:begin` - Where in the palette the colours begin, from 0, its start, to 1, its end. The default value is `0.0`.

* `:end` - Where in the palette the colours end, from 0, its start, to 1, its end. The default value is `1.0`.

* `:direction` - 1 to take the colours from `begin:` to `end:`, -1 from `end:` to `begin:`. The default value is `1`.

* `:alpha` - The colours' opacity, from 0 to 1. The default value is `1.0`.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `"#7F7F7F"`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the bins span whatever the data, `nil` for an end the data decides; either order names the same scale. A value outside them takes the colour of the bin at the nearer end, unless `oob:` says otherwise. The data's range, widened so the end bins are as wide as their neighbours, when neither this nor `breaks:` is given.

* `:oob` - What happens to a value outside the limits before it is binned: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. A value left outside, or left missing, takes `na_value:`. `:squish` when not given, so a value outside takes the colour of the bin at the nearer end.

* `:breaks` - The values the bins are cut at, a list of numbers, those outside the limits left out; a function that returns them, or `{break, label}` pairs, handed the limits, `{low, high}`, and, taking two arguments, `[n: n_breaks]`; or `:none` for one bin and no guide; chosen from the limits as `n_breaks:` and `nice_breaks:` say when not given.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break, a list of numbers, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do, and handed the limits too where `show_limits:` shows them; or `:none` for no labels. A pair's label when a `breaks:` function returns pairs.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted when `breaks:` is not given: 2 or more for nice breaks, which may number a few more or fewer, 1 or more otherwise; or of a `breaks:` function of two arguments. When given, not beside `breaks:` a list, `:none` or a function of one argument, which wants no number. The default value is `5`.

* `:nice_breaks` (`t:boolean/0`) - Whether breaks not given are round numbers, chosen as a continuous scale's are, or `n_breaks:` spaced evenly between the ends of the limits. The default value is `true`.

* `:right` (`t:boolean/0`) - Where a value on a break falls: `true` in the bin below it, `false` in the bin above. The default value is `true`.

* `:show_limits` (`t:boolean/0`) - Whether colour steps label the ends of the bar with the limits, unless a break is already there; not beside a list of `labels:`, which labels the breaks alone. The default value is `false`.

* `:guide` - What reads the scale back: `:colorsteps`, a bar of one block of colour for each bin; `:legend`, a key for each break; or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:colorsteps`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "hp" => [0, 5, 10]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, fill: :hp})
    ...>   |> Giggly.Plot.geom_col()
    ...>   |> Giggly.Plot.scale_fill_viridis_b(option: :plasma)
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:fill)
    ["#0D0887", "#9C179E", "#F0F921"]

# `scale_fill_viridis_c`

```elixir
@spec scale_fill_viridis_c(t(), keyword()) :: t()
```

Gives the plot a continuous fill scale, a gradient through a viridis palette, replacing any fill
scale it had, as `scale_color_viridis_c/2` gives a colour scale.

## Options

* `:option` - The palette: `:viridis`, `:magma`, `:inferno`, `:plasma`, `:cividis`, `:rocket`, `:mako` or `:turbo`. The default value is `:viridis`.

* `:begin` - Where in the palette the colours begin, from 0, its start, to 1, its end. The default value is `0.0`.

* `:end` - Where in the palette the colours end, from 0, its start, to 1, its end. The default value is `1.0`.

* `:direction` - 1 to take the colours from `begin:` to `end:`, -1 from `end:` to `begin:`. The default value is `1`.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `"#7F7F7F"`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the scale spans whatever the data, `nil` for an end the data decides; either order names the same scale. A value outside them takes `na_value:`, unless `oob:` says otherwise where the scale takes it.

* `:breaks` - The values the legend or colour bar marks, a list of numbers, those outside the limits left out; a function that returns them, or `{break, label}` pairs, handed the limits, `{low, high}`, and, taking two arguments, `[n: n]` as `n_breaks:` asks, `[]` when not given; or `:none` for no guide; chosen from the limits when not given.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted, 2 or more, of the breaks chosen when `breaks:` is not given, or of a `breaks:` function of two arguments; not beside `breaks:` a list, `:none` or a function of one argument, which wants no number.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break, a list of numbers, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do; or `:none` for no labels. A pair's label when a `breaks:` function returns pairs.

* `:transform` - What each value is put through before the scale sees it, a transformation of `Scales.Transform`'s: `:identity`, `:log`, `:log2`, `:log10`, `{:log, base}`, `:log1p`, `:exp`, `{:exp, base}`, `:asinh`, `:pseudo_log`, `{:pseudo_log, sigma: sigma, base: base}`, `:sqrt`, `:reverse`, `:reciprocal`, `:asn`, `:atanh`, `:logit`, `:probit`, `{:probability, :normal, mean: mean, sd: sd}`, `{:probability, :logistic, location: location, scale: scale}`, `{:boxcox, exponent}`, `{:boxcox, exponent, offset: offset}`, `{:modulus, exponent}`, `{:modulus, exponent, offset: offset}`, `{:yj, exponent}`, `:timespan`, `{:timespan, unit}`, a composition `{:compose, [part, ...]}` or one `Scales.Transform.new/2` makes; `:identity` when not given. The scale trains, breaks and places in transformed space, its limits and breaks given in data units, and labels its breaks in data units.

* `:oob` - What happens to a value outside the limits: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. A value left outside, or left missing, takes `na_value:`, but an opacity or a size kept outside runs on past its range. `:censor` when not given.

* `:guide` - What reads the scale back: `:colorbar`, a bar the colours run up; `:colorsteps`, a bar of one block of colour between each break and the next; `:legend`, a key for each break; or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:colorbar`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "hp" => [0, 5, 10]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, fill: :hp})
    ...>   |> Giggly.Plot.geom_col()
    ...>   |> Giggly.Plot.scale_fill_viridis_c(option: :plasma, begin: 0.2)
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:fill)
    ["#6A00A8", "#E06663", "#F0F921"]

# `scale_fill_viridis_d`

```elixir
@spec scale_fill_viridis_d(t(), keyword()) :: t()
```

Gives the plot a discrete fill scale from a viridis palette, replacing any fill scale it had, as
`scale_color_viridis_d/2` gives a colour scale.

## Options

* `:option` - The palette: `:viridis`, `:magma`, `:inferno`, `:plasma`, `:cividis`, `:rocket`, `:mako` or `:turbo`. The default value is `:viridis`.

* `:begin` - Where in the palette the colours begin, from 0, its start, to 1, its end. The default value is `0.0`.

* `:end` - Where in the palette the colours end, from 0, its start, to 1, its end. The default value is `1.0`.

* `:direction` - 1 to take the colours from `begin:` to `end:`, -1 from `end:` to `begin:`. The default value is `1`.

* `:alpha` - The colours' opacity, from 0 to 1. The default value is `1.0`.

* `:na_value` - The colour of a missing value, or of one outside the limits, or `:none` for none, which draws nothing. The default value is `:none`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - The values the scale shows, a list in the order shown, whatever the data; each value as the column holds it, `nil` for the missing value, a number naming the value equal to it. A value not among them takes `na_value:`. Every value the data holds, in order, when not given.

* `:breaks` - The values the legend shows a key for, a list in the order given, those not among the limits left out; a function of one argument handed the limits that returns them, or `{value, label}` pairs, a pair's label its key's; or `:none` for no legend; every one of the limits when not given.

* `:labels` - The keys' labels: a list of strings, `nil` drawn `NA`, one for each break, or for each limit when no breaks are given; a map from a value to its label, a value it does not hold keeping its own; a function handed every break, a list of values, that returns a label for each, a string, a power or `nil`; or `:none` for keys with no labels. Each value written as text when not given.

* `:guide` - What reads the scale back: `:legend`, a key for each break, or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:legend`.

    iex> plot =
    ...>   %{"drv" => ["f", "r"], "hwy" => [28, 19]}
    ...>   |> Giggly.Plot.new(%{x: :drv, y: :hwy, fill: :drv})
    ...>   |> Giggly.Plot.geom_col()
    ...>   |> Giggly.Plot.scale_fill_viridis_d(direction: -1)
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:fill)
    ["#FDE725", "#440154"]

# `scale_linetype_discrete`

```elixir
@spec scale_linetype_discrete(t(), keyword()) :: t()
```

Gives the plot a discrete line type scale, replacing any line type scale it had.

The values are drawn in 13 line types, in order, easy to tell apart: solid, then the dash
patterns `{2, 2}`, `{4, 2}`, `{4, 4}`, `{1, 3}`, `{1, 3, 4, 3}`, `{7, 3}`, `{2, 2, 6, 2}`,
`{1, 2, 2, 2, 3, 2, 4, 2}`, `{15, 2, 8, 2}`, `{15, 4, 4, 4, 8, 4, 4, 4}`,
`{2, 2, 4, 2, 8, 2, 15, 2}` and `{15, 1}`. Line types have no order, so a line type scale is
always discrete. Its guide is a legend unless `guide:` says otherwise. Raises
`NimbleOptions.ValidationError` for an option it does not take or a value it cannot use, a
`guide:` of `:colorbar` or `:colorsteps` among them, and `ArgumentError` for a list of labels not
one for each break or limit given; a continuous column, or more than 13 values, is refused when
the plot is run, and `scale_linetype_manual/2` gives as many line types as a scale has values.

## Options

* `:na_value` - The line type of a missing value, or of one not among the limits: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; none, which draws no line, when not given.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - The values the scale shows, a list in the order shown, whatever the data; each value as the column holds it, `nil` for the missing value, a number naming the value equal to it. A value not among them takes `na_value:`. Every value the data holds, in order, when not given.

* `:breaks` - The values the legend shows a key for, a list in the order given, those not among the limits left out; a function of one argument handed the limits that returns them, or `{value, label}` pairs, a pair's label its key's; or `:none` for no legend; every one of the limits when not given.

* `:labels` - The keys' labels: a list of strings, `nil` drawn `NA`, one for each break, or for each limit when no breaks are given; a map from a value to its label, a value it does not hold keeping its own; a function handed every break, a list of values, that returns a label for each, a string, a power or `nil`; or `:none` for keys with no labels. Each value written as text when not given.

* `:guide` - What reads the scale back: `:legend`, a key for each break, or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:legend`.

    iex> plot =
    ...>   %{"month" => [1, 2, 1, 2], "value" => [0.2, 0.4, 0.9, 0.7], "series" => ["pce", "pce", "pop", "pop"]}
    ...>   |> Giggly.Plot.new(%{x: :month, y: :value, linetype: :series})
    ...>   |> Giggly.Plot.geom_line()
    ...>   |> Giggly.Plot.scale_linetype_discrete(limits: ["pop", "pce"])
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:linetype)
    [{2, 2}, {2, 2}, {}, {}]

# `scale_linetype_manual`

```elixir
@spec scale_linetype_manual(t(), keyword()) :: t()
```

Gives the plot a discrete line type scale of the line types given, replacing any line type scale
it had.

`values:` gives the line types, each by name, by its number or as a dash pattern, as
`geom_line/3`'s `linetype:` takes one: a list handed to the values in order, or a map from a
value to its line type. The legend shows a key for each value the scale shows, labelled. Raises
`NimbleOptions.ValidationError` for an option it does not take or a value it cannot use, a line
type no line is drawn in or a `guide:` of `:colorbar` or `:colorsteps` among them, and
`ArgumentError` for a list of labels not one for each break or limit given; a continuous column,
or more values than a list has line types, is refused when the plot is run.

## Options

* `:values` - Required. The line types, each `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`: a list, given to the values in order, or to `breaks:` in order where they are a list; or a map from a value, as the column holds it, to its line type, whose scale shows only the values the data holds that it names, unless `limits:` gives others. A value with no line type takes `na_value:`.

* `:na_value` - The line type of a missing value, or of one not among the limits: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; none, which draws no line, when not given.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - The values the scale shows, a list in the order shown, whatever the data; each value as the column holds it, `nil` for the missing value, a number naming the value equal to it. A value not among them takes `na_value:`. Every value the data holds, in order, when not given.

* `:breaks` - The values the legend shows a key for, a list in the order given, those not among the limits left out; a function of one argument handed the limits that returns them, or `{value, label}` pairs, a pair's label its key's; or `:none` for no legend; every one of the limits when not given.

* `:labels` - The keys' labels: a list of strings, `nil` drawn `NA`, one for each break, or for each limit when no breaks are given; a map from a value to its label, a value it does not hold keeping its own; a function handed every break, a list of values, that returns a label for each, a string, a power or `nil`; or `:none` for keys with no labels. Each value written as text when not given.

* `:guide` - What reads the scale back: `:legend`, a key for each break, or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:legend`.

    iex> plot =
    ...>   %{"month" => [1, 2, 1, 2], "value" => [0.2, 0.4, 0.9, 0.7], "series" => ["pce", "pce", "pop", "pop"]}
    ...>   |> Giggly.Plot.new(%{x: :month, y: :value, linetype: :series})
    ...>   |> Giggly.Plot.geom_line()
    ...>   |> Giggly.Plot.scale_linetype_manual(values: %{"pce" => :dotted, "pop" => {3, 1}})
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:linetype)
    [{1, 3}, {1, 3}, {3, 1}, {3, 1}]

# `scale_linewidth_continuous`

```elixir
@spec scale_linewidth_continuous(t(), keyword()) :: t()
```

Gives the plot a continuous line width scale, replacing any line width scale it had.

Each value's line is drawn at a width between the first of `range:` and the second, in
millimetres, as far between them as the value is through the limits. A line whose width changes
along it is drawn a segment from each row to the next, each as wide as the row it starts from.
Its guide is a legend unless `guide:` says otherwise. A value outside the limits, or missing,
draws no line, and an infinite one is an infinite width, which raises when the plot is drawn. Raises `NimbleOptions.ValidationError` for an option it does not take or a value
it cannot use, a width below 0 or a `guide:` of `:colorbar` or `:colorsteps`, and `ArgumentError`
for a list of labels without a list of breaks as long; a column that is not numbers is refused
when the plot is run.

## Options

* `:range` - `{low, high}`: the widths, in millimetres, the values run between, each 0 or more. The default value is `{1.0, 6.0}`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the scale spans whatever the data, `nil` for an end the data decides; either order names the same scale. A value outside them draws no line.

* `:breaks` - The values the legend or colour bar marks, a list of numbers, those outside the limits left out; a function that returns them, or `{break, label}` pairs, handed the limits, `{low, high}`, and, taking two arguments, `[n: n]` as `n_breaks:` asks, `[]` when not given; or `:none` for no guide; chosen from the limits when not given.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted, 2 or more, of the breaks chosen when `breaks:` is not given, or of a `breaks:` function of two arguments; not beside `breaks:` a list, `:none` or a function of one argument, which wants no number.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break, a list of numbers, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do; or `:none` for no labels. A pair's label when a `breaks:` function returns pairs.

* `:transform` - What each value is put through before the scale sees it, a transformation of `Scales.Transform`'s: `:identity`, `:log`, `:log2`, `:log10`, `{:log, base}`, `:log1p`, `:exp`, `{:exp, base}`, `:asinh`, `:pseudo_log`, `{:pseudo_log, sigma: sigma, base: base}`, `:sqrt`, `:reverse`, `:reciprocal`, `:asn`, `:atanh`, `:logit`, `:probit`, `{:probability, :normal, mean: mean, sd: sd}`, `{:probability, :logistic, location: location, scale: scale}`, `{:boxcox, exponent}`, `{:boxcox, exponent, offset: offset}`, `{:modulus, exponent}`, `{:modulus, exponent, offset: offset}`, `{:yj, exponent}`, `:timespan`, `{:timespan, unit}`, a composition `{:compose, [part, ...]}` or one `Scales.Transform.new/2` makes; `:identity` when not given. The scale trains, breaks and places in transformed space, its limits and breaks given in data units, and labels its breaks in data units.

* `:guide` - What reads the scale back: `:legend`, a key for each break, or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:legend`.

    iex> plot =
    ...>   %{"month" => [1, 2, 3], "unemploy" => [2944, 2945, 2958], "uempmed" => [4.5, 4.7, 4.6]}
    ...>   |> Giggly.Plot.new(%{x: :month, y: :unemploy, linewidth: :uempmed})
    ...>   |> Giggly.Plot.geom_line()
    ...>   |> Giggly.Plot.scale_linewidth_continuous(range: {0, 4})
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:linewidth)
    [0.0, 4.0, 1.9999999999999911]

# `scale_linewidth_discrete`

```elixir
@spec scale_linewidth_discrete(t(), keyword()) :: t()
```

Gives the plot a discrete line width scale, replacing any line width scale it had.

The values' lines are drawn at widths spaced evenly from the first of `range:` to the second, in
millimetres, in order. Its guide is a legend unless `guide:` says otherwise. Raises
`NimbleOptions.ValidationError` for an option it does not take or a value it cannot use, a width
below 0 or a `guide:` of `:colorbar` or `:colorsteps`, and `ArgumentError` for a list of labels
not one for each break or limit given; a column of numbers is refused when the plot is run.

## Options

* `:range` - `{first, last}`: the widths, in millimetres, of the first and last values, each 0 or more. The default value is `{2.0, 6.0}`.

* `:na_value` - The width, in millimetres, of a missing value, or of one not among the limits, 0 or more; none, which draws no line, when not given.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - The values the scale shows, a list in the order shown, whatever the data; each value as the column holds it, `nil` for the missing value, a number naming the value equal to it. A value not among them takes `na_value:`. Every value the data holds, in order, when not given.

* `:breaks` - The values the legend shows a key for, a list in the order given, those not among the limits left out; a function of one argument handed the limits that returns them, or `{value, label}` pairs, a pair's label its key's; or `:none` for no legend; every one of the limits when not given.

* `:labels` - The keys' labels: a list of strings, `nil` drawn `NA`, one for each break, or for each limit when no breaks are given; a map from a value to its label, a value it does not hold keeping its own; a function handed every break, a list of values, that returns a label for each, a string, a power or `nil`; or `:none` for keys with no labels. Each value written as text when not given.

* `:guide` - What reads the scale back: `:legend`, a key for each break, or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:legend`.

    iex> plot =
    ...>   %{"class" => ["suv", "compact", "pickup"], "hwy" => [18, 28, 16]}
    ...>   |> Giggly.Plot.new(%{x: :class, y: :hwy, linewidth: :class})
    ...>   |> Giggly.Plot.geom_col(colour: "black")
    ...>   |> Giggly.Plot.scale_linewidth_discrete(range: {1, 3})
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:linewidth)
    [3.0, 1.0, 2.0]

# `scale_radius`

```elixir
@spec scale_radius(t(), keyword()) :: t()
```

Gives the plot a continuous size scale by width, replacing any size scale it had.

Each value is drawn at a size between the first of `range:` and the second, in millimetres, as
far between them as the value is through the limits, so a point's width, not its area, grows
with the value. Its guide is a legend unless `guide:` says otherwise. A value outside the limits,
or missing, is not drawn. Raises `NimbleOptions.ValidationError` for an option it does not take
or a value it cannot use, a size below 0 or a `guide:` of `:colorbar` or `:colorsteps`, and
`ArgumentError` for a list of labels without a list of breaks as long; a column that is not
numbers is refused when the plot is run.

## Options

* `:range` - `{low, high}`: the sizes, in millimetres, the values run between, each 0 or more. The default value is `{1.0, 6.0}`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the scale spans whatever the data, `nil` for an end the data decides; either order names the same scale. A value outside them is not drawn.

* `:breaks` - The values the legend or colour bar marks, a list of numbers, those outside the limits left out; a function that returns them, or `{break, label}` pairs, handed the limits, `{low, high}`, and, taking two arguments, `[n: n]` as `n_breaks:` asks, `[]` when not given; or `:none` for no guide; chosen from the limits when not given.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted, 2 or more, of the breaks chosen when `breaks:` is not given, or of a `breaks:` function of two arguments; not beside `breaks:` a list, `:none` or a function of one argument, which wants no number.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break, a list of numbers, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do; or `:none` for no labels. A pair's label when a `breaks:` function returns pairs.

* `:transform` - What each value is put through before the scale sees it, a transformation of `Scales.Transform`'s: `:identity`, `:log`, `:log2`, `:log10`, `{:log, base}`, `:log1p`, `:exp`, `{:exp, base}`, `:asinh`, `:pseudo_log`, `{:pseudo_log, sigma: sigma, base: base}`, `:sqrt`, `:reverse`, `:reciprocal`, `:asn`, `:atanh`, `:logit`, `:probit`, `{:probability, :normal, mean: mean, sd: sd}`, `{:probability, :logistic, location: location, scale: scale}`, `{:boxcox, exponent}`, `{:boxcox, exponent, offset: offset}`, `{:modulus, exponent}`, `{:modulus, exponent, offset: offset}`, `{:yj, exponent}`, `:timespan`, `{:timespan, unit}`, a composition `{:compose, [part, ...]}` or one `Scales.Transform.new/2` makes; `:identity` when not given. The scale trains, breaks and places in transformed space, its limits and breaks given in data units, and labels its breaks in data units.

* `:guide` - What reads the scale back: `:legend`, a key for each break, or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:legend`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "hp" => [110, 93, 175]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, size: :hp})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_radius(range: {2, 8})
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:size)
    [3.2439024390243905, 2.0, 8.0]

# `scale_shape_discrete`

```elixir
@spec scale_shape_discrete(t(), keyword()) :: t()
```

Gives the plot a discrete shape scale, replacing any shape scale it had.

The values are drawn in six shapes, in order, easy to tell apart: solid, `:circle_small`,
`:triangle`, `:square`, `:plus`, `:square_cross` and `:asterisk`, or, with `solid: false`, the
first three open, `:circle_open`, `:triangle_open` and `:square_open`. Shapes have no order, so a
shape scale is always discrete. Its guide is a legend unless `guide:` says otherwise. Raises
`NimbleOptions.ValidationError` for an option it does not take or a value it cannot use, a
`guide:` of `:colorbar` or `:colorsteps` among them, and `ArgumentError` for a list of labels not
one for each break or limit given; a continuous column, or more than six values, is refused when
the plot is run, and `scale_shape_manual/2` gives as many shapes as a scale has values.

## Options

* `:solid` (`t:boolean/0`) - Whether the shapes are solid, `:circle_small`, `:triangle`, `:square`, `:plus`, `:square_cross` and `:asterisk` in order, or, `false`, open, `:circle_open`, `:triangle_open`, `:square_open` and the last three. The default value is `true`.

* `:na_value` - The shape of a missing value, or of one not among the limits, by name or by number, or `:none`; none, which draws no point, when not given.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - The values the scale shows, a list in the order shown, whatever the data; each value as the column holds it, `nil` for the missing value, a number naming the value equal to it. A value not among them takes `na_value:`. Every value the data holds, in order, when not given.

* `:breaks` - The values the legend shows a key for, a list in the order given, those not among the limits left out; a function of one argument handed the limits that returns them, or `{value, label}` pairs, a pair's label its key's; or `:none` for no legend; every one of the limits when not given.

* `:labels` - The keys' labels: a list of strings, `nil` drawn `NA`, one for each break, or for each limit when no breaks are given; a map from a value to its label, a value it does not hold keeping its own; a function handed every break, a list of values, that returns a label for each, a string, a power or `nil`; or `:none` for keys with no labels. Each value written as text when not given.

* `:guide` - What reads the scale back: `:legend`, a key for each break, or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:legend`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "cyl" => ["6", "4", "8"]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, shape: :cyl})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_shape_discrete(solid: false)
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:shape)
    [:triangle_open, :circle_open, :square_open]

# `scale_shape_manual`

```elixir
@spec scale_shape_manual(t(), keyword()) :: t()
```

Gives the plot a discrete shape scale of the shapes given, replacing any shape scale it had.

`values:` gives the shapes, each by name or by its number, as `geom_point/3` names them: a list
handed to the values in order, or a map from a value to its shape. The legend shows a key for
each value the scale shows, labelled. Raises `NimbleOptions.ValidationError` for an option it
does not take or a value it cannot use, a shape no point is drawn in or a `guide:` of
`:colorbar` or `:colorsteps` among them, and `ArgumentError` for a list of labels not one for each
break or limit given; a continuous column, or more values than a list has shapes, is refused when
the plot is run.

## Options

* `:values` - Required. The shapes, each by name or by number, or `:none`: a list, given to the values in order, or to `breaks:` in order where they are a list; or a map from a value, as the column holds it, to its shape, whose scale shows only the values the data holds that it names, unless `limits:` gives others. A value with no shape takes `na_value:`.

* `:na_value` - The shape of a missing value, or of one not among the limits, by name or by number, or `:none`; none, which draws no point, when not given.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - The values the scale shows, a list in the order shown, whatever the data; each value as the column holds it, `nil` for the missing value, a number naming the value equal to it. A value not among them takes `na_value:`. Every value the data holds, in order, when not given.

* `:breaks` - The values the legend shows a key for, a list in the order given, those not among the limits left out; a function of one argument handed the limits that returns them, or `{value, label}` pairs, a pair's label its key's; or `:none` for no legend; every one of the limits when not given.

* `:labels` - The keys' labels: a list of strings, `nil` drawn `NA`, one for each break, or for each limit when no breaks are given; a map from a value to its label, a value it does not hold keeping its own; a function handed every break, a list of values, that returns a label for each, a string, a power or `nil`; or `:none` for keys with no labels. Each value written as text when not given.

* `:guide` - What reads the scale back: `:legend`, a key for each break, or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:legend`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "cyl" => ["6", "4", "8"]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, shape: :cyl})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_shape_manual(values: %{"4" => 21, "6" => :diamond, "8" => 4})
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:shape)
    [:diamond, :circle_filled, :cross]

# `scale_size_area`

```elixir
@spec scale_size_area(t(), keyword()) :: t()
```

Gives the plot a continuous size scale that draws 0 at size 0, replacing any size scale it had.

Each value is drawn at a size, in millimetres, whose square is as far toward the square of
`max_size:` as the value is toward the high end of the limits from 0, so a point's area is in
proportion to the value, and the high end is drawn at `max_size:`. A value below 0 is drawn as
large as its distance from 0, and an infinite value at an infinite size, so it is not drawn.
Its guide is a legend unless `guide:` says otherwise. Raises
`NimbleOptions.ValidationError` for an option it does not take or a value it cannot use, a size
below 0 or a `guide:` of `:colorbar` or `:colorsteps`, and `ArgumentError` for a list of labels
without a list of breaks as long; a column that is not numbers, and a value below limits whose
high end is 0, which would be drawn infinitely large, are refused when the plot is run.

## Options

* `:max_size` - The size, in millimetres, of a value at the high end of the limits, 0 or more. The default value is `6.0`.

* `:na_value` - The size, in millimetres, of a missing value, or of one outside the limits, 0 or more; none, which draws nothing, when not given.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the scale spans whatever the data, `nil` for an end the data decides; either order names the same scale. A value outside them takes `na_value:`, unless `oob:` says otherwise where the scale takes it.

* `:breaks` - The values the legend or colour bar marks, a list of numbers, those outside the limits left out; a function that returns them, or `{break, label}` pairs, handed the limits, `{low, high}`, and, taking two arguments, `[n: n]` as `n_breaks:` asks, `[]` when not given; or `:none` for no guide; chosen from the limits when not given.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted, 2 or more, of the breaks chosen when `breaks:` is not given, or of a `breaks:` function of two arguments; not beside `breaks:` a list, `:none` or a function of one argument, which wants no number.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break, a list of numbers, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do; or `:none` for no labels. A pair's label when a `breaks:` function returns pairs.

* `:transform` - What each value is put through before the scale sees it, a transformation of `Scales.Transform`'s: `:identity`, `:log`, `:log2`, `:log10`, `{:log, base}`, `:log1p`, `:exp`, `{:exp, base}`, `:asinh`, `:pseudo_log`, `{:pseudo_log, sigma: sigma, base: base}`, `:sqrt`, `:reverse`, `:reciprocal`, `:asn`, `:atanh`, `:logit`, `:probit`, `{:probability, :normal, mean: mean, sd: sd}`, `{:probability, :logistic, location: location, scale: scale}`, `{:boxcox, exponent}`, `{:boxcox, exponent, offset: offset}`, `{:modulus, exponent}`, `{:modulus, exponent, offset: offset}`, `{:yj, exponent}`, `:timespan`, `{:timespan, unit}`, a composition `{:compose, [part, ...]}` or one `Scales.Transform.new/2` makes; `:identity` when not given. The scale trains, breaks and places in transformed space, its limits and breaks given in data units, and labels its breaks in data units.

* `:oob` - What happens to a value outside the limits: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. A value left outside, or left missing, takes `na_value:`, but an opacity or a size kept outside runs on past its range. `:censor` when not given.

* `:guide` - What reads the scale back: `:legend`, a key for each break, or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:legend`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "hp" => [110, 93, 175]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, size: :hp})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_size_area(max_size: 10)
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:size)
    [7.928249671720918, 7.289914755527471, 10.0]

# `scale_size_continuous`

```elixir
@spec scale_size_continuous(t(), keyword()) :: t()
```

Gives the plot a continuous size scale, replacing any size scale it had.

Each value is drawn at a size between the first of `range:` and the second, in millimetres, by
area: its size's square is as far between theirs as the value is through the limits, so a
point's area grows with the value. Its guide is a legend unless `guide:` says otherwise. A value
outside the limits, or missing, is not drawn. Raises `NimbleOptions.ValidationError` for an
option it does not take or a value it cannot use, a size below 0 or a `guide:` of `:colorbar` or
`:colorsteps`, and `ArgumentError` for a list of labels without a list of breaks as long; a column
that is not numbers is refused when the plot is run.

## Options

* `:range` - `{low, high}`: the sizes, in millimetres, the values run between by area, each 0 or more. The default value is `{1.0, 6.0}`.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the scale spans whatever the data, `nil` for an end the data decides; either order names the same scale. A value outside them is not drawn.

* `:breaks` - The values the legend or colour bar marks, a list of numbers, those outside the limits left out; a function that returns them, or `{break, label}` pairs, handed the limits, `{low, high}`, and, taking two arguments, `[n: n]` as `n_breaks:` asks, `[]` when not given; or `:none` for no guide; chosen from the limits when not given.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted, 2 or more, of the breaks chosen when `breaks:` is not given, or of a `breaks:` function of two arguments; not beside `breaks:` a list, `:none` or a function of one argument, which wants no number.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break, a list of numbers, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do; or `:none` for no labels. A pair's label when a `breaks:` function returns pairs.

* `:transform` - What each value is put through before the scale sees it, a transformation of `Scales.Transform`'s: `:identity`, `:log`, `:log2`, `:log10`, `{:log, base}`, `:log1p`, `:exp`, `{:exp, base}`, `:asinh`, `:pseudo_log`, `{:pseudo_log, sigma: sigma, base: base}`, `:sqrt`, `:reverse`, `:reciprocal`, `:asn`, `:atanh`, `:logit`, `:probit`, `{:probability, :normal, mean: mean, sd: sd}`, `{:probability, :logistic, location: location, scale: scale}`, `{:boxcox, exponent}`, `{:boxcox, exponent, offset: offset}`, `{:modulus, exponent}`, `{:modulus, exponent, offset: offset}`, `{:yj, exponent}`, `:timespan`, `{:timespan, unit}`, a composition `{:compose, [part, ...]}` or one `Scales.Transform.new/2` makes; `:identity` when not given. The scale trains, breaks and places in transformed space, its limits and breaks given in data units, and labels its breaks in data units.

* `:guide` - What reads the scale back: `:legend`, a key for each break, or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:legend`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "hp" => [110, 93, 175]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, size: :hp})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_size_continuous(range: {1, 10})
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:size)
    [5.097887617642688, 1.0, 10.0]

# `scale_size_discrete`

```elixir
@spec scale_size_discrete(t(), keyword()) :: t()
```

Gives the plot a discrete size scale, replacing any size scale it had.

The values are drawn at sizes from the first of `range:` to the second, in millimetres, in
order, their squares, and so a point's area, evenly spaced. Its guide is a legend unless `guide:`
says otherwise. Raises `NimbleOptions.ValidationError` for an option it does not take or a value
it cannot use, a size below 0 or a `guide:` of `:colorbar` or `:colorsteps`, and `ArgumentError`
for a list of labels not one for each break or limit given; a column of numbers is refused when
the plot is run.

## Options

* `:range` - `{first, last}`: the sizes, in millimetres, of the first and last values, each 0 or more. The default value is `{2.0, 6.0}`.

* `:na_value` - The size, in millimetres, of a missing value, or of one outside the limits, 0 or more; none, which draws nothing, when not given.

* `:name` - The legend's or colour bar's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - The values the scale shows, a list in the order shown, whatever the data; each value as the column holds it, `nil` for the missing value, a number naming the value equal to it. A value not among them takes `na_value:`. Every value the data holds, in order, when not given.

* `:breaks` - The values the legend shows a key for, a list in the order given, those not among the limits left out; a function of one argument handed the limits that returns them, or `{value, label}` pairs, a pair's label its key's; or `:none` for no legend; every one of the limits when not given.

* `:labels` - The keys' labels: a list of strings, `nil` drawn `NA`, one for each break, or for each limit when no breaks are given; a map from a value to its label, a value it does not hold keeping its own; a function handed every break, a list of values, that returns a label for each, a string, a power or `nil`; or `:none` for keys with no labels. Each value written as text when not given.

* `:guide` - What reads the scale back: `:legend`, a key for each break, or a legend `guide_legend/1` makes, or `:none` for none; `guides/2` sets one over it. The default value is `:legend`.

    iex> plot =
    ...>   %{"wt" => [2.62, 2.32, 3.44], "mpg" => [21.0, 22.8, 18.7], "cyl" => ["6", "4", "8"]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg, size: :cyl})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_size_discrete(range: {1, 3})
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:size)
    [2.23606797749979, 1.0, 3.0]

# `scale_x_continuous`

```elixir
@spec scale_x_continuous(t(), keyword()) :: t()
```

Gives the plot a continuous x scale with the given options, replacing any x scale it had.

A value outside the limits is missing, so its mark is not drawn: a point, or a bar counted from
it, and a bar whose ends the limits cut once it is placed. An end at `:infinity` or
`:neg_infinity` is kept. `oob:` says otherwise: `:squish` moves a value onto the nearer limit,
`:keep` draws it past the panel's edge, cut off there. The scale's name titles the axis whatever `labs/2` says. Raises
`ArgumentError` for a list of labels without a list of breaks as long; a column on the axis
that is not numbers is refused when the plot is run.

## Options

* `:name` - The axis's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the axis spans whatever the data, in data units, `nil` for an end the data decides; either order names the same axis. A value outside them is missing, so its mark is not drawn, unless `oob:` says otherwise.

* `:oob` - What happens to a value outside the limits: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. Run on the positions as given and again once the stat and position have moved them, so a bar whose base the limits leave out is missing; a value kept outside is drawn past the panel's edge and cut off there. `:censor` when not given.

* `:breaks` - The values the axis marks with a tick, a label and a grid line, a list of numbers in data units; a function that returns them, or `{break, label}` pairs, handed the axis's extent in data units, `{low, high}`, and, taking two arguments, `[n: n]` as `n_breaks:` asks, `[]` when not given, such as `&Scales.Breaks.extended/2`; or `:none` for none; chosen from the limits when not given. A break is drawn wherever it falls inside the widened axis.

* `:minor_breaks` - The values the panel draws a minor grid line at, a list of numbers in data units; a function that returns them, handed the axis's extent in data units, `{low, high}`, and, taking two arguments, the breaks drawn; or `:none` for none; midway between the breaks, once transformed, when not given.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted, of the breaks chosen when `breaks:` is not given, 2 or more but on a log axis, or of a `breaks:` function of two arguments; not beside `breaks:` a list, `:none` or a function of one argument, which wants no number.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break drawn, a list of numbers in data units, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do; or `:none` for ticks with no labels. A pair's label when a `breaks:` function returns pairs.

* `:expand` - How far the axis reaches beyond its limits, `[mult: m, add: a]`: at each end, that multiple of the limits' width plus that constant, each a number or `{low, high}` for the two ends; `[mult: 0.05]` when not given.

* `:transform` - What each value is put through before the scale sees it, a transformation of `Scales.Transform`'s: `:identity`, `:log`, `:log2`, `:log10`, `{:log, base}`, `:log1p`, `:exp`, `{:exp, base}`, `:asinh`, `:pseudo_log`, `{:pseudo_log, sigma: sigma, base: base}`, `:sqrt`, `:reverse`, `:reciprocal`, `:asn`, `:atanh`, `:logit`, `:probit`, `{:probability, :normal, mean: mean, sd: sd}`, `{:probability, :logistic, location: location, scale: scale}`, `{:boxcox, exponent}`, `{:boxcox, exponent, offset: offset}`, `{:modulus, exponent}`, `{:modulus, exponent, offset: offset}`, `{:yj, exponent}`, `:timespan`, `{:timespan, unit}`, a composition `{:compose, [part, ...]}` or one `Scales.Transform.new/2` makes; `:identity` when not given. The scale trains, breaks and places in transformed space, its limits and breaks given in data units, and labels its breaks in data units.

    iex> frame =
    ...>   %{"wt" => [1.5, 2.6, 3.4, 5.4], "mpg" => [30.4, 21.0, 18.7, 10.4]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_x_continuous(limits: {2, 5})
    ...>   |> Giggly.layer_data()
    iex> Giggly.DataFrame.pull(frame, :x)
    [nil, 2.6, 3.4, nil]

# `scale_x_date`

```elixir
@spec scale_x_date(t(), keyword()) :: t()
```

Gives the plot a date x scale with the given options, replacing any x scale it had.

A date axis places each date at its days since 1970-01-01 and marks it on calendar boundaries:
every day, week, month or year, as suits its span, or every step of `date_breaks:`. Its labels
are written as suits the breaks, or in the format `date_labels:` gives. A value outside the
limits is missing, so its mark is not drawn, unless `oob:` says otherwise. The scale's name titles the axis whatever `labs/2`
says. Raises `ArgumentError` for an option given beside its `date_` twin, or a list of labels
without a list of breaks as long; a column on the axis that is not dates is refused when the
plot is run.

## Options

* `:name` - The axis's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the dates the axis spans whatever the data, `nil` for an end the data decides; either order names the same axis. A value outside them is missing, so its mark is not drawn, unless `oob:` says otherwise.

* `:oob` - What happens to a value outside the limits: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. Run on the positions as given and again once the stat and position have moved them, so a bar whose base the limits leave out is missing; a value kept outside is drawn past the panel's edge and cut off there. `:censor` when not given.

* `:breaks` - The dates the axis marks with a tick, a label and a grid line, a list; a function that returns them, or `{date, label}` pairs, handed the axis's extent, `{low, high}`, its ends rounded out to whole days, and, taking two arguments, `[]`, such as `&Scales.Breaks.pretty/2`; or `:none` for none; chosen from the limits when neither this nor `date_breaks:` is given. A break is drawn wherever it falls inside the widened axis.

* `:date_breaks` - A break every step, `[week: 1]`: one of `:day`, `:week`, `:month` and `:year` and how many of it, laid from the widened axis's start, rounded down to a multiple of the days since 1970-01-01, a Monday, the 1st of a month or 1 January, to its end. Not with `breaks:`.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break drawn, a list of dates, that returns a label for each, a string, a power or `nil`; or `:none` for ticks with no labels. Not with `date_labels:`. When neither is given, the breaks the axis chooses are written as suits their step (`Sep 21`, `2026`), a `breaks:` function's pairs by their labels, and others in full (`2026-09-21`).

* `:date_labels` - The format every break's label is written in, as `Calendar.strftime/3` takes it, such as `"%b %d"`. Not with `labels:`.

* `:minor_breaks` - The dates the panel draws a minor grid line at, a list; a function that returns them, handed the axis's extent as `breaks:`'s is, and, taking two arguments, the breaks drawn; or `:none` for none; midway between the breaks when neither this nor `date_minor_breaks:` is given.

* `:date_minor_breaks` - A minor grid line every step, as `date_breaks:` lays breaks. Not with `minor_breaks:`.

* `:expand` - How far the axis reaches beyond its limits, `[mult: m, add: a]`: at each end, that multiple of the limits' width plus that constant, each a number or `{low, high}` for the two ends; `[mult: 0.05]` when not given.

    iex> svg =
    ...>   %{"day" => [~D[2026-09-20], ~D[2026-10-19]], "price" => [0.3, 0.8]}
    ...>   |> Giggly.Plot.new(%{x: :day, y: :price})
    ...>   |> Giggly.Plot.geom_line()
    ...>   |> Giggly.Plot.scale_x_date(date_breaks: [week: 2], date_labels: "%d %b")
    ...>   |> Giggly.to_svg()
    ...>   |> IO.iodata_to_binary()
    iex> {svg =~ ">28 Sep</text>", svg =~ ">12 Oct</text>"}
    {true, true}

# `scale_x_datetime`

```elixir
@spec scale_x_datetime(t(), keyword()) :: t()
```

Gives the plot a date-time x scale with the given options, replacing any x scale it had.

A date-time axis places each `DateTime` at its seconds since 1970-01-01 00:00 UTC, and each
`NaiveDateTime` at its seconds since the same time on its own clock, as though it were UTC's;
a column holds one kind or the other, and an axis takes one kind. It marks them on clock and
calendar boundaries: every few seconds, minutes or hours, every day, week, month or year, as
suits its span, or every step of `date_breaks:`. Its labels are written as suits the breaks, or
in the format `date_labels:` gives. Breaks are laid and labels written on the clock of the
axis's time zone, `timezone:`, else its first column's, naive date-times on their own clock as
though it were UTC's. Where the zone's offset changes, as daylight saving begins or ends, steps
under a day keep their spacing and days, months and years keep their midnight. A zone other
than UTC needs `time_zone_database:` to name a database that knows it, such as the tz
package's. A value outside the limits is missing, so its mark is not drawn, unless `oob:` says
otherwise. The scale's name
titles the axis whatever `labs/2` says. Raises `ArgumentError` for an option given beside its
`date_` twin, a list of labels without a list of breaks as long, or a time zone the database
does not know; a column on the axis that is not date-times, or is in a zone the database does
not know, or naive beside `timezone:`, is refused when the plot is run.

## Options

* `:name` - The axis's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the date-times the axis spans whatever the data, `DateTime`s or `NaiveDateTime`s as its column holds, `nil` for an end the data decides; either order names the same axis. A value outside them is missing, so its mark is not drawn, unless `oob:` says otherwise.

* `:oob` - What happens to a value outside the limits: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. Run on the positions as given and again once the stat and position have moved them, so a bar whose base the limits leave out is missing; a value kept outside is drawn past the panel's edge and cut off there. `:censor` when not given.

* `:breaks` - The date-times the axis marks with a tick, a label and a grid line, a list; a function that returns them, or `{date_time, label}` pairs, handed the axis's extent, `{low, high}`, as the column holds date-times, and, taking two arguments, `[]`, such as `&Scales.Breaks.pretty/2`; or `:none` for none; chosen from the limits when neither this nor `date_breaks:` is given. A break is drawn wherever it falls inside the widened axis.

* `:date_breaks` - A break every step, `[hour: 6]`: one of `:second`, `:minute`, `:hour`, `:day`, `:week`, `:month` and `:year` and how many of it, laid from the widened axis's start, rounded to the nearest multiple of the step since 1970-01-01 for seconds and minutes, else down to the start of its hour, its day, the Monday of its week, the 1st of its month or 1 January, to its end. Not with `breaks:`.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break drawn, a list of date-times as the column holds them, that returns a label for each, a string, a power or `nil`; or `:none` for ticks with no labels. Not with `date_labels:`. When neither is given, the breaks the axis chooses are written as suits their step (`06:00`, `Mar 10 06:00`, `Mar 10`), a `breaks:` function's pairs by their labels, and others in full, the date alone where every one is a midnight (`2024-03-10`), else to the second (`2024-03-10 06:30:00`).

* `:date_labels` - The format every break's label is written in, as `Calendar.strftime/3` takes it, such as `"%H:%M"`. Not with `labels:`.

* `:minor_breaks` - The date-times the panel draws a minor grid line at, a list; a function that returns them, handed the axis's extent as `breaks:`'s is, and, taking two arguments, the breaks drawn; or `:none` for none; midway between the breaks when neither this nor `date_minor_breaks:` is given.

* `:date_minor_breaks` - A minor grid line every step, as `date_breaks:` lays breaks. Not with `minor_breaks:`.

* `:timezone` (`t:String.t/0`) - The time zone the axis lays its breaks and writes its labels in, such as `"America/New_York"`, which `time_zone_database:` must know; the first date-time column's when not given. Naive date-times are in no time zone, so a column of them is refused beside it.

* `:time_zone_database` (`t:atom/0`) - The time zone database that reads the axis's time zone, a module implementing `Calendar.TimeZoneDatabase`, such as the tz package's `Tz.TimeZoneDatabase`; `Calendar.UTCOnlyTimeZoneDatabase`, which knows UTC alone, when not given, never the one the application configures.

* `:expand` - How far the axis reaches beyond its limits, `[mult: m, add: a]`: at each end, that multiple of the limits' width plus that constant, in seconds, each a number or `{low, high}` for the two ends; `[mult: 0.05]` when not given.

    iex> svg =
    ...>   %{"at" => [~U[2024-03-10 00:00:00Z], ~U[2024-03-10 23:00:00Z]], "load" => [0.3, 0.8]}
    ...>   |> Giggly.Plot.new(%{x: :at, y: :load})
    ...>   |> Giggly.Plot.geom_line()
    ...>   |> Giggly.Plot.scale_x_datetime(date_labels: "%H:%M")
    ...>   |> Giggly.to_svg()
    ...>   |> IO.iodata_to_binary()
    iex> {svg =~ ">06:00</text>", svg =~ ">18:00</text>"}
    {true, true}

The same day shown in Kolkata's time, five and a half hours ahead:

    iex> svg =
    ...>   %{"at" => [~U[2024-03-10 00:00:00Z], ~U[2024-03-10 23:00:00Z]], "load" => [0.3, 0.8]}
    ...>   |> Giggly.Plot.new(%{x: :at, y: :load})
    ...>   |> Giggly.Plot.geom_line()
    ...>   |> Giggly.Plot.scale_x_datetime(
    ...>     timezone: "Asia/Kolkata",
    ...>     time_zone_database: Tz.TimeZoneDatabase
    ...>   )
    ...>   |> Giggly.to_svg()
    ...>   |> IO.iodata_to_binary()
    iex> {svg =~ ">Mar 10 12:00</text>", svg =~ ">Mar 11 00:00</text>"}
    {true, true}

# `scale_x_discrete`

```elixir
@spec scale_x_discrete(t(), keyword()) :: t()
```

Gives the plot a discrete x scale with the given options, replacing any x scale it had.

A discrete axis places each value at its own position, 1, 2, 3 and so on, in order: text
alphabetically, numbers by size, the missing value last. `limits:` chooses which values it shows
and in what order; a value it leaves out is missing, so its mark is not drawn, a point or a bar
counted from it. Each value is named as the column holds it: `factor(cyl)`'s as `4`, `6` and
`8`, a missing value as `nil`. The scale's name titles the axis whatever `labs/2` says. Raises
`ArgumentError` for a list of labels not one for each break, or for each limit when no breaks
are given; a column on the axis that is not discrete is refused when the plot is run.

## Options

* `:name` - The axis's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - The values the axis shows, a list in the order shown, whatever the data; each value as the column holds it, `nil` for the missing value, a number naming the value equal to it. A value not among them is missing, so its mark is not drawn; one the data lacks leaves its place empty. Every value the data holds, in order, when not given.

* `:breaks` - The values the axis marks with a tick and a label, a list in the order given, those not among the limits left out; a function of one argument handed the limits that returns them, or `{value, label}` pairs; or `:none` for none; every one of the limits when not given.

* `:minor_breaks` - The positions the panel draws a minor grid line at, the values placed at 1, 2, 3 and on: a list of numbers; a function that returns them, handed the axis's extent, `{low, high}`, and, taking two arguments, the breaks' positions; or `:none` for none; none when not given.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each break, or for each limit when no breaks are given; a map from a value to its label, a value it does not hold keeping its own; a function handed every break drawn, a list of values, that returns a label for each, a string, a power or `nil`; or `:none` for ticks with no labels. A pair's label when a `breaks:` function returns pairs, else each value written as text, when not given.

* `:expand` - How far the axis reaches beyond its first and last values, `[mult: m, add: a]`: at each end, that multiple of the distance between them plus that constant, each a number or `{low, high}` for the two ends; `[add: 0.6]` when not given.

    iex> frame =
    ...>   %{"class" => ["suv", "compact", "midsize", "suv"], "hwy" => [17, 29, 26, 20]}
    ...>   |> Giggly.Plot.new(%{x: :class, y: :hwy})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_x_discrete(limits: ["suv", "compact"])
    ...>   |> Giggly.layer_data()
    iex> Giggly.DataFrame.pull(frame, :x)
    [1, 2, nil, 1]

Labels given by value:

    iex> svg =
    ...>   %{"class" => ["suv", "compact"], "hwy" => [17, 29]}
    ...>   |> Giggly.Plot.new(%{x: :class, y: :hwy})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_x_discrete(labels: %{"suv" => "SUV"})
    ...>   |> Giggly.to_svg()
    ...>   |> IO.iodata_to_binary()
    iex> {svg =~ ">SUV</text>", svg =~ ">compact</text>"}
    {true, true}

# `scale_x_log10`

```elixir
@spec scale_x_log10(t(), keyword()) :: t()
```

Gives the plot a continuous x scale through a base-10 logarithm, replacing any x scale it had,
as `scale_x_continuous(plot, transform: :log10)` does: each value is placed at its logarithm,
and the axis marked at powers of ten, or at multiples of them where too few powers fall on it,
and labelled in data units. Zero is placed at minus infinity, the panel's edge, and a negative
value is missing.

## Options

* `:name` - The axis's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the axis spans whatever the data, in data units, `nil` for an end the data decides; either order names the same axis. A value outside them is missing, so its mark is not drawn, unless `oob:` says otherwise.

* `:oob` - What happens to a value outside the limits: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. Run on the positions as given and again once the stat and position have moved them, so a bar whose base the limits leave out is missing; a value kept outside is drawn past the panel's edge and cut off there. `:censor` when not given.

* `:breaks` - The values the axis marks with a tick, a label and a grid line, a list of numbers in data units; a function that returns them, or `{break, label}` pairs, handed the axis's extent in data units, `{low, high}`, and, taking two arguments, `[n: n]` as `n_breaks:` asks, `[]` when not given, such as `&Scales.Breaks.extended/2`; or `:none` for none; chosen from the limits when not given. A break is drawn wherever it falls inside the widened axis.

* `:minor_breaks` - The values the panel draws a minor grid line at, a list of numbers in data units; a function that returns them, handed the axis's extent in data units, `{low, high}`, and, taking two arguments, the breaks drawn; or `:none` for none; midway between the breaks, once transformed, when not given.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted, of the breaks chosen when `breaks:` is not given, 2 or more but on a log axis, or of a `breaks:` function of two arguments; not beside `breaks:` a list, `:none` or a function of one argument, which wants no number.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break drawn, a list of numbers in data units, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do; or `:none` for ticks with no labels. A pair's label when a `breaks:` function returns pairs.

* `:expand` - How far the axis reaches beyond its limits, `[mult: m, add: a]`: at each end, that multiple of the limits' width plus that constant, each a number or `{low, high}` for the two ends; `[mult: 0.05]` when not given.

    iex> plot =
    ...>   %{"x" => [1, 10, 100], "y" => [3, 1, 2]}
    ...>   |> Giggly.Plot.new(%{x: :x, y: :y})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_x_log10()
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:x)
    [0.0, 1.0, 2.0]

# `scale_x_reverse`

```elixir
@spec scale_x_reverse(t(), keyword()) :: t()
```

Gives the plot a continuous x scale running from high to low, replacing any x scale it had, as
`scale_x_continuous(plot, transform: :reverse)` does: each value is placed at its negation, and
the axis marked and labelled in data units.

## Options

* `:name` - The axis's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the axis spans whatever the data, in data units, `nil` for an end the data decides; either order names the same axis. A value outside them is missing, so its mark is not drawn, unless `oob:` says otherwise.

* `:oob` - What happens to a value outside the limits: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. Run on the positions as given and again once the stat and position have moved them, so a bar whose base the limits leave out is missing; a value kept outside is drawn past the panel's edge and cut off there. `:censor` when not given.

* `:breaks` - The values the axis marks with a tick, a label and a grid line, a list of numbers in data units; a function that returns them, or `{break, label}` pairs, handed the axis's extent in data units, `{low, high}`, and, taking two arguments, `[n: n]` as `n_breaks:` asks, `[]` when not given, such as `&Scales.Breaks.extended/2`; or `:none` for none; chosen from the limits when not given. A break is drawn wherever it falls inside the widened axis.

* `:minor_breaks` - The values the panel draws a minor grid line at, a list of numbers in data units; a function that returns them, handed the axis's extent in data units, `{low, high}`, and, taking two arguments, the breaks drawn; or `:none` for none; midway between the breaks, once transformed, when not given.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted, of the breaks chosen when `breaks:` is not given, 2 or more but on a log axis, or of a `breaks:` function of two arguments; not beside `breaks:` a list, `:none` or a function of one argument, which wants no number.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break drawn, a list of numbers in data units, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do; or `:none` for ticks with no labels. A pair's label when a `breaks:` function returns pairs.

* `:expand` - How far the axis reaches beyond its limits, `[mult: m, add: a]`: at each end, that multiple of the limits' width plus that constant, each a number or `{low, high}` for the two ends; `[mult: 0.05]` when not given.

    iex> plot =
    ...>   %{"x" => [1.5, 2.5, 3.5], "y" => [3, 1, 2]}
    ...>   |> Giggly.Plot.new(%{x: :x, y: :y})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_x_reverse()
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:x)
    [-1.5, -2.5, -3.5]

# `scale_x_sqrt`

```elixir
@spec scale_x_sqrt(t(), keyword()) :: t()
```

Gives the plot a continuous x scale through a square root, replacing any x scale it had, as
`scale_x_continuous(plot, transform: :sqrt)` does: each value is placed at its square root, and
the axis marked and labelled in data units. A negative value is missing.

## Options

* `:name` - The axis's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the axis spans whatever the data, in data units, `nil` for an end the data decides; either order names the same axis. A value outside them is missing, so its mark is not drawn, unless `oob:` says otherwise.

* `:oob` - What happens to a value outside the limits: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. Run on the positions as given and again once the stat and position have moved them, so a bar whose base the limits leave out is missing; a value kept outside is drawn past the panel's edge and cut off there. `:censor` when not given.

* `:breaks` - The values the axis marks with a tick, a label and a grid line, a list of numbers in data units; a function that returns them, or `{break, label}` pairs, handed the axis's extent in data units, `{low, high}`, and, taking two arguments, `[n: n]` as `n_breaks:` asks, `[]` when not given, such as `&Scales.Breaks.extended/2`; or `:none` for none; chosen from the limits when not given. A break is drawn wherever it falls inside the widened axis.

* `:minor_breaks` - The values the panel draws a minor grid line at, a list of numbers in data units; a function that returns them, handed the axis's extent in data units, `{low, high}`, and, taking two arguments, the breaks drawn; or `:none` for none; midway between the breaks, once transformed, when not given.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted, of the breaks chosen when `breaks:` is not given, 2 or more but on a log axis, or of a `breaks:` function of two arguments; not beside `breaks:` a list, `:none` or a function of one argument, which wants no number.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break drawn, a list of numbers in data units, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do; or `:none` for ticks with no labels. A pair's label when a `breaks:` function returns pairs.

* `:expand` - How far the axis reaches beyond its limits, `[mult: m, add: a]`: at each end, that multiple of the limits' width plus that constant, each a number or `{low, high}` for the two ends; `[mult: 0.05]` when not given.

    iex> plot =
    ...>   %{"x" => [1, 4, 9], "y" => [3, 1, 2]}
    ...>   |> Giggly.Plot.new(%{x: :x, y: :y})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_x_sqrt()
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:x)
    [1.0, 2.0, 3.0]

# `scale_x_time`

```elixir
@spec scale_x_time(t(), keyword()) :: t()
```

Gives the plot a time x scale with the given options, replacing any x scale it had.

A time axis places each `Time` at its seconds since midnight and marks it on round seconds,
minutes or hours, as suits its span, or every step of `date_breaks:`. Its labels give hours,
minutes and seconds (`10:30:00`), the hours counting on past midnight where the axis reaches
beyond it (`24:00:00`), or are written in the format `date_labels:` gives, wrapped round
midnight. A value outside the limits is missing, so its mark is not drawn, unless `oob:` says
otherwise. The scale's name
titles the axis whatever `labs/2` says. Raises `ArgumentError` for an option given beside its
`date_` twin, or a list of labels without a list of breaks as long; a column on the axis that is
not times is refused when the plot is run.

## Options

* `:name` - The axis's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the times of day the axis spans whatever the data, `nil` for an end the data decides; either order names the same axis. A value outside them is missing, so its mark is not drawn, unless `oob:` says otherwise.

* `:oob` - What happens to a value outside the limits: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. Run on the positions as given and again once the stat and position have moved them, so a bar whose base the limits leave out is missing; a value kept outside is drawn past the panel's edge and cut off there. `:censor` when not given.

* `:breaks` - The times of day the axis marks with a tick, a label and a grid line, a list; a function that returns them, or `{time, label}` pairs, handed the axis's extent, `{low, high}`, as times of day wrapped past midnight, and, taking two arguments, `[]`; or `:none` for none; chosen from the limits when neither this nor `date_breaks:` is given. A break is drawn wherever it falls inside the widened axis.

* `:date_breaks` - A break every step, `[minute: 30]`: one of `:second`, `:minute` and `:hour` and how many of it, laid from the widened axis's start, rounded down to a multiple of the step since midnight, to its end. Not with `breaks:`.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns, a pair's label when it returns pairs; a function handed every break drawn, a list of times of day, wrapped past midnight, so a break at the end of the day is `~T[00:00:00]`, that returns a label for each, a string, a power or `nil`; or `:none` for ticks with no labels. Not with `date_labels:`. When neither is given, each break is written in hours, minutes and seconds, with as many decimals of a second as the most precise needs, the hours counting on past midnight and a break before it negative (`10:30:00`, `24:00:00`, `-00:00:30`).

* `:date_labels` - The format every break's label is written in, as `Calendar.strftime/3` writes a time of day, such as `"%H:%M"`, a break past midnight wrapped round it, so the end of the day is written as its start. Not with `labels:`.

* `:minor_breaks` - The times of day the panel draws a minor grid line at, a list; a function that returns them, handed the axis's extent as `breaks:`'s is, and, taking two arguments, the breaks drawn; or `:none` for none; midway between the breaks when neither this nor `date_minor_breaks:` is given.

* `:date_minor_breaks` - A minor grid line every step, as `date_breaks:` lays breaks. Not with `minor_breaks:`.

* `:expand` - How far the axis reaches beyond its limits, `[mult: m, add: a]`: at each end, that multiple of the limits' width plus that constant, in seconds, each a number or `{low, high}` for the two ends; `[mult: 0.05]` when not given.

    iex> svg =
    ...>   %{"at" => [~T[06:10:00], ~T[21:40:00]], "load" => [0.3, 0.8]}
    ...>   |> Giggly.Plot.new(%{x: :at, y: :load})
    ...>   |> Giggly.Plot.geom_line()
    ...>   |> Giggly.Plot.scale_x_time()
    ...>   |> Giggly.to_svg()
    ...>   |> IO.iodata_to_binary()
    iex> {svg =~ ">06:00:00</text>", svg =~ ">22:00:00</text>"}
    {true, true}

A break every six hours of a whole day, its last at midnight again:

    iex> svg =
    ...>   %{"at" => [~T[00:00:00], ~T[23:59:59]], "load" => [0.3, 0.8]}
    ...>   |> Giggly.Plot.new(%{x: :at, y: :load})
    ...>   |> Giggly.Plot.geom_line()
    ...>   |> Giggly.Plot.scale_x_time(date_breaks: [hour: 6], date_labels: "%H:%M")
    ...>   |> Giggly.to_svg()
    ...>   |> IO.iodata_to_binary()
    iex> svg |> String.split(">00:00</text>") |> length()
    3

# `scale_y_continuous`

```elixir
@spec scale_y_continuous(t(), keyword()) :: t()
```

Gives the plot a continuous y scale with the given options, replacing any y scale it had, as
`scale_x_continuous/2` gives an x scale.

## Options

* `:name` - The axis's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the axis spans whatever the data, in data units, `nil` for an end the data decides; either order names the same axis. A value outside them is missing, so its mark is not drawn, unless `oob:` says otherwise.

* `:oob` - What happens to a value outside the limits: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. Run on the positions as given and again once the stat and position have moved them, so a bar whose base the limits leave out is missing; a value kept outside is drawn past the panel's edge and cut off there. `:censor` when not given.

* `:breaks` - The values the axis marks with a tick, a label and a grid line, a list of numbers in data units; a function that returns them, or `{break, label}` pairs, handed the axis's extent in data units, `{low, high}`, and, taking two arguments, `[n: n]` as `n_breaks:` asks, `[]` when not given, such as `&Scales.Breaks.extended/2`; or `:none` for none; chosen from the limits when not given. A break is drawn wherever it falls inside the widened axis.

* `:minor_breaks` - The values the panel draws a minor grid line at, a list of numbers in data units; a function that returns them, handed the axis's extent in data units, `{low, high}`, and, taking two arguments, the breaks drawn; or `:none` for none; midway between the breaks, once transformed, when not given.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted, of the breaks chosen when `breaks:` is not given, 2 or more but on a log axis, or of a `breaks:` function of two arguments; not beside `breaks:` a list, `:none` or a function of one argument, which wants no number.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break drawn, a list of numbers in data units, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do; or `:none` for ticks with no labels. A pair's label when a `breaks:` function returns pairs.

* `:expand` - How far the axis reaches beyond its limits, `[mult: m, add: a]`: at each end, that multiple of the limits' width plus that constant, each a number or `{low, high}` for the two ends; `[mult: 0.05]` when not given.

* `:transform` - What each value is put through before the scale sees it, a transformation of `Scales.Transform`'s: `:identity`, `:log`, `:log2`, `:log10`, `{:log, base}`, `:log1p`, `:exp`, `{:exp, base}`, `:asinh`, `:pseudo_log`, `{:pseudo_log, sigma: sigma, base: base}`, `:sqrt`, `:reverse`, `:reciprocal`, `:asn`, `:atanh`, `:logit`, `:probit`, `{:probability, :normal, mean: mean, sd: sd}`, `{:probability, :logistic, location: location, scale: scale}`, `{:boxcox, exponent}`, `{:boxcox, exponent, offset: offset}`, `{:modulus, exponent}`, `{:modulus, exponent, offset: offset}`, `{:yj, exponent}`, `:timespan`, `{:timespan, unit}`, a composition `{:compose, [part, ...]}` or one `Scales.Transform.new/2` makes; `:identity` when not given. The scale trains, breaks and places in transformed space, its limits and breaks given in data units, and labels its breaks in data units.

    iex> svg =
    ...>   %{"wt" => [2.62, 2.875], "mpg" => [21.0, 22.8]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_y_continuous(name: "Miles per gallon", breaks: [21, 22])
    ...>   |> Giggly.to_svg()
    ...>   |> IO.iodata_to_binary()
    iex> {svg =~ ">Miles per gallon</text>", svg =~ ">21</text>", svg =~ ">22</text>"}
    {true, true, true}

# `scale_y_date`

```elixir
@spec scale_y_date(t(), keyword()) :: t()
```

Gives the plot a date y scale with the given options, replacing any y scale it had, as
`scale_x_date/2` gives an x scale.

## Options

* `:name` - The axis's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the dates the axis spans whatever the data, `nil` for an end the data decides; either order names the same axis. A value outside them is missing, so its mark is not drawn, unless `oob:` says otherwise.

* `:oob` - What happens to a value outside the limits: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. Run on the positions as given and again once the stat and position have moved them, so a bar whose base the limits leave out is missing; a value kept outside is drawn past the panel's edge and cut off there. `:censor` when not given.

* `:breaks` - The dates the axis marks with a tick, a label and a grid line, a list; a function that returns them, or `{date, label}` pairs, handed the axis's extent, `{low, high}`, its ends rounded out to whole days, and, taking two arguments, `[]`, such as `&Scales.Breaks.pretty/2`; or `:none` for none; chosen from the limits when neither this nor `date_breaks:` is given. A break is drawn wherever it falls inside the widened axis.

* `:date_breaks` - A break every step, `[week: 1]`: one of `:day`, `:week`, `:month` and `:year` and how many of it, laid from the widened axis's start, rounded down to a multiple of the days since 1970-01-01, a Monday, the 1st of a month or 1 January, to its end. Not with `breaks:`.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break drawn, a list of dates, that returns a label for each, a string, a power or `nil`; or `:none` for ticks with no labels. Not with `date_labels:`. When neither is given, the breaks the axis chooses are written as suits their step (`Sep 21`, `2026`), a `breaks:` function's pairs by their labels, and others in full (`2026-09-21`).

* `:date_labels` - The format every break's label is written in, as `Calendar.strftime/3` takes it, such as `"%b %d"`. Not with `labels:`.

* `:minor_breaks` - The dates the panel draws a minor grid line at, a list; a function that returns them, handed the axis's extent as `breaks:`'s is, and, taking two arguments, the breaks drawn; or `:none` for none; midway between the breaks when neither this nor `date_minor_breaks:` is given.

* `:date_minor_breaks` - A minor grid line every step, as `date_breaks:` lays breaks. Not with `minor_breaks:`.

* `:expand` - How far the axis reaches beyond its limits, `[mult: m, add: a]`: at each end, that multiple of the limits' width plus that constant, each a number or `{low, high}` for the two ends; `[mult: 0.05]` when not given.

    iex> frame =
    ...>   %{"price" => [0.3, 0.8, 0.5], "day" => [~D[2026-09-20], ~D[2026-10-19], ~D[2026-10-01]]}
    ...>   |> Giggly.Plot.new(%{x: :price, y: :day})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_y_date(limits: {~D[2026-10-01], nil})
    ...>   |> Giggly.layer_data()
    iex> Giggly.DataFrame.pull(frame, :y)
    [nil, 20745.0, 20727.0]

# `scale_y_datetime`

```elixir
@spec scale_y_datetime(t(), keyword()) :: t()
```

Gives the plot a date-time y scale with the given options, replacing any y scale it had, as
`scale_x_datetime/2` gives an x scale.

## Options

* `:name` - The axis's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the date-times the axis spans whatever the data, `DateTime`s or `NaiveDateTime`s as its column holds, `nil` for an end the data decides; either order names the same axis. A value outside them is missing, so its mark is not drawn, unless `oob:` says otherwise.

* `:oob` - What happens to a value outside the limits: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. Run on the positions as given and again once the stat and position have moved them, so a bar whose base the limits leave out is missing; a value kept outside is drawn past the panel's edge and cut off there. `:censor` when not given.

* `:breaks` - The date-times the axis marks with a tick, a label and a grid line, a list; a function that returns them, or `{date_time, label}` pairs, handed the axis's extent, `{low, high}`, as the column holds date-times, and, taking two arguments, `[]`, such as `&Scales.Breaks.pretty/2`; or `:none` for none; chosen from the limits when neither this nor `date_breaks:` is given. A break is drawn wherever it falls inside the widened axis.

* `:date_breaks` - A break every step, `[hour: 6]`: one of `:second`, `:minute`, `:hour`, `:day`, `:week`, `:month` and `:year` and how many of it, laid from the widened axis's start, rounded to the nearest multiple of the step since 1970-01-01 for seconds and minutes, else down to the start of its hour, its day, the Monday of its week, the 1st of its month or 1 January, to its end. Not with `breaks:`.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break drawn, a list of date-times as the column holds them, that returns a label for each, a string, a power or `nil`; or `:none` for ticks with no labels. Not with `date_labels:`. When neither is given, the breaks the axis chooses are written as suits their step (`06:00`, `Mar 10 06:00`, `Mar 10`), a `breaks:` function's pairs by their labels, and others in full, the date alone where every one is a midnight (`2024-03-10`), else to the second (`2024-03-10 06:30:00`).

* `:date_labels` - The format every break's label is written in, as `Calendar.strftime/3` takes it, such as `"%H:%M"`. Not with `labels:`.

* `:minor_breaks` - The date-times the panel draws a minor grid line at, a list; a function that returns them, handed the axis's extent as `breaks:`'s is, and, taking two arguments, the breaks drawn; or `:none` for none; midway between the breaks when neither this nor `date_minor_breaks:` is given.

* `:date_minor_breaks` - A minor grid line every step, as `date_breaks:` lays breaks. Not with `minor_breaks:`.

* `:timezone` (`t:String.t/0`) - The time zone the axis lays its breaks and writes its labels in, such as `"America/New_York"`, which `time_zone_database:` must know; the first date-time column's when not given. Naive date-times are in no time zone, so a column of them is refused beside it.

* `:time_zone_database` (`t:atom/0`) - The time zone database that reads the axis's time zone, a module implementing `Calendar.TimeZoneDatabase`, such as the tz package's `Tz.TimeZoneDatabase`; `Calendar.UTCOnlyTimeZoneDatabase`, which knows UTC alone, when not given, never the one the application configures.

* `:expand` - How far the axis reaches beyond its limits, `[mult: m, add: a]`: at each end, that multiple of the limits' width plus that constant, in seconds, each a number or `{low, high}` for the two ends; `[mult: 0.05]` when not given.

    iex> frame =
    ...>   %{"load" => [0.3, 0.8], "at" => [~U[2024-03-10 00:00:00Z], ~U[2024-03-10 12:00:00Z]]}
    ...>   |> Giggly.Plot.new(%{x: :load, y: :at})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_y_datetime(limits: {~U[2024-03-10 06:00:00Z], nil})
    ...>   |> Giggly.layer_data()
    iex> Giggly.DataFrame.pull(frame, :y)
    [nil, 1710072000.0]

# `scale_y_discrete`

```elixir
@spec scale_y_discrete(t(), keyword()) :: t()
```

Gives the plot a discrete y scale with the given options, replacing any y scale it had, as
`scale_x_discrete/2` gives an x scale.

## Options

* `:name` - The axis's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - The values the axis shows, a list in the order shown, whatever the data; each value as the column holds it, `nil` for the missing value, a number naming the value equal to it. A value not among them is missing, so its mark is not drawn; one the data lacks leaves its place empty. Every value the data holds, in order, when not given.

* `:breaks` - The values the axis marks with a tick and a label, a list in the order given, those not among the limits left out; a function of one argument handed the limits that returns them, or `{value, label}` pairs; or `:none` for none; every one of the limits when not given.

* `:minor_breaks` - The positions the panel draws a minor grid line at, the values placed at 1, 2, 3 and on: a list of numbers; a function that returns them, handed the axis's extent, `{low, high}`, and, taking two arguments, the breaks' positions; or `:none` for none; none when not given.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each break, or for each limit when no breaks are given; a map from a value to its label, a value it does not hold keeping its own; a function handed every break drawn, a list of values, that returns a label for each, a string, a power or `nil`; or `:none` for ticks with no labels. A pair's label when a `breaks:` function returns pairs, else each value written as text, when not given.

* `:expand` - How far the axis reaches beyond its first and last values, `[mult: m, add: a]`: at each end, that multiple of the distance between them plus that constant, each a number or `{low, high}` for the two ends; `[add: 0.6]` when not given.

    iex> frame =
    ...>   %{"hwy" => [17, 29, 26], "class" => ["suv", "compact", "midsize"]}
    ...>   |> Giggly.Plot.new(%{x: :hwy, y: :class})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_y_discrete(limits: ["suv", "midsize", "compact"])
    ...>   |> Giggly.layer_data()
    iex> Giggly.DataFrame.pull(frame, :y)
    [1, 3, 2]

# `scale_y_log10`

```elixir
@spec scale_y_log10(t(), keyword()) :: t()
```

Gives the plot a continuous y scale through a base-10 logarithm, replacing any y scale it had,
as `scale_x_log10/2` gives an x scale.

## Options

* `:name` - The axis's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the axis spans whatever the data, in data units, `nil` for an end the data decides; either order names the same axis. A value outside them is missing, so its mark is not drawn, unless `oob:` says otherwise.

* `:oob` - What happens to a value outside the limits: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. Run on the positions as given and again once the stat and position have moved them, so a bar whose base the limits leave out is missing; a value kept outside is drawn past the panel's edge and cut off there. `:censor` when not given.

* `:breaks` - The values the axis marks with a tick, a label and a grid line, a list of numbers in data units; a function that returns them, or `{break, label}` pairs, handed the axis's extent in data units, `{low, high}`, and, taking two arguments, `[n: n]` as `n_breaks:` asks, `[]` when not given, such as `&Scales.Breaks.extended/2`; or `:none` for none; chosen from the limits when not given. A break is drawn wherever it falls inside the widened axis.

* `:minor_breaks` - The values the panel draws a minor grid line at, a list of numbers in data units; a function that returns them, handed the axis's extent in data units, `{low, high}`, and, taking two arguments, the breaks drawn; or `:none` for none; midway between the breaks, once transformed, when not given.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted, of the breaks chosen when `breaks:` is not given, 2 or more but on a log axis, or of a `breaks:` function of two arguments; not beside `breaks:` a list, `:none` or a function of one argument, which wants no number.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break drawn, a list of numbers in data units, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do; or `:none` for ticks with no labels. A pair's label when a `breaks:` function returns pairs.

* `:expand` - How far the axis reaches beyond its limits, `[mult: m, add: a]`: at each end, that multiple of the limits' width plus that constant, each a number or `{low, high}` for the two ends; `[mult: 0.05]` when not given.

    iex> plot =
    ...>   %{"x" => [3, 1, 2], "y" => [1, 10, 100]}
    ...>   |> Giggly.Plot.new(%{x: :x, y: :y})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_y_log10()
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:y)
    [0.0, 1.0, 2.0]

# `scale_y_reverse`

```elixir
@spec scale_y_reverse(t(), keyword()) :: t()
```

Gives the plot a continuous y scale running from high to low, replacing any y scale it had, as
`scale_x_reverse/2` gives an x scale.

## Options

* `:name` - The axis's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the axis spans whatever the data, in data units, `nil` for an end the data decides; either order names the same axis. A value outside them is missing, so its mark is not drawn, unless `oob:` says otherwise.

* `:oob` - What happens to a value outside the limits: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. Run on the positions as given and again once the stat and position have moved them, so a bar whose base the limits leave out is missing; a value kept outside is drawn past the panel's edge and cut off there. `:censor` when not given.

* `:breaks` - The values the axis marks with a tick, a label and a grid line, a list of numbers in data units; a function that returns them, or `{break, label}` pairs, handed the axis's extent in data units, `{low, high}`, and, taking two arguments, `[n: n]` as `n_breaks:` asks, `[]` when not given, such as `&Scales.Breaks.extended/2`; or `:none` for none; chosen from the limits when not given. A break is drawn wherever it falls inside the widened axis.

* `:minor_breaks` - The values the panel draws a minor grid line at, a list of numbers in data units; a function that returns them, handed the axis's extent in data units, `{low, high}`, and, taking two arguments, the breaks drawn; or `:none` for none; midway between the breaks, once transformed, when not given.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted, of the breaks chosen when `breaks:` is not given, 2 or more but on a log axis, or of a `breaks:` function of two arguments; not beside `breaks:` a list, `:none` or a function of one argument, which wants no number.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break drawn, a list of numbers in data units, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do; or `:none` for ticks with no labels. A pair's label when a `breaks:` function returns pairs.

* `:expand` - How far the axis reaches beyond its limits, `[mult: m, add: a]`: at each end, that multiple of the limits' width plus that constant, each a number or `{low, high}` for the two ends; `[mult: 0.05]` when not given.

    iex> plot =
    ...>   %{"x" => [3, 1, 2], "y" => [1.5, 2.5, 3.5]}
    ...>   |> Giggly.Plot.new(%{x: :x, y: :y})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_y_reverse()
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:y)
    [-1.5, -2.5, -3.5]

# `scale_y_sqrt`

```elixir
@spec scale_y_sqrt(t(), keyword()) :: t()
```

Gives the plot a continuous y scale through a square root, replacing any y scale it had, as
`scale_x_sqrt/2` gives an x scale.

## Options

* `:name` - The axis's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the values the axis spans whatever the data, in data units, `nil` for an end the data decides; either order names the same axis. A value outside them is missing, so its mark is not drawn, unless `oob:` says otherwise.

* `:oob` - What happens to a value outside the limits: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. Run on the positions as given and again once the stat and position have moved them, so a bar whose base the limits leave out is missing; a value kept outside is drawn past the panel's edge and cut off there. `:censor` when not given.

* `:breaks` - The values the axis marks with a tick, a label and a grid line, a list of numbers in data units; a function that returns them, or `{break, label}` pairs, handed the axis's extent in data units, `{low, high}`, and, taking two arguments, `[n: n]` as `n_breaks:` asks, `[]` when not given, such as `&Scales.Breaks.extended/2`; or `:none` for none; chosen from the limits when not given. A break is drawn wherever it falls inside the widened axis.

* `:minor_breaks` - The values the panel draws a minor grid line at, a list of numbers in data units; a function that returns them, handed the axis's extent in data units, `{low, high}`, and, taking two arguments, the breaks drawn; or `:none` for none; midway between the breaks, once transformed, when not given.

* `:n_breaks` (`t:pos_integer/0`) - How many breaks are wanted, of the breaks chosen when `breaks:` is not given, 2 or more but on a log axis, or of a `breaks:` function of two arguments; not beside `breaks:` a list, `:none` or a function of one argument, which wants no number.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns; a function handed every break drawn, a list of numbers in data units, that returns a label for each, a string, a power or `nil`, as `Scales.Labels`'s do; or `:none` for ticks with no labels. A pair's label when a `breaks:` function returns pairs.

* `:expand` - How far the axis reaches beyond its limits, `[mult: m, add: a]`: at each end, that multiple of the limits' width plus that constant, each a number or `{low, high}` for the two ends; `[mult: 0.05]` when not given.

    iex> plot =
    ...>   %{"x" => [3, 1, 2], "y" => [1, 4, 9]}
    ...>   |> Giggly.Plot.new(%{x: :x, y: :y})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_y_sqrt()
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:y)
    [1.0, 2.0, 3.0]

# `scale_y_time`

```elixir
@spec scale_y_time(t(), keyword()) :: t()
```

Gives the plot a time y scale with the given options, replacing any y scale it had, as
`scale_x_time/2` gives an x scale.

## Options

* `:name` - The axis's title, or `:none` for none; the title its mapping gives when not given.

* `:limits` - `{low, high}`: the times of day the axis spans whatever the data, `nil` for an end the data decides; either order names the same axis. A value outside them is missing, so its mark is not drawn, unless `oob:` says otherwise.

* `:oob` - What happens to a value outside the limits: `:censor`, a finite number outside made missing; `: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; or a function handed the values and the limits, `{low, high}`, both transformed, that returns a value for each, a number, an infinity, `nil` or `:nan`. Run on the positions as given and again once the stat and position have moved them, so a bar whose base the limits leave out is missing; a value kept outside is drawn past the panel's edge and cut off there. `:censor` when not given.

* `:breaks` - The times of day the axis marks with a tick, a label and a grid line, a list; a function that returns them, or `{time, label}` pairs, handed the axis's extent, `{low, high}`, as times of day wrapped past midnight, and, taking two arguments, `[]`; or `:none` for none; chosen from the limits when neither this nor `date_breaks:` is given. A break is drawn wherever it falls inside the widened axis.

* `:date_breaks` - A break every step, `[minute: 30]`: one of `:second`, `:minute` and `:hour` and how many of it, laid from the widened axis's start, rounded down to a multiple of the step since midnight, to its end. Not with `breaks:`.

* `:labels` - The breaks' labels: a list of strings, `nil` drawn `NA`, one for each of `breaks:`, or of the breaks its function returns, a pair's label when it returns pairs; a function handed every break drawn, a list of times of day, wrapped past midnight, so a break at the end of the day is `~T[00:00:00]`, that returns a label for each, a string, a power or `nil`; or `:none` for ticks with no labels. Not with `date_labels:`. When neither is given, each break is written in hours, minutes and seconds, with as many decimals of a second as the most precise needs, the hours counting on past midnight and a break before it negative (`10:30:00`, `24:00:00`, `-00:00:30`).

* `:date_labels` - The format every break's label is written in, as `Calendar.strftime/3` writes a time of day, such as `"%H:%M"`, a break past midnight wrapped round it, so the end of the day is written as its start. Not with `labels:`.

* `:minor_breaks` - The times of day the panel draws a minor grid line at, a list; a function that returns them, handed the axis's extent as `breaks:`'s is, and, taking two arguments, the breaks drawn; or `:none` for none; midway between the breaks when neither this nor `date_minor_breaks:` is given.

* `:date_minor_breaks` - A minor grid line every step, as `date_breaks:` lays breaks. Not with `minor_breaks:`.

* `:expand` - How far the axis reaches beyond its limits, `[mult: m, add: a]`: at each end, that multiple of the limits' width plus that constant, in seconds, each a number or `{low, high}` for the two ends; `[mult: 0.05]` when not given.

    iex> frame =
    ...>   %{"load" => [0.3, 0.8], "at" => [~T[05:00:00], ~T[12:00:00]]}
    ...>   |> Giggly.Plot.new(%{x: :load, y: :at})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.scale_y_time(limits: {~T[06:00:00], nil})
    ...>   |> Giggly.layer_data()
    iex> Giggly.DataFrame.pull(frame, :y)
    [nil, 43200.0]

# `stat_bin`

```elixir
@spec stat_bin(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds the layer `geom_histogram/3` adds, bars counting the rows in each bin, from the same mapping
and options.

    iex> plot =
    ...>   %{"x" => [1.0, 1.5, 2.5, 4.0]}
    ...>   |> Giggly.Plot.new(%{x: :x})
    ...>   |> Giggly.Plot.stat_bin(binwidth: 1, boundary: 0)
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:density)
    [0.5, 0.25, 0.25]

# `stat_bin_hex`

```elixir
@spec stat_bin_hex(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds the layer `geom_hex/3` adds, hexagons counting the rows in each, from the same mapping and
options.

    iex> frame =
    ...>   %{"x" => [0.0, 0.1, 1.0, 2.0], "y" => [0.0, 0.1, 1.0, 2.0]}
    ...>   |> Giggly.Plot.new(%{x: :x, y: :y})
    ...>   |> Giggly.Plot.stat_bin_hex(binwidth: 1)
    ...>   |> Giggly.layer_data()
    iex> Giggly.DataFrame.pull(frame, :density)
    [0.5, 0.25, 0.25]

# `stat_density`

```elixir
@spec stat_density(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer of densities, each the same estimate `geom_density/3` makes, drawn as areas
(`geom_area/3`): filled with the theme's ink mixed 20% toward its paper and unoutlined unless a
colour is mapped or set, and piled on one another unless `position: :identity` draws each where
it is. It takes `geom_density/3`'s options, and computes and refuses what it does.

## Options

* `:data` (`t:term/0`) - A table for the layer to draw instead of the plot's data, anything implementing `Table.Reader`. The plot's mapping applies to it, so it must hold each column the plot's mapping names for an aesthetic the layer neither maps nor sets. Under a facet, a table lacking a faceting column is drawn in every panel of that column's values.

* `:position` - Where the marks are moved once the stat has run: left at their positions (`:identity`), piled on one another (`:stack`), piled to the same height (`:fill`), set side by side within the width given, `{:dodge, width: width}`, or each taken as that wide and set side by side with the marks it overlaps, `{:dodge2, width: width}`, having no width of their own to share, each moved a small random distance (`:jitter`), set side by side and then each moved a small random distance (`:jitterdodge`), or nudged (`:nudge`), each alone or with its options, as [Positions](#module-positions) says. The default value is `:stack`.

* `:outline_type` - Which of each band's edges its outline draws: the upper and the lower, each a line (`:both`), the upper alone (`:upper`), the lower alone (`:lower`), or the band's whole border (`:full`). The default value is `:both`.

* `:bw` - How smooth each curve is, its bandwidth, the kernel's standard deviation in the axis's transformed units: a number above 0, or a rule worked out from each group's rows, taking no weight: Silverman's rule of thumb (`:nrd0`), 0.9 times the lesser of the rows' standard deviation and their interquartile range over 1.34, times the rows to the power -0.2, or Scott's variation of it (`:nrd`), 1.06 times the lesser. The default value is `:nrd0`.

* `:adjust` - A multiple of the bandwidth, above 0: `adjust: 0.5` halves it, for a curve that follows the rows more closely, and `adjust: 2` doubles it, for a smoother one. The default value is `1.0`.

* `:kernel` - The shape put at each row and summed, scaled so its standard deviation is the bandwidth: a normal curve (`:gaussian`), a parabola (`:epanechnikov`), a block (`:rectangular`), a tent (`:triangular`), a parabola squared (`:biweight`), or a cosine's hump (`:cosine`) or a narrower one (`:optcosine`). The default value is `:gaussian`.

* `:n` (`t:pos_integer/0`) - How many evenly spaced places each curve is worked out at, twice as many with one finite bound and three times with two. The default value is `512`.

* `:trim` (`t:boolean/0`) - Whether each curve spans only its own group's extent rather than the panel's axis, short of its widening; trimmed curves no longer share their places, so they do not stack. The default value is `false`.

* `:bounds` - Limits the rows are known to lie within, `{low, high}`, the low a number or `:neg_infinity`, the high a number or `:infinity`, not below the low: the rows outside them are left out, and each curve's part beyond a finite one is folded back inside it, so the curve does not spill past a limit the data cannot. The default value is `{:neg_infinity, :infinity}`.

* `:orientation` - The axis the layer runs along, `:x` or `:y`, which must be the one of `:x` and `:y` mapped; it runs along that one when this is not given.

* `:alpha` - How opaque every band's fill is, from 0, invisible, to 1, opaque; its outline keeps its colour's own alpha.

* `:color` - The colour of every band's outline, written `colour:` or `color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; no outline when not given.

* `:fill` - The colour every band is filled with: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; when not given, the theme's ink mixed 20% toward its paper, `#333333`, or `#000000CC` under `theme_void/2`, whose paper is clear.

* `:linewidth` - How wide every band's outline is, in millimetres; the theme's `base_line_size` when not given, 0.5 at its default sizes.

* `:linetype` - The line type of every band's outline: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; `:solid` when not given.

* `:lineend` - How a line's ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half the line's width beyond it (`:square`). The default value is `:butt`.

* `:linejoin` - How a line turns a corner: rounded (`:round`), pointed (`:mitre`) or cut off (`:bevel`); when not given, rounded, and pointed in a legend's keys.

* `:linemitre` - How far a pointed corner may reach, in widths of the line, before it is cut off; 1 or more. The default value is `10.0`.

* `:nudge_x` - How far every mark moves along x from its place, in the units of the x axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

* `:nudge_y` - How far every mark moves along y from its place, in the units of the y axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

    iex> frame =
    ...>   %{"x" => [1.0, 2.0, 4.0, 4.0]}
    ...>   |> Giggly.Plot.new(%{x: :x})
    ...>   |> Giggly.Plot.stat_density(n: 2)
    ...>   |> Giggly.layer_data()
    iex> Giggly.DataFrame.pull(frame, :x)
    [1.0, 4.0]

# `stat_smooth`

```elixir
@spec stat_smooth(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer of smooths, as `geom_smooth/3` does: the same curves, options and refusals.

## Options

* `:data` (`t:term/0`) - A table for the layer to draw instead of the plot's data, anything implementing `Table.Reader`. The plot's mapping applies to it, so it must hold each column the plot's mapping names for an aesthetic the layer neither maps nor sets. Under a facet, a table lacking a faceting column is drawn in every panel of that column's values.

* `:position` - Where the marks are moved once the stat has run: left at their positions (`:identity`), piled on one another (`:stack`), piled to the same height (`:fill`), set side by side within the width given, `{:dodge, width: width}`, or each taken as that wide and set side by side with the marks it overlaps, `{:dodge2, width: width}`, having no width of their own to share, each moved a small random distance (`:jitter`), set side by side and then each moved a small random distance (`:jitterdodge`), or nudged (`:nudge`), each alone or with its options, as [Positions](#module-positions) says. The default value is `:identity`.

* `:method` - How each curve is fitted: `:lm`, a straight line by least squares; `:loess`, at each place a quadratic fitted to the nearest rows, nearer ones weighing more; or `:gam`, a smoothing spline, its wiggliness chosen from the rows; each row weighted too by its `:weight` where one is mapped. When not given, loess where the largest group in any panel holds under 1,000 rows, and gam from there.

* `:se` (`t:boolean/0`) - Whether each curve is drawn over its band, the confidence interval around it at `level:`. The default value is `true`.

* `:level` - How confident each band is, above 0 and below 1. The default value is `0.95`.

* `:n` (`t:pos_integer/0`) - How many evenly spaced places along x each curve is worked out at. The default value is `80`.

* `:span` - How much of a group each loess fit reads, above 0: the share of its rows nearest each place, so a smaller span follows the rows more closely; only loess reads it. The default value is `0.75`.

* `:fullrange` (`t:boolean/0`) - Whether each curve spans the panel's axis it runs along, short of its widening, rather than its own group's extent along it. The default value is `false`.

* `:orientation` - The axis each curve runs along: `:x`, y fitted to x, or `:y`, x fitted to y, for a curve that runs up the panel. The default value is `:x`.

* `:alpha` - How opaque every band's fill is, from 0, invisible, to 1, opaque; 0.4 when not given. The line keeps its colour's own alpha.

* `:color` - The colour of every curve's line, written `colour:` or `color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; the theme's accent, `#3366FF`, when not given.

* `:fill` - The colour every band is filled with: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; when not given, the theme's ink mixed 60% toward its paper, `#999999`, or `#00000066` under `theme_void/2`, whose paper is clear.

* `:linewidth` - How wide every curve's line is, in millimetres; twice the theme's `base_line_size` when not given, 1 at its default sizes.

* `:linetype` - The line type of every line: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; `:solid` when not given.

* `:lineend` - How a line's ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half the line's width beyond it (`:square`). The default value is `:butt`.

* `:linejoin` - How a line turns a corner: rounded (`:round`), pointed (`:mitre`) or cut off (`:bevel`). The default value is `:round`.

* `:linemitre` - How far a pointed corner may reach, in widths of the line, before it is cut off; 1 or more. The default value is `10.0`.

* `:nudge_x` - How far every mark moves along x from its place, in the units of the x axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

* `:nudge_y` - How far every mark moves along y from its place, in the units of the y axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

    iex> frame =
    ...>   %{"x" => [1.0, 2.0, 3.0, 4.0], "y" => [1.0, 3.0, 2.0, 4.0]}
    ...>   |> Giggly.Plot.new(%{x: :x, y: :y})
    ...>   |> Giggly.Plot.stat_smooth(method: :lm, n: 2)
    ...>   |> Giggly.layer_data()
    iex> Giggly.DataFrame.pull(frame, :y)
    [1.2999999999999998, 3.7]

# `stat_sum`

```elixir
@spec stat_sum(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds the layer `geom_count/3` adds, points counting the rows at each place, from the same
mapping and options.

    iex> plot =
    ...>   %{"cty" => [18, 18, 21], "hwy" => [29, 29, 29]}
    ...>   |> Giggly.Plot.new(%{x: :cty, y: :hwy})
    ...>   |> Giggly.Plot.stat_sum()
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:prop)
    [0.6666666666666666, 0.3333333333333333]

# `stat_summary`

```elixir
@spec stat_summary(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer summarising the `y` values at each `x`: for each group, a row at each of its `x`
positions, its `y` a summary of the values there and its `ymin` and `ymax` an interval round
it, drawn as point ranges unless `geom:` says otherwise. Given no summary, it is the mean less
and plus one standard error, which a position holding one value has no interval for. A row
missing its `x` or `y`, or at an infinite one, is left out.

`fun_data:` gives the whole summary by name, alone or in a tuple with its arguments; `fun:`,
`fun_min:` and `fun_max:` give its `y`, `ymin` and `ymax` one at a time, by name or as a
function of the values, and one not given is missing, so `fun: :mean` alone draws points with no
ranges. A bootstrap's resamples are drawn from its `seed:`, each position's afresh, so a plot
draws the same intervals every time it is drawn, and another seed draws others.

Where `y` alone is discrete, the `x` values are summarised at each `y` instead, into `x`,
`xmin` and `xmax`, and the marks run across the panel; `orientation:` says which way.

A summary uses `:x`, `:y` and `:group` and the aesthetics its geom draws with, and needs `:x` and
`:y`; it writes the range, so `:ymin`, `:ymax`, `:xmin` and `:xmax` are not mapped. Every other
aesthetic goes to the summary at each position where it holds one value among that position's
rows, and is missing where it holds more, so a discrete one groups the rows and gives each
group its own summaries.

## Options

* `:data` (`t:term/0`) - A table for the layer to draw instead of the plot's data, anything implementing `Table.Reader`. The plot's mapping applies to it, so it must hold each column the plot's mapping names for an aesthetic the layer neither maps nor sets. Under a facet, a table lacking a faceting column is drawn in every panel of that column's values.

* `:geom` - What each summary is drawn as: a point range (`:pointrange`), a point (`:point`), a line through each group's (`:line`), a bar from 0 (`:bar`), a crossbar (`:crossbar`), an error bar (`:errorbar`), a line range (`:linerange`), or a band through each group's ranges (`:ribbon`). The other options are those the geom's own function takes, but its `orientation:`, which is the summary's. The default value is `:pointrange`.

* `:fun_data` - The whole summary at each position, its `y`, `ymin` and `ymax`, by name, alone or in a tuple with its arguments, `{:mean_sdl, mult: 1}`: `:mean_se`, the mean less and plus `mult:` standard errors (1); `:mean_cl_normal`, the mean and its confidence interval at `conf_int:` (0.95, from 0, below 1) from the t distribution, or `mult:` standard errors in place of the t; `:mean_sdl`, the mean less and plus `mult:` standard deviations (2); `:median_hilow`, the median and the quantiles holding `conf_int:` (0.95, 0 to 1) of the values between them, as many either side; and `:mean_cl_boot`, the mean and its bootstrap interval at `conf_int:` (0.95, 0 to 1), from `resamples:` (1000) resamples drawn from `seed:` (0), any integer. A `mult:` is any number. Refused beside `fun:`, `fun_min:` or `fun_max:`; `:mean_se` when none of them is given.

* `:fun` - The summary's `y` at each position: `:mean`, `:median`, `:min` or `:max`, or a function given the values there, a list of numbers in their rows' order, returning a number. Missing when not given beside `fun_min:` or `fun_max:`.

* `:fun_min` - The summary's `ymin` at each position, as `fun:` gives its `y`.

* `:fun_max` - The summary's `ymax` at each position, as `fun:` gives its `y`.

* `:orientation` - Which way the summary runs: `:x`, the `y` values summarised at each `x`, or `:y`, the `x` values at each `y`; when not given, `:y` where `y` alone is discrete, and `:x` otherwise.

Each geom takes the options of its own function but `orientation:`: `:pointrange` those of
`geom_pointrange/3`, `:point` of `geom_point/3`, `:line` of `geom_line/3`, `:bar` of
`geom_col/3`, `:crossbar` of `geom_crossbar/3`, `:errorbar` of `geom_errorbar/3`, `:linerange`
of `geom_linerange/3` and `:ribbon` of `geom_ribbon/3`. Its `position:` is `:identity` unless
given, the bars' included.

Raises `ArgumentError` for a geom it does not draw with, and for `fun_data:` beside `fun:`,
`fun_min:` or `fun_max:`; `NimbleOptions.ValidationError` for an option the geom does not take,
or a value it cannot use.

    iex> frame =
    ...>   %{"cyl" => [4, 4, 6, 6], "mpg" => [22.0, 26.0, 18.0, 20.0]}
    ...>   |> Giggly.Plot.new(%{x: :cyl, y: :mpg})
    ...>   |> Giggly.Plot.stat_summary()
    ...>   |> Giggly.layer_data()
    iex> {Giggly.DataFrame.pull(frame, :y), Giggly.DataFrame.pull(frame, :ymin)}
    {[24.0, 19.0], [22.0, 18.0]}

# `stat_ydensity`

```elixir
@spec stat_ydensity(t(), mapping_argument() | keyword(), keyword()) :: t()
```

Adds a layer of violins, the same layer `geom_violin/3` adds: each group's densities along `y`,
drawn as a violin. It takes `geom_violin/3`'s options, and computes and refuses what it does.

## Options

* `:data` (`t:term/0`) - A table for the layer to draw instead of the plot's data, anything implementing `Table.Reader`. The plot's mapping applies to it, so it must hold each column the plot's mapping names for an aesthetic the layer neither maps nor sets. Under a facet, a table lacking a faceting column is drawn in every panel of that column's values.

* `:position` - Where the marks are moved once the stat has run: left at their positions (`:identity`), piled on one another (`:stack`), piled to the same height (`:fill`), set side by side within the width one mark takes or the width given (`:dodge`), set side by side, each its share of their widths, with a gap between them (`:dodge2`), each moved a small random distance (`:jitter`), set side by side and then each moved a small random distance (`:jitterdodge`), or nudged (`:nudge`), each alone or with its options, as [Positions](#module-positions) says. The default value is `:dodge`.

* `:bw` - How smooth each curve is, its bandwidth, the kernel's standard deviation in the axis's transformed units: a number above 0, or a rule worked out from each group's rows, taking no weight: Silverman's rule of thumb (`:nrd0`), 0.9 times the lesser of the rows' standard deviation and their interquartile range over 1.34, times the rows to the power -0.2, or Scott's variation of it (`:nrd`), 1.06 times the lesser. The default value is `:nrd0`.

* `:adjust` - A multiple of the bandwidth, above 0: `adjust: 0.5` halves it, for a curve that follows the rows more closely, and `adjust: 2` doubles it, for a smoother one. The default value is `1.0`.

* `:kernel` - The shape put at each row and summed, scaled so its standard deviation is the bandwidth: a normal curve (`:gaussian`), a parabola (`:epanechnikov`), a block (`:rectangular`), a tent (`:triangular`), a parabola squared (`:biweight`), or a cosine's hump (`:cosine`) or a narrower one (`:optcosine`). The default value is `:gaussian`.

* `:trim` (`t:boolean/0`) - Whether each violin spans only its own group's extent; `false` reaches three of the rule's bandwidths, before `adjust:`, past it either end, so its tails show. The default value is `true`.

* `:bounds` - Limits the rows are known to lie within, `{low, high}`, the low a number or `:neg_infinity`, the high a number or `:infinity`, not below the low: the rows outside them are left out, and each curve's part beyond a finite one is folded back inside it, so the curve does not spill past a limit the data cannot. The default value is `{:neg_infinity, :infinity}`.

* `:scale` - How the violins are sized beside one another: each the same area (`:area`), as wide as its density makes it beside the panel's greatest; that times its rows over the panel's most, so a violin of more rows is bigger (`:count`); or each as wide at its widest (`:width`). The default value is `:area`.

* `:quantiles` - The quantiles of each group's `y` the densities mark, each a row of its own whose `quantile` is its probability, a list of numbers from 0 to 1, or `:none` for no `quantile` column at all. The default value is `[0.25, 0.5, 0.75]`.

* `:drop` (`t:boolean/0`) - Whether to leave out a group of fewer than two rows, or, `false`, keep it as one row of missing densities, so a position makes room for it. The default value is `true`.

* `:width` - How wide a violin's room is, in the units of the axis it stands on, any number; it replaces a mapped `:width`, and gives way to 0.9 of the range of a group spanning several positions. 0.9 times the closest spacing of the positions, counting from zero, when not given.

* `:orientation` - The axis the violins stand along, `:x` or `:y`, estimating the other; when not given they stand along the discrete one, or else along the axis on which every group holds one value, or else along x.

* `:alpha` - How opaque every violin's fill and quantile lines are, from 0, invisible, to 1, opaque; its border keeps its colour's own alpha.

* `:color` - The colour of every violin's border, written `colour:` or `color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; when not given, the theme's ink mixed 20% toward its paper, `#333333`, or `#000000CC` under `theme_void/2`.

* `:fill` - The colour every violin is filled with: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; the theme's paper when not given, white, or clear under `theme_void/2`.

* `:linewidth` - How wide every violin's border is, in millimetres; the theme's `base_line_size` when not given, 0.5 at its default sizes.

* `:linetype` - The line type of every violin's border: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; `:solid` when not given.

* `:quantile_color` - The colour of the lines across each violin at the quantiles its densities mark, written `quantile_colour:` or `quantile_color:`: a CSS colour name, such as `"steelblue"`, a hex colour, such as `"#4682B4"`, or `"#4682B480"` with an alpha of its own, `"transparent"`, or `:none` for none; its violin's border colour when not given.

* `:quantile_linetype` - The line type of the lines across each violin at the quantiles its densities mark (`quantiles:`): `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`; `:blank`, drawing none, when not given. The default value is `:blank`.

* `:quantile_linewidth` - How wide the quantile lines are, in millimetres; their violin's border width when not given.

* `:lineend` - How the borders of the legend's keys end: cut square at the end (`:butt`), rounded (`:round`), or cut square half the line's width beyond it (`:square`); the violins' own borders are always cut square at the end. The default value is `:butt`.

* `:linejoin` - How the borders of the legend's keys turn a corner: pointed (`:mitre`), rounded (`:round`) or cut off (`:bevel`); the violins' own borders always turn rounded. The default value is `:mitre`.

* `:nudge_x` - How far every mark moves along x from its place, in the units of the x axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

* `:nudge_y` - How far every mark moves along y from its place, in the units of the y axis, beside `position: :nudge`, which reads it, and refused beside another position; 0 when not given.

    iex> frame =
    ...>   %{"g" => ["a", "a", "a"], "y" => [1.0, 2.0, 4.0]}
    ...>   |> Giggly.Plot.new(%{x: :g, y: :y})
    ...>   |> Giggly.Plot.stat_ydensity(quantiles: :none)
    ...>   |> Giggly.layer_data()
    iex> {Giggly.DataFrame.row_count(frame), Enum.at(Giggly.DataFrame.pull(frame, :y), 0)}
    {512, 1.0}

# `theme`

```elixir
@spec theme(t(), keyword()) :: t()
```

Changes the look everything but the marks is drawn in: its backgrounds, grid lines, axes,
strips, legends and titles, each an element of the theme, set by name.

The theme is a tree of elements, each inheriting what it leaves unset from its parent: every
text inherits from `:text`, every line from `:line` and every rectangle from `:rect`, so
`text: [size: 14]` makes every label bigger, and the x axis's tick labels below the panels,
`:axis_text_x_bottom`, inherit from `:axis_text_x`, which inherits from `:axis_text`. A line,
a rectangle or a text is a keyword list of the properties it sets; a size or a line width may be
`{:rel, share}`, a share of its parent's. A setting replaces only the properties it gives, so
`theme(axis_text: [color: "red"])` keeps the labels' size, and a later call's properties replace
an earlier one's. A colour may have an alpha of its own (`"#FF000080"`, `"transparent"`), drawn
at that opacity.

The settings are laid over the plot's complete theme, the default unless `theme_gray/2`,
`theme_bw/2` or another chose one. After a chosen theme each call is laid over it in turn, so
an element set after a call removed it replaces the theme's element whole, inheriting what it
leaves unset from its parent; a plot that chose none merges its calls first and lays them over
the default at once, so there the element keeps the default's own properties.

A line's `linetype:` and `lineend:` and a rectangle's `linetype:`, its border's, take what a
layer's take: a line of the blank line type draws nothing but keeps its room, as an axis's
ticks do, and a border of it is no border. A rectangle's `fill: :none` leaves it unfilled. The
axes' lines (`:axis_line`) and the panels' border (`:panel_border`), drawn over the layers and
never filled, are removed until a setting gives them, and `panel_ontop: true` draws the panels'
backgrounds and grid lines over the layers, under the border.

A text's `face:` makes it bold or italic, `angle:` turns it, and `hjust:` and `vjust:` place it
in its room: the room is as deep as the turned text, so `axis_text_x: [angle: 45, hjust: 1]`
turns the x axis's labels to end at their ticks and deepens the axis to fit them, and
`plot_title: [hjust: 0.5]` centres the title over the panels. The justification is the text's
own, along and across it once turned: the y axis's title is turned 90 degrees, so its `vjust:
1` puts its top toward the left. A legend's labels sit right of their keys, left-aligned and
centred on them, and its title is left-aligned, unless `:legend_text` or `:legend_title` says
otherwise; `:text`'s justification never reaches them. `lineheight:` spaces a text's lines,
a tick label's and a legend's as a title's.
`family:` names the font a text is drawn in, inherited as any property is: `title: [family:
"mono"]` reaches the axes' titles, the legends' titles and the plot's title, and `text:
[family: "serif"]` every text but a layer's, which takes the complete theme's `base_family`.
How a family is measured and drawn, with Pica or without it: the [fonts guide](fonts.md).

A length is a number of ggplot2's points (1/72.27 inch), `{amount, unit}` in `:pt`, `:cm`,
`:mm`, `:in` or `:lines`, a line of text, or `{:rel, share}`, a share of its parent's. A margin
is one length for every side, a keyword list of `:top`, `:right`, `:bottom` and `:left`, a side
left out 0, or `{:rel, share}`. `:spacing` and `:margins`, which inherit from nothing, take no
share.

A line, a rectangle or a text set to `:none` is removed: it draws nothing and takes no room, and
the elements that inherit from it go with it, so `axis_text: :none` removes every axis's tick
labels and the room they took. An element a setting gives is drawn all the same, inheriting from
the nearest element above it that is not removed, so `theme(axis_text: :none, axis_text_x:
[color: "red"])` keeps the x axis's labels, red and at the size of `:text`; a later setting of a
removed element replaces the removal. Under a removed `:line`, `:rect` or `:text`, a property
nothing above an element gives is drawn at the drawing's own default: black, filled white, a
solid line 0.75 points wide with round ends, text 12 points with its lines 1.2 sizes apart, and no
margin.

The legends go right of the panels unless `legend_position:` puts them left of the panels
(`:left`), above (`:top`) or below (`:bottom`), inside them (`:inside`), or nowhere (`:none`).
Beside the panels they are stacked in a box the theme's spacing from them, one above another on
the left and right and side by side above and below, their keys running down and across; a box
above or below the panels sits below the plot's title and above its caption, and one on the left
outside the y axis's title. `legend_direction:` runs every legend's keys one way, and
`legend_box:` arranges the legends one way, wherever they go. Which point of the box is placed
at the same point of the room beside the panels is its justification, `:center` unless
`legend_justification:` or the side's own (`legend_justification_right:` and the rest) says
otherwise: `:top` hangs a box right of the panels from their top. The room beside the panels is
as long as the panels, or as the whole plot with `legend_location: :plot`. Inside the panels,
the box's justification is placed at `legend_position_inside:`, `{x, y}` as shares of the panels'
width and height, or at the same point of the panels when none is given, so `legend_position:
:inside, legend_justification_inside: {1, 0}` puts the box in the panels' bottom right corner.
`legend_box_just:` places each legend in the box, `legend_box_margin:` spaces them from its
edge, and `legend_box_background:` draws its background, which no complete theme draws, as its
setting gives it, taking nothing from `:rect`: `legend_box_background: []` is white with a black
border 0.75 points wide.

Raises `NimbleOptions.ValidationError` for an element it does not know or a value it cannot use,
and `ArgumentError` for an element or a property given twice.

## Options

* `:line` (`t:keyword/0`) - Every line.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

  * `:lineend` - How its ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half its width beyond it (`:square`).

* `:rect` (`t:keyword/0`) - Every rectangle: backgrounds and borders.

  * `:fill` - Its fill, a CSS colour, which may have an alpha of its own, or `:none` for none.

  * `:color` - Its border's colour, a CSS colour, which may have an alpha of its own, or `:none` for no border (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

* `:text` (`t:keyword/0`) - Every text.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:size` - How big it is, in points, or `{:rel, share}`, a share of its parent's size.

  * `:family` (`t:String.t/0`) - The font it is drawn in, by name, such as `"Lobster"`, or one of the generic families `"sans"`, `"serif"` and `"mono"`; `""` is the default sans-serif. How it is measured and drawn: the [fonts guide](fonts.md).

  * `:face` - Its face: `:plain`, `:bold`, `:italic` or `:bold_italic`.

  * `:angle` - How far it is turned, in degrees anticlockwise, any number.

  * `:hjust` - Where it sits across, any number: 0 at its left, 0.5 centred, 1 at its right, in its own turned frame.

  * `:vjust` - Where it sits up, any number: 0 at its bottom, 0.5 centred, 1 at its top, in its own turned frame.

  * `:lineheight` - How far apart its lines are, 0 or more, a share of 1.2 times its size: a text's lines are 0.9 apart unless given.

  * `:margin` - The space on each side of it: one length for every side, or a keyword list of `:top`, `:right`, `:bottom` and `:left`, a side left out 0.

* `:title` (`t:keyword/0`) - Every title: the axes', the legends' and the plot's. Inherits from `:text`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:size` - How big it is, in points, or `{:rel, share}`, a share of its parent's size.

  * `:family` (`t:String.t/0`) - The font it is drawn in, by name, such as `"Lobster"`, or one of the generic families `"sans"`, `"serif"` and `"mono"`; `""` is the default sans-serif. How it is measured and drawn: the [fonts guide](fonts.md).

  * `:face` - Its face: `:plain`, `:bold`, `:italic` or `:bold_italic`.

  * `:angle` - How far it is turned, in degrees anticlockwise, any number.

  * `:hjust` - Where it sits across, any number: 0 at its left, 0.5 centred, 1 at its right, in its own turned frame.

  * `:vjust` - Where it sits up, any number: 0 at its bottom, 0.5 centred, 1 at its top, in its own turned frame.

  * `:lineheight` - How far apart its lines are, 0 or more, a share of 1.2 times its size: a text's lines are 0.9 apart unless given.

  * `:margin` - The space on each side of it: one length for every side, or a keyword list of `:top`, `:right`, `:bottom` and `:left`, a side left out 0.

* `:spacing` - Every spacing between parts of the plot.

* `:margins` - Every margin inside a part of the plot.

* `:axis_line` (`t:keyword/0`) - The axes' lines, along the panels' edges. Inherits from `:line`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

  * `:lineend` - How its ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half its width beyond it (`:square`).

* `:axis_text` (`t:keyword/0`) - The axes' tick labels. Inherits from `:text`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:size` - How big it is, in points, or `{:rel, share}`, a share of its parent's size.

  * `:family` (`t:String.t/0`) - The font it is drawn in, by name, such as `"Lobster"`, or one of the generic families `"sans"`, `"serif"` and `"mono"`; `""` is the default sans-serif. How it is measured and drawn: the [fonts guide](fonts.md).

  * `:face` - Its face: `:plain`, `:bold`, `:italic` or `:bold_italic`.

  * `:angle` - How far it is turned, in degrees anticlockwise, any number.

  * `:hjust` - Where it sits across, any number: 0 at its left, 0.5 centred, 1 at its right, in its own turned frame.

  * `:vjust` - Where it sits up, any number: 0 at its bottom, 0.5 centred, 1 at its top, in its own turned frame.

  * `:lineheight` - How far apart its lines are, 0 or more, a share of 1.2 times its size: a text's lines are 0.9 apart unless given.

  * `:margin` - The space on each side of it: one length for every side, or a keyword list of `:top`, `:right`, `:bottom` and `:left`, a side left out 0.

* `:axis_ticks` (`t:keyword/0`) - The axes' ticks. Inherits from `:line`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

  * `:lineend` - How its ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half its width beyond it (`:square`).

* `:axis_title` (`t:keyword/0`) - The axes' titles. Inherits from `:title`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:size` - How big it is, in points, or `{:rel, share}`, a share of its parent's size.

  * `:family` (`t:String.t/0`) - The font it is drawn in, by name, such as `"Lobster"`, or one of the generic families `"sans"`, `"serif"` and `"mono"`; `""` is the default sans-serif. How it is measured and drawn: the [fonts guide](fonts.md).

  * `:face` - Its face: `:plain`, `:bold`, `:italic` or `:bold_italic`.

  * `:angle` - How far it is turned, in degrees anticlockwise, any number.

  * `:hjust` - Where it sits across, any number: 0 at its left, 0.5 centred, 1 at its right, in its own turned frame.

  * `:vjust` - Where it sits up, any number: 0 at its bottom, 0.5 centred, 1 at its top, in its own turned frame.

  * `:lineheight` - How far apart its lines are, 0 or more, a share of 1.2 times its size: a text's lines are 0.9 apart unless given.

  * `:margin` - The space on each side of it: one length for every side, or a keyword list of `:top`, `:right`, `:bottom` and `:left`, a side left out 0.

* `:axis_line_x` (`t:keyword/0`) - The x axis's line. Inherits from `:axis_line`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

  * `:lineend` - How its ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half its width beyond it (`:square`).

* `:axis_line_x_bottom` (`t:keyword/0`) - The line of the x axis below the panels. Inherits from `:axis_line_x`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

  * `:lineend` - How its ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half its width beyond it (`:square`).

* `:axis_line_y` (`t:keyword/0`) - The y axis's line. Inherits from `:axis_line`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

  * `:lineend` - How its ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half its width beyond it (`:square`).

* `:axis_line_y_left` (`t:keyword/0`) - The line of the y axis left of the panels. Inherits from `:axis_line_y`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

  * `:lineend` - How its ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half its width beyond it (`:square`).

* `:axis_line_theta` (`t:keyword/0`) - The line round a radial panel's circle. Inherits from `:axis_line_x`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

  * `:lineend` - How its ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half its width beyond it (`:square`).

* `:axis_line_r` (`t:keyword/0`) - The line of a radial panel's radius axis. Inherits from `:axis_line_y`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

  * `:lineend` - How its ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half its width beyond it (`:square`).

* `:axis_text_x` (`t:keyword/0`) - The x axis's tick labels. Inherits from `:axis_text`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:size` - How big it is, in points, or `{:rel, share}`, a share of its parent's size.

  * `:family` (`t:String.t/0`) - The font it is drawn in, by name, such as `"Lobster"`, or one of the generic families `"sans"`, `"serif"` and `"mono"`; `""` is the default sans-serif. How it is measured and drawn: the [fonts guide](fonts.md).

  * `:face` - Its face: `:plain`, `:bold`, `:italic` or `:bold_italic`.

  * `:angle` - How far it is turned, in degrees anticlockwise, any number.

  * `:hjust` - Where it sits across, any number: 0 at its left, 0.5 centred, 1 at its right, in its own turned frame.

  * `:vjust` - Where it sits up, any number: 0 at its bottom, 0.5 centred, 1 at its top, in its own turned frame.

  * `:lineheight` - How far apart its lines are, 0 or more, a share of 1.2 times its size: a text's lines are 0.9 apart unless given.

  * `:margin` - The space on each side of it: one length for every side, or a keyword list of `:top`, `:right`, `:bottom` and `:left`, a side left out 0.

* `:axis_text_x_bottom` (`t:keyword/0`) - The tick labels of the x axis below the panels. Inherits from `:axis_text_x`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:size` - How big it is, in points, or `{:rel, share}`, a share of its parent's size.

  * `:family` (`t:String.t/0`) - The font it is drawn in, by name, such as `"Lobster"`, or one of the generic families `"sans"`, `"serif"` and `"mono"`; `""` is the default sans-serif. How it is measured and drawn: the [fonts guide](fonts.md).

  * `:face` - Its face: `:plain`, `:bold`, `:italic` or `:bold_italic`.

  * `:angle` - How far it is turned, in degrees anticlockwise, any number.

  * `:hjust` - Where it sits across, any number: 0 at its left, 0.5 centred, 1 at its right, in its own turned frame.

  * `:vjust` - Where it sits up, any number: 0 at its bottom, 0.5 centred, 1 at its top, in its own turned frame.

  * `:lineheight` - How far apart its lines are, 0 or more, a share of 1.2 times its size: a text's lines are 0.9 apart unless given.

  * `:margin` - The space on each side of it: one length for every side, or a keyword list of `:top`, `:right`, `:bottom` and `:left`, a side left out 0.

* `:axis_text_y` (`t:keyword/0`) - The y axis's tick labels. Inherits from `:axis_text`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:size` - How big it is, in points, or `{:rel, share}`, a share of its parent's size.

  * `:family` (`t:String.t/0`) - The font it is drawn in, by name, such as `"Lobster"`, or one of the generic families `"sans"`, `"serif"` and `"mono"`; `""` is the default sans-serif. How it is measured and drawn: the [fonts guide](fonts.md).

  * `:face` - Its face: `:plain`, `:bold`, `:italic` or `:bold_italic`.

  * `:angle` - How far it is turned, in degrees anticlockwise, any number.

  * `:hjust` - Where it sits across, any number: 0 at its left, 0.5 centred, 1 at its right, in its own turned frame.

  * `:vjust` - Where it sits up, any number: 0 at its bottom, 0.5 centred, 1 at its top, in its own turned frame.

  * `:lineheight` - How far apart its lines are, 0 or more, a share of 1.2 times its size: a text's lines are 0.9 apart unless given.

  * `:margin` - The space on each side of it: one length for every side, or a keyword list of `:top`, `:right`, `:bottom` and `:left`, a side left out 0.

* `:axis_text_y_left` (`t:keyword/0`) - The tick labels of the y axis left of the panels. Inherits from `:axis_text_y`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:size` - How big it is, in points, or `{:rel, share}`, a share of its parent's size.

  * `:family` (`t:String.t/0`) - The font it is drawn in, by name, such as `"Lobster"`, or one of the generic families `"sans"`, `"serif"` and `"mono"`; `""` is the default sans-serif. How it is measured and drawn: the [fonts guide](fonts.md).

  * `:face` - Its face: `:plain`, `:bold`, `:italic` or `:bold_italic`.

  * `:angle` - How far it is turned, in degrees anticlockwise, any number.

  * `:hjust` - Where it sits across, any number: 0 at its left, 0.5 centred, 1 at its right, in its own turned frame.

  * `:vjust` - Where it sits up, any number: 0 at its bottom, 0.5 centred, 1 at its top, in its own turned frame.

  * `:lineheight` - How far apart its lines are, 0 or more, a share of 1.2 times its size: a text's lines are 0.9 apart unless given.

  * `:margin` - The space on each side of it: one length for every side, or a keyword list of `:top`, `:right`, `:bottom` and `:left`, a side left out 0.

* `:axis_text_theta` (`t:keyword/0`) - The tick labels round a radial panel. Inherits from `:axis_text_x`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:size` - How big it is, in points, or `{:rel, share}`, a share of its parent's size.

  * `:family` (`t:String.t/0`) - The font it is drawn in, by name, such as `"Lobster"`, or one of the generic families `"sans"`, `"serif"` and `"mono"`; `""` is the default sans-serif. How it is measured and drawn: the [fonts guide](fonts.md).

  * `:face` - Its face: `:plain`, `:bold`, `:italic` or `:bold_italic`.

  * `:angle` - How far it is turned, in degrees anticlockwise, any number.

  * `:hjust` - Where it sits across, any number: 0 at its left, 0.5 centred, 1 at its right, in its own turned frame.

  * `:vjust` - Where it sits up, any number: 0 at its bottom, 0.5 centred, 1 at its top, in its own turned frame.

  * `:lineheight` - How far apart its lines are, 0 or more, a share of 1.2 times its size: a text's lines are 0.9 apart unless given.

  * `:margin` - The space on each side of it: one length for every side, or a keyword list of `:top`, `:right`, `:bottom` and `:left`, a side left out 0.

* `:axis_text_r` (`t:keyword/0`) - The tick labels of a radial panel's radius axis. Inherits from `:axis_text_y`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:size` - How big it is, in points, or `{:rel, share}`, a share of its parent's size.

  * `:family` (`t:String.t/0`) - The font it is drawn in, by name, such as `"Lobster"`, or one of the generic families `"sans"`, `"serif"` and `"mono"`; `""` is the default sans-serif. How it is measured and drawn: the [fonts guide](fonts.md).

  * `:face` - Its face: `:plain`, `:bold`, `:italic` or `:bold_italic`.

  * `:angle` - How far it is turned, in degrees anticlockwise, any number.

  * `:hjust` - Where it sits across, any number: 0 at its left, 0.5 centred, 1 at its right, in its own turned frame.

  * `:vjust` - Where it sits up, any number: 0 at its bottom, 0.5 centred, 1 at its top, in its own turned frame.

  * `:lineheight` - How far apart its lines are, 0 or more, a share of 1.2 times its size: a text's lines are 0.9 apart unless given.

  * `:margin` - The space on each side of it: one length for every side, or a keyword list of `:top`, `:right`, `:bottom` and `:left`, a side left out 0.

* `:axis_ticks_length` - How long the axes' ticks are. Inherits from `:spacing`.

* `:axis_ticks_length_x` - How long the x axis's ticks are. Inherits from `:axis_ticks_length`.

* `:axis_ticks_length_x_bottom` - How long the ticks of the x axis below the panels are. Inherits from `:axis_ticks_length_x`.

* `:axis_ticks_length_y` - How long the y axis's ticks are. Inherits from `:axis_ticks_length`.

* `:axis_ticks_length_y_left` - How long the ticks of the y axis left of the panels are. Inherits from `:axis_ticks_length_y`.

* `:axis_ticks_length_theta` - How long the ticks round a radial panel are. Inherits from `:axis_ticks_length_x`.

* `:axis_ticks_length_r` - How long the ticks of a radial panel's radius axis are. Inherits from `:axis_ticks_length_y`.

* `:axis_ticks_x` (`t:keyword/0`) - The x axis's ticks. Inherits from `:axis_ticks`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

  * `:lineend` - How its ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half its width beyond it (`:square`).

* `:axis_ticks_x_bottom` (`t:keyword/0`) - The ticks of the x axis below the panels. Inherits from `:axis_ticks_x`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

  * `:lineend` - How its ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half its width beyond it (`:square`).

* `:axis_ticks_y` (`t:keyword/0`) - The y axis's ticks. Inherits from `:axis_ticks`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

  * `:lineend` - How its ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half its width beyond it (`:square`).

* `:axis_ticks_y_left` (`t:keyword/0`) - The ticks of the y axis left of the panels. Inherits from `:axis_ticks_y`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

  * `:lineend` - How its ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half its width beyond it (`:square`).

* `:axis_ticks_theta` (`t:keyword/0`) - The ticks round a radial panel. Inherits from `:axis_ticks_x`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

  * `:lineend` - How its ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half its width beyond it (`:square`).

* `:axis_ticks_r` (`t:keyword/0`) - The ticks of a radial panel's radius axis. Inherits from `:axis_ticks_y`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

  * `:lineend` - How its ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half its width beyond it (`:square`).

* `:axis_title_x` (`t:keyword/0`) - The x axis's title. Inherits from `:axis_title`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:size` - How big it is, in points, or `{:rel, share}`, a share of its parent's size.

  * `:family` (`t:String.t/0`) - The font it is drawn in, by name, such as `"Lobster"`, or one of the generic families `"sans"`, `"serif"` and `"mono"`; `""` is the default sans-serif. How it is measured and drawn: the [fonts guide](fonts.md).

  * `:face` - Its face: `:plain`, `:bold`, `:italic` or `:bold_italic`.

  * `:angle` - How far it is turned, in degrees anticlockwise, any number.

  * `:hjust` - Where it sits across, any number: 0 at its left, 0.5 centred, 1 at its right, in its own turned frame.

  * `:vjust` - Where it sits up, any number: 0 at its bottom, 0.5 centred, 1 at its top, in its own turned frame.

  * `:lineheight` - How far apart its lines are, 0 or more, a share of 1.2 times its size: a text's lines are 0.9 apart unless given.

  * `:margin` - The space on each side of it: one length for every side, or a keyword list of `:top`, `:right`, `:bottom` and `:left`, a side left out 0.

* `:axis_title_x_bottom` (`t:keyword/0`) - The title of the x axis below the panels. Inherits from `:axis_title_x`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:size` - How big it is, in points, or `{:rel, share}`, a share of its parent's size.

  * `:family` (`t:String.t/0`) - The font it is drawn in, by name, such as `"Lobster"`, or one of the generic families `"sans"`, `"serif"` and `"mono"`; `""` is the default sans-serif. How it is measured and drawn: the [fonts guide](fonts.md).

  * `:face` - Its face: `:plain`, `:bold`, `:italic` or `:bold_italic`.

  * `:angle` - How far it is turned, in degrees anticlockwise, any number.

  * `:hjust` - Where it sits across, any number: 0 at its left, 0.5 centred, 1 at its right, in its own turned frame.

  * `:vjust` - Where it sits up, any number: 0 at its bottom, 0.5 centred, 1 at its top, in its own turned frame.

  * `:lineheight` - How far apart its lines are, 0 or more, a share of 1.2 times its size: a text's lines are 0.9 apart unless given.

  * `:margin` - The space on each side of it: one length for every side, or a keyword list of `:top`, `:right`, `:bottom` and `:left`, a side left out 0.

* `:axis_title_y` (`t:keyword/0`) - The y axis's title. Inherits from `:axis_title`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:size` - How big it is, in points, or `{:rel, share}`, a share of its parent's size.

  * `:family` (`t:String.t/0`) - The font it is drawn in, by name, such as `"Lobster"`, or one of the generic families `"sans"`, `"serif"` and `"mono"`; `""` is the default sans-serif. How it is measured and drawn: the [fonts guide](fonts.md).

  * `:face` - Its face: `:plain`, `:bold`, `:italic` or `:bold_italic`.

  * `:angle` - How far it is turned, in degrees anticlockwise, any number.

  * `:hjust` - Where it sits across, any number: 0 at its left, 0.5 centred, 1 at its right, in its own turned frame.

  * `:vjust` - Where it sits up, any number: 0 at its bottom, 0.5 centred, 1 at its top, in its own turned frame.

  * `:lineheight` - How far apart its lines are, 0 or more, a share of 1.2 times its size: a text's lines are 0.9 apart unless given.

  * `:margin` - The space on each side of it: one length for every side, or a keyword list of `:top`, `:right`, `:bottom` and `:left`, a side left out 0.

* `:axis_title_y_left` (`t:keyword/0`) - The title of the y axis left of the panels. Inherits from `:axis_title_y`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:size` - How big it is, in points, or `{:rel, share}`, a share of its parent's size.

  * `:family` (`t:String.t/0`) - The font it is drawn in, by name, such as `"Lobster"`, or one of the generic families `"sans"`, `"serif"` and `"mono"`; `""` is the default sans-serif. How it is measured and drawn: the [fonts guide](fonts.md).

  * `:face` - Its face: `:plain`, `:bold`, `:italic` or `:bold_italic`.

  * `:angle` - How far it is turned, in degrees anticlockwise, any number.

  * `:hjust` - Where it sits across, any number: 0 at its left, 0.5 centred, 1 at its right, in its own turned frame.

  * `:vjust` - Where it sits up, any number: 0 at its bottom, 0.5 centred, 1 at its top, in its own turned frame.

  * `:lineheight` - How far apart its lines are, 0 or more, a share of 1.2 times its size: a text's lines are 0.9 apart unless given.

  * `:margin` - The space on each side of it: one length for every side, or a keyword list of `:top`, `:right`, `:bottom` and `:left`, a side left out 0.

* `:legend_background` (`t:keyword/0`) - Each legend's background. Inherits from `:rect`.

  * `:fill` - Its fill, a CSS colour, which may have an alpha of its own, or `:none` for none.

  * `:color` - Its border's colour, a CSS colour, which may have an alpha of its own, or `:none` for no border (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

* `:legend_margin` - The margin inside each legend's edge. Inherits from `:margins`.

* `:legend_spacing` - The space between legends. Inherits from `:spacing`.

* `:legend_spacing_x` - The space between a legend and the next beside it. Inherits from `:legend_spacing`.

* `:legend_spacing_y` - The space between a legend and the next below it. Inherits from `:legend_spacing`.

* `:legend_key` (`t:keyword/0`) - The background of each legend key. Inherits from `:panel_background`.

  * `:fill` - Its fill, a CSS colour, which may have an alpha of its own, or `:none` for none.

  * `:color` - Its border's colour, a CSS colour, which may have an alpha of its own, or `:none` for no border (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

* `:legend_key_size` - How big each legend key is. Inherits from `:spacing`.

* `:legend_key_height` - How tall each legend key is. Inherits from `:legend_key_size`.

* `:legend_key_width` - How wide each legend key is. Inherits from `:legend_key_size`.

* `:legend_key_spacing` - The space between a legend's keys and its labels, and below its title. Inherits from `:spacing`.

* `:legend_axis_line` (`t:keyword/0`) - The line along a legend's axis. Inherits from `:line`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

  * `:lineend` - How its ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half its width beyond it (`:square`).

* `:legend_ticks` (`t:keyword/0`) - A colour bar's ticks, and colour steps'. Inherits from `:legend_axis_line`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

  * `:lineend` - How its ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half its width beyond it (`:square`).

* `:legend_ticks_length` - How far a colour bar's or colour steps' ticks reach into the bar. Inherits from `:legend_key_size`.

* `:legend_text` (`t:keyword/0`) - The legends' labels. Inherits from `:text`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:size` - How big it is, in points, or `{:rel, share}`, a share of its parent's size.

  * `:family` (`t:String.t/0`) - The font it is drawn in, by name, such as `"Lobster"`, or one of the generic families `"sans"`, `"serif"` and `"mono"`; `""` is the default sans-serif. How it is measured and drawn: the [fonts guide](fonts.md).

  * `:face` - Its face: `:plain`, `:bold`, `:italic` or `:bold_italic`.

  * `:angle` - How far it is turned, in degrees anticlockwise, any number.

  * `:hjust` - Where it sits across, any number: 0 at its left, 0.5 centred, 1 at its right, in its own turned frame.

  * `:vjust` - Where it sits up, any number: 0 at its bottom, 0.5 centred, 1 at its top, in its own turned frame.

  * `:lineheight` - How far apart its lines are, 0 or more, a share of 1.2 times its size: a text's lines are 0.9 apart unless given.

  * `:margin` - The space on each side of it: one length for every side, or a keyword list of `:top`, `:right`, `:bottom` and `:left`, a side left out 0.

* `:legend_title` (`t:keyword/0`) - The legends' titles. Inherits from `:title`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:size` - How big it is, in points, or `{:rel, share}`, a share of its parent's size.

  * `:family` (`t:String.t/0`) - The font it is drawn in, by name, such as `"Lobster"`, or one of the generic families `"sans"`, `"serif"` and `"mono"`; `""` is the default sans-serif. How it is measured and drawn: the [fonts guide](fonts.md).

  * `:face` - Its face: `:plain`, `:bold`, `:italic` or `:bold_italic`.

  * `:angle` - How far it is turned, in degrees anticlockwise, any number.

  * `:hjust` - Where it sits across, any number: 0 at its left, 0.5 centred, 1 at its right, in its own turned frame.

  * `:vjust` - Where it sits up, any number: 0 at its bottom, 0.5 centred, 1 at its top, in its own turned frame.

  * `:lineheight` - How far apart its lines are, 0 or more, a share of 1.2 times its size: a text's lines are 0.9 apart unless given.

  * `:margin` - The space on each side of it: one length for every side, or a keyword list of `:top`, `:right`, `:bottom` and `:left`, a side left out 0.

* `:legend_position` - Where the legends go: `:right`, `:left`, `:top` or `:bottom`, beside the panels on that side, `:inside`, over them, or `:none`, for no legends.

* `:legend_position_inside` - Where the legends' box goes when they are inside the panels: `{x, y}`, each a share of the panels' width or height from their left or bottom; at its justification unless given.

* `:legend_direction` - Which way each legend's keys run: `:horizontal` or `:vertical`; across above or below the panels and down elsewhere unless given.

* `:legend_justification` - Which point of the legends' box is placed where it goes: `:center`, a side (`:left`, `:right`, `:top`, `:bottom`), or `{horizontal, vertical}`, each a share of the box's width or height or `:left`, `:center` or `:right` across and `:bottom`, `:center` or `:top` up; beside the panels, the same point of the room beside them.

* `:legend_justification_top` - The justification of legends above the panels. Inherits from `:legend_justification`.

* `:legend_justification_bottom` - The justification of legends below the panels. Inherits from `:legend_justification`.

* `:legend_justification_left` - The justification of legends left of the panels. Inherits from `:legend_justification`.

* `:legend_justification_right` - The justification of legends right of the panels. Inherits from `:legend_justification`.

* `:legend_justification_inside` - The justification of legends inside the panels. Inherits from `:legend_justification`.

* `:legend_location` - What legends beside the panels line up with: `:panel`, the panels, or `:plot`, the axes and their titles too.

* `:legend_box` - How several legends are arranged: `:horizontal`, side by side, or `:vertical`, one above another; side by side above or below the panels and one above another elsewhere unless given.

* `:legend_box_just` - Which point of each legend is placed at the same point of its room in the box: as `:legend_justification` takes, by name alone; at the box's top, centred across above or below the panels and at its left elsewhere, unless given.

* `:legend_box_margin` - The margin inside the legends' box. Inherits from `:margins`.

* `:legend_box_background` (`t:keyword/0`) - The background of the legends' box, over its margin too, drawn as its own setting gives it: what that leaves unset is the drawing's default, a white fill and a solid black border 0.75 points wide, never `:rect`'s.

  * `:fill` - Its fill, a CSS colour, which may have an alpha of its own, or `:none` for none.

  * `:color` - Its border's colour, a CSS colour, which may have an alpha of its own, or `:none` for no border (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

* `:legend_box_spacing` - The space between the panels and the legends. Inherits from `:spacing`.

* `:panel_background` (`t:keyword/0`) - The panels' background, under the layers. Inherits from `:rect`.

  * `:fill` - Its fill, a CSS colour, which may have an alpha of its own, or `:none` for none.

  * `:color` - Its border's colour, a CSS colour, which may have an alpha of its own, or `:none` for no border (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

* `:panel_border` (`t:keyword/0`) - The panels' border, drawn over the layers and never filled. Inherits from `:rect`.

  * `:fill` - Its fill, a CSS colour, which may have an alpha of its own, or `:none` for none.

  * `:color` - Its border's colour, a CSS colour, which may have an alpha of its own, or `:none` for no border (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

* `:panel_spacing` - The space between panels. Inherits from `:spacing`.

* `:panel_spacing_x` - The space between panels side by side. Inherits from `:panel_spacing`.

* `:panel_spacing_y` - The space between panels one above another. Inherits from `:panel_spacing`.

* `:panel_grid` (`t:keyword/0`) - The panels' grid lines. Inherits from `:line`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

  * `:lineend` - How its ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half its width beyond it (`:square`).

* `:panel_grid_major` (`t:keyword/0`) - The grid lines at the axes' breaks. Inherits from `:panel_grid`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

  * `:lineend` - How its ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half its width beyond it (`:square`).

* `:panel_grid_minor` (`t:keyword/0`) - The grid lines between the axes' breaks. Inherits from `:panel_grid`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

  * `:lineend` - How its ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half its width beyond it (`:square`).

* `:panel_grid_major_x` (`t:keyword/0`) - The grid lines at the x axis's breaks. Inherits from `:panel_grid_major`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

  * `:lineend` - How its ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half its width beyond it (`:square`).

* `:panel_grid_major_y` (`t:keyword/0`) - The grid lines at the y axis's breaks. Inherits from `:panel_grid_major`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

  * `:lineend` - How its ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half its width beyond it (`:square`).

* `:panel_grid_minor_x` (`t:keyword/0`) - The grid lines between the x axis's breaks. Inherits from `:panel_grid_minor`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

  * `:lineend` - How its ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half its width beyond it (`:square`).

* `:panel_grid_minor_y` (`t:keyword/0`) - The grid lines between the y axis's breaks. Inherits from `:panel_grid_minor`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

  * `:lineend` - How its ends are drawn: cut square at the end (`:butt`), rounded (`:round`), or cut square half its width beyond it (`:square`).

* `:panel_ontop` (`t:boolean/0`) - Whether the panels' background and grid lines are drawn over the layers, `true`, or under them, `false`.

* `:strip_background` (`t:keyword/0`) - The strips' background. Inherits from `:rect`.

  * `:fill` - Its fill, a CSS colour, which may have an alpha of its own, or `:none` for none.

  * `:color` - Its border's colour, a CSS colour, which may have an alpha of its own, or `:none` for no border (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

* `:strip_background_x` (`t:keyword/0`) - The background of the strips above panels. Inherits from `:strip_background`.

  * `:fill` - Its fill, a CSS colour, which may have an alpha of its own, or `:none` for none.

  * `:color` - Its border's colour, a CSS colour, which may have an alpha of its own, or `:none` for no border (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

* `:strip_background_y` (`t:keyword/0`) - The background of the strips right of panels. Inherits from `:strip_background`.

  * `:fill` - Its fill, a CSS colour, which may have an alpha of its own, or `:none` for none.

  * `:color` - Its border's colour, a CSS colour, which may have an alpha of its own, or `:none` for no border (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

* `:strip_text` (`t:keyword/0`) - The strips' labels. Inherits from `:text`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:size` - How big it is, in points, or `{:rel, share}`, a share of its parent's size.

  * `:family` (`t:String.t/0`) - The font it is drawn in, by name, such as `"Lobster"`, or one of the generic families `"sans"`, `"serif"` and `"mono"`; `""` is the default sans-serif. How it is measured and drawn: the [fonts guide](fonts.md).

  * `:face` - Its face: `:plain`, `:bold`, `:italic` or `:bold_italic`.

  * `:angle` - How far it is turned, in degrees anticlockwise, any number.

  * `:hjust` - Where it sits across, any number: 0 at its left, 0.5 centred, 1 at its right, in its own turned frame.

  * `:vjust` - Where it sits up, any number: 0 at its bottom, 0.5 centred, 1 at its top, in its own turned frame.

  * `:lineheight` - How far apart its lines are, 0 or more, a share of 1.2 times its size: a text's lines are 0.9 apart unless given.

  * `:margin` - The space on each side of it: one length for every side, or a keyword list of `:top`, `:right`, `:bottom` and `:left`, a side left out 0.

* `:strip_text_x` (`t:keyword/0`) - The labels of the strips above or below panels. Inherits from `:strip_text`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:size` - How big it is, in points, or `{:rel, share}`, a share of its parent's size.

  * `:family` (`t:String.t/0`) - The font it is drawn in, by name, such as `"Lobster"`, or one of the generic families `"sans"`, `"serif"` and `"mono"`; `""` is the default sans-serif. How it is measured and drawn: the [fonts guide](fonts.md).

  * `:face` - Its face: `:plain`, `:bold`, `:italic` or `:bold_italic`.

  * `:angle` - How far it is turned, in degrees anticlockwise, any number.

  * `:hjust` - Where it sits across, any number: 0 at its left, 0.5 centred, 1 at its right, in its own turned frame.

  * `:vjust` - Where it sits up, any number: 0 at its bottom, 0.5 centred, 1 at its top, in its own turned frame.

  * `:lineheight` - How far apart its lines are, 0 or more, a share of 1.2 times its size: a text's lines are 0.9 apart unless given.

  * `:margin` - The space on each side of it: one length for every side, or a keyword list of `:top`, `:right`, `:bottom` and `:left`, a side left out 0.

* `:strip_text_x_top` (`t:keyword/0`) - The labels of the strips above panels. Inherits from `:strip_text_x`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:size` - How big it is, in points, or `{:rel, share}`, a share of its parent's size.

  * `:family` (`t:String.t/0`) - The font it is drawn in, by name, such as `"Lobster"`, or one of the generic families `"sans"`, `"serif"` and `"mono"`; `""` is the default sans-serif. How it is measured and drawn: the [fonts guide](fonts.md).

  * `:face` - Its face: `:plain`, `:bold`, `:italic` or `:bold_italic`.

  * `:angle` - How far it is turned, in degrees anticlockwise, any number.

  * `:hjust` - Where it sits across, any number: 0 at its left, 0.5 centred, 1 at its right, in its own turned frame.

  * `:vjust` - Where it sits up, any number: 0 at its bottom, 0.5 centred, 1 at its top, in its own turned frame.

  * `:lineheight` - How far apart its lines are, 0 or more, a share of 1.2 times its size: a text's lines are 0.9 apart unless given.

  * `:margin` - The space on each side of it: one length for every side, or a keyword list of `:top`, `:right`, `:bottom` and `:left`, a side left out 0.

* `:strip_text_y` (`t:keyword/0`) - The labels of the strips left or right of panels. Inherits from `:strip_text`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:size` - How big it is, in points, or `{:rel, share}`, a share of its parent's size.

  * `:family` (`t:String.t/0`) - The font it is drawn in, by name, such as `"Lobster"`, or one of the generic families `"sans"`, `"serif"` and `"mono"`; `""` is the default sans-serif. How it is measured and drawn: the [fonts guide](fonts.md).

  * `:face` - Its face: `:plain`, `:bold`, `:italic` or `:bold_italic`.

  * `:angle` - How far it is turned, in degrees anticlockwise, any number.

  * `:hjust` - Where it sits across, any number: 0 at its left, 0.5 centred, 1 at its right, in its own turned frame.

  * `:vjust` - Where it sits up, any number: 0 at its bottom, 0.5 centred, 1 at its top, in its own turned frame.

  * `:lineheight` - How far apart its lines are, 0 or more, a share of 1.2 times its size: a text's lines are 0.9 apart unless given.

  * `:margin` - The space on each side of it: one length for every side, or a keyword list of `:top`, `:right`, `:bottom` and `:left`, a side left out 0.

* `:strip_text_y_right` (`t:keyword/0`) - The labels of the strips right of panels. Inherits from `:strip_text_y`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:size` - How big it is, in points, or `{:rel, share}`, a share of its parent's size.

  * `:family` (`t:String.t/0`) - The font it is drawn in, by name, such as `"Lobster"`, or one of the generic families `"sans"`, `"serif"` and `"mono"`; `""` is the default sans-serif. How it is measured and drawn: the [fonts guide](fonts.md).

  * `:face` - Its face: `:plain`, `:bold`, `:italic` or `:bold_italic`.

  * `:angle` - How far it is turned, in degrees anticlockwise, any number.

  * `:hjust` - Where it sits across, any number: 0 at its left, 0.5 centred, 1 at its right, in its own turned frame.

  * `:vjust` - Where it sits up, any number: 0 at its bottom, 0.5 centred, 1 at its top, in its own turned frame.

  * `:lineheight` - How far apart its lines are, 0 or more, a share of 1.2 times its size: a text's lines are 0.9 apart unless given.

  * `:margin` - The space on each side of it: one length for every side, or a keyword list of `:top`, `:right`, `:bottom` and `:left`, a side left out 0.

* `:plot_background` (`t:keyword/0`) - The background of the whole plot. Inherits from `:rect`.

  * `:fill` - Its fill, a CSS colour, which may have an alpha of its own, or `:none` for none.

  * `:color` - Its border's colour, a CSS colour, which may have an alpha of its own, or `:none` for no border (`colour:` too).

  * `:linewidth` - How wide it is, in millimetres, or `{:rel, share}`, a share of its parent's.

  * `:linetype` - Its line type: `:blank`, which draws no line, `:solid`, `:dashed`, `:dotted`, `:dotdash`, `:longdash` or `:twodash`, or its number in that order, 0 to 6; or a dash pattern, a tuple of 2, 4, 6 or 8 lengths from 1 to 15, a dash and a gap in turn, which grow with the line's width, `{4, 4}` being `:dashed`.

* `:plot_margin` - The margin round the whole plot. Inherits from `:margins`.

* `:plot_title` (`t:keyword/0`) - The plot's title. Inherits from `:title`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:size` - How big it is, in points, or `{:rel, share}`, a share of its parent's size.

  * `:family` (`t:String.t/0`) - The font it is drawn in, by name, such as `"Lobster"`, or one of the generic families `"sans"`, `"serif"` and `"mono"`; `""` is the default sans-serif. How it is measured and drawn: the [fonts guide](fonts.md).

  * `:face` - Its face: `:plain`, `:bold`, `:italic` or `:bold_italic`.

  * `:angle` - How far it is turned, in degrees anticlockwise, any number.

  * `:hjust` - Where it sits across, any number: 0 at its left, 0.5 centred, 1 at its right, in its own turned frame.

  * `:vjust` - Where it sits up, any number: 0 at its bottom, 0.5 centred, 1 at its top, in its own turned frame.

  * `:lineheight` - How far apart its lines are, 0 or more, a share of 1.2 times its size: a text's lines are 0.9 apart unless given.

  * `:margin` - The space on each side of it: one length for every side, or a keyword list of `:top`, `:right`, `:bottom` and `:left`, a side left out 0.

* `:plot_subtitle` (`t:keyword/0`) - The plot's subtitle. Inherits from `:text`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:size` - How big it is, in points, or `{:rel, share}`, a share of its parent's size.

  * `:family` (`t:String.t/0`) - The font it is drawn in, by name, such as `"Lobster"`, or one of the generic families `"sans"`, `"serif"` and `"mono"`; `""` is the default sans-serif. How it is measured and drawn: the [fonts guide](fonts.md).

  * `:face` - Its face: `:plain`, `:bold`, `:italic` or `:bold_italic`.

  * `:angle` - How far it is turned, in degrees anticlockwise, any number.

  * `:hjust` - Where it sits across, any number: 0 at its left, 0.5 centred, 1 at its right, in its own turned frame.

  * `:vjust` - Where it sits up, any number: 0 at its bottom, 0.5 centred, 1 at its top, in its own turned frame.

  * `:lineheight` - How far apart its lines are, 0 or more, a share of 1.2 times its size: a text's lines are 0.9 apart unless given.

  * `:margin` - The space on each side of it: one length for every side, or a keyword list of `:top`, `:right`, `:bottom` and `:left`, a side left out 0.

* `:plot_caption` (`t:keyword/0`) - The plot's caption. Inherits from `:text`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:size` - How big it is, in points, or `{:rel, share}`, a share of its parent's size.

  * `:family` (`t:String.t/0`) - The font it is drawn in, by name, such as `"Lobster"`, or one of the generic families `"sans"`, `"serif"` and `"mono"`; `""` is the default sans-serif. How it is measured and drawn: the [fonts guide](fonts.md).

  * `:face` - Its face: `:plain`, `:bold`, `:italic` or `:bold_italic`.

  * `:angle` - How far it is turned, in degrees anticlockwise, any number.

  * `:hjust` - Where it sits across, any number: 0 at its left, 0.5 centred, 1 at its right, in its own turned frame.

  * `:vjust` - Where it sits up, any number: 0 at its bottom, 0.5 centred, 1 at its top, in its own turned frame.

  * `:lineheight` - How far apart its lines are, 0 or more, a share of 1.2 times its size: a text's lines are 0.9 apart unless given.

  * `:margin` - The space on each side of it: one length for every side, or a keyword list of `:top`, `:right`, `:bottom` and `:left`, a side left out 0.

* `:plot_tag` (`t:keyword/0`) - The plot's tag. Inherits from `:text`.

  * `:color` - Its colour, a CSS colour, which may have an alpha of its own (`colour:` too).

  * `:size` - How big it is, in points, or `{:rel, share}`, a share of its parent's size.

  * `:family` (`t:String.t/0`) - The font it is drawn in, by name, such as `"Lobster"`, or one of the generic families `"sans"`, `"serif"` and `"mono"`; `""` is the default sans-serif. How it is measured and drawn: the [fonts guide](fonts.md).

  * `:face` - Its face: `:plain`, `:bold`, `:italic` or `:bold_italic`.

  * `:angle` - How far it is turned, in degrees anticlockwise, any number.

  * `:hjust` - Where it sits across, any number: 0 at its left, 0.5 centred, 1 at its right, in its own turned frame.

  * `:vjust` - Where it sits up, any number: 0 at its bottom, 0.5 centred, 1 at its top, in its own turned frame.

  * `:lineheight` - How far apart its lines are, 0 or more, a share of 1.2 times its size: a text's lines are 0.9 apart unless given.

  * `:margin` - The space on each side of it: one length for every side, or a keyword list of `:top`, `:right`, `:bottom` and `:left`, a side left out 0.

    iex> svg =
    ...>   %{"wt" => [2.62, 2.875], "mpg" => [21.0, 22.8]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.theme(panel_background: [fill: "white"], axis_text: [color: "red"])
    ...>   |> Giggly.to_svg()
    ...>   |> IO.iodata_to_binary()
    iex> {svg =~ "fill: #EBEBEB", svg =~ "fill: #FF0000"}
    {false, true}

Removing the panel's background and the tick labels leaves the axes' titles the only text:

    iex> svg =
    ...>   %{"wt" => [2.62, 2.875], "mpg" => [21.0, 22.8]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.theme(panel_background: :none, axis_text: :none)
    ...>   |> Giggly.to_svg()
    ...>   |> IO.iodata_to_binary()
    iex> {svg =~ "fill: #EBEBEB", length(Regex.scan(~r/<text/, svg))}
    {false, 2}

Drawing the axes' lines, and a dashed, unfilled border over the panel:

    iex> svg =
    ...>   %{"wt" => [2.62, 2.875], "mpg" => [21.0, 22.8]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.theme(
    ...>     axis_line: [colour: "black"],
    ...>     panel_border: [colour: "black", linetype: :dashed]
    ...>   )
    ...>   |> Giggly.to_svg()
    ...>   |> IO.iodata_to_binary()
    iex> {length(Regex.scan(~r/<polyline[^>]*#000000/, svg)),
    ...>  svg =~ "stroke: #000000; stroke-dasharray: 5.69,5.69; fill: none;"}
    {2, true}

# `theme_bw`

```elixir
@spec theme_bw(t(), keyword()) :: t()
```

Draws everything but the marks dark on light: a white panel bordered in dark grey, with light
grey grid lines, and light grey strips bordered as the panel is.

It replaces the plot's theme whole, dropping the settings `theme/2` laid over the one before.
Each later `theme/2` call is laid over it in turn: its properties replace only those they give,
and an element set after a removal of the same element replaces the complete theme's element
whole, inheriting what it leaves unset from its parent.

Raises `NimbleOptions.ValidationError` for an option it does not know or a size it cannot use,
and `ArgumentError` for an option given twice.

## Options

* `:base_size` - How big its text is, in points, 0 or more: every text's size is a share of it, and the space between parts of the plot half of it. 11 unless given.

* `:base_line_size` - How wide its lines are, in millimetres, 0 or more. `base_size / 22` unless given.

* `:base_rect_size` - How wide its rectangles' borders are, in millimetres, 0 or more. `base_size / 22` unless given.

* `:base_family` (`t:String.t/0`) - The font its text and its layers' text are drawn in, by name, as `theme/2`'s `family:` takes one. `""`, the default sans-serif, unless given.

* `:header_family` (`t:String.t/0`) - The font its titles are drawn in, by name: the axes' and the legends' titles and the plot's title. The base family unless given.

    iex> svg =
    ...>   %{"wt" => [2.62, 2.875], "mpg" => [21.0, 22.8]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.theme_bw()
    ...>   |> Giggly.to_svg()
    ...>   |> IO.iodata_to_binary()
    iex> {svg =~ "fill: #EBEBEB", svg =~ "stroke: #333333; fill: none;"}
    {false, true}

# `theme_classic`

```elixir
@spec theme_classic(t(), keyword()) :: t()
```

Draws the axes as lines, with no grid: black axis lines with square ends, black ticks and tick
labels, no border round the panel, and white strips bordered in black.

It replaces the plot's theme whole, dropping the settings `theme/2` laid over the one before.
Each later `theme/2` call is laid over it in turn: its properties replace only those they give,
and an element set after a removal of the same element replaces the complete theme's element
whole, inheriting what it leaves unset from its parent.

Raises `NimbleOptions.ValidationError` for an option it does not know or a size it cannot use,
and `ArgumentError` for an option given twice.

## Options

* `:base_size` - How big its text is, in points, 0 or more: every text's size is a share of it, and the space between parts of the plot half of it. 11 unless given.

* `:base_line_size` - How wide its lines are, in millimetres, 0 or more. `base_size / 22` unless given.

* `:base_rect_size` - How wide its rectangles' borders are, in millimetres, 0 or more. `base_size / 22` unless given.

* `:base_family` (`t:String.t/0`) - The font its text and its layers' text are drawn in, by name, as `theme/2`'s `family:` takes one. `""`, the default sans-serif, unless given.

* `:header_family` (`t:String.t/0`) - The font its titles are drawn in, by name: the axes' and the legends' titles and the plot's title. The base family unless given.

    iex> svg =
    ...>   %{"wt" => [2.62, 2.875], "mpg" => [21.0, 22.8]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.theme_classic()
    ...>   |> Giggly.to_svg()
    ...>   |> IO.iodata_to_binary()
    iex> {svg =~ "stroke-linecap: square", svg =~ "stroke: #FFFFFF; stroke-linecap: butt"}
    {true, false}

# `theme_dark`

```elixir
@spec theme_dark(t(), keyword()) :: t()
```

Draws everything but the marks on a dark panel: a mid-grey panel, and legend keys, with darker
grid lines half as wide as a line, the minor ones a quarter, thin dark grey ticks, and
near-black strips with near-white labels.

It replaces the plot's theme whole, dropping the settings `theme/2` laid over the one before.
Each later `theme/2` call is laid over it in turn: its properties replace only those they give,
and an element set after a removal of the same element replaces the complete theme's element
whole, inheriting what it leaves unset from its parent.

Raises `NimbleOptions.ValidationError` for an option it does not know or a size it cannot use,
and `ArgumentError` for an option given twice.

## Options

* `:base_size` - How big its text is, in points, 0 or more: every text's size is a share of it, and the space between parts of the plot half of it. 11 unless given.

* `:base_line_size` - How wide its lines are, in millimetres, 0 or more. `base_size / 22` unless given.

* `:base_rect_size` - How wide its rectangles' borders are, in millimetres, 0 or more. `base_size / 22` unless given.

* `:base_family` (`t:String.t/0`) - The font its text and its layers' text are drawn in, by name, as `theme/2`'s `family:` takes one. `""`, the default sans-serif, unless given.

* `:header_family` (`t:String.t/0`) - The font its titles are drawn in, by name: the axes' and the legends' titles and the plot's title. The base family unless given.

    iex> svg =
    ...>   %{"wt" => [2.62, 2.875], "mpg" => [21.0, 22.8]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.theme_dark()
    ...>   |> Giggly.to_svg()
    ...>   |> IO.iodata_to_binary()
    iex> {svg =~ "fill: #7F7F7F", svg =~ "stroke: #6B6B6B"}
    {true, true}

# `theme_gray`

```elixir
@spec theme_gray(t(), keyword()) :: t()
```

Draws everything but the marks in the default theme, at the base sizes given: a grey panel
with white grid lines, the minor ones half as wide, dark grey ticks, grey tick labels, and
light grey strips.

It replaces the plot's theme whole, dropping the settings `theme/2` laid over the one before.
Each later `theme/2` call is laid over it in turn: its properties replace only those they give,
and an element set after a removal of the same element replaces the complete theme's element
whole, inheriting what it leaves unset from its parent.

Raises `NimbleOptions.ValidationError` for an option it does not know or a size it cannot use,
and `ArgumentError` for an option given twice.

## Options

* `:base_size` - How big its text is, in points, 0 or more: every text's size is a share of it, and the space between parts of the plot half of it. 11 unless given.

* `:base_line_size` - How wide its lines are, in millimetres, 0 or more. `base_size / 22` unless given.

* `:base_rect_size` - How wide its rectangles' borders are, in millimetres, 0 or more. `base_size / 22` unless given.

* `:base_family` (`t:String.t/0`) - The font its text and its layers' text are drawn in, by name, as `theme/2`'s `family:` takes one. `""`, the default sans-serif, unless given.

* `:header_family` (`t:String.t/0`) - The font its titles are drawn in, by name: the axes' and the legends' titles and the plot's title. The base family unless given.

    iex> svg =
    ...>   %{"wt" => [2.62, 2.875], "mpg" => [21.0, 22.8]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.theme_gray(base_size: 16)
    ...>   |> Giggly.to_svg()
    ...>   |> IO.iodata_to_binary()
    iex> {svg =~ "fill: #EBEBEB", svg =~ "font-size: 12.80px"}
    {true, true}

Its text in a serif font, and its titles, here the axes', in a monospaced one:

    iex> svg =
    ...>   %{"wt" => [2.62, 2.875], "mpg" => [21.0, 22.8]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.theme_gray(base_family: "serif", header_family: "mono")
    ...>   |> Giggly.to_svg()
    ...>   |> IO.iodata_to_binary()
    iex> {svg =~ "font-family: serif;", svg =~ "font-family: monospace;"}
    {true, true}

# `theme_light`

```elixir
@spec theme_light(t(), keyword()) :: t()
```

Draws everything but the marks in light grey lines on white: a white panel bordered in light
grey, lighter grey grid lines half as wide as a line, the minor ones a quarter, light grey
ticks, and light grey strips with white labels.

It replaces the plot's theme whole, dropping the settings `theme/2` laid over the one before.
Each later `theme/2` call is laid over it in turn: its properties replace only those they give,
and an element set after a removal of the same element replaces the complete theme's element
whole, inheriting what it leaves unset from its parent.

Raises `NimbleOptions.ValidationError` for an option it does not know or a size it cannot use,
and `ArgumentError` for an option given twice.

## Options

* `:base_size` - How big its text is, in points, 0 or more: every text's size is a share of it, and the space between parts of the plot half of it. 11 unless given.

* `:base_line_size` - How wide its lines are, in millimetres, 0 or more. `base_size / 22` unless given.

* `:base_rect_size` - How wide its rectangles' borders are, in millimetres, 0 or more. `base_size / 22` unless given.

* `:base_family` (`t:String.t/0`) - The font its text and its layers' text are drawn in, by name, as `theme/2`'s `family:` takes one. `""`, the default sans-serif, unless given.

* `:header_family` (`t:String.t/0`) - The font its titles are drawn in, by name: the axes' and the legends' titles and the plot's title. The base family unless given.

    iex> svg =
    ...>   %{"wt" => [2.62, 2.875], "mpg" => [21.0, 22.8]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.theme_light()
    ...>   |> Giggly.to_svg()
    ...>   |> IO.iodata_to_binary()
    iex> {svg =~ "stroke: #B3B3B3; fill: none;", svg =~ "stroke: #DEDEDE"}
    {true, true}

# `theme_linedraw`

```elixir
@spec theme_linedraw(t(), keyword()) :: t()
```

Draws everything but the marks in black lines of various widths on white: a white panel
bordered in black, black grid lines a tenth of a line wide, the minor ones a twentieth, black
ticks and tick labels, and black strips with white labels.

It replaces the plot's theme whole, dropping the settings `theme/2` laid over the one before.
Each later `theme/2` call is laid over it in turn: its properties replace only those they give,
and an element set after a removal of the same element replaces the complete theme's element
whole, inheriting what it leaves unset from its parent.

Raises `NimbleOptions.ValidationError` for an option it does not know or a size it cannot use,
and `ArgumentError` for an option given twice.

## Options

* `:base_size` - How big its text is, in points, 0 or more: every text's size is a share of it, and the space between parts of the plot half of it. 11 unless given.

* `:base_line_size` - How wide its lines are, in millimetres, 0 or more. `base_size / 22` unless given.

* `:base_rect_size` - How wide its rectangles' borders are, in millimetres, 0 or more. `base_size / 22` unless given.

* `:base_family` (`t:String.t/0`) - The font its text and its layers' text are drawn in, by name, as `theme/2`'s `family:` takes one. `""`, the default sans-serif, unless given.

* `:header_family` (`t:String.t/0`) - The font its titles are drawn in, by name: the axes' and the legends' titles and the plot's title. The base family unless given.

    iex> svg =
    ...>   %{"wt" => [2.62, 2.875], "mpg" => [21.0, 22.8]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.theme_linedraw()
    ...>   |> Giggly.to_svg()
    ...>   |> IO.iodata_to_binary()
    iex> {svg =~ "fill: #4D4D4D", svg =~ "stroke-width: 0.11; stroke: #000000;"}
    {false, true}

# `theme_minimal`

```elixir
@spec theme_minimal(t(), keyword()) :: t()
```

Draws nothing behind the marks but their grid lines: no panel background, border or ticks, the
tick labels further from the panel in their stead, no background to the strips, the legends or
their keys, and a white plot background with no border.

It replaces the plot's theme whole, dropping the settings `theme/2` laid over the one before.
Each later `theme/2` call is laid over it in turn: its properties replace only those they give,
and an element set after a removal of the same element replaces the complete theme's element
whole, inheriting what it leaves unset from its parent.

Raises `NimbleOptions.ValidationError` for an option it does not know or a size it cannot use,
and `ArgumentError` for an option given twice.

## Options

* `:base_size` - How big its text is, in points, 0 or more: every text's size is a share of it, and the space between parts of the plot half of it. 11 unless given.

* `:base_line_size` - How wide its lines are, in millimetres, 0 or more. `base_size / 22` unless given.

* `:base_rect_size` - How wide its rectangles' borders are, in millimetres, 0 or more. `base_size / 22` unless given.

* `:base_family` (`t:String.t/0`) - The font its text and its layers' text are drawn in, by name, as `theme/2`'s `family:` takes one. `""`, the default sans-serif, unless given.

* `:header_family` (`t:String.t/0`) - The font its titles are drawn in, by name: the axes' and the legends' titles and the plot's title. The base family unless given.

    iex> svg =
    ...>   %{"wt" => [2.62, 2.875], "mpg" => [21.0, 22.8]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.theme_minimal()
    ...>   |> Giggly.to_svg()
    ...>   |> IO.iodata_to_binary()
    iex> {svg =~ "stroke: #EBEBEB", svg =~ "fill: #EBEBEB", svg =~ "stroke: #333333"}
    {true, false, false}

# `theme_void`

```elixir
@spec theme_void(t(), keyword()) :: t()
```

Draws nothing but the marks, the legends, the strips' labels and the plot's titles: no axes,
grid lines or backgrounds, on a transparent plot with no margin round it. With no lines and no
borders to draw, only its base size changes what it draws.

It replaces the plot's theme whole, dropping the settings `theme/2` laid over the one before.
Each later `theme/2` call is laid over it in turn: its properties replace only those they give,
and an element set after a removal of the same element replaces the complete theme's element
whole, inheriting what it leaves unset from its parent.

Raises `NimbleOptions.ValidationError` for an option it does not know or a size it cannot use,
and `ArgumentError` for an option given twice.

## Options

* `:base_size` - How big its text is, in points, 0 or more: every text's size is a share of it, and the space between parts of the plot half of it. 11 unless given.

* `:base_line_size` - How wide its lines are, in millimetres, 0 or more. `base_size / 22` unless given.

* `:base_rect_size` - How wide its rectangles' borders are, in millimetres, 0 or more. `base_size / 22` unless given.

* `:base_family` (`t:String.t/0`) - The font its text and its layers' text are drawn in, by name, as `theme/2`'s `family:` takes one. `""`, the default sans-serif, unless given.

* `:header_family` (`t:String.t/0`) - The font its titles are drawn in, by name: the axes' and the legends' titles and the plot's title. The base family unless given.

    iex> svg =
    ...>   %{"wt" => [2.62, 2.875], "mpg" => [21.0, 22.8]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.theme_void()
    ...>   |> Giggly.to_svg()
    ...>   |> IO.iodata_to_binary()
    iex> length(Regex.scan(~r/<text|<polyline/, svg))
    0

# `xlim`

```elixir
@spec xlim(t(), list()) :: t()
```

Gives the plot a discrete x scale showing `values`, in the order given, replacing any x scale it
had, as `scale_x_discrete(plot, limits: values)` does.

    iex> plot =
    ...>   %{"cut" => ["Fair", "Good", "Ideal"], "price" => [3000, 4000, 3500]}
    ...>   |> Giggly.Plot.new(%{x: :cut, y: :price})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.xlim(["Ideal", "Fair"])
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:x)
    [2, nil, 1]

# `xlim`

```elixir
@spec xlim(t(), axis_end(), axis_end()) :: t()
```

Gives the plot an x scale from `low` to `high`, replacing any x scale it had: a continuous scale
for numbers, as `scale_x_continuous(plot, limits: {low, high})` gives, a date scale for dates,
as `scale_x_date(plot, limits: {low, high})` gives, or a date-time scale for date-times, as
`scale_x_datetime(plot, limits: {low, high})` gives; `nil` leaves an end to the data. Numbers
given high to low run the axis from high to low, as `transform: :reverse` runs it, each value
placed at its negation; dates and date-times given so name the same axis as low to high. A
discrete axis's limits are a list of its values, which `xlim/2` takes. Two times of day are
refused: `scale_x_time(plot, limits: {low, high})` takes them.

    iex> plot =
    ...>   %{"wt" => [1.5, 2.6, 3.4], "mpg" => [30.4, 21.0, 18.7]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.xlim(nil, 4)
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:x)
    [1.5, 2.6, 3.4]

A reversed axis:

    iex> plot =
    ...>   %{"mpg" => [21.0, 22.8, 18.7], "wt" => [2.62, 2.32, 3.44]}
    ...>   |> Giggly.Plot.new(%{x: :mpg, y: :wt})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.xlim(20, 15)
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:x)
    [nil, nil, -18.7]

Dates:

    iex> plot =
    ...>   %{"day" => [~D[2024-01-01], ~D[2024-01-11]], "value" => [1, 2]}
    ...>   |> Giggly.Plot.new(%{x: :day, y: :value})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.xlim(~D[2024-01-05], nil)
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:x)
    [nil, 19733.0]

# `ylim`

```elixir
@spec ylim(t(), list()) :: t()
```

Gives the plot a discrete y scale showing `values`, in the order given, replacing any y scale it
had, as `xlim/2` gives an x scale.

    iex> plot =
    ...>   %{"price" => [3000, 4000, 3500], "cut" => ["Fair", "Good", "Ideal"]}
    ...>   |> Giggly.Plot.new(%{x: :price, y: :cut})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.ylim(["Good", "Fair"])
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:y)
    [2, 1, nil]

# `ylim`

```elixir
@spec ylim(t(), axis_end(), axis_end()) :: t()
```

Gives the plot a y scale from `low` to `high`, replacing any y scale it had, as `xlim/3` gives
an x scale.

    iex> plot =
    ...>   %{"wt" => [1.5, 2.6, 3.4], "mpg" => [30.4, 21.0, 18.7]}
    ...>   |> Giggly.Plot.new(%{x: :wt, y: :mpg})
    ...>   |> Giggly.Plot.geom_point()
    ...>   |> Giggly.Plot.ylim(15, 25)
    iex> plot |> Giggly.layer_data() |> Giggly.DataFrame.pull(:y)
    [nil, 21.0, 18.7]

---

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