feat: change "incidence matrix" naming to "biadjacency matrix"

NAMESPACE

@@ -140,6 +140,7 @@ export(as_adj)
 export(as_adj_edge_list)
 export(as_adj_list)
 export(as_adjacency_matrix)
+export(as_biadjacency_matrix)
 export(as_bipartite)
 export(as_data_frame)
 export(as_edgelist)
@@ -442,6 +443,7 @@ export(graph_attr_names)
 export(graph_from_adj_list)
 export(graph_from_adjacency_matrix)
 export(graph_from_atlas)
+export(graph_from_biadjacency_matrix)
 export(graph_from_data_frame)
 export(graph_from_edgelist)
 export(graph_from_graphdb)

R/adjacency.R

@@ -374,7 +374,7 @@ graph_from_adjacency_matrix <- function(adjmatrix,
 
   if (!is.matrix(adjmatrix) && !inherits(adjmatrix, "Matrix")) {
     lifecycle::deprecate_soft(
-      "1.5.2",
+      "1.6.0",
       "graph_from_adjacency_matrix(adjmatrix = 'must be a matrix')"
     )
     adjmatrix <- as.matrix(1)
@@ -383,7 +383,7 @@ graph_from_adjacency_matrix <- function(adjmatrix,
   if (mode == "undirected") {
     if (!is_symmetric(adjmatrix)) {
       lifecycle::deprecate_soft(
-        "1.5.2",
+        "1.6.0",
         "graph_from_adjacency_matrix(adjmatrix = 'must be symmetric with mode = \"undirected\"')",
         details = 'Use mode = "max" to achieve the original behavior.'
       )

R/bipartite.R

@@ -83,7 +83,7 @@
 #' colnames(M) <- c("Party", "Skiing", "Badminton")
 #' M[] <- sample(0:1, length(M), replace = TRUE)
 #' M
-#' g2 <- graph_from_incidence_matrix(M)
+#' g2 <- graph_from_biadjacency_matrix(M)
 #' g2$name <- "Event network"
 #' proj2 <- bipartite_projection(g2)
 #' print(proj2[[1]], g = TRUE, e = TRUE)

R/conversion.R

@@ -801,10 +801,10 @@ get.incidence.sparse <- function(graph, types, names, attr) {
 
 
 
-#' Incidence matrix of a bipartite graph
+#' Bipartite adjacency matrix of a bipartite graph
 #'
-#' This function can return a sparse or dense incidence matrix of a bipartite
-#' network. The incidence matrix is an \eqn{n} times \eqn{m} matrix, \eqn{n}
+#' This function can return a sparse or dense bipartite adjacency matrix of a bipartite
+#' network. The bipartite adjacency matrix is an \eqn{n} times \eqn{m} matrix, \eqn{n}
 #' and \eqn{m} are the number of vertices of the two kinds.
 #'
 #' Bipartite graphs have a `type` vertex attribute in igraph, this is
@@ -818,9 +818,9 @@ get.incidence.sparse <- function(graph, types, names, attr) {
 #'   `type` vertex attribute. You must supply this argument if the graph has
 #'   no `type` vertex attribute.
 #' @param attr Either `NULL` or a character string giving an edge
-#'   attribute name. If `NULL`, then a traditional incidence matrix is
+#'   attribute name. If `NULL`, then a traditional bipartite adjacency matrix is
 #'   returned. If not `NULL` then the values of the given edge attribute are
-#'   included in the incidence matrix. If the graph has multiple edges, the edge
+#'   included in the bipartite adjacency matrix. If the graph has multiple edges, the edge
 #'   attribute of an arbitrarily chosen edge (for the multiple edges) is
 #'   included.
 #' @param names Logical scalar, if `TRUE` and the vertices in the graph
@@ -831,16 +831,20 @@ get.incidence.sparse <- function(graph, types, names, attr) {
 #'   created, you will need the `Matrix` package for this.
 #' @return A sparse or dense matrix.
 #' @author Gabor Csardi \email{csardi.gabor@@gmail.com}
-#' @seealso [graph_from_incidence_matrix()] for the opposite operation.
+#' @seealso [graph_from_biadjacency_matrix()] for the opposite operation.
 #' @family conversion
 #' @export
 #' @keywords graphs
+#' @details
+#' Some authors refer to the bipartite adjacency matrix as the
+#' "bipartite incidence matrix". igraph 1.6.0 and later does not use
+#' this naming to avoid confusion with the edge-vertex incidence matrix.
 #' @examples
 #'
 #' g <- make_bipartite_graph(c(0, 1, 0, 1, 0, 0), c(1, 2, 2, 3, 3, 4))
-#' as_incidence_matrix(g)
+#' as_biadjacency_matrix(g)
 #'
-as_incidence_matrix <- function(graph, types = NULL, attr = NULL,
+as_biadjacency_matrix <- function(graph, types = NULL, attr = NULL,
                                 names = TRUE, sparse = FALSE) {
   # Argument checks
   ensure_igraph(graph)
@@ -855,11 +859,30 @@ as_incidence_matrix <- function(graph, types = NULL, attr = NULL,
     get.incidence.dense(graph, types = types, names = names, attr = attr)
   }
 }
-
+#' As incidence matrix
+#'
+#' @description
+#' `r lifecycle::badge("deprecated")`
+#'
+#' `as_incidence_matrix()` was renamed to `as_biadjacency_matrix()` to create a more
+#' consistent API.
+#' @inheritParams as_biadjacency_matrix
+#' @keywords internal
+#' @details
+#' Some authors refer to the bipartite adjacency matrix as the
+#' "bipartite incidence matrix". igraph 1.6.0 and later does not use
+#' this naming to avoid confusion with the edge-vertex incidence matrix.
+#' @export
+as_incidence_matrix <- function(...) { # nocov start
+   lifecycle::deprecate_soft("1.6.0", "as_incidence_matrix()", "as_biadjacency_matrix()")
+   as_biadjacency_matrix(...)
+} # nocov end
 #' @rdname graph_from_data_frame
 #' @param x An igraph object.
 #' @param what Character constant, whether to return info about vertices,
 #'   edges, or both. The default is \sQuote{edges}.
+#' @family conversion
+#' @family biadjacency
 #' @export
 as_data_frame <- function(x, what = c("edges", "vertices", "both")) {
   ensure_igraph(x)

R/incidence.R

@@ -137,46 +137,46 @@ graph.incidence.dense <- function(incidence, directed, mode, multiple,
   res
 }
 
-#' Create graphs from an incidence matrix
+#' Create graphs from a bipartite adjacency matrix
 #'
-#' `graph_from_incidence_matrix()` creates a bipartite igraph graph from an incidence
+#' `graph_from_biadjacency_matrix()` creates a bipartite igraph graph from an incidence
 #' matrix.
 #'
 #' Bipartite graphs have a \sQuote{`type`} vertex attribute in igraph,
 #' this is boolean and `FALSE` for the vertices of the first kind and
 #' `TRUE` for vertices of the second kind.
 #'
-#' `graph_from_incidence_matrix()` can operate in two modes, depending on the
+#' `graph_from_biadjacency_matrix()` can operate in two modes, depending on the
 #' `multiple` argument. If it is `FALSE` then a single edge is
-#' created for every non-zero element in the incidence matrix. If
+#' created for every non-zero element in the bipartite adjacency matrix. If
 #' `multiple` is `TRUE`, then the matrix elements are rounded up to
 #' the closest non-negative integer to get the number of edges to create
 #' between a pair of vertices.
 #'
 #' @aliases graph.incidence
-#' @param incidence The input incidence matrix. It can also be a sparse matrix
+#' @param incidence The input bipartite adjacency matrix. It can also be a sparse matrix
 #'   from the `Matrix` package.
 #' @param directed Logical scalar, whether to create a directed graph.
 #' @param mode A character constant, defines the direction of the edges in
 #'   directed graphs, ignored for undirected graphs. If \sQuote{`out`}, then
 #'   edges go from vertices of the first kind (corresponding to rows in the
-#'   incidence matrix) to vertices of the second kind (columns in the incidence
+#'   bipartite adjacency matrix) to vertices of the second kind (columns in the incidence
 #'   matrix). If \sQuote{`in`}, then the opposite direction is used. If
 #'   \sQuote{`all`} or \sQuote{`total`}, then mutual edges are created.
 #' @param multiple Logical scalar, specifies how to interpret the matrix
 #'   elements. See details below.
 #' @param weighted This argument specifies whether to create a weighted graph
-#'   from the incidence matrix. If it is `NULL` then an unweighted graph is
+#'   from the bipartite adjacency matrix. If it is `NULL` then an unweighted graph is
 #'   created and the `multiple` argument is used to determine the edges of
 #'   the graph. If it is a character constant then for every non-zero matrix
 #'   entry an edge is created and the value of the entry is added as an edge
 #'   attribute named by the `weighted` argument. If it is `TRUE` then a
 #'   weighted graph is created and the name of the edge attribute will be
 #'   \sQuote{`weight`}.
 #' @param add.names A character constant, `NA` or `NULL`.
-#'   `graph_from_incidence_matrix()` can add the row and column names of the incidence
+#'   `graph_from_biadjacency_matrix()` can add the row and column names of the incidence
 #'   matrix as vertex attributes. If this argument is `NULL` (the default)
-#'   and the incidence matrix has both row and column names, then these are added
+#'   and the bipartite adjacency matrix has both row and column names, then these are added
 #'   as the \sQuote{`name`} vertex attribute. If you want a different vertex
 #'   attribute for this, then give the name of the attributes as a character
 #'   string. If this argument is `NA`, then no vertex attributes (other than
@@ -192,10 +192,15 @@ graph.incidence.dense <- function(incidence, directed, mode, multiple,
 #' inc <- matrix(sample(0:1, 15, repl = TRUE), 3, 5)
 #' colnames(inc) <- letters[1:5]
 #' rownames(inc) <- LETTERS[1:3]
-#' graph_from_incidence_matrix(inc)
+#' graph_from_biadjacency_matrix(inc)
 #'
+#' @details
+#' Some authors refer to the bipartite adjacency matrix as the
+#' "bipartite incidence matrix". igraph 1.6.0 and later does not use
+#' this naming to avoid confusion with the edge-vertex incidence matrix.
+#' @family biadjacency
 #' @export
-graph_from_incidence_matrix <- function(incidence, directed = FALSE,
+graph_from_biadjacency_matrix <- function(incidence, directed = FALSE,
                                         mode = c("all", "out", "in", "total"),
                                         multiple = FALSE, weighted = NULL,
                                         add.names = NULL) {
@@ -243,9 +248,39 @@ graph_from_incidence_matrix <- function(incidence, directed = FALSE,
   }
   res
 }
-
-#' @rdname graph_from_incidence_matrix
-#' @param ... Passed to `graph_from_incidence_matrix()`.
-#' @family incidence
+#' Graph from incidence matrix
+#'
+#' @description
+#' `r lifecycle::badge("deprecated")`
+#'
+#' `graph_from_incidence_matrix()` was renamed to `graph_from_biadjacency_matrix()` to create a more
+#' consistent API.
+#' @inheritParams graph_from_biadjacency_matrix
+#' @keywords internal
+#' @details
+#' Some authors refer to the bipartite adjacency matrix as the
+#' "bipartite incidence matrix". igraph 1.6.0 and later does not use
+#' this naming to avoid confusion with the edge-vertex incidence matrix.
+#' @export
+from_incidence_matrix <- function(...) { # nocov start
+   lifecycle::deprecate_soft("1.6.0", "graph_from_incidence_matrix()", "graph_from_biadjacency_matrix()")
+   graph_from_biadjacency_matrix(...)
+} # nocov end
+#' From incidence matrix
+#'
+#' @description
+#' `r lifecycle::badge("deprecated")`
+#'
+#' `graph_from_incidence_matrix()` was renamed to `graph_from_biadjacency_matrix()` to create a more
+#' consistent API.
+#' @inheritParams graph_from_biadjacency_matrix
+#' @keywords internal
+#' @details
+#' Some authors refer to the bipartite adjacency matrix as the
+#' "bipartite incidence matrix". igraph 1.6.0 and later does not use
+#' this naming to avoid confusion with the edge-vertex incidence matrix.
 #' @export
-from_incidence_matrix <- function(...) constructor_spec(graph_from_incidence_matrix, ...)
+graph_from_incidence_matrix <- function(...) { # nocov start
+   lifecycle::deprecate_soft("1.6.0", "graph_from_incidence_matrix()", "graph_from_biadjacency_matrix()")
+   graph_from_biadjacency_matrix(...)
+} # nocov end

R/layout.R

@@ -270,7 +270,7 @@ normalize <- function(xmin = -1, xmax = 1, ymin = xmin, ymax = xmax,
 #' @examples
 #' # Random bipartite graph
 #' inc <- matrix(sample(0:1, 50, replace = TRUE, prob = c(2, 1)), 10, 5)
-#' g <- graph_from_incidence_matrix(inc)
+#' g <- graph_from_biadjacency_matrix(inc)
 #' plot(g,
 #'   layout = layout_as_bipartite,
 #'   vertex.color = c("green", "cyan")[V(g)$type + 1]

R/zzz-deprecate.R

@@ -184,7 +184,7 @@ deprecated("get.edgelist", as_edgelist)
 #' @export get.graph.attribute
 deprecated("get.graph.attribute", graph_attr)
 #' @export get.incidence
-deprecated("get.incidence", as_incidence_matrix)
+deprecated("get.incidence", as_biadjacency_matrix)
 #' @export get.stochastic
 deprecated("get.stochastic", stochastic_matrix)
 #' @export get.vertex.attribute
@@ -244,7 +244,7 @@ deprecated("graph.full.citation", make_full_citation_graph)
 #' @export graph.graphdb
 deprecated("graph.graphdb", graph_from_graphdb)
 #' @export graph.incidence
-deprecated("graph.incidence", graph_from_incidence_matrix)
+deprecated("graph.incidence", graph_from_biadjacency_matrix)
 #' @export graph.isocreate
 deprecated("graph.isocreate", graph_from_isomorphism_class)
 #' @export graph.kautz

_pkgdown.yml

@@ -138,7 +138,7 @@ reference:
 - subtitle: Bipartite graphs
 - contents:
   - has_concept("bipartite")
-  - has_concept("incidence")
+  - has_concept("biadjacency")
 - subtitle: Efficiency
 - contents:
   - has_concept("efficiency")