Merge pull request #250 from snlab-ch/develop

v0.12.3

.gitignore

@@ -13,3 +13,5 @@ tests/testthat/Rplots.pdf
 .DS_Store
 CRAN-SUBMISSION
 man/figures/unnamed-chunk-1-1.png
+inst/tutorials/community/community_data/*
+inst/tutorials/equivalence/equivalence_data/*

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: migraph
 Title: Tools for Multimodal Network Analysis
-Version: 0.12.2
-Date: 2022-10-12
+Version: 0.12.3
+Date: 2022-10-25
 Description: A set of tools for analysing multimodal networks.
    All functions operate with matrices, edge lists, 
    and 'igraph', 'network', and 'tidygraph' objects,

NAMESPACE

@@ -320,6 +320,7 @@ export(network_adhesion)
 export(network_assortativity)
 export(network_balance)
 export(network_betweenness)
+export(network_brokerage_census)
 export(network_closeness)
 export(network_cohesion)
 export(network_components)
@@ -351,6 +352,7 @@ export(node_attribute)
 export(node_automorphic_equivalence)
 export(node_betweenness)
 export(node_bridges)
+export(node_brokerage_census)
 export(node_closeness)
 export(node_components)
 export(node_constraint)
@@ -569,6 +571,7 @@ importFrom(rlang,":=")
 importFrom(rlang,.data)
 importFrom(rlang,enquo)
 importFrom(rlang,eval_tidy)
+importFrom(sna,brokerage)
 importFrom(sna,gcor)
 importFrom(stats,as.dist)
 importFrom(stats,as.formula)

NEWS.md

@@ -1,3 +1,15 @@
+# migraph 0.12.3
+
+## Package
+
+- Converted 'community' vignette to a learnr tutorial
+- Converted 'equivalence' vignette to a learnr tutorial
+
+## Motifs
+
+- Added node names to node_motif class where available
+- Added `node_brokerage_census()` and `network_network_census()` for counting Gould-Fernandez brokerage roles
+
 # migraph 0.12.2
 
 ## Package

R/class_motifs.R

@@ -14,6 +14,9 @@ make_network_motif <- function(out, object) {
 print.node_motif <- function(x, ...,
                          max.length = 6,
                          digits = 3) {
+  if(!is.null(attr(x, "dimnames")[[1]])){
+    x <- data.frame(names = attr(x, "dimnames")[[1]], x)
+  }
   if (any(attr(x, "mode"))) {
     print(dplyr::tibble(as.data.frame(x)[!attr(x, "mode")]))
     print(dplyr::tibble(as.data.frame(x)[attr(x, "mode")]))

R/motif_census.R

@@ -9,6 +9,10 @@
 #' @name node_census
 #' @family motifs
 #' @inheritParams is
+#' @param membership A vector of partition membership as integers.
+#' @param standardized Whether the score should be standardized
+#'   into a _z_-score indicating how many standard deviations above
+#'   or below the average the score lies.
 #' @importFrom igraph vcount graph.neighborhood delete_vertices triad_census
 NULL
 
@@ -118,12 +122,16 @@ node_triad_census <- function(object){
 #' | 04 | C4
 #' | Z42, Z43 | diamond
 #' | X4 | K4
+#' 
+#' See also [this list of graph classes](https://www.graphclasses.org/smallgraphs.html#nodes4).
 #' @importFrom tidygraph %E>%
 #' @references 
 #'  Ortmann, Mark, and Ulrik Brandes. 2017. 
 #'  “Efficient Orbit-Aware Triad and Quad Census in Directed and Undirected Graphs.” 
 #'  \emph{Applied Network Science} 2(1):13. 
 #'  \doi{10.1007/s41109-017-0027-2}.
+#' @examples 
+#' node_quad_census(ison_southern_women)
 #' @export
 node_quad_census <- function(object){
   if (!("oaqc" %in% rownames(utils::installed.packages()))) {
@@ -150,6 +158,38 @@ node_quad_census <- function(object){
   }
 }
 
+#' #' @export
+#' node_bmotif_census <- function(object, normalized = FALSE){
+#'   if (!("bmotif" %in% rownames(utils::installed.packages()))) {
+#'     message("Please install package `{bmotif}`.")
+#'     out <- bmotif::node_positions(as_matrix(object), 
+#'                                   weights_method = ifelse(is_weighted(object),
+#'                                                           'mean_motifweights', 'none'),
+#'                                   normalisation = ifelse(normalized, 
+#'                                                          'levelsize_NAzero', 'none'))
+#'     make_node_motif(out, object)
+#'   }
+#' }
+#' 
+#' #' @export
+#' node_igraph_census <- function(object, normalized = FALSE){
+#'     out <- igraph::motifs(as_igraph(object), 4)
+#'     if(is_labelled(object))
+#'       rownames(out) <- node_names(object)
+#'     colnames(out) <- c("co-K4",
+#'                        "co-diamond",
+#'                        "co-C4",
+#'                        "co-paw",
+#'                        "co-claw",
+#'                        "P4",
+#'                        "claw",
+#'                        "paw",
+#'                        "C4",
+#'                        "diamond",
+#'                        "K4")
+#'     make_node_motif(out, object)
+#' }
+
 #' @describeIn node_census Returns the shortest path lengths
 #'   of each node to every other node in the network.
 #' @importFrom igraph distances
@@ -176,17 +216,35 @@ node_path_census <- function(object){
   make_node_motif(out, object)
 }
 
-#' Censuses of graphs' motifs
+#' @describeIn node_census Returns the Gould-Fernandez brokerage
+#'   roles played by nodes in a network.
+#' @importFrom sna brokerage
+#' @references 
+#' Gould, R.V. and Fernandez, R.M. 1989. 
+#' “Structures of Mediation: A Formal Approach to Brokerage in Transaction Networks.” 
+#' _Sociological Methodology_, 19: 89-126.
+#' @examples 
+#' node_brokerage_census(ison_networkers, "Discipline")
+#' @export
+node_brokerage_census <- function(object, membership, standardized = FALSE){
+  out <- sna::brokerage(as_network(object), node_attribute(object, membership))
+  out <- if(standardized) out$z.nli else out$raw.nli
+  colnames(out) <- c("Coordinator", "Itinerant", "Gatekeeper", 
+                     "Representative", "Liaison", "Total")
+  make_node_motif(out, object)
+}
+
+#' Censuses of motifs at the network level
 #' 
 #' @name network_census
 #' @family motifs
-#' @param object A migraph-consistent object.
+#' @inheritParams node_census
 #' @param object2 A second, two-mode migraph-consistent object.
 NULL
 
 #' @describeIn network_census Returns a census of dyad motifs in a network
 #' @examples 
-#' network_dyad_census(ison_adolescents)
+#' network_dyad_census(ison_algebra)
 #' @export
 network_dyad_census <- function(object) {
   if (is_twomode(object)) {
@@ -271,3 +329,23 @@ network_mixed_census <- function (object, object2) {
            "00" = sum(onemode.null * bipartite.null) / 2)  
   make_network_motif(res, object)
 }
+
+#' @describeIn network_census Returns the Gould-Fernandez brokerage
+#'   roles in a network.
+#' @importFrom sna brokerage
+#' @references 
+#' Gould, R.V. and Fernandez, R.M. 1989. 
+#' “Structures of Mediation: A Formal Approach to Brokerage in Transaction Networks.” 
+#' _Sociological Methodology_, 19: 89-126.
+#' @examples 
+#' network_brokerage_census(ison_networkers, "Discipline")
+#' @export
+network_brokerage_census <- function(object, membership, standardized = FALSE){
+  out <- sna::brokerage(as_network(object), node_attribute(object, membership))
+  out <- if(standardized) out$z.gli else out$raw.gli
+  names(out) <- c("Coordinator", "Itinerant", "Gatekeeper", 
+                     "Representative", "Liaison", "Total")
+  make_network_motif(out, object)
+}
+
+

cran-comments.md

@@ -9,4 +9,4 @@
 
 0 errors | 0 warnings | 0 notes
 
-- Package size known to be slight over 5Mb (5.1Mb) due to documentation
+- Package size no longer over 5MB