chronochrt (version 0.1.4)

geom_chronochRt: A chronological chart

Description

Computes and draws a chronological chart.

Usage

geom_chronochRt(
  mapping = NULL,
  data = NULL,
  inherit.aes = TRUE,
  year_lim = NULL,
  minimal = FALSE,
  ...
)

Value

Layer of a ggplot2 object.

Arguments

mapping

Set of aesthetic mappings created by aes(). If specified and inherit.aes = TRUE (the default), it is combined with the default mapping at the top level of the plot. You must supply mapping if there is no plot mapping.

data

The data to be displayed in this layer. There are three options:

If NULL, the default, the data is inherited from the plot data as specified in the call to ggplot().

A data.frame, or other object, will override the plot data. All objects will be fortified to produce a data frame. See fortify() for which variables will be created.

A function will be called with a single argument, the plot data. The return value must be a data.frame, and will be used as the layer data. A function can be created from a formula (e.g. ~ head(.x, 10)).

inherit.aes

If FALSE, overrides the default aesthetics, rather than combining with them. This is most useful for helper functions that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. annotation_borders().

year_lim

A numeric vector of length 2 to define the lower and upper limit of the chronological chart.

minimal

Should chrons be optically separated by vertical lines? If TRUE only vertical lines between around the chronological columns will be drawn.

...

Other arguments passed on to layer. These are often aesthetics, used to set an aesthetic to a fixed value, like hjust = 0.1.

Aesthetics

geom_ChronochRt() understands the following aesthetics (required aesthetics are in bold):

• region

• level

• end

• start

• add

• alpha

• angle

• colour

• family

• fill

• fontface

• group

• hjust

• lineheight

• name|label

• name_x

• name_y

• size_line

• size_text

• vjust

See Details for how aesthetics specific for this geom work and learn more about setting aesthetics in vignette("ggplot2-specs").

Details

This geom is special because no x and y coordinates are provided in the input. Therefore, the following aesthetics must be provided only in the aes function: region, level, start, end, add (i.e. all required aesthetics).

• region The title(s) of the section(s) the chronological chart is subdivided into

• name The name(s) of the chronological unit(s). To maintain compatibility with other geoms, the aesthetic label can be used instead.

• start, end The start and end date of a chronological unit, respectively.

• level The levels of the chronological units.

• add Logical value indicating whether chronological units within a region should be plotted in an additional column.

Usually, the names of the chronological units are placed in their middle. They can be arbitrarily placed by the aesthetics name_x, name_y:

• name_x The horizontal position within an chronological column, i.e. a value between 0 and 1 if add = FALSE and between 1 and 2 if add = TRUE.

• name_y The vertical position given as a year.

See vignette("ChronochRt") below for further details.

The geom aims to preserve access to as much of the underlying aesthetics as possible. To achieve this aim, ambiguous names were resolved (e.g. size to size_line and size_text).

Examples

# Create example data
library(ggplot2)

chrons <- data.frame(region = c("A", "B", "B", "B", "A"),
                     name = c("a", "a", "1", "2", "b"),
                     start = c(-100, -100, -100, "0/50", "50_100"),
                     end = c("50_100", 150, "0/50", 150, 200),
                     level = c(1, 1, 2, 2, 1),
                     add = FALSE)

ggplot(chrons) +
geom_chronochRt(aes(name = name, region = region, level = level,
                    start = start, end = end, add = add))

ggplot(chrons, aes(name = name, region = region, level = level,
                   start = start, end = end, add = add)) +
   geom_chronochRt()

# If more than one region should be plotted, they must be separated with
# facet_grid():
ggplot(chrons) +
   geom_chronochRt(aes(name = name, region = region, level = level,
                       start = start, end = end, add = add)) +
   facet_grid(cols = vars(region), scales = "free_x", space = "free_x")

# Adjust upper and lower end of a chronological chart with year_lim:
q <- ggplot(chrons, aes(name = name, region = region, level = level,
                        start = start, end = end, add = add)) +
   facet_grid(cols = vars(region), scales = "free_x", space = "free_x")

q + geom_chronochRt(year_lim = c(-50, 100))

# Change aesthetics of the plot:
q + geom_chronochRt(fill = "black", colour = "white")
q + geom_chronochRt(aes(fill = level, size_line = 3))

# Change position of the names:
q + geom_chronochRt(aes(name_x = 0.75))

# To remove vertical lines within a chronological column:
q + geom_chronochRt(minimal = TRUE)