R/aoristic.datacheck.R

In aoristic: Generates Aoristic Probability Distributions

#' Check aoristic input data
#'
#' Flags missing End/To values with `1` and End/To values before Start/From
#' with `2`. The function also reports missing or zero coordinates.
#'
#' @param data1 Data frame containing coordinates and date-time columns.
#' @param Xcoord Name of the numeric X coordinate or latitude column.
#' @param Ycoord Name of the numeric Y coordinate or longitude column.
#' @param DateTimeFrom Name of the Start/From POSIXct column.
#' @param DateTimeTo Name of the End/To POSIXct column.
#' @return A data frame containing the checked fields, elapsed duration, and
#'   an `aoristic_datacheck` flag.
#' @examples
#' datacheck.df <- aoristic.datacheck(
#'   dcburglaries, "X", "Y", "StartDateTime", "EndDateTime"
#' )
#' @export
#' @references Ratcliffe, J. H. (2002). Aoristic signatures and the
#' spatio-temporal analysis of high volume crime patterns. Journal of
#' Quantitative Criminology, 18(1), 23-43.
aoristic.datacheck <- function(data1, Xcoord, Ycoord, DateTimeFrom, DateTimeTo) {
  .validate_aoristic_inputs(data1, Xcoord, Ycoord, DateTimeFrom, DateTimeTo)

  df1 <- data.frame(
    x_lon = data1[[Xcoord]],
    y_lat = data1[[Ycoord]],
    datetime_from = data1[[DateTimeFrom]],
    datetime_to = data1[[DateTimeTo]]
  )
  df1$duration <- lubridate::as.duration(df1$datetime_to - df1$datetime_from)
  df1$aoristic_datacheck <- 0L
  df1$aoristic_datacheck[is.na(df1$datetime_to)] <- 1L
  df1$aoristic_datacheck[!is.na(df1$duration) & df1$duration < 0] <- 2L

  rows.missing.end <- sum(df1$aoristic_datacheck == 1L)
  rows.reversed <- sum(df1$aoristic_datacheck == 2L)
  errors.coord <- sum(is.na(df1$x_lon) | is.na(df1$y_lat))
  errors.zero <- sum(
    (!is.na(df1$x_lon) & df1$x_lon == 0) |
      (!is.na(df1$y_lat) & df1$y_lat == 0)
  )

  txt <- "\n---- Aoristic data check -------------------------------------------\n"
  if (rows.missing.end > 0 || rows.reversed > 0) {
    txt <- paste0(
      txt,
      "     ", rows.missing.end, " rows were missing END/TO datetime values.\n",
      "     ", rows.reversed, " rows had END/TO datetimes before START/FROM datetimes.\n",
      "     In the aoristic.datacheck data frame these rows are indicated\n",
      "     with missing end datetimes = 1 and start/end logical errors = 2.\n",
      "     See the aoristic_datacheck column and ?aoristic.datacheck.\n"
    )
  } else {
    txt <- paste0(
      txt,
      "     Congratulations!\n",
      "     Data check did not find missing END/TO values or date-sequence errors.\n"
    )
  }
  message(txt)
  message("     Coordinates check:")

  if (errors.coord > 0 || errors.zero > 0) {
    txt <- ""
    if (errors.coord > 0) {
      txt <- paste0(txt, "     ", errors.coord, " rows missing spatial coordinates.\n")
    }
    if (errors.zero > 0) {
      txt <- paste0(txt, "     ", errors.zero, " rows had a zero spatial coordinate.\n")
    }
    message(txt)
  } else {
    message("     No missing or zero coordinates.\n")
  }

  df1
}