Merge pull request #285 from snlab-ch/develop

v1.1.9

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: migraph
 Title: Multimodal Network Analysis and More
-Version: 1.1.8
-Date: 2023-12-06
+Version: 1.1.9
+Date: 2023-12-13
 Description: A set of tools for analysing multimodal networks.
    It includes functions for measuring 
    centrality, centralization, cohesion, closure, constraint and diversity,

NAMESPACE

@@ -41,9 +41,9 @@ export("%>%")
 export(.E)
 export(.G)
 export(.N)
-export(activate)
 export(aes)
 export(as.network)
+export(as_diffusion)
 export(bind_edges)
 export(cluster_concor)
 export(cluster_hierarchical)
@@ -92,7 +92,6 @@ export(is.network)
 export(is.tbl_graph)
 export(is_acyclic)
 export(is_aperiodic)
-export(is_bipartite)
 export(is_connected)
 export(is_eulerian)
 export(is_perfect_matching)
@@ -124,6 +123,7 @@ export(network_factions)
 export(network_harmonic)
 export(network_heterophily)
 export(network_homophily)
+export(network_immunity)
 export(network_indegree)
 export(network_infection_length)
 export(network_length)
@@ -163,6 +163,7 @@ export(node_efficiency)
 export(node_effsize)
 export(node_eigenvector)
 export(node_equivalence)
+export(node_exposure)
 export(node_fast_greedy)
 export(node_harmonic)
 export(node_heterophily)
@@ -173,6 +174,7 @@ export(node_infection_length)
 export(node_infomap)
 export(node_is_core)
 export(node_is_cutpoint)
+export(node_is_exposed)
 export(node_is_isolate)
 export(node_is_max)
 export(node_is_mentor)
@@ -210,6 +212,7 @@ export(play_diffusions)
 export(play_learning)
 export(play_segregation)
 export(rename)
+export(test_gof)
 export(test_permutation)
 export(test_random)
 export(tidy)
@@ -231,6 +234,7 @@ import(tidygraph)
 importFrom(dplyr,"%>%")
 importFrom(dplyr,bind_cols)
 importFrom(dplyr,left_join)
+importFrom(dplyr,tibble)
 importFrom(furrr,furrr_options)
 importFrom(furrr,future_map_dfr)
 importFrom(future,plan)
@@ -318,7 +322,6 @@ importFrom(tidygraph,"%E>%")
 importFrom(tidygraph,.E)
 importFrom(tidygraph,.G)
 importFrom(tidygraph,.N)
-importFrom(tidygraph,activate)
 importFrom(tidygraph,bind_edges)
 importFrom(tidygraph,is.tbl_graph)
 importFrom(tidygraph,mutate)

NEWS.md

@@ -1,3 +1,29 @@
+# migraph 1.1.9
+
+2023-12-13
+
+## Marks
+
+- Added `node_is_exposed()` function to mark nodes (logical) that are currently exposed to diffusion content in a network.
+
+## Measures
+
+- Fixed bugs for `network_reproduction()` function that calculates the R-nought value.
+- Added `network_immunity()` function to calculate the Herd Immunity Threshold for the network.
+- Added `node_exposure()` function to calculate the number of infected/adopting nodes to which each susceptible node is exposed.
+- Added documentation for diffusion measures, separating documentation for `node_*()` and `network_*()` measures.
+
+## Models
+
+- Added `as_diffusion()` function to convert a diffusion event table into a `diff_model` object.
+- Added `test_gof()` function for testing goodness-of-fit in diffusion models.
+
+## Tutorials
+
+- Updates to tutorial 7 (diffusion):
+  - Added section on R-nought and Herd Immunity.
+  - Fixed layouts for plots using `autographs()` and `autographd()` for `diff_model` objects.
+
 # migraph 1.1.8
 
 2023-12-06

R/class_measures.R

@@ -79,7 +79,7 @@ summary.node_measure <- function(object, ...,
     out <- c(Minimum = min(object, na.rm = TRUE), 
              Maximum = max(object, na.rm = TRUE), 
              Mean = mean(object, na.rm = TRUE), 
-             StdDev = sd(object, na.rm = TRUE),
+             StdDev = stats::sd(object, na.rm = TRUE),
              Missing = sum(is.na(object))
     )
   } else {

R/class_members.R

@@ -9,15 +9,15 @@ make_node_member <- function(out, .data) {
 print.node_member <- function(x, ..., n = NULL) {
   if (any(attr(x, "mode"))) {
     for(m in c(FALSE, TRUE)){
-      print_tblvec(y = as.numeric(x)[attr(x, "mode") == m], 
+      suppressWarnings(print_tblvec(y = as.numeric(x)[attr(x, "mode") == m], 
                    names = list(names(x)[attr(x, "mode") == m]),
-                   n = n)
+                   n = n))
       if(!m) cat("\n")
     }
   } else {
-    print_tblvec(y = `if`(all(is.na(as.numeric(x))), x, as.numeric(x)), 
+    suppressWarnings(print_tblvec(y = `if`(all(is.na(as.numeric(x))), x, as.numeric(x)), 
                  names = list(names(x)),
-                 n = n)
+                 n = n))
   }
 }
 

R/class_models.R

@@ -187,10 +187,17 @@ make_diffs_model <- function(report, .data) {
   report
 }
 
+
 #' @export
-print.diff_model <- function(x, ...){
+print.diff_model <- function(x, ..., verbose = FALSE){
   x <- x[,colSums(x, na.rm=TRUE) != 0]
-  x$I_new <- NULL
+  if(!verbose){
+    x$n <- NULL
+    x$s <- NULL
+    x$I_new <- NULL
+    x$E_new <- NULL
+    x$R_new <- NULL
+  }
   print(dplyr::tibble(x, ...))
 }
 

R/mark_nodes.R

@@ -12,7 +12,7 @@
 #'   for converting the results from some node measure into a mark-class object.
 #'   They can be particularly useful for highlighting which node or nodes
 #'   are key because they minimise or, more often, maximise some measure.
-#' @inheritParams is
+#' @inheritParams cohesion
 #' @family marks
 #' @name mark_nodes
 NULL
@@ -105,6 +105,40 @@ node_is_mentor <- function(.data, elites = 0.1){
   make_node_mark(out, .data)
 }
 
+#' @rdname mark_nodes 
+#' @param mark A valid 'node_mark' object or
+#'   logical vector (TRUE/FALSE) of length equal to 
+#'   the number of nodes in the network.
+#' @section Exposed:
+#'   `node_is_exposed()` is similar to `node_exposure()`,
+#'   but returns a mark (TRUE/FALSE) vector indicating which nodes
+#'   are currently exposed to the diffusion content.
+#'   This diffusion content can be expressed in the 'mark' argument.
+#'   If no 'mark' argument is provided,
+#'   and '.data' is a diff_model object,
+#'   then the function will return nodes exposure to the seed nodes
+#'   in that diffusion.
+#' @param mark vector denoting which nodes are infected
+#' @examples
+#'   # To mark which nodes are currently exposed
+#'   (expos <- node_is_exposed(manynet::create_tree(14), mark = c(1,3)))
+#'   which(expos)
+#' @export
+node_is_exposed <- function(.data, mark){
+  event <- nodes <- NULL
+  if(missing(mark) && inherits(.data, "diff_model")){
+    mark <- summary(.data) |> 
+      dplyr::filter(t == 0 & event == "I") |> 
+      dplyr::select(nodes) |> unlist()
+    .data <- attr(.data, "network")
+  }
+  if(is.logical(mark)) mark <- which(mark)
+  out <- rep(F, manynet::network_nodes(.data))
+  out[unique(setdiff(unlist(igraph::neighborhood(.data, nodes = mark)),
+                     mark))] <- TRUE
+  make_node_mark(out, .data)
+}
+
 #' @describeIn mark_nodes Returns logical of which nodes 
 #'   hold the maximum of some measure
 #' @param node_measure An object created by a `node_` measure.

R/mark_ties.R

@@ -5,7 +5,7 @@
 #'   in a network, identifying which hold some property.
 #'   They are most useful in highlighting parts of the network that
 #'   are particularly well- or poorly-connected.
-#' @inheritParams is
+#' @inheritParams cohesion
 #' @family marks
 #' @name mark_ties
 NULL

R/measure_centrality.R

@@ -15,7 +15,7 @@
 #' @family centrality
 #' @seealso [to_undirected()] for removing edge directions
 #'   and [to_unweighted()] for removing weights from a graph.
-#' @inheritParams is
+#' @inheritParams cohesion
 #' @param normalized Logical scalar, whether the centrality scores are normalized.
 #'   Different denominators are used depending on whether the object is one-mode or two-mode,
 #'   the type of centrality, and other arguments.

R/measure_closure.R

@@ -12,7 +12,7 @@
 #' For three-mode networks, `network_congruency` calculates the proportion of three-paths 
 #' spanning two two-mode networks that are closed by a fourth tie to establish a 
 #' "congruent four-cycle" structure.
-#' @inheritParams is
+#' @inheritParams cohesion
 #' @param object2 Optionally, a second (two-mode) matrix, igraph, or tidygraph
 #' @param method For reciprocity, either `default` or `ratio`.
 #' See `?igraph::reciprocity`

R/measure_cohesion.R

@@ -1,14 +1,26 @@
 #' Measures of network cohesion or connectedness
 #' 
-#' These functions return values or vectors relating to how connected a network is
-#' and the number of nodes or edges to remove that would increase fragmentation.
-#' @inheritParams is
+#' @description
+#'   These functions return values or vectors relating to how connected a network is
+#'   and the number of nodes or edges to remove that would increase fragmentation.
+#'   
+#'   - `network_density()`: Measures the ratio of ties to the number
+#'   of possible ties
+#'   - `network_components()`: Measures the number of (strong) components 
+#'   in the network.
+#' @param .data An object of a `{manynet}`-consistent class:
+#'   \itemize{
+#'   \item matrix (adjacency or incidence) from `{base}` R
+#'   \item edgelist, a data frame from `{base}` R or tibble from `{tibble}`
+#'   \item igraph, from the `{igraph}` package
+#'   \item network, from the `{network}` package
+#'   \item tbl_graph, from the `{tidygraph}` package
+#'   }
 #' @name cohesion
 #' @family measures
 NULL
 
-#' @describeIn cohesion Summarises the ratio of ties
-#' to the number of possible ties.
+#' @rdname cohesion
 #' @importFrom igraph edge_density
 #' @examples 
 #' network_density(mpn_elite_mex)
@@ -24,13 +36,14 @@ network_density <- function(.data) {
   make_network_measure(out, .data)
 }
 
-#' @describeIn cohesion Returns number of (strong) components in the network.
+#' @rdname cohesion
+#' @section Cohesion: 
 #'   To get the 'weak' components of a directed graph, 
 #'   please use `manynet::to_undirected()` first.
 #' @importFrom igraph components
 #' @examples
-#' network_components(mpn_ryanair)
-#' network_components(manynet::to_undirected(mpn_ryanair))
+#'   network_components(mpn_ryanair)
+#'   network_components(manynet::to_undirected(mpn_ryanair))
 #' @export
 network_components <- function(.data){
   object <- manynet::as_igraph(.data)