feat: voronoi()

DESCRIPTION

@@ -70,5 +70,5 @@ Config/testthat/start-first: vs-es, scan, vs-operators, weakref,
     watts.strogatz.game
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.3.0.9000
+RoxygenNote: 7.3.1
 SystemRequirements: gmp, libxml2, glpk (>= 4.57)

NAMESPACE

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

R/aaa-auto.R

@@ -739,8 +739,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 Voronoi cells.
+#' @inheritParams distances
+#' @param mode Character string. In directed graphs, whether to compute
+#'   distances from generator vertices to other vertices (\dQuote{out}), to
+#'   generatorvertices from other vertices (\dQuote{in}), or ignore edge
+#'   directions entirely (\dQuote{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. \dQuote{random} assigns
+#'   a minimal-distance generator randomly, \dQuote{first} takes the first one,
+#'   and \dQuote{last} takes the last one.
+#' @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}
+#' @author Szabolcs Horvát \email{[email protected]}
+#' @seealso [distances()]
+#' @examples
+#'
+#' g <- make_lattice(c(10,10))
+#' clu <- voronoi(g, c(25, 43, 67))
+#' groups(clu)
+#' plot(g, vertex.color=clu$membership)
+#'
+#' @export
+#' @family community
+voronoi <- voronoi_impl

tools/stimulus/functions-R.yaml

@@ -367,6 +367,10 @@ igraph_distances_johnson:
 igraph_distances_floyd_warshall:
 
 igraph_voronoi:
+    PARAMS: |-
+        GRAPH graph, OUT VECTOR_INT membership, OUT VECTOR distances,
+        VERTEX_INDICES generators, *, EDGEWEIGHTS weights=NULL, NEIMODE mode=OUT,
+        VORONOI_TIEBREAKER tiebreaker=RANDOM
 
 igraph_get_all_simple_paths:
     IGNORE: RR