From fcb12d5fb1859d88535403777ddf6c0dd0844d1f Mon Sep 17 00:00:00 2001 From: mpadge Date: Fri, 2 Aug 2024 13:47:48 +0200 Subject: [PATCH] update uncontract_graph docs to close #236 --- DESCRIPTION | 2 +- R/graph-contraction.R | 12 +++++++++++- codemeta.json | 2 +- man/dodgr_uncontract_graph.Rd | 13 ++++++++++++- 4 files changed, 25 insertions(+), 4 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 55da09e75..4f51f4dbc 100644 --- a/DESCRIPTION +++ b/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"), diff --git a/R/graph-contraction.R b/R/graph-contraction.R index 68c9d4ec1..6fff28bbd 100644 --- a/R/graph-contraction.R +++ b/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, diff --git a/codemeta.json b/codemeta.json index 8e18c1b39..fea8e2d16 100644 --- a/codemeta.json +++ b/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", diff --git a/man/dodgr_uncontract_graph.Rd b/man/dodgr_uncontract_graph.Rd index 09ebcefb4..e2f466d0b 100644 --- a/man/dodgr_uncontract_graph.Rd +++ b/man/dodgr_uncontract_graph.Rd @@ -15,10 +15,21 @@ uncontracted graph. } \description{ 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. } +\details{ +Note that this function will generally \emph{not} recover original graphs +submitted to \link{dodgr_contract_graph}. Specifically, the sequence +\code{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. +} \examples{ graph0 <- weight_streetnet (hampi) nrow (graph0) # 6,813