feat: Split sample_bipartite() into two functions for the G(n, m) a…

.Rbuildignore

@@ -52,11 +52,11 @@
 ^compile_commands\.json$
 ^\.cache$
 ^rchk$
+^vendor\.sh$
+^vendor-one\.sh$
+^patch$
 ^man/dot-igraph.progress\.Rd$
 ^man/dot-igraph.status\.Rd$
 ^man/dot-extract_constructor_and_modifiers\.Rd$
 ^man/dot-apply_modifiers\.Rd$
 ^man/handle_vertex_type_arg\.Rd$
-^vendor\.sh$
-^vendor-one\.sh$
-^patch$

NAMESPACE

@@ -186,6 +186,8 @@ export(bipartite.mapping)
 export(bipartite.projection)
 export(bipartite.projection.size)
 export(bipartite.random.game)
+export(bipartite_gnm)
+export(bipartite_gnp)
 export(bipartite_graph)
 export(bipartite_mapping)
 export(bipartite_projection)
@@ -746,6 +748,8 @@ export(running_mean)
 export(sample_)
 export(sample_asym_pref)
 export(sample_bipartite)
+export(sample_bipartite_gnm)
+export(sample_bipartite_gnp)
 export(sample_chung_lu)
 export(sample_cit_cit_types)
 export(sample_cit_types)

R/aaa-auto.R

@@ -2080,6 +2080,38 @@ is_bipartite_impl <- function(graph) {
   res
 }
 
+
+bipartite_game_gnp_impl <- function(n1, n2, p, directed=FALSE, mode=c("all", "out", "in", "total")) {
+  # Argument checks
+  n1 <- as.numeric(n1)
+  n2 <- as.numeric(n2)
+  p <- as.numeric(p)
+  directed <- as.logical(directed)
+  mode <- switch(igraph.match.arg(mode), "out"=1L, "in"=2L, "all"=3L, "total"=3L)
+
+  on.exit( .Call(R_igraph_finalizer) )
+  # Function call
+  res <- .Call(R_igraph_bipartite_game_gnp, n1, n2, p, directed, mode)
+  res <- set_vertex_attr(res$graph, "type", value = res$types)
+  res
+}
+
+bipartite_game_gnm_impl <- function(n1, n2, m, directed=FALSE, mode=c("all", "out", "in", "total")) {
+  # Argument checks
+  n1 <- as.numeric(n1)
+  n2 <- as.numeric(n2)
+  m <- as.numeric(m)
+  directed <- as.logical(directed)
+  mode <- switch(igraph.match.arg(mode), "out"=1L, "in"=2L, "all"=3L, "total"=3L)
+
+  on.exit( .Call(R_igraph_finalizer) )
+  # Function call
+  res <- .Call(R_igraph_bipartite_game_gnm, n1, n2, m, directed, mode)
+  res <- set_vertex_attr(res$graph, "type", value = res$types)
+
+  res
+}
+
 get_laplacian_impl <- function(graph, mode=c("out", "in", "all", "total"), normalization=c("unnormalized", "symmetric", "left", "right"), weights=NULL) {
   # Argument checks
   ensure_igraph(graph)

R/games.R

@@ -264,7 +264,10 @@ callaway.traits.game <- function(nodes, types, edge.per.step = 1, type.dist = re
 #' @keywords internal
 #' @export
 bipartite.random.game <- function(n1, n2, type = c("gnp", "gnm"), p, m, directed = FALSE, mode = c("out", "in", "all")) { # nocov start
-  lifecycle::deprecate_soft("2.0.0", "bipartite.random.game()", "sample_bipartite()")
+  lifecycle::deprecate_warn(
+    "2.0.0", "bipartite.random.game()",
+    details = "Use sample_bipartite_gnp() or sample_bipartite_gnm()"
+  )
   sample_bipartite(n1 = n1, n2 = n2, type = type, p = p, m = m, directed = directed, mode = mode)
 } # nocov end
 
@@ -1703,13 +1706,8 @@ cit_cit_types <- function(...) constructor_spec(sample_cit_cit_types, ...)
 
 #' Bipartite random graphs
 #'
-#' Generate bipartite graphs using the Erdős-Rényi model
-#'
-#' Similarly to unipartite (one-mode) networks, we can define the \eqn{G(n,p)}, and
-#' \eqn{G(n,m)} graph classes for bipartite graphs, via their generating process.
-#' In \eqn{G(n,p)} every possible edge between top and bottom vertices is realized
-#' with probability \eqn{p}, independently of the rest of the edges. In \eqn{G(n,m)}, we
-#' uniformly choose \eqn{m} edges to realize.
+#' `r lifecycle::badge("deprecated")` Generate bipartite graphs using the Erdős-Rényi model.
+#' Use [`sample_bipartite_gnm()`] and [`sample_bipartite_gnp()`] instead.
 #'
 #' @param n1 Integer scalar, the number of bottom vertices.
 #' @param n2 Integer scalar, the number of top vertices.
@@ -1749,55 +1747,152 @@ cit_cit_types <- function(...) constructor_spec(sample_cit_cit_types, ...)
 #'
 sample_bipartite <- function(n1, n2, type = c("gnp", "gnm"), p, m,
                              directed = FALSE, mode = c("out", "in", "all")) {
-  n1 <- as.numeric(n1)
-  n2 <- as.numeric(n2)
-  type <- igraph.match.arg(type)
-  if (!missing(p)) {
-    p <- as.numeric(p)
-  }
-  if (!missing(m)) {
-    m <- as.numeric(m)
-  }
-  directed <- as.logical(directed)
-  mode <- switch(igraph.match.arg(mode),
-    "out" = 1,
-    "in" = 2,
-    "all" = 3
-  )
 
-  if (type == "gnp" && missing(p)) {
-    cli::cli_abort("Connection probability {.arg p} must be given for Gnp graph")
-  }
-  if (type == "gnp" && !missing(m)) {
-    cli::cli_warn("Number of edges {.arg m} is ignored for Gnp graph.")
-  }
-  if (type == "gnm" && missing(m)) {
-    cli::cli_abort("Number of edges {.arg m} must be given for Gnm graph")
-  }
-  if (type == "gnm" && !missing(p)) {
-    cli::cli_warn("Connection probability {.arg p} is ignored for Gnm graph.")
-  }
+  type <- igraph.match.arg(type)
+  mode <- igraph.match.arg(mode)
 
-  on.exit(.Call(R_igraph_finalizer))
   if (type == "gnp") {
-    res <- .Call(R_igraph_bipartite_game_gnp, n1, n2, p, directed, mode)
-    res <- set_vertex_attr(res$graph, "type", value = res$types)
-    res$name <- "Bipartite Gnp random graph"
-    res$p <- p
+    lifecycle::deprecate_soft(
+      "2.2.0",
+      "sample_bipartite()",
+      "sample_bipartite_gnp()"
+    )
+    sample_bipartite_gnp(n1, n2, p, directed = directed, mode = mode)
   } else if (type == "gnm") {
-    res <- .Call(R_igraph_bipartite_game_gnm, n1, n2, m, directed, mode)
-    res <- set_vertex_attr(res$graph, "type", value = res$types)
-    res$name <- "Bipartite Gnm random graph"
-    res$m <- m
+    lifecycle::deprecate_soft(
+      "2.2.0",
+      "sample_bipartite()",
+      "sample_bipartite_gnm()"
+    )
+    sample_bipartite_gnm(n1, n2, m, directed = directed, mode = mode)
   }
-
-  res
 }
 
 #' @rdname sample_bipartite
 #' @param ... Passed to `sample_bipartite()`.
 #' @export
-bipartite <- function(...) constructor_spec(sample_bipartite, ...)
+bipartite <- function(..., type = NULL) {
+
+  if (is.null(type) || type == "gnp") {
+    lifecycle::deprecate_soft(
+      "2.1.3",
+      "bipartite()",
+      "bipartite_gnp()"
+    )
+    bipartite_gnp(...)
+  } else if (type == "gnm") {
+    lifecycle::deprecate_soft(
+      "2.1.3",
+      "bipartite()",
+      "bipartite_gnm()"
+    )
+    bipartite_gnm(...)
+  } else {
+    cli::cli_abort(
+      "{.arg type} must be 'gnp' or 'gnm'.",
+      "Use {.fun bipartite_gnp} or {.fun bipartite_gnm}."
+    )
+  }
+
+}
+
+#' @rdname sample_bipartite_gnm
+#' @param ... Passed to `sample_bipartite_gnm()`.
+#' @export
+bipartite_gnm <- function(...) constructor_spec(sample_bipartite_gnm, ...)
+
+#' @rdname sample_bipartite_gnm
+#' @param ... Passed to `sample_bipartite_gnp()`.
+#' @export
+bipartite_gnp <- function(...) constructor_spec(sample_bipartite_gnp, ...)
+
+#' Bipartite random graphs
+#'
+#' Generate bipartite graphs using the Erdős-Rényi model
+#'
+#' Similarly to unipartite (one-mode) networks, we can define the \eqn{G(n,p)}, and
+#' \eqn{G(n,m)} graph classes for bipartite graphs, via their generating process.
+#' In \eqn{G(n,p)} every possible edge between top and bottom vertices is realized
+#' with probability \eqn{p}, independently of the rest of the edges. In \eqn{G(n,m)}, we
+#' uniformly choose \eqn{m} edges to realize.
+#'
+#'
+#' @param n1 Integer scalar, the number of bottom vertices.
+#' @param n2 Integer scalar, the number of top vertices.
+#' @param p Real scalar, connection probability for \eqn{G(n,p)} graphs.
+#' @param m Integer scalar, the number of edges for \eqn{G(n,m)} graphs.
+#' @param directed Logical scalar, whether to create a directed graph. See also
+#'   the `mode` argument.
+#' @param mode Character scalar, specifies how to direct the edges in directed
+#'   graphs. If it is \sQuote{out}, then directed edges point from bottom
+#'   vertices to top vertices. If it is \sQuote{in}, edges point from top
+#'   vertices to bottom vertices. \sQuote{out} and \sQuote{in} do not generate
+#'   mutual edges. If this argument is \sQuote{all}, then each edge direction is
+#'   considered independently and mutual edges might be generated. This argument
+#'   is ignored for undirected graphs.
+#' @inheritParams rlang::args_dots_empty
+#' @examples
+#'
+#' ## empty graph
+#' sample_bipartite_gnp(10, 5, p = 0)
+#'
+#' ## full graph
+#' sample_bipartite_gnp(10, 5, p = 1)
+#'
+#' ## random bipartite graph
+#' sample_bipartite_gnp(10, 5, p = .1)
+#'
+#' ## directed bipartite graph, G(n,m)
+#' sample_bipartite_gnm(10, 5, m = 20, directed = TRUE, mode = "all")
+#'
+#' @family games
+#' @export
+sample_bipartite_gnm <- function(n1, n2, m,
+                                ...,
+                                directed = FALSE,
+                                mode = c("out", "in", "all")) {
+  check_dots_empty()
+  mode <- igraph.match.arg(mode)
+  m <- as.numeric(m)
+
+  res <- bipartite_game_gnm_impl(
+    n1 = n1,
+    n2 = n2,
+    m = m,
+    directed = directed,
+    mode = mode
+  )
+  res$name <- "Bipartite Gnm random graph"
+  res$m <- m
+
+  res
+
+}
+#' @rdname sample_bipartite_gnm
+#' @export
+sample_bipartite_gnp <- function(n1, n2, p,
+                                ...,
+                                directed = FALSE,
+                                mode = c("out", "in", "all")) {
+  check_dots_empty()
+  mode <- igraph.match.arg(mode)
+  p <- as.numeric(p)
+
+  res <- bipartite_game_gnp_impl(
+    n1 = n1,
+    n2 = n2,
+    p = p,
+    directed = directed,
+    mode = mode
+  )
+
+  res$name <- "Bipartite Gnp random graph"
+  res$p <- p
+
+  res
+
+}
+
 
 
 #' Sample stochastic block model