more iso vignette for #225

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: dodgr
 Title: Distances on Directed Graphs
-Version: 0.3.0.053
+Version: 0.3.0.054
 Authors@R: c(
     person("Mark", "Padgham", , "mark.padgham@email.com", role = c("aut", "cre")),
     person("Andreas", "Petutschnig", role = "aut"),

codemeta.json

@@ -6,7 +6,7 @@
   "name": "dodgr: Distances on Directed Graphs",
   "codeRepository": "https://github.com/UrbanAnalyst/dodgr",
   "issueTracker": "https://github.com/UrbanAnalyst/dodgr/issues",
-  "version": "0.3.0.053",
+  "version": "0.3.0.054",
   "license": "https://spdx.org/licenses/GPL-3.0",
   "programmingLanguage": {
     "@type": "ComputerLanguage",

vignettes/iso.Rmd

@@ -14,17 +14,23 @@ vignette: >
   %\VignetteEncoding{UTF-8}
 ---
 
+```{r knitr-opts, echo = FALSE}
+opts <- knitr::opts_chunk$get ()
+knitr::opts_chunk$set (fig.height = 6)
+```
+
 ```{r pkg-load, echo = FALSE, message = FALSE}
 library (dodgr)
 ```
 
 The `dodgr`package includes three functions for calculating iso-contours from
 one or more points of origin:
-[`dodgr_isodists()`](https://UrbanAnalyst.github.io/dodgr/reference/dodgr_isodists.html)
+
+- [`dodgr_isodists()`](https://UrbanAnalyst.github.io/dodgr/reference/dodgr_isodists.html)
 for contours of equal distance;
-[`dodgr_isochrones()`](https://UrbanAnalyst.github.io/dodgr/reference/dodgr_isochrones.html)
+- [`dodgr_isochrones()`](https://UrbanAnalyst.github.io/dodgr/reference/dodgr_isochrones.html)
 for contours of equal time; and
-[`dodgr_isoverts()`](https://UrbanAnalyst.github.io/dodgr/reference/dodgr_isoverts.html)
+- [`dodgr_isoverts()`](https://UrbanAnalyst.github.io/dodgr/reference/dodgr_isoverts.html)
 to return full set of vertices within defined isodistance or isochrone contours.
 
 Each of these functions is fully vectorised to accept both multiple origin
@@ -61,12 +67,12 @@ The points defining the contours are arranged in an anticlockwise order around
 each point of origin, and so can be directly visualised using base graphics
 functions. This is easier to see by using just a single point of origin:
 
-```{r isodist-plot-fakey, eval = FALSE}
-set.seed (42)
+```{r isodist-plot, echo = TRUE}
+set.seed (1)
 from <- sample (graph$from_id, size = 1)
 dlim <- c (1, 2, 5, 10, 20) * 100
 d <- dodgr_isodists (graph, from = from, dlim)
-cols <- terrain.colors (length (dlim))
+cols <- terrain.colors (length (dlim) + 2) # + 2 to avoid light colours at end of scale.
 index <- which (d$dlim == max (d$dlim)) # plot max contour first
 plot (
     d$x [index], d$y [index], "l",
@@ -78,13 +84,25 @@ for (i in seq (dlim) [-1]) {
     lines (d$x [index], d$y [index], col = cols [i], lwd = i + 1)
 }
 ```
-```{r isodist-plot, echo = FALSE}
+
+### The `concavity` parameter
+
+The default contours are convex hulls. The
+[`dodgr_isodists()`](https://UrbanAnalyst.github.io/dodgr/reference/dodgr_isodists.html)
+and
+[`dodgr_isochrones()`](https://UrbanAnalyst.github.io/dodgr/reference/dodgr_isochrones.html)
+functions include an additional `concavity` parameter to return generate concave 
+isodistance or isochrone polygons, defaulting to a value of 0 for no
+concavity. Changing this value can generate concave contours like in the
+following results:
+
+```{r isodist-plot-concave, echo = TRUE}
 set.seed (1)
 from <- sample (graph$from_id, size = 1)
 dlim <- c (1, 2, 5, 10, 20) * 100
-d <- dodgr_isodists (graph, from = from, dlim)
+d <- dodgr_isodists (graph, from = from, dlim, concavity = 0.5)
 cols <- terrain.colors (length (dlim))
-index <- which (d$dlim == max (d$dlim)) # plot max contour first
+index <- which (d$dlim == max (d$dlim))
 plot (
     d$x [index], d$y [index], "l",
     col = cols [1],
@@ -96,27 +114,51 @@ for (i in seq (dlim) [-1]) {
 }
 ```
 
-The default contours are convex hulls. The
-[`dodgr_isodists()`](https://UrbanAnalyst.github.io/dodgr/reference/dodgr_isodists.html)
-function includes an additional `concavity` parameter to return generate concave 
-isodistance (or isochrone) polygons, defaulting to a value of 0 for no
-concavity. Changing this value can generate concave contours like in the
-following results:
+The calculation of `isodists` or `isochrone` values is cached, so different
+values of the `concavity` parameter can be trialled without needing to
+re-calculate the underlying values:
 
-```{r isodist-plot-convex, echo = FALSE}
-set.seed (1)
+```{r iso-caching}
+set.seed (2)
 from <- sample (graph$from_id, size = 1)
 dlim <- c (1, 2, 5, 10, 20) * 100
-d <- dodgr_isodists (graph, from = from, dlim, concavity = 0.5)
-cols <- terrain.colors (length (dlim))
-index <- which (d$dlim == max (d$dlim)) # plot max contour first
+system.time ( # Initial call calculates distances to all points:
+    d <- dodgr_isodists (graph, from = from, dlim, concavity = 0.5)
+)
+system.time ( # Subsequent call uses cached values:
+    d <- dodgr_isodists (graph, from = from, dlim, concavity = 0.75)
+)
+```
+
+The `concavity` parameter has a default value of 0 for strictly convex
+polygons. Values closer to 1 generate more concave polygons. The following code
+demonstrates the effect of increasing values of this parameter.
+
+```{r concavity}
+set.seed (5)
+from <- sample (graph$from_id, size = 1)
+dlim <- 2000
+concavity <- 0:4 / 4
+d <- lapply (concavity, function (i) dodgr_isodists (graph, from = from, dlim, concavity = i))
+cols <- terrain.colors (length (d) + 2)
 plot (
-    d$x [index], d$y [index], "l",
-    col = cols [1],
+    d [[1]]$x, d [[1]]$y,
+    type = "l",
+    col = cols [1], lwd = 5,
     xlab = "longitude", ylab = "latitude"
 )
-for (i in seq (dlim) [-1]) {
-    index <- which (d$dlim == rev (dlim) [i])
-    lines (d$x [index], d$y [index], col = cols [i], lwd = i + 1)
+for (i in seq_along (d) [-1]) {
+    lines (
+        d [[i]]$x, d [[i]]$y,
+        col = cols [i], lwd = 6 - i, lty = i
+    )
 }
+v <- dodgr_vertices (graph)
+v_from <- v [match (from, v$id), ]
+points (v_from [, c ("x", "y")], pch = 19, col = "red", cex = 2)
+```
+
+```{r knitr-opts-reset, echo = FALSE}
+opts <- knitr::opts_chunk$get ()
+knitr::opts_chunk$set (fig.height = opts$fig.height)
 ```