@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"]}

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

@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

@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.

@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 (pos_integer/0) - How many rows to lay the panels out in.

• :ncol (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.

@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 (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]}

@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 (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 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]

@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 (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 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]

@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 (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 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 (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 (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 (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]]}

@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 (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 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]

@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 (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 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]

@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 (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 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]}

@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 (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 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 (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 (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]}

@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 (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 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]}

@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 (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 says. The default value is :identity.

• :bins (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]

@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 (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 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]

@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 (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 says. The default value is :stack.

• :bins (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 (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]

@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 (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 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]}

@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 (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 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]

@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 (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 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 (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.

• :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}

@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 (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 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]

@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 (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 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]

@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 (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 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}]

@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 (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 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]