plot_chronochrt {chronochrt}

Plot a chronological chart

Description

This function converts a chronological data set into a chronological chart. It provides basic features for the export of the plot and for its customisation.

Usage

plot_chronochrt(
  data,
  labels_text = NULL,
  labels_image = NULL,
  year_lim = NULL,
  axis_title = "Years",
  minimal = FALSE,
  size_text = 6,
  height_image = 2,
  size_line = 0.5,
  fill_chron = "white",
  color_chron = "black",
  color_label = "black",
  line_break = 10,
  filename = NULL,
  plot_dim,
  background = NULL,
  ...
)

Arguments

data

A data set with chronological data.

labels_text

A data set containing the text labels.

labels_image

A data set containing the image labels.

year_lim

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

axis_title

A character string with the axis label of the vertical axis. Default is "Years".

minimal

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

size_text

Font size of the names of the chronological units in mm. All other text elements will be scaled accordingly. The default is 6 mm.

height_image

The absolute height of the image labels in cm. The default is 2 cm.

size_line

Thickness of the line in mm. The default is 0.5 mm.

fill_chron

Fill colour of the chronological units. The default is "white". See the colour specification section of par for how to specify colours in R.

color_chron

Line (border) colour of the chronological units. The default is "black". See the colour specification section of par for how to specify colours in R.

color_label

Colour of the text labels. The default is "black". See the colour specification section of par for how to specify colours in R.

line_break

Line length of the section labels in characters. Text will be wrapped at the blank closest to the specified number of characters. Default is 10 characters.

filename

A character string with the filename or path. If specified, the plot will be saved in the given location. The file format is automatically recognised from the file extension. The most common file types are supported, e.g. .tiff, .png, .jpg, .eps, and .pdf. To export as .svg installation of the package svglite is required. See ggsave for more details about the supported file formats.

plot_dim

Dimensions of the plot as a vector in the format c(width, height, units). Supported units are "cm", "mm", in". For example, plot_dim = c(5,5,"cm") will produce a plot of the dimensions 5 x 5 cm. If unspecified, the standard values of the respective graphic device are used.

background

Optional specifications for the background of the chronological chart as vector in the format c(background colour, linetype of grid lines) to overwrite the default behaviour of theme_chronochrt. Any valid colour and line type specifications are accepted, e.g. c("grey90", "dotted") (these are the default values of theme_chronochrt. See the sections "colour specification" and "line type specification" in par for how to specify colours and line types in R.

...

Additional arguments passed to ggsave to enhance the saved plot like dpi to specify its resolution. See ggsave for detailed information.

Details

This function is wrapper around various functions for an quick and convenient way to draw chronological charts. It relies on the common data structure of ChronochRt (see vignette("ChronochRt") for details). For full customisation use the respective geoms to build your own plot.

It is assumed that the majority of the text labels will be placed on the right side of each column. Therefore they are right aligned to prevent them from running outside the plotting area. Vertically, it will be placed centred on the year given. Text in labels can be wrapped by inserting "\n" (without blanks).

Value

A ggplot2 object with the chronological chart.

Examples

# Create Example data
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)

# Plot with default options
plot_chronochrt(chrons)

# Add labels
labels <- data.frame(region = "A",
                     year = -50,
                     position = 0.5,
                     label = "Event")

images <- data.frame(region = "B",
                     year = 100,
                     position = 0.5,
                     image_path = "https://www.r-project.org/logo/Rlogo.png")

plot_chronochrt(chrons, labels, images)

# Customise plot
plot_chronochrt(chrons, axis_title = "BC/AD", year_lim = c(-50,100),
                fill_chron = "black", color_chron = "white", size_line = 5)
plot_chronochrt(chrons, labels, images, color_label = "red", size_text = 5, height_image = 4)

# Export plot

file <- tempfile(fileext = ".jpg")

plot_chronochrt(chrons, filename = tempfile(fileext = ".jpg"),
  plot_dim = c(10, 15, "cm"))

  # with additional parameters
  plot_chronochrt(chrons, filename = tempfile(fileext = ".jpg"),
    plot_dim = c(10, 15, "cm"), dpi = 300)

unlink(file)

# Additional customisation with ggplot2
plot_chronochrt(chrons) + ggplot2::theme_bw()