Merge pull request #244 from snlab-ch/develop

Renamed diversity measures

DESCRIPTION

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

NAMESPACE

@@ -96,7 +96,6 @@ S3method(plot,netlogit)
 S3method(plot,node_measure)
 S3method(plot,node_member)
 S3method(plot,tie_measure)
-S3method(print,block_model)
 S3method(print,graph_measure)
 S3method(print,graph_motif)
 S3method(print,graph_test)
@@ -210,12 +209,8 @@ export(as_network)
 export(as_tidygraph)
 export(autographr)
 export(bind_edges)
-export(blockmodel)
-export(blockmodel_concor)
 export(cluster_concor)
 export(cluster_hierarchical)
-export(cluster_regular_equivalence)
-export(cluster_structural_equivalence)
 export(copy_node_attributes)
 export(create_complete)
 export(create_components)
@@ -240,14 +235,11 @@ export(generate_permutation)
 export(generate_random)
 export(generate_scalefree)
 export(generate_smallworld)
-export(ggatyear)
 export(ggevolution)
-export(ggidentify_clusters)
 export(gglineage)
 export(ggplot)
 export(ggsave)
 export(ggtitle)
-export(ggtree)
 export(glance)
 export(graph_adhesion)
 export(graph_assortativity)
@@ -263,13 +255,15 @@ export(graph_degree)
 export(graph_density)
 export(graph_diameter)
 export(graph_dims)
+export(graph_diversity)
 export(graph_dyad_census)
 export(graph_edge_attributes)
 export(graph_edges)
 export(graph_ei_index)
 export(graph_eigenvector)
 export(graph_equivalency)
 export(graph_factions)
+export(graph_homophily)
 export(graph_length)
 export(graph_mixed_census)
 export(graph_modularity)
@@ -281,8 +275,6 @@ export(graph_tie_attributes)
 export(graph_ties)
 export(graph_transitivity)
 export(graph_triad_census)
-export(group_tie_census)
-export(group_triad_census)
 export(is.igraph)
 export(is.network)
 export(is.tbl_graph)
@@ -351,9 +343,7 @@ export(read_edgelist)
 export(read_nodelist)
 export(read_pajek)
 export(read_ucinet)
-export(reduce_graph)
 export(rename)
-export(summarise_statistics)
 export(test_permutation)
 export(test_random)
 export(tidy)
@@ -373,6 +363,7 @@ export(tie_weights)
 export(to_blocks)
 export(to_edges)
 export(to_giant)
+export(to_main_component)
 export(to_matching)
 export(to_mode1)
 export(to_mode2)

NEWS.md

@@ -1,3 +1,25 @@
+# migraph 0.11.2
+
+## Package
+
+- Filled in some further documentation
+- Dropped some older defunct functions
+
+## Measures
+
+- Renamed `graph_blau_index()` to `graph_diversity()`
+- Renamed `graph_ei_index()` to `graph_homophily()`
+
+## Mapping
+
+- Fixed bug with `autographr()`'s "node_group" argument
+
+# migraph 0.11.1
+
+## Package
+
+- Fixed documentation issues (URLs, equations)
+
 # migraph 0.11.0
 
 ## Package

R/class_marks.R

@@ -1,6 +1,6 @@
 make_node_mark <- function(out, object) {
   class(out) <- c("node_mark", class(out))
-  if(is.null(names(out)) & is_labelled(object))
+  if (is.null(names(out)) && is_labelled(object))
     names(out) <- node_names(object)
   attr(out, "mode") <- node_mode(object)
   out
@@ -13,24 +13,24 @@ make_tie_mark <- function(out, object) {
 
 #' @export
 print.node_mark <- function(x, ...,
-                           max.length = 6,
-                           digits = 3) {
+                            max.length = 6,
+                            digits = 3) {
   if (any(attr(x, "mode"))) {
     for(m in c(FALSE, TRUE)){
-      print_tblvec(y = as.logical(x)[attr(x, "mode")==m], 
-                   names = list(names(x)[attr(x, "mode")==m]))
-      if(!m) cat("\n")
+      print_tblvec(y = as.logical(x)[attr(x, "mode") == m],
+                   names = list(names(x)[attr(x, "mode") == m]))
+      if (!m) cat("\n")
     }
   } else {
-    print_tblvec(y = as.logical(x), 
+    print_tblvec(y = as.logical(x),
                  names = list(names(x)))
   }
 }
 
 #' @export
 print.tie_mark <- function(x, ...,
-                              max.length = 6,
-                              digits = 3) {
+                           max.length = 6,
+                           digits = 3) {
   print_tblvec(y = as.logical(x),
                names = list(names(x)))
 }

R/data_ison.R

@@ -84,7 +84,7 @@
 
 #' Multiplex graph object of friends, social, and task ties (McFarland 2001)
 #' 
-#' @details Multiplex graph object of friends, social, and task ties between 16 #' anonymous students. 
+#' @details Multiplex graph object of friends, social, and task ties between 16 anonymous students. 
 #' M182 was an honors algebra class where researchers
 #' collected friendship, social, and task ties between 16 students.
 #' The edge attribute `friends` contains friendship ties,
@@ -117,7 +117,7 @@
 
 # Adolescents ####
 
-#' One-mode subset of the adolescent society (Coleman 1961)
+#' One-mode subset (8 individuals) of the adolescent society (Coleman 1961).
 #'
 #'   ```{r, eval = FALSE, echo = FALSE, include = FALSE}
 #'   autographr(ison_adolescents, labels = FALSE) + ggtitle("ison_adolescents")

R/data_mpn.R

@@ -335,7 +335,7 @@ NULL
 #' Cambridge University Press. Cambridge University Press.
 #' @source 
 #' The Correlates of War Project. 2012.
-#' \href{https://correlatesofwar.org/data-sets/bilateral-trade}{\emph{Trade}}.
+#' \href{https://correlatesofwar.org/data-sets/bilateral-trade/}{\emph{Trade}}.
 #' 
 #' Barbieri, Katherine and Omar Keshk. 2012. 
 #' Correlates of War Project Trade Data Set Codebook, Version 3.0.
@@ -349,7 +349,7 @@ NULL
 #' @usage data(mpn_cow_igo)
 #' @source
 #' The Correlates of War Project. 2019.
-#' \href{https://correlatesofwar.org/data-sets/IGOs}{\emph{Intergovernmental Organization v3}}.
+#' \href{https://correlatesofwar.org/data-sets/IGOs/}{\emph{Intergovernmental Organization v3}}.
 #' @references 
 #' Pevehouse, Jon C.W., Timothy Nordstron, Roseanne W McManus, Anne Spencer Jamison. 2020.
 #' “Tracking Organizations in the World: The Correlates of War IGO Version 3.0 datasets”.

R/manip_to.R

@@ -485,16 +485,13 @@ to_twomode.network <- function(object, mark){
 #' 
 #' |  to_      | edgelists | matrices  |igraph  |tidygraph  |network  |
 #' | ------------- |:-----:|:-----:|:-----:|:-----:|:-----:|
-#' | mode1 | | X | X | X | |
-#' | mode2 | | X | X | X | |
-#' | main_component  |  |   | X | X | X |
-#' | subgraph  | X |  X | X | X | X |
-#' | ties  | X |  X | X | X | X |
-#' | blocks  | X |  X | X | X | X |
-#'
-#' Note that `to_subgraph()` returns a 'tidygraph' object,
-#' `to_ties()` returns an 'igraph' object,
-#' and `to_blocks()` returns a 'matrix' object.
+#' | mode1 | X | X | X | X | X |
+#' | mode2 | X | X | X | X | X |
+#' | giant  | X | X | X | X | X |
+#' | subgraph  | X | X | X | X | X |
+#' | ties  | X | X | X | X | X |
+#' | blocks  | X | X | X | X | X |
+#' | matching | X | X | X | X | X |
 #' @name transform
 #' @family manipulations
 #' @inheritParams reformat
@@ -719,7 +716,10 @@ to_ties.matrix <- function(object){
 }
 
 #' @describeIn transform Returns a reduced graph from a given
-#'   partition membership vector
+#'   partition membership vector.
+#'   Reduced graphs provide summary representations of network structures 
+#'   by collapsing groups of connected nodes into single nodes 
+#'   while preserving the topology of the original structures.
 #' @param membership A vector of partition memberships.
 #' @param FUN A function for summarising block content.
 #'   By default `mean`.
@@ -786,6 +786,23 @@ to_blocks.tbl_graph <- function(object, membership, FUN = mean){
 
 #' @describeIn transform Returns a network with only
 #'   matching ties
+#' @section to_matching:
+#'   `to_matching()` uses `{igraph}`'s `max_bipartite_match()`
+#'   to return a network in which each node is only tied to
+#'   one of its previous ties.
+#'   The number of these ties left is its _cardinality_,
+#'   and the algorithm seeks to maximise this such that,
+#'   where possible, each node will be associated with just one
+#'   node in the other mode or some other mark.
+#'   The algorithm used is the push-relabel algorithm
+#'   with greedy initialization and a global relabelling
+#'   after every \eqn{\frac{n}{2}} steps,
+#'   where \eqn{n} is the number of nodes in the network.
+#' @references 
+#'   Goldberg, A V; Tarjan, R E (1986). 
+#'   "A new approach to the maximum flow problem". 
+#'   _Proceedings of the eighteenth annual ACM symposium on Theory of computing – STOC '86_. p. 136. 
+#'   \doi{10.1145/12130.12144}
 #' @param mark A logical vector marking two types or modes.
 #'   By default "type".
 #' @importFrom igraph max_bipartite_match

R/measure_cohesion.R

@@ -1,7 +1,7 @@
 #' Measures of network cohesion or connectedness
 #' 
 #' These functions return values or vectors relating to how connected a network is
-#' and where the nodes or edges that would increase fragmentation are.
+#' and the number of nodes or edges to remove that would increase fragmentation.
 #' @inheritParams is
 #' @name cohesion
 #' @family measures

R/measure_diversity.R

@@ -3,22 +3,41 @@
 #' These functions offer ways to summarise the heterogeneity of an attribute
 #' across a network, within groups of a network, or the distribution of ties
 #' across this attribute.
-#' @inheritParams as_igraph
-#' @param attribute The name of a vertex attribute to measure the diversity of.
+#' @inheritParams as
+#' @param attribute Name of a nodal attribute or membership vector
+#'   to use as categories for the diversity measure.
 #' @param clusters A nodal cluster membership vector or name of a vertex attribute.
 #' @name diversity
 #' @family measures
 NULL
 
 #' @describeIn diversity Calculates the heterogeneity of ties across a network or 
-#'    within clusters by node attributes
+#'    within clusters by node attributes.
+#' @section graph_diversity:
+#'    Blau's index (1977) uses a formula known also in other disciplines
+#'    by other names 
+#'    (Gini-Simpson Index, Gini impurity, Gini's diversity index, 
+#'    Gibbs-Martin index, and probability of interspecific encounter (PIE)): 
+#'    \deqn{1 - \sum\limits_{i = 1}^k {p_i^2 }}, 
+#'    where \eqn{p_i} is the proportion of group members in \eqn{i}th category 
+#'    and _k_ is the number of categories for an attribute of interest. 
+#'    This index can be interpreted as the probability that two members 
+#'    randomly selected from a group would be from different categories. 
+#'    This index finds its minimum value (0) when there is no variety, 
+#'    i.e. when all individuals are classified in the same category. 
+#'    The maximum value depends on the number of categories and 
+#'    whether nodes can be evenly distributed across categories. 
+#' @references 
+#'   Blau, Peter M. (1977). 
+#'   _Inequality and heterogeneity_. 
+#'   New York: Free Press.
 #' @examples
 #' marvel_friends <- to_unsigned(ison_marvel_relationships, "positive")
-#' graph_blau_index(marvel_friends, "Gender")
-#' graph_blau_index(marvel_friends, "Attractive")
-#' graph_blau_index(marvel_friends, "Gender", "Rich")
+#' graph_diversity(marvel_friends, "Gender")
+#' graph_diversity(marvel_friends, "Attractive")
+#' graph_diversity(marvel_friends, "Gender", "Rich")
 #' @export
-graph_blau_index <- function(object, attribute, clusters = NULL){
+graph_diversity <- function(object, attribute, clusters = NULL){
   blau <- function(features) { 1 - sum((table(features)/length(features))^2) }
   attr <- node_attribute(object, attribute)
   if (is.null(clusters)) {
@@ -41,11 +60,23 @@ graph_blau_index <- function(object, attribute, clusters = NULL){
 
 #' @describeIn diversity Calculates the embeddedness of a node within the group
 #'    of nodes of the same attribute
+#' @section graph_homophily:
+#'   Given a partition of a network into a number of mutually exclusive groups then 
+#'   The E-I index is the number of ties between (or _external_) nodes 
+#'   grouped in some mutually exclusive categories
+#'   minus the number of ties within (or _internal_) these groups
+#'   divided by the total number of ties. 
+#'   This value can range from 1 to -1,
+#'   where 1 indicates ties only between categories/groups and -1 ties only within categories/groups.
+#' @references 
+#'   Krackhardt, David and Robert N. Stern (1988). 
+#'   Informal networks and organizational crises: an experimental simulation. 
+#'   _Social Psychology Quarterly_ 51(2), 123-140.
 #' @examples 
-#' graph_ei_index(marvel_friends, "Gender")
-#' graph_ei_index(marvel_friends, "Attractive")
+#' graph_homophily(marvel_friends, "Gender")
+#' graph_homophily(marvel_friends, "Attractive")
 #' @export
-graph_ei_index <- function(object, attribute){
+graph_homophily <- function(object, attribute){
   m <- as_matrix(object)
   if (length(attribute) == 1 && is.character(attribute)) {
     attribute <- node_attribute(object, attribute)
@@ -60,7 +91,7 @@ graph_ei_index <- function(object, attribute){
   make_graph_measure(ei, object)
 }
 
-#' @describeIn diversity Calculates the degree assortativity in a graph
+#' @describeIn diversity Calculates the degree assortativity in a graph.
 #' @importFrom igraph assortativity_degree
 #' @examples 
 #' graph_assortativity(mpn_elite_mex)

R/measure_holes.R

@@ -14,6 +14,7 @@
 #'   Redundancy is thus \eqn{\frac{2t}{n}}, 
 #'   where \eqn{t} is the sum of ties and \eqn{n} the sum of nodes in each node's neighbourhood,
 #'   and effective size is calculated as \eqn{n - \frac{2t}{n}}.
+#'   Node efficiency is the node's effective size divided by its degree.
 #' @name holes
 #' @family measures
 #' @references 

R/member_core.R

@@ -3,7 +3,7 @@
 #'   This function is used to identify which nodes should belong to the core,
 #'   and which to the periphery.
 #'   It seeks to minimize the following quantity:
-#'   \deqn{Z(S_1) = \sum_{(i<j)\in S_1} \mathbb{I}_{\{A_{ij}=0\}} + \sum_{(i<j)\notin S_1} \mathbb{I}_{\{A_{ij}=1\}}}
+#'   \deqn{Z(S_1) = \sum_{(i<j)\in S_1} \textbf{I}_{\{A_{ij}=0\}} + \sum_{(i<j)\notin S_1} \textbf{I}_{\{A_{ij}=1\}}}
 #'   where nodes \eqn{\{i,j,...,n\}} are ordered in descending degree,
 #'   \eqn{A} is the adjacency matrix,
 #'   and the indicator function is 1 if the predicate is true or 0 otherwise.