diff --git a/DESCRIPTION b/DESCRIPTION index 1ab860c8cd..2707c5c077 100644 --- a/DESCRIPTION +++ b/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) diff --git a/NAMESPACE b/NAMESPACE index e1c4ab5393..6d45f125d5 100644 --- a/NAMESPACE +++ b/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) diff --git a/R/aaa-auto.R b/R/aaa-auto.R index e6c01f42d0..3f6efa3bed 100644 --- a/R/aaa-auto.R +++ b/R/aaa-auto.R @@ -740,8 +740,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)) { diff --git a/R/community.R b/R/community.R index 5f9a5d90d0..4adaa0668e 100644 --- a/R/community.R +++ b/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(g, c(25, 43, 67)) +#' groups(clu) +#' plot(g, vertex.color=clu$membership) +#' +#' @export +#' @family community +voronoi <- voronoi_impl diff --git a/man/as_membership.Rd b/man/as_membership.Rd index fc3d64d31c..90f9c676c6 100644 --- a/man/as_membership.Rd +++ b/man/as_membership.Rd @@ -45,6 +45,7 @@ Community detection \code{\link{membership}()}, \code{\link{modularity.igraph}()}, \code{\link{plot_dendrogram}()}, -\code{\link{split_join_distance}()} +\code{\link{split_join_distance}()}, +\code{\link{voronoi}()} } \concept{community} diff --git a/man/cluster_edge_betweenness.Rd b/man/cluster_edge_betweenness.Rd index cc5dd190a5..24edc27159 100644 --- a/man/cluster_edge_betweenness.Rd +++ b/man/cluster_edge_betweenness.Rd @@ -127,7 +127,8 @@ Community detection \code{\link{membership}()}, \code{\link{modularity.igraph}()}, \code{\link{plot_dendrogram}()}, -\code{\link{split_join_distance}()} +\code{\link{split_join_distance}()}, +\code{\link{voronoi}()} } \author{ Gabor Csardi \email{csardi.gabor@gmail.com} diff --git a/man/cluster_fast_greedy.Rd b/man/cluster_fast_greedy.Rd index 89e011519d..7bcae85070 100644 --- a/man/cluster_fast_greedy.Rd +++ b/man/cluster_fast_greedy.Rd @@ -86,7 +86,8 @@ Community detection \code{\link{membership}()}, \code{\link{modularity.igraph}()}, \code{\link{plot_dendrogram}()}, -\code{\link{split_join_distance}()} +\code{\link{split_join_distance}()}, +\code{\link{voronoi}()} } \author{ Tamas Nepusz \email{ntamas@gmail.com} and Gabor Csardi diff --git a/man/cluster_fluid_communities.Rd b/man/cluster_fluid_communities.Rd index cfefcfd373..36c81cc0b7 100644 --- a/man/cluster_fluid_communities.Rd +++ b/man/cluster_fluid_communities.Rd @@ -66,7 +66,8 @@ Community detection \code{\link{membership}()}, \code{\link{modularity.igraph}()}, \code{\link{plot_dendrogram}()}, -\code{\link{split_join_distance}()} +\code{\link{split_join_distance}()}, +\code{\link{voronoi}()} } \author{ Ferran Parés diff --git a/man/cluster_infomap.Rd b/man/cluster_infomap.Rd index c486514b71..67542a3f91 100644 --- a/man/cluster_infomap.Rd +++ b/man/cluster_infomap.Rd @@ -86,7 +86,8 @@ Community detection \code{\link{membership}()}, \code{\link{modularity.igraph}()}, \code{\link{plot_dendrogram}()}, -\code{\link{split_join_distance}()} +\code{\link{split_join_distance}()}, +\code{\link{voronoi}()} } \author{ Martin Rosvall wrote the original C++ code. This was ported to diff --git a/man/cluster_label_prop.Rd b/man/cluster_label_prop.Rd index 7e6e71977b..452a05d329 100644 --- a/man/cluster_label_prop.Rd +++ b/man/cluster_label_prop.Rd @@ -105,7 +105,8 @@ Community detection \code{\link{membership}()}, \code{\link{modularity.igraph}()}, \code{\link{plot_dendrogram}()}, -\code{\link{split_join_distance}()} +\code{\link{split_join_distance}()}, +\code{\link{voronoi}()} } \author{ Tamas Nepusz \email{ntamas@gmail.com} for the C implementation, diff --git a/man/cluster_leading_eigen.Rd b/man/cluster_leading_eigen.Rd index 63be0e7d3a..48de081f57 100644 --- a/man/cluster_leading_eigen.Rd +++ b/man/cluster_leading_eigen.Rd @@ -139,7 +139,8 @@ Community detection \code{\link{membership}()}, \code{\link{modularity.igraph}()}, \code{\link{plot_dendrogram}()}, -\code{\link{split_join_distance}()} +\code{\link{split_join_distance}()}, +\code{\link{voronoi}()} } \author{ Gabor Csardi \email{csardi.gabor@gmail.com} diff --git a/man/cluster_leiden.Rd b/man/cluster_leiden.Rd index dc97b8b91a..899ecab60d 100644 --- a/man/cluster_leiden.Rd +++ b/man/cluster_leiden.Rd @@ -148,7 +148,8 @@ Community detection \code{\link{membership}()}, \code{\link{modularity.igraph}()}, \code{\link{plot_dendrogram}()}, -\code{\link{split_join_distance}()} +\code{\link{split_join_distance}()}, +\code{\link{voronoi}()} } \author{ Vincent Traag diff --git a/man/cluster_louvain.Rd b/man/cluster_louvain.Rd index ef47e62fe6..45f65c1db3 100644 --- a/man/cluster_louvain.Rd +++ b/man/cluster_louvain.Rd @@ -93,7 +93,8 @@ Community detection \code{\link{membership}()}, \code{\link{modularity.igraph}()}, \code{\link{plot_dendrogram}()}, -\code{\link{split_join_distance}()} +\code{\link{split_join_distance}()}, +\code{\link{voronoi}()} } \author{ Tom Gregorovic, Tamas Nepusz \email{ntamas@gmail.com} diff --git a/man/cluster_optimal.Rd b/man/cluster_optimal.Rd index 1b27644744..d19b286357 100644 --- a/man/cluster_optimal.Rd +++ b/man/cluster_optimal.Rd @@ -92,7 +92,8 @@ Community detection \code{\link{membership}()}, \code{\link{modularity.igraph}()}, \code{\link{plot_dendrogram}()}, -\code{\link{split_join_distance}()} +\code{\link{split_join_distance}()}, +\code{\link{voronoi}()} } \author{ Gabor Csardi \email{csardi.gabor@gmail.com} diff --git a/man/cluster_spinglass.Rd b/man/cluster_spinglass.Rd index 765f526880..2607c56416 100644 --- a/man/cluster_spinglass.Rd +++ b/man/cluster_spinglass.Rd @@ -163,7 +163,8 @@ Community detection \code{\link{membership}()}, \code{\link{modularity.igraph}()}, \code{\link{plot_dendrogram}()}, -\code{\link{split_join_distance}()} +\code{\link{split_join_distance}()}, +\code{\link{voronoi}()} } \author{ Jorg Reichardt for the original code and Gabor Csardi diff --git a/man/cluster_walktrap.Rd b/man/cluster_walktrap.Rd index 7efa5a3117..2065012af3 100644 --- a/man/cluster_walktrap.Rd +++ b/man/cluster_walktrap.Rd @@ -92,7 +92,8 @@ Community detection \code{\link{membership}()}, \code{\link{modularity.igraph}()}, \code{\link{plot_dendrogram}()}, -\code{\link{split_join_distance}()} +\code{\link{split_join_distance}()}, +\code{\link{voronoi}()} } \author{ Pascal Pons (\url{http://psl.pons.free.fr/}) and Gabor Csardi diff --git a/man/communities.Rd b/man/communities.Rd index 26d22528db..d33dc88d7c 100644 --- a/man/communities.Rd +++ b/man/communities.Rd @@ -272,7 +272,8 @@ Community detection \code{\link{make_clusters}()}, \code{\link{modularity.igraph}()}, \code{\link{plot_dendrogram}()}, -\code{\link{split_join_distance}()} +\code{\link{split_join_distance}()}, +\code{\link{voronoi}()} } \author{ Gabor Csardi \email{csardi.gabor@gmail.com} diff --git a/man/compare.Rd b/man/compare.Rd index be522b0adb..66f8b4787f 100644 --- a/man/compare.Rd +++ b/man/compare.Rd @@ -84,7 +84,8 @@ Community detection \code{\link{membership}()}, \code{\link{modularity.igraph}()}, \code{\link{plot_dendrogram}()}, -\code{\link{split_join_distance}()} +\code{\link{split_join_distance}()}, +\code{\link{voronoi}()} } \author{ Tamas Nepusz \email{ntamas@gmail.com} diff --git a/man/groups.Rd b/man/groups.Rd index a72ac54bb8..7f927c5f06 100644 --- a/man/groups.Rd +++ b/man/groups.Rd @@ -58,6 +58,7 @@ Community detection \code{\link{membership}()}, \code{\link{modularity.igraph}()}, \code{\link{plot_dendrogram}()}, -\code{\link{split_join_distance}()} +\code{\link{split_join_distance}()}, +\code{\link{voronoi}()} } \concept{community} diff --git a/man/make_clusters.Rd b/man/make_clusters.Rd index 96521866a7..9c2749e2df 100644 --- a/man/make_clusters.Rd +++ b/man/make_clusters.Rd @@ -55,6 +55,7 @@ Community detection \code{\link{membership}()}, \code{\link{modularity.igraph}()}, \code{\link{plot_dendrogram}()}, -\code{\link{split_join_distance}()} +\code{\link{split_join_distance}()}, +\code{\link{voronoi}()} } \concept{community} diff --git a/man/modularity.igraph.Rd b/man/modularity.igraph.Rd index af780bb871..a568ec5382 100644 --- a/man/modularity.igraph.Rd +++ b/man/modularity.igraph.Rd @@ -121,7 +121,8 @@ Community detection \code{\link{make_clusters}()}, \code{\link{membership}()}, \code{\link{plot_dendrogram}()}, -\code{\link{split_join_distance}()} +\code{\link{split_join_distance}()}, +\code{\link{voronoi}()} } \author{ Gabor Csardi \email{csardi.gabor@gmail.com} diff --git a/man/plot_dendrogram.communities.Rd b/man/plot_dendrogram.communities.Rd index 03d1b48f6e..75f00ec261 100644 --- a/man/plot_dendrogram.communities.Rd +++ b/man/plot_dendrogram.communities.Rd @@ -118,7 +118,8 @@ Community detection \code{\link{make_clusters}()}, \code{\link{membership}()}, \code{\link{modularity.igraph}()}, -\code{\link{split_join_distance}()} +\code{\link{split_join_distance}()}, +\code{\link{voronoi}()} } \author{ Gabor Csardi \email{csardi.gabor@gmail.com} diff --git a/man/split_join_distance.Rd b/man/split_join_distance.Rd index 241059882b..e1cddf81b3 100644 --- a/man/split_join_distance.Rd +++ b/man/split_join_distance.Rd @@ -60,6 +60,7 @@ Community detection \code{\link{make_clusters}()}, \code{\link{membership}()}, \code{\link{modularity.igraph}()}, -\code{\link{plot_dendrogram}()} +\code{\link{plot_dendrogram}()}, +\code{\link{voronoi}()} } \concept{community} diff --git a/man/voronoi.Rd b/man/voronoi.Rd new file mode 100644 index 0000000000..742a12f43d --- /dev/null +++ b/man/voronoi.Rd @@ -0,0 +1,86 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/community.R +\name{voronoi} +\alias{voronoi} +\title{Voronoi partitioning of a graph} +\usage{ +voronoi( + graph, + generators, + ..., + weights = NULL, + mode = c("out", "in", "all", "total"), + tiebreaker = c("random", "first", "last") +) +} +\arguments{ +\item{graph}{The graph to partition into Voronoi cells.} + +\item{generators}{The generator vertices of the Voronoi cells.} + +\item{...}{These dots are for future extensions and must be empty.} + +\item{weights}{Possibly a numeric vector giving edge weights. If this is +\code{NULL} and the graph has a \code{weight} edge attribute, then the +attribute is used. If this is \code{NA} then no weights are used (even if +the graph has a \code{weight} attribute).} + +\item{mode}{Character string. In directed graphs, whether to compute +distances from generator vertices to other vertices (\code{"out"}), to +generator vertices from other vertices (\code{"in"}), or ignore edge +directions entirely (\code{"all"}). Ignored in undirected graphs.} + +\item{tiebreaker}{Character string that specifies what to do when a vertex +is at the same distance from multiple generators. \code{"random"} assigns +a minimal-distance generator randomly, \code{"first"} takes the first one, +and \code{"last"} takes the last one.} +} +\value{ +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} +} +\description{ +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[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. + +\code{\link[=groups]{groups()}} may be used on the output of this function. +} +\examples{ + +g <- make_lattice(c(10,10)) +clu <- voronoi(g, c(25, 43, 67)) +groups(clu) +plot(g, vertex.color=clu$membership) + +} +\seealso{ +\code{\link[=distances]{distances()}} + +Community detection +\code{\link{as_membership}()}, +\code{\link{cluster_edge_betweenness}()}, +\code{\link{cluster_fast_greedy}()}, +\code{\link{cluster_fluid_communities}()}, +\code{\link{cluster_infomap}()}, +\code{\link{cluster_label_prop}()}, +\code{\link{cluster_leading_eigen}()}, +\code{\link{cluster_leiden}()}, +\code{\link{cluster_louvain}()}, +\code{\link{cluster_optimal}()}, +\code{\link{cluster_spinglass}()}, +\code{\link{cluster_walktrap}()}, +\code{\link{compare}()}, +\code{\link{groups}()}, +\code{\link{make_clusters}()}, +\code{\link{membership}()}, +\code{\link{modularity.igraph}()}, +\code{\link{plot_dendrogram}()}, +\code{\link{split_join_distance}()} +} +\concept{community} diff --git a/tools/stimulus/functions-R.yaml b/tools/stimulus/functions-R.yaml index 5b33047654..8b4e0de033 100644 --- a/tools/stimulus/functions-R.yaml +++ b/tools/stimulus/functions-R.yaml @@ -367,6 +367,7 @@ igraph_distances_johnson: igraph_distances_floyd_warshall: igraph_voronoi: + FIRST_KW_PARAM: weights igraph_get_all_simple_paths: IGNORE: RR