From 4109071117961415b218cb2a8c799cda956f4482 Mon Sep 17 00:00:00 2001
From: Robin <Robinlovelace@users.noreply.github.com>
Date: Sun, 5 Dec 2021 11:21:33 +0000
Subject: [PATCH] Add od_disag args to od_jitter for #39 (#40)

* Add od_disag args to od_jitter for #39

* Use od_dissaggrate backend for #39
---
 R/jitter.R       | 36 ++++++++++++++++++++++++++++--------
 man/od_jitter.Rd | 42 +++++++++++++++++++++++++++++++++++++++---
 2 files changed, 67 insertions(+), 11 deletions(-)

diff --git a/R/jitter.R b/R/jitter.R
index 3beef29..7f24393 100644
--- a/R/jitter.R
+++ b/R/jitter.R
@@ -8,6 +8,8 @@
 #' @param zd Zones with ids matching the destination codes in input OD data
 #' @param subpoints_o Points within origin zones representing possible destinations
 #' @param subpoints_d Points within destination zones representing possible destinations
+#' @param disag Should the od_disaggregate function be used as a 'back end' where possible?
+#'   TRUE by default. See https://github.com/ITSLeeds/od/issues/39.
 #' @inheritParams od_disaggregate
 #'
 #' @return An `sf` data frame
@@ -21,8 +23,10 @@
 #' dlr = od_jitter(od, z) # desire_lines_random
 #' desire_lines = od_to_sf(od, z)
 #' plot(z$geometry)
-#' plot(dlr, add = TRUE, lwd = 3)
-#' plot(desire_lines, add = TRUE, lwd = 5)
+#' plot(dlr["all"], add = TRUE, lwd = 3)
+#' dlr$all
+#' desire_lines$all
+#' plot(desire_lines["all"], add = TRUE, lwd = 5)
 #'
 #' # Example showing use of subpoints
 #' subpoints_o = sf::st_sample(z, 200)
@@ -62,20 +66,36 @@
 #' # plot(od_sf[od$all > 200, 1])
 #' # plot(dlr3[od$all > 200, 1])
 #' # mapview::mapview(od_sf$geometry[od$all > 200])
-od_jitter = function(od,
-                     z,
-                     zd = NULL,
-                     subpoints_o = NULL,
-                     subpoints_d = NULL) {
+od_jitter = function(
+  od,
+  z,
+  zd = NULL,
+  subpoints = NULL,
+  code_append = "_ag",
+  population_column = 3,
+  max_per_od = 100000,
+  keep_ids = TRUE,
+  integer_outputs = FALSE,
+  # od_jitter-specific arguments (and zd)
+  subpoints_o = NULL,
+  subpoints_d = NULL,
+  disag = TRUE
+  ) {
+
   if (!methods::is(od, "sf")) {
     # the data structure to reproduce for matching OD pairs
     od = od::od_to_sf(od, z = z, zd = zd)
   }
+  disag = all(is.null(zd), is.null(subpoints_o), is.null(subpoints_d), disag)
+  if(disag) {
+    message("Using od_disaggregate") # todo remove once tested
+    return(od_disaggregate(od, z, subpoints, code_append, population_column,
+                           max_per_od, keep_ids, integer_outputs))
+  }
   odc_new = odc_original = od::od_coordinates(od)
   od = sf::st_drop_geometry(od)
   odc_df = data.frame(o = od[[1]], d = od[[2]], odc_original)
   z_geo = sf::st_geometry(z)
-  # browser()
   id_origins = od[[1]]
   points_per_zone = data.frame(table(id_origins))
   names(points_per_zone)[1] = names(z)[1]
diff --git a/man/od_jitter.Rd b/man/od_jitter.Rd
index 99ffafa..631ab0b 100644
--- a/man/od_jitter.Rd
+++ b/man/od_jitter.Rd
@@ -4,7 +4,20 @@
 \alias{od_jitter}
 \title{Move desire line end points within zone to avoid all trips going to a single centroid}
 \usage{
-od_jitter(od, z, zd = NULL, subpoints_o = NULL, subpoints_d = NULL)
+od_jitter(
+  od,
+  z,
+  zd = NULL,
+  subpoints = NULL,
+  code_append = "_ag",
+  population_column = 3,
+  max_per_od = 1e+05,
+  keep_ids = TRUE,
+  integer_outputs = FALSE,
+  subpoints_o = NULL,
+  subpoints_d = NULL,
+  disag = TRUE
+)
 }
 \arguments{
 \item{od}{An origin-destination data frame}
@@ -13,9 +26,30 @@ od_jitter(od, z, zd = NULL, subpoints_o = NULL, subpoints_d = NULL)
 
 \item{zd}{Zones with ids matching the destination codes in input OD data}
 
+\item{subpoints}{Points, lines or polygons within the zones.
+These define the OD data start/end points.}
+
+\item{code_append}{The name of the column containing aggregate zone names}
+
+\item{population_column}{The column containing the total population (if it exists)}
+
+\item{max_per_od}{Maximum flow in the population_column to assign per OD pair.
+This only comes into effect if there are enough subpoints to choose from.}
+
+\item{keep_ids}{Should the origin and destination ids be kept?
+\code{TRUE} by default, meaning 2 extra columns are appended, with the
+names \code{o_agg} and \code{d_agg} containing IDs from the original OD data.}
+
+\item{integer_outputs}{Should integer outputs be returned? \code{FALSE} by default.
+Note: there is a known issue when integer results are generated. See
+https://github.com/ITSLeeds/od/issues/31 for details.}
+
 \item{subpoints_o}{Points within origin zones representing possible destinations}
 
 \item{subpoints_d}{Points within destination zones representing possible destinations}
+
+\item{disag}{Should the od_disaggregate function be used as a 'back end' where possible?
+TRUE by default. See https://github.com/ITSLeeds/od/issues/39.}
 }
 \value{
 An \code{sf} data frame
@@ -34,8 +68,10 @@ z = od_data_zones_min
 dlr = od_jitter(od, z) # desire_lines_random
 desire_lines = od_to_sf(od, z)
 plot(z$geometry)
-plot(dlr, add = TRUE, lwd = 3)
-plot(desire_lines, add = TRUE, lwd = 5)
+plot(dlr["all"], add = TRUE, lwd = 3)
+dlr$all
+desire_lines$all
+plot(desire_lines["all"], add = TRUE, lwd = 5)
 
 # Example showing use of subpoints
 subpoints_o = sf::st_sample(z, 200)