update uncontract_graph docs to close #236

DESCRIPTION

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

R/graph-contraction.R

@@ -269,10 +269,20 @@ rm_edges_with_heterogenous_data <- function (graph, graph_contracted, gr_cols) {
 #' Re-expand a contracted graph.
 #'
 #' Revert a contracted graph created with \link{dodgr_contract_graph} back to
-#' the full, uncontracted version. This function is mostly used for the side
+#' a full, uncontracted version. This function is mostly used for the side
 #' effect of mapping any new columns inserted on to the contracted graph back
 #' on to the original graph, as demonstrated in the example.
 #'
+#' Note that this function will generally *not* recover original graphs
+#' submitted to \link{dodgr_contract_graph}. Specifically, the sequence
+#' `dodgr_contract_graph(graph) |> dodgr_uncontract_graph()` will generally
+#' produce a graph with fewer edges than the original. This is because graphs
+#' may have multiple paths between a given pair of points. Contraction will
+#' reduce these to the single path with the shortest weighted distance (or
+#' time), and uncontraction will restore only that single edge with shortest
+#' weighted distance, and not any original edges which may have had longer
+#' weighted distances.
+#'
 #' @param graph A contracted graph created from \link{dodgr_contract_graph}.
 #'
 #' @return A single `data.frame` representing the equivalent original,

codemeta.json

@@ -11,7 +11,7 @@
   "codeRepository": "https://github.com/UrbanAnalyst/dodgr",
   "issueTracker": "https://github.com/UrbanAnalyst/dodgr/issues",
   "license": "https://spdx.org/licenses/GPL-3.0",
-  "version": "0.4.1.017",
+  "version": "0.4.1.018",
   "programmingLanguage": {
     "@type": "ComputerLanguage",
     "name": "R",