# Geometries

Geometries are responsible for actually doing the drawing. A geometry takes as input one or more aesthetics, and use data bound to these aesthetics to draw things. For instance, the `Geom.point`

geometry draws points using the `x`

and `y`

aesthetics, while the `Geom.line`

geometry draws lines with those same two aesthetics.

Core geometries:

`Gadfly.Geom.abline`

`Gadfly.Geom.bar`

`Gadfly.Geom.beeswarm`

`Gadfly.Geom.blank`

`Gadfly.Geom.boxplot`

`Gadfly.Geom.errorbar`

`Gadfly.Geom.hexbin`

`Gadfly.Geom.hline`

`Gadfly.Geom.label`

`Gadfly.Geom.line`

`Gadfly.Geom.point`

`Gadfly.Geom.polygon`

`Gadfly.Geom.rectbin`

`Gadfly.Geom.ribbon`

`Gadfly.Geom.segment`

`Gadfly.Geom.subplot_grid`

`Gadfly.Geom.violin`

`Gadfly.Geom.vline`

`Gadfly.Geom.xerrorbar`

`Gadfly.Geom.yerrorbar`

Derived geometries build on core geometries by automatically applying a default statistic:

`Gadfly.Geom.band`

`Gadfly.Geom.contour`

`Gadfly.Geom.density`

`Gadfly.Geom.density2d`

`Gadfly.Geom.ellipse`

`Gadfly.Geom.hair`

`Gadfly.Geom.hband`

`Gadfly.Geom.histogram`

`Gadfly.Geom.histogram2d`

`Gadfly.Geom.path`

`Gadfly.Geom.rect`

`Gadfly.Geom.smooth`

`Gadfly.Geom.step`

`Gadfly.Geom.vband`

`Gadfly.Geom.vector`

`Gadfly.Geom.vectorfield`

`Gadfly.Geom.abline`

— Type`Geom.abline[(; color=nothing, size=nothing, style=nothing)]`

For each corresponding pair of elements in the `intercept`

and `slope`

aesthetics, draw the lines `T(y) = slope * T(x) + intercept`

across the plot canvas, where `T(⋅)`

defaults to the identity function. If unspecified, `intercept`

defaults to [0] and `slope`

to [1].

This geometry also works with nonlinear `Scale`

transformations of the `y`

and/or `x`

variable, with one caveat: for log transformations of the `x`

variable, the `intercept`

is the `y`

-value at `x=1`

rather than at `x=0`

.

`Gadfly.Geom.bar`

— Type`Geom.bar[(; position=:stack, orientation=:vertical)]`

Draw bars of height `y`

centered at positions `x`

, or from `xmin`

to `xmax`

. If orientation is `:horizontal`

switch x for y. Optionally categorically groups bars using the `color`

aesthetic. If `position`

is `:stack`

they will be placed on top of each other; if it is `:dodge`

they will be placed side by side. For labelling dodged or stacked bar plots see `Stat.dodge`

. If `position`

is `:identity`

then the bars can overlap (use the `alpha`

aesthetic).

`Gadfly.Geom.beeswarm`

— Type`Geom.beeswarm[; (orientation=:vertical, padding=0.1mm)]`

Plot the `x`

and `y`

aesthetics, the former being categorical and the latter continuous, by shifting the x position of each point to ensure that there is at least `padding`

gap between neighbors. If `orientation`

is `:horizontal`

, switch x for y. Points can optionally be colored using the `color`

aesthetic.

`Gadfly.Geom.blank`

— Type`Geom.blank`

A blank geometry is drawn, and guides maybe drawn if aesthetics are provided.

`Gadfly.Geom.boxplot`

— Type`Geom.boxplot[(; method=:tukey, suppress_outliers=false)]`

Draw box plots of the `middle`

, `lower_hinge`

, `upper_hinge`

, `lower_fence`

, `upper_fence`

, and `outliers`

aesthetics. The categorical `x`

aesthetic is optional. If `suppress_outliers`

is true, don't draw points indicating outliers.

Alternatively, if the `y`

aesthetic is specified instead, the middle, hinges, fences, and outliers aesthetics will be computed using `Stat.boxplot`

.

Boxplots will be automatically dodged by specifying a `color`

aesthetic different to the `x`

aesthetic.

`Gadfly.Geom.errorbar`

— Type`Geom.errorbar`

Draw vertical error bars if the `x`

, `ymin`

, and `ymax`

aesthetics are specified and/or horizontal error bars for `y`

, `xmin`

, and `xmax`

. Optionally color them with `color`

.

See also `Geom.xerrorbar`

and `Geom.yerrorbar`

.

`Gadfly.Geom.hexbin`

— Type`Geom.hexbin[(; xbincount=200, ybincount=200)]`

Bin the `x`

and `y`

aesthetics into tiled hexagons and color by count. `xbincount`

and `ybincount`

specify the number of bins. This behavior relies on the default use of `Stat.hexbin`

.

Alternatively, draw hexagons of size `xsize`

and `ysize`

at positions `x`

and `y`

by passing `Stat.identity`

to `plot`

and manually binding the `color`

aesthetic.

`Gadfly.Geom.hline`

— Type`Geom.hline[(; color=nothing, size=nothing, style=nothing)]`

Draw horizontal lines across the plot canvas at each position in the `yintercept`

aesthetic.

`Gadfly.Geom.label`

— Type`Geom.label[(; position=:dynamic, hide_overlaps=true)]`

Place the text strings in the `label`

aesthetic at the `x`

and `y`

coordinates on the plot frame. Offset the text according to `position`

, which can be `:left`

, `:right`

, `:above`

, `:below`

, `:centered`

, or `:dynamic`

. The latter tries a variety of positions for each label to minimize the number that overlap.

`Gadfly.Geom.line`

— Type`Geom.line[(; preserve_order=false, order=2)]`

Draw a line connecting the `x`

and `y`

coordinates. Optionally plot multiple lines according to the `group`

, `color`

, `alpha`

, or `linestyle`

aesthetics. `order`

controls whether the lines(s) are underneath or on top of other forms.

Set `preserve_order=true`

to *not* sort the points according to their position along the x axis, or use the equivalent `Geom.path`

alias.

`Gadfly.Geom.point`

— Type`Geom.point`

Draw scatter plots of the `x`

and `y`

aesthetics.

**Optional Aesthetics**

`color`

: Categorical data will choose maximally distinguishable colors from the LCHab color space. Continuous data will map onto LCHab as well. Colors can also be specified explicitly for each data point with a vector of colors of length(x). A vector of length one specifies the color to use for all points. Default is`Theme.default_color`

.`shape`

: Categorical data will cycle through`Theme.point_shapes`

. Shapes can also be specified explicitly for each data point with a vector of shapes of length(x). A vector of length one specifies the shape to use for all points. Default is`Theme.point_shapes[1]`

.`size`

: Categorical data and vectors of`Ints`

will interpolate between`Theme.point_size_{min,max}`

. A continuous vector of`AbstractFloats`

or`Measures`

of length(x) specifies the size of each data point explicitly. A vector of length one specifies the size to use for all points. Default is`Theme.point_size`

.`alpha`

: Categorical data will use the alpha palette in`Theme.alphas`

. Continuous data will remap from 0-1. Default is`Theme.alphas[1]`

.

`Gadfly.Geom.polygon`

— Type`Geom.polygon[(; order=0, fill=false, preserve_order=false)]`

Draw polygons with vertices specified by the `x`

and `y`

aesthetics. Optionally plot multiple polygons according to the `group`

, `color`

, `linestyle`

, and/or `alpha`

aesthetics. `order`

controls whether the polygon(s) are underneath or on top of other forms. If `fill=true`

, fill the polygons using `Theme.lowlight_color`

and stroke the polygons using `Theme.discrete_highlight_color`

. If `fill=false`

stroke the polygons using `Theme.lowlight_color`

. If `preserve_order=true`

connect points in the order they are given, otherwise order the points around their centroid.

`Gadfly.Geom.rectbin`

— Type`Geom.rectbin`

Draw equal sizes rectangles centered at `x`

and `y`

positions. Optionally specify their `color`

.

`Gadfly.Geom.ribbon`

— Type`Geom.ribbon[(; fill=true)]`

Draw a ribbon at the positions in `x`

bounded above and below by `ymax`

and `ymin`

, respectively. Optionally draw multiple ribbons by grouping with `color`

and `alpha`

(for `fill=true`

), or `color`

and `linestyle`

(for `fill=false`

).

`Gadfly.Geom.segment`

— Type`Geom.segment[(; arrow=false, filled=false)]`

Draw line segments from `x`

, `y`

to `xend`

, `yend`

. Optionally specify their `color`

. If `arrow`

is `true`

a `Scale`

object for both axes must be provided. If `filled`

is `true`

the arrows are drawn with a filled polygon, otherwise with a stroked line.

`Gadfly.Geom.subplot_grid`

— Type`Geom.subplot_grid[(elements...)]`

Draw multiple subplots in a grid organized by one or two categorial vectors.

**Optional Aesthetics**

`xgroup`

,`ygroup`

: Arrange subplots on the X and Y axes, respectively, by categorial data.`free_x_axis`

,`free_y_axis`

: Whether the X and Y axis scales, respectively, can differ across the subplots. Defaults to`false`

. If`true`

, scales are set appropriately for individual subplots.

One or both of `xgroup`

or `ygroup`

must be bound. If only one, a single column or row of subplots is drawn, if both, a grid.

**Arguments**

Unlike most geometries, `Geom.subplot_grid`

is typically passed one or more parameters. The constructor works for the most part like the `layer`

function. Arbitrary plot elements may be passed, while aesthetic bindings are inherited from the parent plot.

`Gadfly.Geom.violin`

— Type`Geom.violin[(; order=1)]`

Draw `y`

versus `width`

, optionally grouping categorically by `x`

and coloring with `color`

. Alternatively, if `width`

is not supplied, the data in `y`

will be transformed to a density estimate using `Stat.violin`

`Gadfly.Geom.vline`

— Type`Geom.vline[(; color=nothing, size=nothing, style=nothing)]`

Draw vertical lines across the plot canvas at each position in the `xintercept`

aesthetic.

`Gadfly.Geom.xerrorbar`

— Type`Geom.xerrorbar`

Draw horizontal error bars at `y`

from `xmin`

to `xmax`

. Optionally color them with `color`

.

`Gadfly.Geom.yerrorbar`

— Type`Geom.yerrorbar`

Draw vertical error bars at `x`

from `ymin`

to `ymax`

. Optionally color them with `color`

.

`Gadfly.Geom.band`

— Method`Geom.band[(; orientation=:vertical)]`

Draw bands across the plot canvas with a horizontal span specifed by `xmin`

and `xmax`

if `orientation`

is `:vertical`

, or a vertical span specified by `ymin`

and `ymax`

if the `orientation`

is `:horizontal`

.

`Gadfly.Geom.contour`

— Method`Geom.contours[(; levels=15, samples=150, preserve_order=true)]`

Draw contour lines of the 2D function, matrix, or DataFrame in the `z`

aesthetic. This geometry is equivalent to `Geom.line`

with `Stat.contour`

; see the latter for more information.

`Gadfly.Geom.density`

— Method`Geom.density[(; bandwidth=-Inf)]`

Draw a line showing the density estimate of the `x`

aesthetic. This geometry is equivalent to `Geom.line`

with `Stat.density`

; see the latter for more information.

`Gadfly.Geom.density2d`

— Method`Geom.density2d[(; bandwidth=(-Inf,-Inf), levels=15)]`

Draw a set of contours showing the density estimate of the `x`

and `y`

aesthetics. If grouped by `color`

, then contour lines are mapped to `linestyle`

. This geometry is equivalent to `Geom.line`

with `Stat.density2d`

; see the latter for more information.

`Gadfly.Geom.ellipse`

— Method`Geom.ellipse[(; distribution=MvNormal, levels=[0.95], nsegments=51, fill=false)]`

Draw a confidence ellipse, using a parametric multivariate distribution, for a scatter of points specified by the `x`

and `y`

aesthetics. Optionally plot multiple ellipses according to the `group`

and/or `color`

aesthetics. `levels`

are auto-mapped to the `linestyle`

aesthetic. This geometry is equivalent to `Geom.polygon`

with `Stat.ellipse`

; see the latter for more information.

`Gadfly.Geom.hair`

— Method`Geom.hair[(; intercept=0.0, orientation=:vertical)]`

Draw lines from `x`

, `y`

to y=`intercept`

if `orientation`

is `:vertical`

or x=`intercept`

if `:horizontal`

. Optionally specify their `color`

. This geometry is equivalent to `Geom.segment`

with `Stat.hair`

.

`Gadfly.Geom.hband`

— Method`Geom.hband[()]`

Draw horizontal bands across the plot canvas with a vertical span specified by `ymin`

and `ymax`

aesthetics.

This geometry is equivalent to `Geom.band`

with `orientation`

set to `:vertical`

.

`Gadfly.Geom.histogram`

— Method```
Geom.histogram[(; position=:stack, bincount=nothing, minbincount=3, maxbincount=150,
orientation=:vertical, density=false, limits=NamedTuple())]
```

Draw histograms from a series of observations in `x`

or `y`

optionally grouping by `color`

. This geometry is equivalent to `Geom.bar`

with `Stat.histogram`

; see the latter for more information.

`Gadfly.Geom.histogram2d`

— Method```
Geom.histogram2d[(; xbincount=nothing, xminbincount=3, xmaxbincount=150,
ybincount=nothing, yminbincount=3, ymaxbincount=150)]
```

Draw a heatmap of the `x`

and `y`

aesthetics by binning into rectangles and indicating density with color. This geometry is equivalent to `Geom.rect`

with `Stat.histogram2d`

; see the latter for more information.

`Gadfly.Geom.path`

— Method`Geom.path`

Draw lines between `x`

and `y`

points in the order they are listed. This geometry is equivalent to `Geom.line`

with `preserve_order=true`

.

`Gadfly.Geom.rect`

— Method`Geom.rect`

Draw colored rectangles with the corners specified by the `xmin`

, `xmax`

, `ymin`

and `ymax`

aesthetics. Optionally specify their `color`

.

`Gadfly.Geom.smooth`

— Method`Geom.smooth[(; method:loess, smoothing=0.75)]`

Plot a smooth function estimated from the line described by `x`

and `y`

aesthetics. Optionally group by `color`

and plot multiple independent smooth lines. This geometry is equivalent to `Geom.line`

with `Stat.smooth`

; see the latter for more information.

`Gadfly.Geom.step`

— Method`Geom.step[(; direction=:hv)]`

Connect points described by the `x`

and `y`

aesthetics using a stepwise function. Optionally group by `color`

or `group`

. This geometry is equivalent to `Geom.line`

with `Stat.step`

; see the latter for more information.

`Gadfly.Geom.vband`

— Function`Geom.vband[()]`

Draw vertical bands across the plot canvas with a horizontal span specified by `xmin`

and `xmax`

aesthetics.

This geometry is equivalent to `Geom.band`

.

`Gadfly.Geom.vector`

— Method`Geom.vector[(; filled=false)]`

This geometry is equivalent to `Geom.segment(arrow=true)`

.

`Gadfly.Geom.vectorfield`

— Method`Geom.vectorfield[(; smoothness=1.0, scale=1.0, samples=20, filled=false)]`

Draw a gradient vector field of the 2D function or a matrix in the `z`

aesthetic. This geometry is equivalent to `Geom.segment`

with `Stat.vectorfield`

; see the latter for more information.