Package 'gog'

Description

Derive a compound layer atom from a mark and a transform.

Usage

## S3 method for class 'gog_atom'
e1 * e2

## S3 method for class 'gog_callable'
e1 * e2

Arguments

Value

A layer gog_atom carrying the mark and its transforms.

Description

Compose plot atoms with +.

Usage

## S3 method for class 'gog_spec'
lhs + rhs

Arguments

Value

A gog_spec carrying both sides.

Description

Bin a continuous variable into equal-width buckets (the histogram transform).

Usage

bin(bins = NULL, width = NULL, tiling = NULL, ...)

Arguments

Description

Pre-computed bounds.

Usage

bounds(lower, upper, start, end)

Arguments

Description

Box-and-whisker mark.

Usage

box(whiskers = NULL)

Arguments

Description

brush puts a bound on one column's values. Rows inside it keep the plot's colors; rows outside it are dimmed, so a selection is read against what it was taken from. Where the page can run the engine, dragging moves the bound; on paper it stays where the sentence put it.

Usage

brush(field, at = NULL)

Arguments

Details

A brush highlights. It never removes rows. Removing rows before the statistics run is what limits does, on the binding, and it counts what it dropped. The two are the same shape and different operations: change a domain and a histogram re-bins the survivors, brush it and the same bars stay, with the selected part standing out.

One column per brush. Write two for a rectangle: brush(gdp, at = c(1200, 45000)) + brush(life, at = c(55, 78)).

A mark can be brushed when one row is one shape: point, text, rule and zone. A line draws one shape through many rows, so there is no single row to select, and gog says so rather than guessing. A summarized layer is drawn whole, because a selection of twelve of a bar's forty rows has no honest picture.

Value

A gog_atom added to a plot with +.

Description

The leaves are the levels of the bound categorical position, and each one is described by a profile: its value at every level of the over column. The engine measures the distance between every pair of profiles, joins the closest two, and keeps joining until one tree holds them all. The other position stays unbound and carries the merge distance, which the axis names itself.

Usage

cluster(value, over)

Arguments

Details

Two marks read the one tree. path * cluster(amount, over = nutrient) + x(food) draws it: each join stands at the height its two branches merged, so the reader can see which leaves sit close and where the groups part. y(food) instead lays the same tree on its side. zone * cluster(over = nutrient) is the other reading: the tile plot unchanged, with the leaf axis's slots reordered to the tree's leaf order, so alike rows sit together. On a tile plot the values are already on color, which is why value is omitted there.

Composed with | and /, a clustered panel decides the order of any axis it shares, which is what puts a tree flush against a reordered tile plot.

The statistic is fixed: distances are Euclidean on the values as given, and branches join at their average distance. Rescale the value column where the data lives if its units should not weigh in.

Description

Map fill/stroke color to a column.

Usage

color(
  field,
  scale = NULL,
  base = NULL,
  limits = NULL,
  tick_count = NULL,
  speed = NULL,
  free = FALSE,
  legend = NULL,
  axis = NULL,
  decimals = NULL,
  short = NULL
)

Arguments

Description

gog writes American English throughout and accepts no second spelling, which is Law 2 applied to the vocabulary itself: two ways to write one word is a silent letter, and the reader pays for it. ggplot2 accepts colour and color both, so a reader arriving from there types colour and, unexported, would meet R's "could not find function" — a message that names no fix. Exported for the same reason JavaScript still exports facet (spec §13): a word a reader will plausibly type earns a refusal that says what to write instead.

Usage

colour(...)

Arguments

Description

Confidence interval of the mean per group, for the interval mark.

Usage

confidence(level = NULL)

Arguments

Description

cumulative adds each position's value to the values before it, in the order the axis draws its positions: left to right on a number, in the categories' own order on a category. It adds up what the layer already measures – the column named on y, or what a transform before it made – and every mark draws the total as it draws any measure. The total is the column cumulative, while the measure's own column keeps each row's value, so label(count) and label(cumulative) print the two.

Usage

cumulative(share = NULL)

Arguments

Details

Each color or group split runs its own total. A category axis is added up in its declared order, so sort it in the table rather than with order().

Value

A gog_atom joined to a mark with *.

See Also

transforms for the measures it adds up; stack(), which adds up the groups at one position instead of the positions of one group.

Examples

# Each year's sales added to the years before it.
sales <- data.frame(year = 2019:2023, sales = c(120, 135, 128, 150, 162))
r <- data(sales) + line * cumulative + x(year) + y(sales)

# The cumulative histogram, and one distribution function per species.
h <- data(iris) + step * bin * cumulative + x(Sepal.Length)
e <- data(iris) + step * bin * cumulative(share = TRUE) + x(Sepal.Length) +
  color(Species)

Description

Every plot begins by naming its table. The columns are then written as bare names in the channels that follow, and the nearest table wins where a plot has more than one.

Arguments

Details

Masks utils::data(), R's dataset loader. Use utils::data() to load a built-in dataset; this one binds a table you already have. Both readings of data(mtcars) are well formed, so that one case cannot be told apart and is the reason the collision is documented rather than caught.

Value

A gog_spec – the start of a sentence, extended with +.

Usage

data(df, name = NULL)

The Usage section is written out here rather than generated, because ⁠R CMD check⁠ reads a generated ⁠\usage\{data(...)\}⁠ as base R's dataset loader and then reports df as a missing dataset. Suppressing the generated one is the documented way out; the signature is not lost, only moved.

Examples

p <- data(mtcars) + point + x(wt) + y(mpg)

# Naming the table explicitly, which matters when a plot has more than one.
q <- data(mtcars, name = "cars") + point + x(wt) + y(mpg)

Description

Estimate the smooth probability density of a continuous variable (a KDE).

Usage

density(
  adjust = NULL,
  bandwidth = NULL,
  levels = NULL,
  compare = NULL,
  reach = NULL
)

Arguments

Description

Spread band per group, mean +/- k standard deviations.

Usage

deviation(multiplier = NULL)

Arguments

Description

facet() joins the plot with the facet operators, not +:

Usage

facet(field, wrap = NULL)

Arguments

Details

plot | facet(cyl)               one panel per category, side by side
plot / facet(drv)               one panel per category, stacked
plot / facet(drv) | facet(cyl)  crossed into a grid (rows x columns)

The panels share one scale — that is what makes them comparable — and any transform in the plot runs within each panel's rows. The facet column must be a category column: a number is a position along an axis, not a name for a panel.

wrap folds a long line of panels into a rectangle: twelve countries side by side are twelve slivers, and wrap = 4 makes them a 4 x 3 grid. The number is how many panels before the line turns, and which way the line runs is the operator's to say, not wrap's:

plot | facet(country, wrap = 4)  levels run across, 4 to a row
plot / facet(country, wrap = 4)  levels run down, 4 to a column

That is one number where ggplot2 has nrow and ncol, and it cannot contradict itself. Wrapping a crossed facet is refused: a crossing already fills a rectangle.

Description

| facets into panel columns and sets plots side by side; / facets into panel rows and sets them one above the other.

Usage

## S3 method for class 'gog_spec'
e1 | e2

## S3 method for class 'gog_spec'
e1 / e2

Arguments

Value

A faceted gog_spec, or a gog_arrangement when two plots are composed.

Description

The stages arrive as columns, in reading order: one row of the table is one path through all of them, and flow(class, sex, survived) runs each row from its class to its survived. Rows sharing a path add together, which quietly sets aside any column the atom did not name.

Usage

flow(..., shared = FALSE, layered = FALSE)

Arguments

Details

Three marks read the one layout. ribbon * flow(...) draws the bands, a path's magnitude carried between adjacent stages; zone * flow(...) draws each stage's slots, stacked with no padding so the measure axis stays honest; text * flow(...) + label(name) names each slot where it sits. Layer any two or all three.

What each path is weighed by rides on y: + y(count) weighs that column, and binding nothing at all makes every path weigh 1. Bound to x instead, the count runs the stages from top to bottom. On the band layer, ⁠color(<stage>)⁠ colors every band by the category its path holds at that stage, and color() of any other categorical column splits each band by its values; the slots take their paint from style().

The stage axis is drawn from the atom's own columns, so there is nothing for x() to say — to reorder the stages, reorder the arguments.

Two columns that name one set of places take shared = TRUE: flow(exporter, importer, shared = TRUE) reads each row as an amount leaving one place and arriving at another, gives each place one slot whichever column names it, and lays every slot on the one count axis. Flat, that draws the arc diagram, each band arching from one place to the other; in polar() the count goes around the circle and it draws the chord diagram. Each slot is in two parts with no line between them: the ends where the place is named in the first column, in the slot's color, then the ends where it is named in the second, a shade darker. So flow(importer, exporter, shared = TRUE) shades the exports instead of the imports. The panel is white and has no frame unless theme() says otherwise, since the plot has no numbers to read.

A list of links whose places stand in layers takes layered = TRUE: flow(source, target, layered = TRUE) reads each row as an amount moving from one place to another, and puts each place in the first layer after every place that sends to it. That draws the Sankey diagram: a band may skip a layer, and a flow may stop before the last layer. Each layer is sorted by where its places' partners are, the places of a layer stand a gap apart, and each name stands beside its slot. Links that form a cycle have no layers and are refused.

Description

The globe coordinate space. x is longitude and y is latitude, both in degrees, and each mark stands at its place on the sphere's surface. The marks that draw on a map() draw here: point is a place, path is a route bending along great circles, text is a name at a place, rule holds one coordinate whole (a meridian pole to pole, or a parallel all the way round), and zone with group() fills each region of a boundary. The graticule is the panel grid, turned off like any other with theme(grid = "none").

Usage

globe(turn = 0, tilt = 0)

Arguments

Details

A globe shows one half of the earth. turn and tilt name the place the view faces, in the words space() already uses: globe(turn = 178, tilt = -18) puts Fiji at the center of the disk. A bearing wraps, so any turn is a view; tilt is a latitude and stops at the poles. Rows on the far half are hidden behind the sphere, and gog says how many rather than dropping them in silence. In the web edition, dragging the globe turns it.

Both positions are spent on the place, so a mark that measures along an axis has none left; carry a quantity on size() or color() instead, as on a map. A binned field on the sphere is designed and not drawn yet: its correct tiling is hexagonal, because rectangular bins do not cover equal area on a sphere, and that equal-area grid is not built.

Examples

## Not run: 
data(quakes_fiji) + point + x(east) + y(north) + size(magnitude) +
  globe(turn = 178, tilt = -18)
data(borders) + zone + x(lon) + y(lat) + group(country) +
  color(continent) + globe(turn = 20, tilt = 5)

## End(Not run)

Description

Fetches a table published beside the manual and returns it ready to plot. The full list of names is in the book's data chapter.

Usage

gog_table(name, text = character())

Arguments

Value

A data frame.

Examples

## Not run: 
gapminder_2007 <- gog_table("gapminder_2007")
data(gapminder_2007) + point + x(gdp) + y(life)

# `session` holds labels that look like numbers, so it stays text.
sessions <- gog_table("sessions", text = "session")

## End(Not run)

Description

Group line/path marks by a column (connects points within the same group). Use color(field) when you also want color distinction — it implies grouping.

Usage

group(
  field,
  scale = NULL,
  base = NULL,
  limits = NULL,
  tick_count = NULL,
  speed = NULL,
  free = FALSE,
  legend = NULL,
  axis = NULL,
  decimals = NULL,
  short = NULL
)

Arguments

Value

A gog_atom added to a plot with +.

Description

Spread a strip plot's coincident points apart, along the categorical axis only.

Usage

jitter(amount = NULL)

Arguments

Description

knitr print method for an arrangement.

Usage

knit_print.gog_arrangement(x, ...)

Arguments

Description

knitr print method: the plot inline as SVG in HTML, and as a converted

Usage

knit_print.gog_spec(x, ...)

Arguments

Description

label supplies the string a text mark draws, the way x and y supply its position: text + x(a) + y(b) + label(name). A string column is drawn as-is, a numeric one is formatted. It is text's required channel — no other mark accepts it, so a labeled scatter is the superposition point + text. A scale is refused: a label is content, like shape, not a magnitude to run a scale along.

Usage

label(
  field,
  scale = NULL,
  base = NULL,
  limits = NULL,
  tick_count = NULL,
  speed = NULL,
  free = FALSE,
  legend = NULL,
  axis = NULL,
  decimals = NULL,
  short = NULL
)

Arguments

Value

A gog_atom added to a plot with +.

Description

The two columns name each row's endpoints, and one row of the table is one edge between its two values. The nodes derive: their names from the columns' union, their degree by counting the rows that name them. The engine computes every position, the same way in every binding, so one table is one picture wherever it is drawn.

Usage

layout(from, to)

Arguments

Details

Three marks read the one placement, inside network(). edge * layout(from, to) draws the connections, point * layout(...) the nodes, and text * layout(...) + label(name) names them. On the node layers, size(degree) and color(degree) read that count.

The positions mean nothing as quantities – the picture can be mirrored without changing what the graph says – so nothing binds to x, y or z, and the third dimension, when you want it, is the space's: network(turn = 30, tilt = 25).

Description

The cartographic coordinate space. x is longitude and y is latitude, both in degrees, and the projection decides where each place lands. Nothing else about the sentence changes: point is a place, path is a route through places in the table's order, text is a name at a place, and rule spans the axis it does not name, which on a map is a meridian or a parallel.

Usage

map(preserve = "area")

Arguments

Details

Both positions are spent on the place, so a mark that measures along an axis has none left. Carry a quantity on a channel instead. ⁠size(<column>)⁠ gives the proportional-symbol map and ⁠color(<column>)⁠ shades each place, which is what cartography does once the two axes are gone.

A sphere cannot be laid flat without giving something up, and area and angle cannot both survive. preserve names which one does:

• "area" – every region gets ink in proportion to its true size. The default, because a map is usually read by area: a projection that inflates Greenland says something false about the number inside it. Uses the Equal Earth projection, which reaches both poles.

• "angle" – every small shape keeps its true form, and area is what pays. Uses Mercator, so Greenland arrives the size of Africa while being fourteen times smaller. Mercator sends the poles infinitely far away, so it stops at 85.05 degrees and says how many rows it could not reach.

The panel is shaped by the projection rather than by the page, so theme(ratio = ) is refused here: an equal-area map stretched to fit a box is no longer equal-area, though it still looks like a map.

Examples

## Not run: 
data(quakes_fiji) + point + x(east) + y(north) + size(magnitude) + map()
data(borders) + path + x(lon) + y(lat) + group(country) + map()
data(borders) + path + x(lon) + y(lat) + group(country) +
  map(preserve = "angle")

## End(Not run)

Description

A mark is the shape a layer draws, and every plot needs exactly one. A mark carries no data of its own: it is combined with channels that say which column goes to which part of the picture, and the engine decides every stroke from there.

Usage

point

line

path

rule

zone

area

bar

step

interval

ribbon

text

surface

edge

Format

Each is a gog_atom object, used bare rather than called.

Details

Marks are the grammar's consonants. They are plain objects rather than functions, so they are written bare in a sentence:

data(table) + point + x(column) + y(column)

A mark and its required positions together are the smallest thing that draws; neither renders alone. Which channels a mark accepts is a property of the mark, and asking for one it cannot carry is refused with a direction rather than silently ignored.

The marks

point

One glyph per row. How two measurements move together.

line

Connects rows in x order. How one value changed over time.

path

Connects rows in data order rather than x order, so a series may double back on itself.

area

Fills the region between the line and the baseline.

bar

A rectangle from the baseline to the value. How large each category is.

step

The line family's right-angled member: a value holds steady until it jumps.

interval

A segment from a low value to a high one. Needs a pair, so it is usually written with range or confidence.

ribbon

A band between two values across a span.

text

Draws the string given by label at each position.

rule

A reference line across the panel – the threshold everything else is compared against.

zone

Shades a rectangular region of the panel.

surface

A sheet over a grid of samples, for three-dimensional data.

box is a mark too, but takes an argument, so it is documented separately.

See Also

box() for the box-and-whisker mark; x() and y() for positions; style() for settings that do not vary with the data.

Examples

# A mark plus its positions is the smallest sentence that draws.
p <- data(mtcars) + point + x(wt) + y(mpg)

# The same data, a different shape: one atom is all that changes.
q <- data(mtcars) + line + x(wt) + y(mpg)

Description

The nested coordinate space, and the treemap is what it draws. Every row's measure becomes an area rather than a length, and the areas partition the panel: a region's share of the picture is its share of the total.

Usage

nest()

Details

Nothing else about the sentence changes, which is what makes this a space and not a chart type. bar * sum + y(revenue) + color(region) is a stacked column flat, a pie in polar(), and a treemap here — three answers to the one question of what carries a share, and the words are the same in all three.

A packed panel has no axes: its two directions carry no variable, and two neighboring regions are not near each other in the data. So there is nothing to label and nothing to tick, and the color legend is what decodes the regions. Bind a position to split the packing one level further — each category gets a region of its own and its rows are packed inside it.

dodge, stack and jitter are refused here: they decide what happens when two marks land in the same place, and in a packing none can.

Examples

## Not run: 
data(sales) + bar * sum + y(revenue) + color(region) + nest()
data(sales) + bar * sum + x(region) + y(revenue) + color(product) + nest()

## End(Not run)

The graph-theoretic space – where a layout()'s placement is drawn.

Description

A layout's positions are the graph's, not the data's, so this space draws no axes, no ticks and no grid: there is nothing there for them to number. It is the one space a layout draws in, and a layout is the one thing that stands in it.

Usage

network(turn = NULL, tilt = NULL)

Arguments

Details

Stating a viewing angle states the third dimension. Bare network() draws the graph flat; network(turn = 30, tilt = 25) computes the placement in a cube and draws it from that angle, with each unstated angle taking the standard view. In the web edition the cube turns with a drag, the way the cube in space() turns.

Description

Map opacity to a numeric column.

Usage

opacity(
  field,
  scale = NULL,
  base = NULL,
  limits = NULL,
  tick_count = NULL,
  speed = NULL,
  free = FALSE,
  legend = NULL,
  axis = NULL,
  decimals = NULL,
  short = NULL
)

Arguments

Description

Every atom that takes a column is a noun naming a property, and its argument is the column that drives it — color(species), size(population), order(gold). This one was called sort_by until it became the last survivor of a _by convention that color_by → color had already retired: the suffix marked the argument as a key, which says nothing when every atom in the group takes a key.

Usage

order(field, desc = FALSE)

Arguments

Details

Masks base::order, as data, title, and palette mask theirs. Use base::order() for the base function.

Examples

## Not run: 
data(medals) + bar + x(gold) + y(country) + order(gold, desc = TRUE)

## End(Not run)

Description

Set the categorical color palette.

Usage

palette(pal)

Arguments

Description

The hierarchy arrives as columns, outermost first: one row of the table is one leaf, and partition(group, item, detail) says which columns spell the path down to it. A blank level ends that branch early, which is what gives a real hierarchy its ragged rim.

Usage

partition(..., cross = FALSE)

Arguments

Details

zone * partition(...) flat is the icicle; the same sentence + polar() is the sunburst, and that one atom is the whole difference. text * partition(...) + label(name) names each node where it sits, reading the center the same computation published.

What each branch is weighed by rides on x: + x(amount) apportions that column, and binding nothing at all makes every leaf weigh 1. Compose with proportion for shares. y(depth, limits = c(0, 4)) puts the hole in the middle, depth being the ring the transform synthesizes.

Every number belongs to a leaf. An interior node carrying one of its own is ambiguous — is its arc the children's total, or its own beside them? — so it is refused rather than guessed.

cross = TRUE turns the levels across each other instead of down one axis: the first divides the width, the second divides the height within each of those columns. That is the mosaic, and because both directions are then spent on the hierarchy there is no ring left to step and only the leaves are drawn.

Description

pattern tells categories apart by texture rather than hue: on a fill (bar/box/area/ribbon) each category draws as a hatch, on a stroke (line/step/interval) as a dash. It is the color-free way to separate series, so it survives grayscale printing and color-blindness; pairing it with color on the same column is the redundant encoding that is the accessibility best practice. A scale is refused: like shape it answers "which one?", not "how much?".

Usage

pattern(
  field,
  scale = NULL,
  base = NULL,
  limits = NULL,
  tick_count = NULL,
  speed = NULL,
  free = FALSE,
  legend = NULL,
  axis = NULL,
  decimals = NULL,
  short = NULL
)

Arguments

Details

Distinct from the style(pattern = ) setting, which fixes one texture for the whole layer; pattern() maps a column to several.

Value

A gog_atom added to a plot with +.

Description

play is facet read in time. Both split the rows by a column's distinct values; | facet(continent) lays the pieces out across the page and play(year) lays them out in sequence, so point + x(gdp) + y(life) + play(year) is the time-lapse of the same data the faceted grid shows all at once.

Usage

play(
  field,
  speed = NULL,
  scale = NULL,
  base = NULL,
  limits = NULL,
  tick_count = NULL,
  free = FALSE,
  legend = NULL,
  axis = NULL,
  decimals = NULL,
  short = NULL
)

Arguments

Details

Every scale, the color map and every legend are fitted across the whole sequence, never per frame — a scale that re-fitted would move the axis under the data and make a still point look like a moving one. A layer that does not bind play is drawn in every frame, so a reference line stands still behind the marks that move.

Unlike facet, a number is welcome: panels compete for page area, where a hundred of them are unreadable at any size, but frames compete for time, where a hundred is a longer loop rather than a smaller picture.

speed is how many times faster than normal the frames run — 2 is twice as fast, 0.5 half. Where a static image is made from the plot (the PDF of this book, or any SVG converter) the first frame is what it shows.

Value

A gog_atom added to a plot with +.

Description

The polar coordinate space. x becomes the angle and y the radius, so the axis a bar chart stands its categories on is the axis a rose wraps around the circle. Nothing else about the sentence changes: bar * count + x(month) is a bar chart flat and a rose in polar, from the same words.

Usage

polar(start = 0)

Arguments

Details

The angular axis is periodic — one turn spans exactly the fitted range of x, so the circle closes with no seam. Angles run clockwise from twelve o'clock.

Examples

## Not run: 
data(winds) + bar * count + x(direction) + polar()
data(winds) + bar * count + x(direction) + polar(start = -22.5)

## End(Not run)

Description

The p-th quantile of y per group.

Usage

quantile(p = NULL)

Arguments

Description

query() stands exactly where data() stands, and nothing after it changes — the same operators, channels, bare column names and transforms:

Usage

query(con, sql, name = NULL)

Arguments

Details

data(orders)                             + bar + x(status)
query(con, "SELECT * FROM orders")       + bar + x(status)

The SQL is confined to this one argument and never enters the grammar, which is the point: x(status) is still a bare column resolved by the same mask, not a fragment of another language.

The connection is the caller's own — gog opens none. It is a DBI connection, R's database standard, so RSQLite, RPostgres, RMariaDB, odbc and bigrquery all reach this. DBI is Suggests rather than Imports: a user who never writes SQL should not install a database stack to draw a plot.

The query is not run here. It runs once, at render.

Value

A gog_spec.

Description

Quantile band per group, for the span marks.

Usage

range(low = NULL, high = NULL)

Arguments

Description

Render a gog_spec to an SVG string.

Usage

render_svg(gog)

Arguments

Value

A character string containing the SVG.

Description

text * repel reads where the labels and the points actually sit and pushes each label a different way until they stop overlapping, drawing a thin leader line back to the point when a label has moved clear of it. Where there is no arrangement that fits, every label is still drawn and the plot reports how many are still crowded.

Usage

repel

Value

A gog_atom joined to a mark with *.

See Also

style()'s nudge, the constant offset this is the data-derived counterpart to; jitter(), the same idea for a scatter's points.

Examples

## Not run: 
# Every country named, with the names moved off one another.
gapminder_2007 <- gog_table("gapminder_2007")
p <- data(gapminder_2007) + point + text * repel +
  x(gdp) + y(life) + label(country)

## End(Not run)

Description

repr method: an arrangement as inline SVG in a Jupyter cell.

Usage

repr_html.gog_arrangement(obj, ...)

Arguments

Description

repr method: the plot as inline SVG in a Jupyter cell.

Usage

repr_html.gog_spec(obj, ...)

Arguments

Description

repr method: a one-line description of an arrangement.

Usage

repr_text.gog_arrangement(obj, ...)

Arguments

Description

repr method: a one-line description for the text/plain fallback.

Usage

repr_text.gog_spec(obj, ...)

Arguments

Description

A plot that binds play() moves in a browser, because the SVG carries its own timing. Most other places do not read that: a message to a friend, a slide, a post. This writes the same sequence as a GIF, which they do read.

Usage

save_gif(gog, path, scale = 1)

Arguments

Details

The frames come out of the one renderer, so the file cannot disagree with the plot. Every scale, the color map and each legend are fitted across the whole sequence at once, and the frames are cut from that single drawing rather than drawn again one at a time.

Nothing needs to be installed. The engine converts and encodes on its own.

Value

The path, invisibly.

Description

The drawing render_svg() returns, written to path byte for byte, so the file is the same in every binding and on every platform.

Usage

save_svg(gog, path)

Arguments

Details

The plot is drawn first and written second, so a plot gog refuses leaves a file already at path as it was.

Value

The path, invisibly.

Description

A scale is refused: shape answers "which one?", and there is no distance between circle and square for a scale to run along.

Usage

shape(
  field,
  scale = NULL,
  base = NULL,
  limits = NULL,
  tick_count = NULL,
  speed = NULL,
  free = FALSE,
  legend = NULL,
  axis = NULL,
  decimals = NULL,
  short = NULL
)

Arguments

Value

A gog_atom added to a plot with +.

Description

Map point radius to a numeric column.

Usage

size(
  field,
  scale = NULL,
  base = NULL,
  limits = NULL,
  tick_count = NULL,
  speed = NULL,
  free = FALSE,
  legend = NULL,
  axis = NULL,
  decimals = NULL,
  short = NULL
)

Arguments

Description

smooth's pair form, as confidence is mean's. At each point of the LOESS curve it gives the fit's low and high ends, so ribbon * smooth_band + line * smooth draws the trend with its band.

Usage

smooth_band(level = NULL)

Arguments

Description

Binding z is what makes a plot three-dimensional — one more vowel, not a chart type. space() sets the angle that plot is viewed from. That angle is a view parameter of the coordinate space — the way a polar plot needs a start angle — not a channel (it maps no column) and not a mark. Omit it and a 3-D plot takes a default three-quarter view that shows all three axes.

Usage

space(turn = 30, tilt = 25)

Arguments

Examples

## Not run: 
data(clusters) + point + x(a) + y(b) + z(c) +
  space(turn = -45, tilt = 30)

## End(Not run)

Description

When several marks land in the same place, something has to decide where they go. These are collision modifiers: they do not compute a statistic, they move marks that would otherwise cover each other. Like transforms they ride the * slot, so they compose with a statistic rather than replacing it – bar * count * stack bins, counts, and then piles the result.

Usage

dodge

stack(share = NULL, baseline = NULL)

Arguments

Details

stack

Piles the marks of each group end to end, so the total is the height of the pile.

dodge

Places them side by side instead, so each is measured from the same baseline and they can be compared directly. On point it moves each point across its category only as far as it must to clear its neighbors, so no two touch: the beeswarm.

On bars, boxes and whiskers both need something to separate: a color or group binding that says which mark belongs to which group. Without one there is nothing to stack or dodge, and the engine says so. point * dodge needs none, since the points in one category already collide.

Value

A gog_atom joined to a mark with *.

See Also

jitter(), which resolves overlap by displacing marks slightly rather than by arranging them; transforms for the statistics these compose with.

Examples

# Piled: the height of the pile is the total.
s <- data(mtcars) + bar * count * stack + x(cyl) + color(gear)

# Side by side: each bar measured from the same baseline.
d <- data(mtcars) + bar * count * dodge + x(cyl) + color(gear)

# Every pile the same height, so the plot shows shares.
f <- data(mtcars) + bar * count * stack(share = TRUE) + x(cyl) + color(gear)

Description

Channels map: color(species) asks the reader "which species?" and earns a legend to answer it. style() sets: it fixes a visual property at one value for the whole layer, maps no column, consumes no scale, and produces no legend — there is nothing to decode.

Usage

style(
  color = NULL,
  opacity = NULL,
  size = NULL,
  shape = NULL,
  border_color = NULL,
  border_size = NULL,
  caps = NULL,
  center = NULL,
  nudge = NULL,
  pattern = NULL,
  arrow = NULL,
  reach = NULL,
  angle = NULL,
  gap = NULL,
  ...
)

Arguments

Details

A constant is therefore not a channel, by the same reasoning that keeps rotation out of the channel set: a channel maps a data column to a visual feature, and a constant maps nothing.

Examples

## Not run: 
data(df) + x(a) + y(b) + point + style(color = "tomato", opacity = 0.3)
data(df) + x(a) + y(b) + line + style(color = "gray70", size = 1)

## End(Not run)

Description

Everything here maps no column, so each is a setting; but none of it belongs to a mark either, which is why it is not style(). A layer has no gridlines and a plot has no fill, so the two property sets are disjoint and telling them apart by where they were written would make a sub-expression mean different things in different places (Law 6). Spec §7 is the ruling.

Usage

theme(
  preset = NULL,
  grid = NULL,
  ratio = NULL,
  tick_angle = NULL,
  font_size = NULL,
  background = NULL,
  strip = NULL,
  strip_text = NULL,
  frame = NULL,
  axis_label = NULL,
  legend = NULL,
  width = NULL,
  height = NULL,
  gap = NULL
)

Arguments

Details

A named preset comes first and anything named adjusts it, because a preset you cannot adjust sends you straight back to asking for knobs.

Description

Set the plot title.

Usage

title(text)

Arguments

Description

A transform replaces the rows with a summary of them, and the mark then draws that summary. It is joined to a mark with *, which reads as derivation: bar * count is a bar of counts, and it is where a histogram comes from rather than being a chart type to look up.

Usage

smooth

count

sum

mean

median

max

min

proportion

Format

Each is a gog_atom object, used bare rather than called.

Details

The same transform behaves identically on every mark it is legal on. Keep the statistic and change the shape and the same numbers draw a line, an area or a step – that is the point of separating the two.

The transforms

count

The number of rows for each value of the grouping position.

proportion

Each group's share of the total, rather than its count.

sum, mean, median, max, min

The aggregate of the measure within each group.

range

The lowest and highest value in each group, as a pair – which is what interval and ribbon need.

smooth

A fitted trend through the points rather than the points.

Transforms that take an argument are documented on their own pages: bin(), density(), confidence(), bounds(), partition(), cumulative(). stack(), dodge and jitter() are a different kind of atom – they resolve the overlap of marks rather than computing a statistic.

See Also

marks for the shapes these are drawn with; stack() for resolving overlap.

Examples

# A histogram is a bar of binned counts -- derived, not a chart type.
h <- data(mtcars) + bar * count + x(cyl)

# The same statistic, a different shape.
l <- data(mtcars) + line * count + x(cyl)

# An aggregate of a measure within each group.
m <- data(mtcars) + bar * mean + x(cyl) + y(mpg)

Description

Bind the x-axis to a column.

Usage

x(
  field,
  scale = NULL,
  base = NULL,
  limits = NULL,
  tick_count = NULL,
  speed = NULL,
  free = FALSE,
  legend = NULL,
  axis = NULL,
  decimals = NULL,
  short = NULL
)

Arguments

Examples

## Not run: 
data(gapminder_2007) + point + x(gdp, scale = "log") + y(life)
data(audio) + line + x(freq, scale = "log", base = 2) + y(level)

## End(Not run)

Description

Override the x-axis label.

Usage

x_label(text)

Arguments

Description

Bind the y-axis to a column.

Usage

y(
  field,
  scale = NULL,
  base = NULL,
  limits = NULL,
  tick_count = NULL,
  speed = NULL,
  free = FALSE,
  legend = NULL,
  axis = NULL,
  decimals = NULL,
  short = NULL
)

Arguments

Description

Override the y-axis label.

Usage

y_label(text)

Arguments

Description

Bind the z-axis to a column.

Usage

z(
  field,
  scale = NULL,
  base = NULL,
  limits = NULL,
  tick_count = NULL,
  speed = NULL,
  free = FALSE,
  legend = NULL,
  axis = NULL,
  decimals = NULL,
  short = NULL
)

Arguments

Description

The third position takes a label override for the same reason it takes a scale and a tick: the positions are a family of three, and two of them having one is the per-channel exception the orthogonality law catches. Read only in 3-D, where the axis names sit on the projected cube's edges.

Usage

z_label(text)

Arguments