pass centrality param to RcppParallel routines for #90

(not yet implemented)

R/RcppExports.R

@@ -4,15 +4,15 @@
 #' rcpp_centrality_vertex - parallel function
 #'
 #' @noRd
-rcpp_centrality_vertex <- function(graph, vert_map_in, heap_type, dirtxt) {
-    invisible(.Call(`_dodgr_rcpp_centrality_vertex`, graph, vert_map_in, heap_type, dirtxt))
+rcpp_centrality_vertex <- function(graph, vert_map_in, heap_type, dirtxt, dist_threshold) {
+    invisible(.Call(`_dodgr_rcpp_centrality_vertex`, graph, vert_map_in, heap_type, dirtxt, dist_threshold))
 }
 
 #' rcpp_centrality_edge - parallel function
 #'
 #' @noRd
-rcpp_centrality_edge <- function(graph, vert_map_in, heap_type, dirtxt) {
-    invisible(.Call(`_dodgr_rcpp_centrality_edge`, graph, vert_map_in, heap_type, dirtxt))
+rcpp_centrality_edge <- function(graph, vert_map_in, heap_type, dirtxt, dist_threshold) {
+    invisible(.Call(`_dodgr_rcpp_centrality_edge`, graph, vert_map_in, heap_type, dirtxt, dist_threshold))
 }
 
 #' Make unordered_set of all new edge names

R/centrality.R

@@ -15,6 +15,12 @@
 #' the input `graph` with an additional `centrality` column; otherwise
 #' centrality is calculated for vertices, returning the equivalent of
 #' `dodgr_vertices(graph)`, with an additional vertex-based `centrality` column.
+#' @param dist_threshold If not `NULL`, only calculate centrality for each point
+#' out to specified threshold. Setting values for this will result in
+#' approximate estimates for centrality, yet with considerable gains in
+#' computational efficiency. For sufficiently large values, approximations will
+#' be accurate to within some constant multiplier. Appropriate values can be
+#' established via the \link{estimate_centrality_threshold} function.
 #' @param heap Type of heap to use in priority queue. Options include
 #' Fibonacci Heap (default; `FHeap`), Binary Heap (`BHeap`),
 #' `Radix`, Trinomial Heap (`TriHeap`), Extended Trinomial Heap
@@ -77,12 +83,14 @@
 #'
 #' @export
 dodgr_centrality <- function (graph, contract = TRUE, edges = TRUE,
-                              heap = "BHeap")
+                              dist_threshold = NULL, heap = "BHeap")
 {
     if ("centrality" %in% names (graph))
         warning ("graph already has a 'centrality' column; ",
                   "this will be overwritten")
 
+    dist_threshold <- ifelse (is.null (dist_threshold), 0, dist_threshold)
+
     hps <- get_heap (heap, graph)
     heap <- hps$heap
     graph <- hps$graph
@@ -112,11 +120,13 @@ dodgr_centrality <- function (graph, contract = TRUE, edges = TRUE,
     if (edges)
     {
         dirtxt <- get_random_prefix ("centrality_edge")
-        rcpp_centrality_edge (graph2, vert_map, heap, dirtxt)
+        rcpp_centrality_edge (graph2, vert_map, heap, dirtxt,
+                              dist_threshold)
     } else
     {
         dirtxt <- get_random_prefix ("centrality_vert")
-        rcpp_centrality_vertex (graph2, vert_map, heap, dirtxt)
+        rcpp_centrality_vertex (graph2, vert_map, heap, dirtxt,
+                                dist_threshold)
     }
 
     # aggregate results from the threads:
@@ -146,3 +156,22 @@ dodgr_centrality <- function (graph, contract = TRUE, edges = TRUE,
 
     return (res)
 }
+
+#' estimate_centrality_threshold
+#'
+#' Estimate a value for the `dist_threshold` parameter of the
+#' \link{dodgr_centrality} function. Providing distance thresholds to this
+#' function generally provides considerably speed gains, and results in
+#' approximations of centrality. This function enables the determination of
+#' values of `dist_threshold` corresponding to specific degrees of accuracy.
+#'
+#' @inheritParams dodgr_centrality
+#' @param tolerance Desired maximal degree of inaccuracy in centrality estimates
+#' - values will be accurate to within this amount, subject to a constant
+#' scaling factor.
+#' @return A single value for `dist_threshold` giving the required tolerance.
+#' @export
+estimate_centrality_threshold <- function (graph, tolerance = 0.001)
+{
+    graph <- weight_column (hampi)
+}

src/RcppExports.cpp

@@ -6,28 +6,30 @@
 using namespace Rcpp;
 
 // rcpp_centrality_vertex
-void rcpp_centrality_vertex(const Rcpp::DataFrame graph, const Rcpp::DataFrame vert_map_in, const std::string& heap_type, const std::string dirtxt);
-RcppExport SEXP _dodgr_rcpp_centrality_vertex(SEXP graphSEXP, SEXP vert_map_inSEXP, SEXP heap_typeSEXP, SEXP dirtxtSEXP) {
+void rcpp_centrality_vertex(const Rcpp::DataFrame graph, const Rcpp::DataFrame vert_map_in, const std::string& heap_type, const std::string dirtxt, const double dist_threshold);
+RcppExport SEXP _dodgr_rcpp_centrality_vertex(SEXP graphSEXP, SEXP vert_map_inSEXP, SEXP heap_typeSEXP, SEXP dirtxtSEXP, SEXP dist_thresholdSEXP) {
 BEGIN_RCPP
     Rcpp::RNGScope rcpp_rngScope_gen;
     Rcpp::traits::input_parameter< const Rcpp::DataFrame >::type graph(graphSEXP);
     Rcpp::traits::input_parameter< const Rcpp::DataFrame >::type vert_map_in(vert_map_inSEXP);
     Rcpp::traits::input_parameter< const std::string& >::type heap_type(heap_typeSEXP);
     Rcpp::traits::input_parameter< const std::string >::type dirtxt(dirtxtSEXP);
-    rcpp_centrality_vertex(graph, vert_map_in, heap_type, dirtxt);
+    Rcpp::traits::input_parameter< const double >::type dist_threshold(dist_thresholdSEXP);
+    rcpp_centrality_vertex(graph, vert_map_in, heap_type, dirtxt, dist_threshold);
     return R_NilValue;
 END_RCPP
 }
 // rcpp_centrality_edge
-void rcpp_centrality_edge(const Rcpp::DataFrame graph, const Rcpp::DataFrame vert_map_in, const std::string& heap_type, const std::string dirtxt);
-RcppExport SEXP _dodgr_rcpp_centrality_edge(SEXP graphSEXP, SEXP vert_map_inSEXP, SEXP heap_typeSEXP, SEXP dirtxtSEXP) {
+void rcpp_centrality_edge(const Rcpp::DataFrame graph, const Rcpp::DataFrame vert_map_in, const std::string& heap_type, const std::string dirtxt, const double dist_threshold);
+RcppExport SEXP _dodgr_rcpp_centrality_edge(SEXP graphSEXP, SEXP vert_map_inSEXP, SEXP heap_typeSEXP, SEXP dirtxtSEXP, SEXP dist_thresholdSEXP) {
 BEGIN_RCPP
     Rcpp::RNGScope rcpp_rngScope_gen;
     Rcpp::traits::input_parameter< const Rcpp::DataFrame >::type graph(graphSEXP);
     Rcpp::traits::input_parameter< const Rcpp::DataFrame >::type vert_map_in(vert_map_inSEXP);
     Rcpp::traits::input_parameter< const std::string& >::type heap_type(heap_typeSEXP);
     Rcpp::traits::input_parameter< const std::string >::type dirtxt(dirtxtSEXP);
-    rcpp_centrality_edge(graph, vert_map_in, heap_type, dirtxt);
+    Rcpp::traits::input_parameter< const double >::type dist_threshold(dist_thresholdSEXP);
+    rcpp_centrality_edge(graph, vert_map_in, heap_type, dirtxt, dist_threshold);
     return R_NilValue;
 END_RCPP
 }
@@ -260,8 +262,8 @@ END_RCPP
 }
 
 static const R_CallMethodDef CallEntries[] = {
-    {"_dodgr_rcpp_centrality_vertex", (DL_FUNC) &_dodgr_rcpp_centrality_vertex, 4},
-    {"_dodgr_rcpp_centrality_edge", (DL_FUNC) &_dodgr_rcpp_centrality_edge, 4},
+    {"_dodgr_rcpp_centrality_vertex", (DL_FUNC) &_dodgr_rcpp_centrality_vertex, 5},
+    {"_dodgr_rcpp_centrality_edge", (DL_FUNC) &_dodgr_rcpp_centrality_edge, 5},
     {"_dodgr_rcpp_aggregate_to_sf", (DL_FUNC) &_dodgr_rcpp_aggregate_to_sf, 3},
     {"_dodgr_rcpp_aggregate_files", (DL_FUNC) &_dodgr_rcpp_aggregate_files, 2},
     {"_dodgr_rcpp_flows_aggregate_par", (DL_FUNC) &_dodgr_rcpp_flows_aggregate_par, 8},

src/centrality.cpp

@@ -38,6 +38,7 @@ struct OneCentralityVert : public RcppParallel::Worker
     size_t nverts; // can't be const because of reinterpret case
     const std::string dirtxt;
     const std::string heap_type;
+    const double dist_threshold;
 
     std::shared_ptr <DGraph> g;
 
@@ -46,9 +47,10 @@ struct OneCentralityVert : public RcppParallel::Worker
             const size_t nverts_in,
             const std::string dirtxt_in,
             const std::string heap_type_in,
+            const double dist_threshold_in,
             const std::shared_ptr <DGraph> g_in) :
-        nverts (nverts_in), dirtxt (dirtxt_in),
-        heap_type (heap_type_in), g (g_in)
+        nverts (nverts_in), dirtxt (dirtxt_in), heap_type (heap_type_in), 
+        dist_threshold (dist_threshold_in), g (g_in)
     {
     }
 
@@ -79,7 +81,7 @@ struct OneCentralityVert : public RcppParallel::Worker
 
         for (size_t v = begin; v < end; v++)
         {
-            pathfinder->Centrality_vertex (cent, v);
+            pathfinder->Centrality_vertex (cent, v, dist_threshold);
         }
         // dump flowvec to a file; chance of re-generating same file name is
         // 61^10, so there's no check for re-use of same
@@ -99,6 +101,7 @@ struct OneCentralityEdge : public RcppParallel::Worker
     size_t nedges;
     const std::string dirtxt;
     const std::string heap_type;
+    const double dist_threshold;
 
     std::shared_ptr <DGraph> g;
 
@@ -108,9 +111,10 @@ struct OneCentralityEdge : public RcppParallel::Worker
             const size_t nedges_in,
             const std::string dirtxt_in,
             const std::string heap_type_in,
+            const double dist_threshold_in,
             const std::shared_ptr <DGraph> g_in) :
-        nverts (nverts_in), nedges (nedges_in),
-        dirtxt (dirtxt_in), heap_type (heap_type_in), g (g_in)
+        nverts (nverts_in), nedges (nedges_in), dirtxt (dirtxt_in),
+        heap_type (heap_type_in), dist_threshold (dist_threshold_in), g (g_in)
     {
     }
 
@@ -141,7 +145,7 @@ struct OneCentralityEdge : public RcppParallel::Worker
 
         for (size_t v = begin; v < end; v++)
         {
-            pathfinder->Centrality_edge (cent, v, nedges);
+            pathfinder->Centrality_edge (cent, v, nedges, dist_threshold);
         }
         // dump flowvec to a file; chance of re-generating same file name is
         // 61^10, so there's no check for re-use of same
@@ -157,7 +161,8 @@ struct OneCentralityEdge : public RcppParallel::Worker
 
 void PF::PathFinder::Centrality_vertex (
         std::vector <double>& cent,
-        const unsigned int s)
+        const unsigned int s,
+        const double dist_threshold)
 {
     const DGraphEdge *edge;
 
@@ -242,7 +247,8 @@ void PF::PathFinder::Centrality_vertex (
 void PF::PathFinder::Centrality_edge (
         std::vector <double>& cent,
         const unsigned int s,
-        const unsigned int nedges)
+        const unsigned int nedges,
+        const double dist_threshold)
 {
     const DGraphEdge *edge;
 
@@ -346,7 +352,8 @@ void PF::PathFinder::Centrality_edge (
 void rcpp_centrality_vertex (const Rcpp::DataFrame graph,
         const Rcpp::DataFrame vert_map_in,
         const std::string& heap_type,
-        const std::string dirtxt)
+        const std::string dirtxt,
+        const double dist_threshold)
 {
     std::vector <std::string> from = graph ["from"];
     std::vector <std::string> to = graph ["to"];
@@ -364,7 +371,8 @@ void rcpp_centrality_vertex (const Rcpp::DataFrame graph,
     inst_graph (g, nedges, vert_map, from, to, dist, wt);
 
     // Create parallel worker
-    OneCentralityVert one_centrality (nverts, dirtxt, heap_type, g);
+    OneCentralityVert one_centrality (nverts, dirtxt, heap_type,
+            dist_threshold, g);
 
     GetRNGstate (); // Initialise R random seed
     RcppParallel::parallelFor (0, nverts, one_centrality);
@@ -378,7 +386,8 @@ void rcpp_centrality_vertex (const Rcpp::DataFrame graph,
 void rcpp_centrality_edge (const Rcpp::DataFrame graph,
         const Rcpp::DataFrame vert_map_in,
         const std::string& heap_type,
-        const std::string dirtxt)
+        const std::string dirtxt,
+        const double dist_threshold)
 {
     std::vector <std::string> from = graph ["from"];
     std::vector <std::string> to = graph ["to"];
@@ -396,7 +405,8 @@ void rcpp_centrality_edge (const Rcpp::DataFrame graph,
     inst_graph (g, nedges, vert_map, from, to, dist, wt);
 
     // Create parallel worker
-    OneCentralityEdge one_centrality (nverts, nedges, dirtxt, heap_type, g);
+    OneCentralityEdge one_centrality (nverts, nedges, dirtxt, heap_type,
+            dist_threshold, g);
 
     GetRNGstate (); // Initialise R random seed
     RcppParallel::parallelFor (0, nverts, one_centrality);

src/pathfinders.h

@@ -111,11 +111,13 @@ class PathFinder {
                 unsigned int v0);
         void Centrality_vertex (
                 std::vector <double>& cent,
-                const unsigned int s);
+                const unsigned int s,
+                const double dist_threshold);
         void Centrality_edge (
                 std::vector <double>& cent,
                 const unsigned int s,
-                const unsigned int nedges);
+                const unsigned int nedges,
+                const double dist_threshold);
 
     private:
         Heap *m_heap;        // pointer: heap

src/run_sp.h

@@ -67,9 +67,11 @@ Rcpp::List rcpp_get_paths (const Rcpp::DataFrame graph,
 void rcpp_centrality_vertex (const Rcpp::DataFrame graph,
         const Rcpp::DataFrame vert_map_in,
         const std::string& heap_type,
-        const std::string dirtxt);
+        const std::string dirtxt,
+        const double dist_threshold);
 
 void rcpp_centrality_edge (const Rcpp::DataFrame graph,
         const Rcpp::DataFrame vert_map_in,
         const std::string& heap_type,
-        const std::string dirtxt);
+        const std::string dirtxt,
+        const double dist_threshold);