feat: New voronoi_cells() to compute the Voronoi partitioning of a graph

NAMESPACE

@@ -863,6 +863,7 @@ export(vertex_attr_names)
 export(vertex_connectivity)
 export(vertex_disjoint_paths)
 export(vertices)
+export(voronoi_cells)
 export(walktrap.community)
 export(watts.strogatz.game)
 export(weighted_clique_num)

R/aaa-auto.R

@@ -763,8 +763,9 @@ distances_floyd_warshall_impl <- function(graph, from=V(graph), to=V(graph), wei
   res
 }
 
-voronoi_impl <- function(graph, generators, weights=NULL, mode=c("out", "in", "all", "total"), tiebreaker=c("random", "first", "last")) {
+voronoi_impl <- function(graph, generators, ..., weights=NULL, mode=c("out", "in", "all", "total"), tiebreaker=c("random", "first", "last")) {
   # Argument checks
+  check_dots_empty()
   ensure_igraph(graph)
   generators <- as_igraph_vs(graph, generators)
   if (is.null(weights) && "weight" %in% edge_attr_names(graph)) {

R/community.R

@@ -2782,3 +2782,44 @@ communities <- groups.communities
 #' @export
 #' @family functions for manipulating graph structure
 contract <- contract_vertices_impl
+
+
+#' Voronoi partitioning of a graph
+#'
+#' @description
+#' `r lifecycle::badge("experimental")`
+#'
+#' This function partitions the vertices of a graph based on a set of generator
+#' vertices. Each vertex is assigned to the generator vertex from (or to) which
+#' it is closest.
+#'
+#' [groups()] may be used on the output of this function.
+#'
+#' @param graph The graph to partition into Voronoi cells.
+#' @param generators The generator vertices of the Voronoi cells.
+#' @param mode Character string. In directed graphs, whether to compute
+#'   distances from generator vertices to other vertices (`"out"`), to
+#'   generator vertices from other vertices (`"in"`), or ignore edge
+#'   directions entirely (`"all"`). Ignored in undirected graphs.
+#' @param tiebreaker Character string that specifies what to do when a vertex
+#'   is at the same distance from multiple generators. `"random"` assigns
+#'   a minimal-distance generator randomly, `"first"` takes the first one,
+#'   and `"last"` takes the last one.
+#' @inheritParams distances
+#' @inheritParams rlang::args_dots_empty
+#' @return A named list with two components:
+#'   \item{membership}{numeric vector giving the cluster id to which each vertex
+#'   belongs.}
+#'   \item{distances}{numeric vector giving the distance of each vertex from its
+#'   generator}
+#' @seealso [distances()]
+#' @examples
+#'
+#' g <- make_lattice(c(10,10))
+#' clu <- voronoi_cells(g, c(25, 43, 67))
+#' groups(clu)
+#' plot(g, vertex.color=clu$membership)
+#'
+#' @export
+#' @family community
+voronoi_cells <- voronoi_impl

tests/testthat/test-voronoi.R

@@ -0,0 +1,11 @@
+test_that("voronoi works", {
+  res <- voronoi_cells(make_ring(10), c(1, 6))
+  expect_equal(res$membership, c(0, 0, 0, 1, 1, 1, 1, 1, 0, 0))
+  expect_equal(res$distances, c(0, 1, 2, 2, 1, 0, 1, 2, 2, 1))
+})
+
+test_that("voronoi works with weights", {
+  res <- voronoi_cells(make_ring(10), c(1, 6), weights = 1:10)
+  expect_equal(res$membership, c(0, 0, 0, 0, 1, 1, 1, 1, 0, 0))
+  expect_equal(res$distances, c(0, 1, 3, 6, 5, 0, 6, 13, 19, 10))
+})

tools/stimulus/functions-R.yaml

@@ -380,6 +380,7 @@ igraph_distances_johnson:
 igraph_distances_floyd_warshall:
 
 igraph_voronoi:
+    FIRST_KW_PARAM: weights
 
 igraph_get_all_simple_paths:
     IGNORE: RR