diff --git a/NAMESPACE b/NAMESPACE index 593ae4789ce..1e24abca1f1 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -378,6 +378,7 @@ export(get.stochastic) export(get.vertex.attribute) export(getIgraphOpt) export(get_diameter) +export(get_edge_ids) export(girth) export(global_efficiency) export(gnm) diff --git a/R/indexing.R b/R/indexing.R index e30b31733fa..aa2db39f4eb 100644 --- a/R/indexing.R +++ b/R/indexing.R @@ -183,7 +183,7 @@ ################################################################## if (!missing(from)) { - res <- get.edge.ids(x, rbind(from, to), error = FALSE) + res <- get_edge_ids(x, rbind(from, to), error = FALSE) if (edges) { ## nop } else if (!is.null(attr)) { diff --git a/R/interface.R b/R/interface.R index f6281fb4cfb..114d14664b8 100644 --- a/R/interface.R +++ b/R/interface.R @@ -251,7 +251,7 @@ add_vertices <- function(graph, nv, ..., attr = list()) { #' g #' #' g <- make_ring(5) -#' g <- delete_edges(g, get.edge.ids(g, c(1, 5, 4, 5))) +#' g <- delete_edges(g, get_edge_ids(g, c(1, 5, 4, 5))) #' g delete_edges <- function(graph, edges) { ensure_igraph(graph) @@ -490,8 +490,6 @@ get.edges <- function(graph, es) { #' @param error Logical scalar, whether to report an error if an edge is not #' found in the graph. If `FALSE`, then no error is reported, and zero is #' returned for the non-existant edge(s). -#' @param multi -#' `r lifecycle::badge("deprecated")` #' @return A numeric vector of edge ids, one for each pair of input vertices. #' If there is no edge in the input graph for a given pair of vertices, then #' zero is reported. (If the `error` argument is `FALSE`.) @@ -502,27 +500,50 @@ get.edges <- function(graph, es) { #' @examples #' #' g <- make_ring(10) -#' ei <- get.edge.ids(g, c(1, 2, 4, 5)) +#' ei <- get_edge_ids(g, c(1, 2, 4, 5)) #' E(g)[ei] #' #' ## non-existant edge -#' get.edge.ids(g, c(2, 1, 1, 4, 5, 4)) +#' get_edge_ids(g, c(2, 1, 1, 4, 5, 4)) #' #' ## For multiple edges, a single edge id is returned, #' ## as many times as corresponding pairs in the vertex series. #' g <- make_graph(rep(c(1, 2), 5)) -#' eis <- get.edge.ids(g, c(1, 2, 1, 2)) +#' eis <- get_edge_ids(g, c(1, 2, 1, 2)) #' eis #' E(g)[eis] #' -get.edge.ids <- function( - graph, - vp, - directed = TRUE, - error = FALSE, - multi = deprecated()) { +get_edge_ids <- function(graph, + vp, + directed = TRUE, + error = FALSE) { ensure_igraph(graph) + on.exit(.Call(R_igraph_finalizer)) + .Call( + R_igraph_get_eids, graph, as_igraph_vs(graph, vp) - 1, + as.logical(directed), as.logical(error) + ) + 1 +} + +#' Find the edge ids based on the incident vertices of the edges +#' +#' @description +#' `r lifecycle::badge("deprecated")` +#' +#' `get.edge.ids()` was renamed to `get_edge_ids()` to create a more +#' consistent API. +#' @inheritParams get_edge_ids +#' @param multi +#' `r lifecycle::badge("deprecated")` +#' @keywords internal +#' @export +get.edge.ids <- function(graph, + vp, + directed = TRUE, + error = FALSE, + multi = deprecated()) { + if (lifecycle::is_present(multi)) { if (isTRUE(multi)) { lifecycle::deprecate_stop("2.0.0", "get.edge.ids(multi = )") @@ -530,15 +551,10 @@ get.edge.ids <- function( lifecycle::deprecate_soft("2.0.0", "get.edge.ids(multi = )") } - - on.exit(.Call(R_igraph_finalizer)) - .Call( - R_igraph_get_eids, graph, as_igraph_vs(graph, vp) - 1, - as.logical(directed), as.logical(error) - ) + 1 + lifecycle::deprecate_soft("2.0.4", "get.edge.ids()", "get_edge_ids()") + get_edge_ids(graph = graph, vp = vp, directed = directed, error = error) } - #' Order (number of vertices) of a graph #' #' @description `vcount()` and `gorder()` are aliases. diff --git a/R/iterators.R b/R/iterators.R index 105577f0b4b..001c35850dc 100644 --- a/R/iterators.R +++ b/R/iterators.R @@ -1453,7 +1453,7 @@ as_igraph_es <- function(graph, e) { if (!"name" %in% vertex_attr_names(graph)) { vp <- as.numeric(vp) } - res[Pairs] <- get.edge.ids(graph, vp) + res[Pairs] <- get_edge_ids(graph, vp) } ## Based on edge ids/names diff --git a/man/adjacent_vertices.Rd b/man/adjacent_vertices.Rd index 80b0b5d1770..61a934277fc 100644 --- a/man/adjacent_vertices.Rd +++ b/man/adjacent_vertices.Rd @@ -32,7 +32,7 @@ Other structural queries: \code{\link{[[.igraph}()}, \code{\link{are_adjacent}()}, \code{\link{ends}()}, -\code{\link{get.edge.ids}()}, +\code{\link{get_edge_ids}()}, \code{\link{gorder}()}, \code{\link{gsize}()}, \code{\link{head_of}()}, diff --git a/man/are_adjacent.Rd b/man/are_adjacent.Rd index 6ddd1788001..56843838e5b 100644 --- a/man/are_adjacent.Rd +++ b/man/are_adjacent.Rd @@ -37,7 +37,7 @@ Other structural queries: \code{\link{[[.igraph}()}, \code{\link{adjacent_vertices}()}, \code{\link{ends}()}, -\code{\link{get.edge.ids}()}, +\code{\link{get_edge_ids}()}, \code{\link{gorder}()}, \code{\link{gsize}()}, \code{\link{head_of}()}, diff --git a/man/delete_edges.Rd b/man/delete_edges.Rd index 1233663c2b7..62c7f23b37c 100644 --- a/man/delete_edges.Rd +++ b/man/delete_edges.Rd @@ -30,7 +30,7 @@ g <- make_ring(10) \%>\% g g <- make_ring(5) -g <- delete_edges(g, get.edge.ids(g, c(1, 5, 4, 5))) +g <- delete_edges(g, get_edge_ids(g, c(1, 5, 4, 5))) g } \seealso{ diff --git a/man/ends.Rd b/man/ends.Rd index 6d07e647abf..2274c14a7c0 100644 --- a/man/ends.Rd +++ b/man/ends.Rd @@ -31,7 +31,7 @@ Other structural queries: \code{\link{[[.igraph}()}, \code{\link{adjacent_vertices}()}, \code{\link{are_adjacent}()}, -\code{\link{get.edge.ids}()}, +\code{\link{get_edge_ids}()}, \code{\link{gorder}()}, \code{\link{gsize}()}, \code{\link{head_of}()}, diff --git a/man/get.edge.ids.Rd b/man/get.edge.ids.Rd index 6cc9fbcb990..b57e9280cd5 100644 --- a/man/get.edge.ids.Rd +++ b/man/get.edge.ids.Rd @@ -22,58 +22,10 @@ returned for the non-existant edge(s).} \item{multi}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}} } -\value{ -A numeric vector of edge ids, one for each pair of input vertices. -If there is no edge in the input graph for a given pair of vertices, then -zero is reported. (If the \code{error} argument is \code{FALSE}.) -} \description{ -Find the edges in an igraph graph that have the specified end points. This -function handles multi-graph (graphs with multiple edges) and can consider -or ignore the edge directions in directed graphs. -} -\details{ -igraph vertex ids are natural numbers, starting from one, up to the number -of vertices in the graph. Similarly, edges are also numbered from one, up to -the number of edges. - -This function allows finding the edges of the graph, via their incident -vertices. -} -\examples{ - -g <- make_ring(10) -ei <- get.edge.ids(g, c(1, 2, 4, 5)) -E(g)[ei] +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} -## non-existant edge -get.edge.ids(g, c(2, 1, 1, 4, 5, 4)) - -## For multiple edges, a single edge id is returned, -## as many times as corresponding pairs in the vertex series. -g <- make_graph(rep(c(1, 2), 5)) -eis <- get.edge.ids(g, c(1, 2, 1, 2)) -eis -E(g)[eis] - -} -\seealso{ -Other structural queries: -\code{\link{[.igraph}()}, -\code{\link{[[.igraph}()}, -\code{\link{adjacent_vertices}()}, -\code{\link{are_adjacent}()}, -\code{\link{ends}()}, -\code{\link{gorder}()}, -\code{\link{gsize}()}, -\code{\link{head_of}()}, -\code{\link{incident}()}, -\code{\link{incident_edges}()}, -\code{\link{is_directed}()}, -\code{\link{neighbors}()}, -\code{\link{tail_of}()} -} -\author{ -Gabor Csardi \email{csardi.gabor@gmail.com} +\code{get.edge.ids()} was renamed to \code{get_edge_ids()} to create a more +consistent API. } -\concept{structural queries} +\keyword{internal} diff --git a/man/get_edge_ids.Rd b/man/get_edge_ids.Rd new file mode 100644 index 00000000000..6c0c6a8bf86 --- /dev/null +++ b/man/get_edge_ids.Rd @@ -0,0 +1,77 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/interface.R +\name{get_edge_ids} +\alias{get_edge_ids} +\title{Find the edge ids based on the incident vertices of the edges} +\usage{ +get_edge_ids(graph, vp, directed = TRUE, error = FALSE) +} +\arguments{ +\item{graph}{The input graph.} + +\item{vp}{The incident vertices, given as vertex ids or symbolic vertex +names. They are interpreted pairwise, i.e. the first and second are used for +the first edge, the third and fourth for the second, etc.} + +\item{directed}{Logical scalar, whether to consider edge directions in +directed graphs. This argument is ignored for undirected graphs.} + +\item{error}{Logical scalar, whether to report an error if an edge is not +found in the graph. If \code{FALSE}, then no error is reported, and zero is +returned for the non-existant edge(s).} +} +\value{ +A numeric vector of edge ids, one for each pair of input vertices. +If there is no edge in the input graph for a given pair of vertices, then +zero is reported. (If the \code{error} argument is \code{FALSE}.) +} +\description{ +Find the edges in an igraph graph that have the specified end points. This +function handles multi-graph (graphs with multiple edges) and can consider +or ignore the edge directions in directed graphs. +} +\details{ +igraph vertex ids are natural numbers, starting from one, up to the number +of vertices in the graph. Similarly, edges are also numbered from one, up to +the number of edges. + +This function allows finding the edges of the graph, via their incident +vertices. +} +\examples{ + +g <- make_ring(10) +ei <- get_edge_ids(g, c(1, 2, 4, 5)) +E(g)[ei] + +## non-existant edge +get_edge_ids(g, c(2, 1, 1, 4, 5, 4)) + +## For multiple edges, a single edge id is returned, +## as many times as corresponding pairs in the vertex series. +g <- make_graph(rep(c(1, 2), 5)) +eis <- get_edge_ids(g, c(1, 2, 1, 2)) +eis +E(g)[eis] + +} +\seealso{ +Other structural queries: +\code{\link{[.igraph}()}, +\code{\link{[[.igraph}()}, +\code{\link{adjacent_vertices}()}, +\code{\link{are_adjacent}()}, +\code{\link{ends}()}, +\code{\link{gorder}()}, +\code{\link{gsize}()}, +\code{\link{head_of}()}, +\code{\link{incident}()}, +\code{\link{incident_edges}()}, +\code{\link{is_directed}()}, +\code{\link{neighbors}()}, +\code{\link{tail_of}()} +} +\author{ +Gabor Csardi \email{csardi.gabor@gmail.com} +} +\concept{structural queries} diff --git a/man/gorder.Rd b/man/gorder.Rd index 99ca1cd0c19..407d273fd05 100644 --- a/man/gorder.Rd +++ b/man/gorder.Rd @@ -30,7 +30,7 @@ Other structural queries: \code{\link{adjacent_vertices}()}, \code{\link{are_adjacent}()}, \code{\link{ends}()}, -\code{\link{get.edge.ids}()}, +\code{\link{get_edge_ids}()}, \code{\link{gsize}()}, \code{\link{head_of}()}, \code{\link{incident}()}, diff --git a/man/gsize.Rd b/man/gsize.Rd index 26c1f80de3c..31d99ee4c17 100644 --- a/man/gsize.Rd +++ b/man/gsize.Rd @@ -35,7 +35,7 @@ Other structural queries: \code{\link{adjacent_vertices}()}, \code{\link{are_adjacent}()}, \code{\link{ends}()}, -\code{\link{get.edge.ids}()}, +\code{\link{get_edge_ids}()}, \code{\link{gorder}()}, \code{\link{head_of}()}, \code{\link{incident}()}, diff --git a/man/head_of.Rd b/man/head_of.Rd index b8ca1abeaa8..adeda86f7f1 100644 --- a/man/head_of.Rd +++ b/man/head_of.Rd @@ -26,7 +26,7 @@ Other structural queries: \code{\link{adjacent_vertices}()}, \code{\link{are_adjacent}()}, \code{\link{ends}()}, -\code{\link{get.edge.ids}()}, +\code{\link{get_edge_ids}()}, \code{\link{gorder}()}, \code{\link{gsize}()}, \code{\link{incident}()}, diff --git a/man/incident.Rd b/man/incident.Rd index a60ebb9a4da..b69fb6b753c 100644 --- a/man/incident.Rd +++ b/man/incident.Rd @@ -34,7 +34,7 @@ Other structural queries: \code{\link{adjacent_vertices}()}, \code{\link{are_adjacent}()}, \code{\link{ends}()}, -\code{\link{get.edge.ids}()}, +\code{\link{get_edge_ids}()}, \code{\link{gorder}()}, \code{\link{gsize}()}, \code{\link{head_of}()}, diff --git a/man/incident_edges.Rd b/man/incident_edges.Rd index 808632f7d8e..bbf46bfe2ca 100644 --- a/man/incident_edges.Rd +++ b/man/incident_edges.Rd @@ -33,7 +33,7 @@ Other structural queries: \code{\link{adjacent_vertices}()}, \code{\link{are_adjacent}()}, \code{\link{ends}()}, -\code{\link{get.edge.ids}()}, +\code{\link{get_edge_ids}()}, \code{\link{gorder}()}, \code{\link{gsize}()}, \code{\link{head_of}()}, diff --git a/man/is_directed.Rd b/man/is_directed.Rd index 17b6113eda2..73e2fce6024 100644 --- a/man/is_directed.Rd +++ b/man/is_directed.Rd @@ -29,7 +29,7 @@ Other structural queries: \code{\link{adjacent_vertices}()}, \code{\link{are_adjacent}()}, \code{\link{ends}()}, -\code{\link{get.edge.ids}()}, +\code{\link{get_edge_ids}()}, \code{\link{gorder}()}, \code{\link{gsize}()}, \code{\link{head_of}()}, diff --git a/man/neighbors.Rd b/man/neighbors.Rd index d8260d32154..b97ce8ef930 100644 --- a/man/neighbors.Rd +++ b/man/neighbors.Rd @@ -35,7 +35,7 @@ Other structural queries: \code{\link{adjacent_vertices}()}, \code{\link{are_adjacent}()}, \code{\link{ends}()}, -\code{\link{get.edge.ids}()}, +\code{\link{get_edge_ids}()}, \code{\link{gorder}()}, \code{\link{gsize}()}, \code{\link{head_of}()}, diff --git a/man/sub-.igraph.Rd b/man/sub-.igraph.Rd index bddf6801851..02f1c83cd31 100644 --- a/man/sub-.igraph.Rd +++ b/man/sub-.igraph.Rd @@ -129,7 +129,7 @@ Other structural queries: \code{\link{adjacent_vertices}()}, \code{\link{are_adjacent}()}, \code{\link{ends}()}, -\code{\link{get.edge.ids}()}, +\code{\link{get_edge_ids}()}, \code{\link{gorder}()}, \code{\link{gsize}()}, \code{\link{head_of}()}, diff --git a/man/sub-sub-.igraph.Rd b/man/sub-sub-.igraph.Rd index c8f68b5a4f3..713e9b1555f 100644 --- a/man/sub-sub-.igraph.Rd +++ b/man/sub-sub-.igraph.Rd @@ -75,7 +75,7 @@ Other structural queries: \code{\link{adjacent_vertices}()}, \code{\link{are_adjacent}()}, \code{\link{ends}()}, -\code{\link{get.edge.ids}()}, +\code{\link{get_edge_ids}()}, \code{\link{gorder}()}, \code{\link{gsize}()}, \code{\link{head_of}()}, diff --git a/man/tail_of.Rd b/man/tail_of.Rd index 3368f78b9e7..b2f2df6d993 100644 --- a/man/tail_of.Rd +++ b/man/tail_of.Rd @@ -26,7 +26,7 @@ Other structural queries: \code{\link{adjacent_vertices}()}, \code{\link{are_adjacent}()}, \code{\link{ends}()}, -\code{\link{get.edge.ids}()}, +\code{\link{get_edge_ids}()}, \code{\link{gorder}()}, \code{\link{gsize}()}, \code{\link{head_of}()}, diff --git a/tests/testthat/_snaps/interface.md b/tests/testthat/_snaps/interface.md new file mode 100644 index 00000000000..e53e5723bc9 --- /dev/null +++ b/tests/testthat/_snaps/interface.md @@ -0,0 +1,19 @@ +# get.edge.ids() deprecation + + Code + get.edge.ids(g, 1:2) + Condition + Warning: + `get.edge.ids()` was deprecated in igraph 2.0.4. + i Please use `get_edge_ids()` instead. + Output + [1] 0 + +--- + + Code + get.edge.ids(g, 1:2, multi = TRUE) + Condition + Error: + ! The `multi` argument of `get.edge.ids()` was deprecated in igraph 2.0.0 and is now defunct. + diff --git a/tests/testthat/test-interface.R b/tests/testthat/test-interface.R index a9d68a42f4d..4c605652267 100644 --- a/tests/testthat/test-interface.R +++ b/tests/testthat/test-interface.R @@ -4,7 +4,7 @@ test_that("add_edges keeps edge id order", { g2 <- add_edges(g, edges) expect_equal(ecount(g2), length(edges) / 2) - expect_equal(get.edge.ids(g2, edges), seq_len(length(edges) / 2)) + expect_equal(get_edge_ids(g2, edges), seq_len(length(edges) / 2)) }) test_that("add_edges adds attributes", { @@ -14,7 +14,7 @@ test_that("add_edges adds attributes", { g3 <- add_edges(g, edges, attr = list(weight = weights)) expect_equal(ecount(g3), (length(edges) / 2)) - expect_equal(get.edge.ids(g3, edges), seq_len(length(edges) / 2)) + expect_equal(get_edge_ids(g3, edges), seq_len(length(edges) / 2)) expect_equal(E(g3)$weight, weights) }) @@ -117,3 +117,9 @@ test_that("ends works", { g2 <- make_graph(edges, dir = FALSE, n = vcount(g)) expect_isomorphic(g, g2) }) + +test_that("get.edge.ids() deprecation", { + g <- make_empty_graph(10) + expect_snapshot(get.edge.ids(g, 1:2)) + expect_snapshot(get.edge.ids(g, 1:2, multi = TRUE), error = TRUE) +}) diff --git a/vignettes/igraph.Rmd b/vignettes/igraph.Rmd index a886b4ea9b0..7b81e68a49d 100644 --- a/vignettes/igraph.Rmd +++ b/vignettes/igraph.Rmd @@ -146,7 +146,7 @@ g We now have an undirected graph with 40 vertices and 86 edges. Vertex and edge IDs are always *contiguous*, so if you delete a vertex all subsequent vertices will be renumbered. When a vertex is renumbered, edges are **not** renumbered, but their source and target vertices will be. Use `delete_vertices()` and `delete_edges()` to perform these operations. For instance, to delete the edge connecting vertices `1-34`, get its ID and then delete it: ```{r echo = TRUE} -edge_id_to_delete <- get.edge.ids(g, c(1, 34)) +edge_id_to_delete <- get_edge_ids(g, c(1, 34)) edge_id_to_delete ``` @@ -161,11 +161,11 @@ g <- make_ring(10) %>% delete_edges("10|1") plot(g) ``` -The example above shows that you can also refer to edges with strings containing the IDs of the source and target vertices, connected by a pipe symbol `|`. `"10|1"` in the above example means the edge that connects vertex 10 to vertex 1. Of course you can also use the edge IDs directly, or retrieve them with the `get.edge.ids()` function: +The example above shows that you can also refer to edges with strings containing the IDs of the source and target vertices, connected by a pipe symbol `|`. `"10|1"` in the above example means the edge that connects vertex 10 to vertex 1. Of course you can also use the edge IDs directly, or retrieve them with the `get_edge_ids()` function: ```{r echo = TRUE} g <- make_ring(5) -g <- delete_edges(g, get.edge.ids(g, c(1, 5, 4, 5))) +g <- delete_edges(g, get_edge_ids(g, c(1, 5, 4, 5))) plot(g) ``` diff --git a/vignettes/igraph_ES.rmd b/vignettes/igraph_ES.rmd index 62139534813..a43d3da9a2b 100644 --- a/vignettes/igraph_ES.rmd +++ b/vignettes/igraph_ES.rmd @@ -153,7 +153,7 @@ g Ahora tenemos un grafo no dirigido con 40 vértices y 89 aristas. Los IDs de los vértices y aristas son siempre *contiguos*, así que si borras un vértice, todos los vértices subsecuentes se vuelven a enumerar. Cuando se re-numera un vértice, las aristas **no** se vuelven a enumerar, pero sí sus vértices origen y destino. Puedes usar `delete_vertices()` y `delete_edges()` para realizar estas operaciones. Por ejemplo, para borrar la arista que conecta los vértices `1-34`, obtén su ID y luego bórrala: ```{r echo = TRUE} -edge_id_para_borrar <- get.edge.ids(g, c(1,34)) +edge_id_para_borrar <- get_edge_ids(g, c(1,34)) edge_id_para_borrar ``` @@ -168,11 +168,11 @@ g <- make_ring(10) %>% delete_edges("10|1") plot(g) ``` -El ejemplo anterior muestra que también puedes referirte a las aristas indicando los IDs de los vértices origen y destino, conectados por el símbolo `|`. En el ejemplo, `"10|1"` significa la arista que conecta el vértice `10` con el vértice `1`. Por supuesto, también puedes usar los IDs de las aristas directamente, o recuperarlos con la función `get.edge.ids()`: +El ejemplo anterior muestra que también puedes referirte a las aristas indicando los IDs de los vértices origen y destino, conectados por el símbolo `|`. En el ejemplo, `"10|1"` significa la arista que conecta el vértice `10` con el vértice `1`. Por supuesto, también puedes usar los IDs de las aristas directamente, o recuperarlos con la función `get_edge_ids()`: ```{r echo = TRUE} g <- make_ring(5) -g <- delete_edges(g, get.edge.ids(g, c(1,5, 4,5))) +g <- delete_edges(g, get_edge_ids(g, c(1,5, 4,5))) plot(g) ```