R/chronochrt_add_chron.R

In chronochrt: Creating Chronological Charts

#' Create or add chronological data
#'
#' 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.
#'
#' 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.
#'
#' \code{start} and \code{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 \code{start} and \code{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 \code{"1000/2000"}. Consistency is required for matching
#' \code{start} and \code{end} dates to avoid unclean or chaotic border
#' orientation in the plot.
#'
#' The \code{level} indicates the position of the chronological unit.
#' \code{level = 1} denotes a top chronological unit (e.g. Ha), a sub-unit (e.g.
#' Ha B) is \code{level = 2}, a sub-sub-unit (e.g. Ha B1) \code{level = 3} etc.
#' The parameter \code{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
#' \code{level} and \code{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.
#'
#' @param data A data set with chronological data. Must not be provided if
#'   \code{new_table = FALSE}.
#' @param region A character string or character vector with the title(s) of the
#'   section(s).
#' @param name A character string or character vector with the name(s) of the
#'   chronological unit(s).
#' @param 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.
#' @param 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.
#' @param 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
#'   \code{1}, i.e. the top unit.
#' @param add  A logical value (\code{TRUE} or \code{FALSE}) or a logical vector
#'   signalling whether the chronological units within a geographical area
#'   should be drawn separately (\code{TRUE}) or not (\code{FLASE}, the
#'   default).
#' @param new_table Logical operator. If \code{TRUE}, a new data set will be
#'   created. If \code{FALSE}, the default, the input will be added to an
#'   existing data set.
#' @param ... Additional columns to include in the data set and/or additional
#'   arguments passed to \code{\link[tibble]{tibble()}} (if \code{new_table =
#'   TRUE}) or \code{\link[tibble]{add_row}} (if \code{new_table = FALSE}).
#' @param ... Further arguments or columns to include in or additional arguments
#'   passed to \code{\link[tibble]{tibble}} or \code{\link[tibble]{add_row}}.
#'
#' @return A tibble with chronological data ready-to-use for plotting with
#'   \code{\link{plot_chronochrt}}.
#'
#' @export
#'
#' @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)
#'


add_chron <- function(data, region, name, start, end, level = 1,
                      add = FALSE, new_table = FALSE, ...) {
  if (new_table == FALSE) {
    if (!missing(data)) {

      if (typeof(data$start) != typeof(start)) {
        data$start <- as.character(data$start)
        start <- as.character(start)
      }

      if (typeof(data$end) != typeof(end)) {
        data$end <- as.character(data$end)
        end <- as.character(end)
      }

      data <- tibble::add_row(data, region, name, start, end, level, add, ...)
    } else {
      stop("The argument `data` must be provided or `new_table` must be TRUE.")
    }
  } else {
    data <- tibble::tibble(region, name, start, end, level, add, ...)
  }

  if (!all(
    is.character(data$region),
    is.character(data$name),
    is.numeric(data$start) | is.character(data$start),
    is.numeric(data$end) | is.character(data$end),
    is.numeric(data$level),
    is.logical(data$add)
  )
  ) {
    stop("One or more columns of the data set contain incompatible data. Data must be :
         strings (region, name),
         numbers (start, end),
         whole numbers (level), and
         logical (add)."
    )
  }

  if (!all(round(data$level) == data$level)) {
    stop(
      "Wrong input format: level must contain only whole numbers (1, 2, 3, ...)"
    )
  }

  data
}