add_chron {chronochrt}

Create or add chronological data

Description

This function either creates a data set with chronological data which can be directly used for plotting or it adds chronological data to such a data set.

Usage

add_chron(
  data,
  region,
  name,
  start,
  end,
  level = 1,
  add = FALSE,
  new_table = FALSE,
  ...
)

Arguments

data

A data set with chronological data. Must not be provided if new_table = FALSE.

region

A character string or character vector with the title(s) of the section(s).

name

A character string or character vector with the name(s) of the chronological unit(s).

start

A number or a vector with the start date(s) of the chronological unit(s). Use negative values for BCE dates. See Details how to handle insecure start dates.

end

A number or a vector with the end date(s) of the chronological unit(s). Use negative values for BCE dates. See Details how to handle insecure end dates.

level

A whole number or numeric vector of whole numbers (i.e. 1, 2, 3, ...) with the level(s) of the chronological unit(s). The default is 1, i.e. the top unit.

add

A logical value (TRUE or FALSE) or a logical vector signalling whether the chronological units within a geographical area should be drawn separately (TRUE) or not (FLASE, the default).

new_table

Logical operator. If TRUE, a new data set will be created. If FALSE, the default, the input will be added to an existing data set.

...

Further arguments or columns to include in or additional arguments passed to tibble or add_row.

Details

If the input is in the same order as the arguments, the arguments do not need to be explicitly named. Values can be provided as one number or one character string, if they are the same for all other data. If not, they must be provided as vectors with equal lengths.

start and end of neighbouring chronological units as well as respective oldest sub-units must be the same to achieve good plotting results. Dates in BCE must provided as negative data. Currently, only years can be handled (i.e. 2020 but not 20.10.2020).The package can handle the year 0.

If start and end dates are not certain or the change between chronological units is regarded a period, dates must be given as character string in the format "1000/2000". Consistency is required for matching start and end dates to avoid unclean or chaotic border orientation in the plot.

The level indicates the position of the chronological unit. level = 1 denotes a top chronological unit (e.g. Ha), a sub-unit (e.g. Ha B) is level = 2, a sub-sub-unit (e.g. Ha B1) level = 3 etc. The parameter add indicates whether the respective chronological unit(s) should be plotted in the same or an additional column. This might be useful if competing chronologies in one region exist (e.g. short and long chronologies). See the vignette for a detailed explanation how the parameters level and add work.

Additional columns might be useful to e.g. specify the x and y position of the names of the chronological units to place them at an arbitrary spot.

Value

A tibble with chronological data ready-to-use for plotting with plot_chronochrt.

Examples

# Create new data set

chrons <- add_chron(region = c("A", "B"),
                    name = c("a", "a"),
                    start = -100,
                    end = c(200, 150),
                    level = c(1, 1),
                    add = FALSE,
                    new_table = TRUE)

# Add chrons to an existing data set
chrons2 <- add_chron(data = chrons,
                     region = "A",
                     name = c("1", "2"),
                     start = c(-100, 100),
                     end = c(100, 200),
                     level = 2,
                     add = FALSE,
                     new_table = FALSE)

# Include chrons with unclear start/end data
chrons <- add_chron(data = chrons,
                    region = "B",
                    name = c("1", "2"),
                    start = c(-100, "0/50"),
                    end = c("0/50", 150),
                    level = 2,
                    add = FALSE,
                    new_table = FALSE)

# They can be linked using the pipe operator \code{%>%}:
library(magrittr)

chrons <- add_chron(region = c("A", "B"),
                    name = c("a", "a"),
                    start = -100,
                    end = c(200, 150),
                    level = c(1, 1),
                    add = FALSE,
                    new_table = TRUE) %>%
          add_chron(region = "B",
                    name = c("1", "2"),
                    start = c(-100, "0/50"),
                    end = c("0/50", 150),
                    level = 2,
                    add = FALSE)