Merge pull request #103 from snlab-ch/develop

Some teaching-related additions

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: migraph
 Title: Multimodal and Multilevel Network Analysis
-Version: 0.7.0
-Date: 2021-09-24
+Version: 0.7.2
+Date: 2021-10-05
 Description: A set of tools that extend common social network analysis packages
    for analysing multimodal and multilevel networks.
    It includes functions for one- and two-mode (and sometimes three-mode) 
@@ -36,7 +36,9 @@ Imports:
     jsonlite,
     lubridate,
     stringr,
-    gridExtra
+    gridExtra,
+    sna,
+    readxl
 Suggests: 
     testthat,
     roxygen2,

NAMESPACE

@@ -25,6 +25,18 @@ S3method(plot,igraph)
 S3method(print,blockmodel)
 S3method(print,summary.netlm)
 S3method(summary,netlm)
+S3method(to_undirected,igraph)
+S3method(to_undirected,matrix)
+S3method(to_undirected,network)
+S3method(to_undirected,tbl_graph)
+S3method(to_unnamed,igraph)
+S3method(to_unnamed,matrix)
+S3method(to_unnamed,network)
+S3method(to_unnamed,tbl_graph)
+S3method(to_unweighted,igraph)
+S3method(to_unweighted,matrix)
+S3method(to_unweighted,network)
+S3method(to_unweighted,tbl_graph)
 export("%>%")
 export(.E)
 export(.G)
@@ -42,8 +54,10 @@ export(create_ring)
 export(create_star)
 export(generate_random)
 export(ggevolution)
+export(ggidentify)
 export(gglineage)
 export(ggraphgrid)
+export(ggraphlabel)
 export(graph_betweenness)
 export(graph_closeness)
 export(graph_clustering)
@@ -66,7 +80,9 @@ export(node_smallworld)
 export(plot_releases)
 export(project_cols)
 export(project_rows)
+export(read_edgelist)
 export(read_ucinet)
+export(to_undirected)
 export(to_unnamed)
 export(to_unweighted)
 export(with_graph)
@@ -106,6 +122,7 @@ importFrom(httr,http_error)
 importFrom(httr,stop_for_status)
 importFrom(httr,warn_for_status)
 importFrom(igraph,V)
+importFrom(igraph,as.undirected)
 importFrom(igraph,as_edgelist)
 importFrom(igraph,bipartite.projection)
 importFrom(igraph,degree)
@@ -126,9 +143,11 @@ importFrom(network,as.matrix.network.incidence)
 importFrom(network,as.network)
 importFrom(network,is.network)
 importFrom(purrr,map)
+importFrom(readxl,read_xlsx)
 importFrom(rlang,.data)
 importFrom(rlang,enquo)
 importFrom(rlang,eval_tidy)
+importFrom(sna,symmetrize)
 importFrom(stats,ave)
 importFrom(stats,cor)
 importFrom(stats,dist)

NEWS.md

@@ -1,3 +1,29 @@
+# migraph 0.7.2
+
+## Data
+
+* Added `brandes` dataset for teaching centrality measures
+* Added `adolescent_society` dataset for teaching friendship paradox
+* Added `read_edgelist()` for importing Excel-created edgelists directly
+
+## Visualization
+
+* Added `ggraphlabel()` for one-function (1F) plotting label-based network graphs
+* Added `ggevolution()` for 1F-plotting begin/end graph comparisons
+* Added `ggraphgrid()` for 1F snap-to-grid graph layouts based on Fruchterman-Reingold or Kamada-Kawai
+* Added `ggidentify()` for 1F identifying nodes with maximum scores based on some arbitrary function
+
+## Manipulation
+
+* Added `to_undirected()` for symmetrising networks of all types
+* Made existing `to_` functions S3 methods
+
+# migraph 0.7.1
+
+## Classes
+
+- Fixed Unicode char bug in coercion documentation
+
 # migraph 0.7.0
 
 ## Classes

R/coercion.R

@@ -45,10 +45,10 @@
 #' |  to/from      | edgelists           | matrices  |igraph  |tidygraph  |network  |
 #' | ------------- |:-----:|:-----:|:-----:|:-----:|:-----:|
 #' | edgelists (data frames)  |  |  |  |  |  |
-#' | matrices                 | √ | √ | √ | √ | √ |
-#' | igraph                   | √ | √ | √ | √ | √ |
-#' | tidygraph                | √ | √ | √ | √ | √ |
-#' | network                  | √ | √ | √ | √ | √ |
+#' | matrices                 | X | X | X | X | X |
+#' | igraph                   | X | X | X | X | X |
+#' | tidygraph                | X | X | X | X | X |
+#' | network                  | X | X | X | X | X |
 #' @export
 as_matrix <- function(object, weight = FALSE) UseMethod("as_matrix")
 

R/data_adolescent_society.R

@@ -0,0 +1,13 @@
+#' One-mode subset of adolescent society dataset
+#'
+#' @docType data
+#' @keywords datasets
+#' @name adolescent_society
+#' @usage data(adolescent_society)
+#' @format tidygraph graph object
+#' @references Coleman, James S. 1961. The Adolescent Society. 
+#' New York:Free Press.
+#' 
+#' Feld, Scott. 1991. “Why your friends have more friends than you do”
+#' American Journal of Sociology 96(6): 1464-1477.
+"adolescent_society"

R/data_brandes.R

@@ -0,0 +1,8 @@
+#' One-mode centrality demonstration structure
+#'
+#' @docType data
+#' @keywords datasets
+#' @name brandes
+#' @usage data(brandes)
+#' @format A tidygraph `tbl_graph` with 11 nodes and 24 edges.
+"brandes"

R/ggidentify.R

@@ -0,0 +1,26 @@
+#' Visualising graphs and identifying nodes with maximum values of the specified
+#' measure.
+#' @param object a migraph-consistent object
+#' @param FUN some arbitrary function that runs on the object and
+#' returns a numeric vector that can be used to scale the nodes
+#' @examples 
+#' ggidentify(brandes, node_degree)
+#' ggidentify(brandes, node_betweenness)
+#' ggidentify(brandes, node_closeness)
+#' ggidentify(brandes, node_eigenvector)
+#' @export
+ggidentify <- function(object, FUN){
+
+  measure <- FUN(object)
+  colord <- ifelse(measure == max(measure),
+               "max", "other")
+
+  ggraph::ggraph(object) + 
+    ggraph::theme_graph() +
+    ggraph::geom_edge_link() +
+    ggraph::geom_node_point(aes(size = measure,
+                                colour = colord)) +
+    ggplot2::scale_color_manual(breaks = c("max", "other"),
+                                values = c("red", "blue")) + 
+    ggplot2::theme(legend.position = "none")
+}

R/ggraphgrid.R

@@ -27,16 +27,18 @@ ggraphgrid <- function(x, algorithm = c("kk","fr")){
   name <- NULL # initialize variables to avoid CMD check notes
   x <- as_tidygraph(x)
   algorithm <- match.arg(algorithm)
+
   gg <- ggraph::create_layout(x, layout = "igraph", 
                               algorithm = algorithm, maxiter = 10000)
+
 
   ggraph::ggraph(x, graph = depth_first_recursive_search(gg)) +
     ggraph::geom_conn_bundle(data = ggraph::get_con(from = igraph::as_edgelist(x, names = FALSE)[,1], 
                                             to = igraph::as_edgelist(x, names = FALSE)[,2]), alpha = 0.1) +
     # ggraph::geom_edge_link(arrow = arrow(length = unit(3, 'mm')), 
     #                        start_cap = circle(4, 'mm'),
     #                        end_cap = circle(4, 'mm'), show.legend = FALSE) +
-    ggraph::geom_node_text(aes(label = name)) + ggplot2::theme_void()
+    ggraph::geom_node_text(aes(label = ifelse(is.null(name), "", name))) + ggplot2::theme_void()
 }
 
 depth_first_recursive_search <- function(layout){

R/ggraphlabel.R

@@ -0,0 +1,30 @@
+#' Plot graph with quick labels
+#' 
+#' For quick and easy graphing of networks with labels
+#' @param x A migraph-consistent network/graph
+#' @param algorithm An initial network layout,
+#' currently either Kamada-Kawai ("kk") or
+#' Fruchterman-Reingold ("fr")
+#' @importFrom ggraph create_layout ggraph geom_edge_link geom_node_text geom_conn_bundle get_con geom_node_point
+#' @importFrom ggplot2 theme_void
+#' @importFrom igraph as_edgelist
+#' @importFrom stats dist
+#' @examples
+#' ggraphlabel(adolescent_society)
+#' @export
+ggraphlabel <- function(x, algorithm = c("kk","fr")){
+  name <- NULL # initialize variables to avoid CMD check notes
+  x <- as_tidygraph(x)
+  algorithm <- match.arg(algorithm)
+
+  gg <- ggraph::create_layout(x, layout = "igraph", 
+                              algorithm = algorithm, maxiter = 10000)
+
+  ggraph::ggraph(x, graph = gg) +
+    ggraph::geom_conn_bundle(data = ggraph::get_con(from = igraph::as_edgelist(x, names = FALSE)[,1], 
+                                                    to = igraph::as_edgelist(x, names = FALSE)[,2]), alpha = 0.1) +
+    # ggraph::geom_edge_link(arrow = arrow(length = unit(3, 'mm')), 
+    #                        start_cap = circle(4, 'mm'),
+    #                        end_cap = circle(4, 'mm'), show.legend = FALSE) +
+    ggraph::geom_node_text(aes(label = name)) + ggplot2::theme_void()
+}

R/read_ucinet.R

@@ -2,12 +2,11 @@
 #' 
 #' These functions import from and export to UCINET network files.
 #' @name read
-#' @param header_file A character string giving the path to the header (.##h) file.
+#' @param file,header_file A character string giving the path to the header (.##h) file.
 #' If the function is called without a header_file specified,
 #' an OS-specific file picker is opened to help users select it.
-#' @param as An output class. One of "igraph", "network", or "matrix".
-#' By default "igraph".
-#' @return By default, [read_ucinet()] will import into a matrix format, 
+#' @return By default, [read_ucinet()] and [read_edgelist()] 
+#' will import into an igraph format, 
 #' but can be easily coerced from there into other formats.
 #' @details These functions only work with relatively recent UCINET
 #' file formats, e.g. type 6406 files.
@@ -23,10 +22,11 @@
 #' @author Christian Steglich, 18 June 2015
 #' @seealso [convert]
 #' @export
-read_ucinet <- function(header_file, as = c("igraph","network","matrix")) {
+read_ucinet <- function(header_file) {
 
-  as <- match.arg(as)
-  if (missing(header_file)) header_file <- file.choose()
+  if (missing(header_file)) {
+    header_file <- file.choose()
+  }
 
 	read_ucinet_header <- function(header_file) {
 	  UCINET.header <- file(header_file, "rb")
@@ -134,9 +134,7 @@ read_ucinet <- function(header_file, as = c("igraph","network","matrix")) {
 	#attr(mat,'labtype') <- header$labtype
 	#attr(mat,'infile.dt') <- header$infile.dt
 
-	if(as=="igraph") mat <- as_igraph(mat)
-	if(as=="network") mat <- as_network(mat)
-	return(mat)
+	as_igraph(mat)
 }
 
 #' @rdname read
@@ -227,3 +225,12 @@ write_ucinet <- function(object,
 		writeBin(t(mat)[i],UCINET.data,size=4,endian='little')
 	close(UCINET.data)
 }
+
+#' @rdname read
+#' @importFrom readxl read_xlsx
+#' @export
+read_edgelist <- function(file){
+  xl <- readxl::read_xlsx(file, col_names = TRUE)
+  as_igraph(xl)
+}
+