Merge pull request #251 from snlab-ch/develop

v0.12.4

.github/workflows/pushrelease.yml

@@ -165,6 +165,7 @@ jobs:
           extra-packages: |
             any::rcmdcheck
             any::pkgdown
+            any::rsconnect
           needs: check
 
       - name: Install package

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: migraph
 Title: Tools for Multimodal Network Analysis
-Version: 0.12.3
-Date: 2022-10-25
+Version: 0.12.4
+Date: 2022-10-26
 Description: A set of tools for analysing multimodal networks.
    All functions operate with matrices, edge lists, 
    and 'igraph', 'network', and 'tidygraph' objects,
@@ -49,6 +49,7 @@ Suggests:
     Rgraphviz,
     rmarkdown,
     roxygen2,
+    rsconnect,
     testthat
 Authors@R: 
     c(person(given = "James",

NEWS.md

@@ -1,3 +1,11 @@
+# migraph 0.12.4
+
+## Package
+
+- Converted 'visualisation' vignette to a learnr tutorial
+- Deleted troublesome URLs to correlatesofwar.org
+- Brokerage census gets their own documentation page
+
 # migraph 0.12.3
 
 ## Package
@@ -8,7 +16,7 @@
 ## Motifs
 
 - Added node names to node_motif class where available
-- Added `node_brokerage_census()` and `network_network_census()` for counting Gould-Fernandez brokerage roles
+- Added `node_brokerage_census()` and `network_brokerage_census()` for counting Gould-Fernandez brokerage roles
 
 # migraph 0.12.2
 

R/data_mpn.R

@@ -334,8 +334,7 @@ NULL
 #' \href{https://www.cambridge.org/core/books/multimodal-political-networks/43EE8C192A1B0DCD65B4D9B9A7842128}{\emph{Multimodal Political Networks}}.
 #' Cambridge University Press. Cambridge University Press.
 #' @source 
-#' The Correlates of War Project. 2012.
-#' \href{https://correlatesofwar.org/data-sets/bilateral-trade/}{\emph{Trade}}.
+#' The Correlates of War Project. 2012. \emph{Trade}.
 #' 
 #' Barbieri, Katherine and Omar Keshk. 2012. 
 #' Correlates of War Project Trade Data Set Codebook, Version 3.0.
@@ -348,8 +347,7 @@ NULL
 #' @rdname mpn_cow
 #' @usage data(mpn_cow_igo)
 #' @source
-#' The Correlates of War Project. 2019.
-#' \href{https://correlatesofwar.org/data-sets/IGOs/}{\emph{Intergovernmental Organization v3}}.
+#' The Correlates of War Project. 2019. \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/member_community.R

@@ -62,7 +62,12 @@ node_kernighanlin <- function(object){
   make_node_member(out, object)
 }
 
-#' @describeIn community The walktrap algorithm
+#' @describeIn community A hierarchical, agglomerative algorithm based on random walks.
+#' @section Walktrap:
+#'   The general idea is that random walks on a network are more likely to stay 
+#'   within the same community because few edges lead outside a community.
+#'   By repeating random walks of 4 steps many times,
+#'   information about the hierarchical merging of communities is collected.
 #' @param times Integer indicating number of simulations/walks used.
 #'   By default, `times=50`.
 #' @examples
@@ -75,7 +80,19 @@ node_walktrap <- function(object, times = 50){
 
 }
 
-#' @describeIn community The edge-betweenness algorithm
+#' @describeIn community A hierarchical, decomposition algorithm
+#'   where edges are removed in decreasing order of the number of
+#'   shortest paths passing through the edge,
+#'   resulting in a hierarchical representation of group membership.
+#' @section Edge-betweenness:
+#'   This is motivated by the idea that edges connecting different groups 
+#'   are more likely to lie on multiple shortest paths when they are the 
+#'   only option to go from one group to another. 
+#'   This method yields good results but is very slow because of 
+#'   the computational complexity of edge-betweenness calculations and 
+#'   the betweenness scores have to be re-calculated after every edge removal. 
+#'   Networks of ~700 nodes and ~3500 ties are around the upper size limit 
+#'   that are feasible with this approach. 
 #' @examples
 #' node_edge_betweenness(ison_adolescents)
 #' @export
@@ -86,7 +103,16 @@ node_edge_betweenness <- function(object){
 
 }
 
-#' @describeIn community The fast-greedy algorithm
+#' @describeIn community A hierarchical, agglomerative algorithm, 
+#'   that tries to optimize modularity in a greedy manner.
+#' @section Fast-greedy:
+#'   Initially, each node is assigned a separate community.
+#'   Communities are then merged iteratively such that each merge
+#'   yields the largest increase in the current value of modularity,
+#'   until no further increases to the modularity are possible.
+#'   The method is fast and recommended as a first approximation 
+#'   because it has no parameters to tune. 
+#'   However, it is known to suffer from a resolution limit.
 #' @examples
 #' node_fast_greedy(ison_adolescents)
 #' @export

R/motif_census.R

@@ -9,10 +9,6 @@
 #' @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
 
@@ -216,24 +212,6 @@ node_path_census <- function(object){
   make_node_motif(out, object)
 }
 
-#' @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
@@ -330,14 +308,38 @@ network_mixed_census <- function (object, object2) {
   make_network_motif(res, object)
 }
 
-#' @describeIn network_census Returns the Gould-Fernandez brokerage
-#'   roles in a network.
+#' Censuses of brokerage motifs
+#' 
+#' @name brokerage_census
+#' @family motifs
+#' @inheritParams node_census
+#' @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.
+NULL
+
+#' @describeIn brokerage_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)
+}
+
+#' @describeIn brokerage_census Returns the Gould-Fernandez brokerage
+#'   roles in a network.
+#' @examples 
 #' network_brokerage_census(ison_networkers, "Discipline")
 #' @export
 network_brokerage_census <- function(object, membership, standardized = FALSE){

README.Rmd

@@ -237,6 +237,26 @@ This gives you access to the compiled vignettes in html form,
 as well as the original source (an Rmarkdown file),
 and just the R code without any of the annotations.
 
+### Tutorials
+
+We are however moving away from the use of vignettes in this package,
+in favour of smaller and more interactive `{learnr}` tutorials.
+Since version 0.12.3, many of the previous vignettes are instead
+available as tutorials, more will be converted soon,
+and those that have been converted will continue to be updated and enriched.
+
+To access the tutorials, you will need to have the additional package `{learnr}` installed:
+`install.packages("learnr")`.
+Then we would first suggest that you check to see which vignettes are currently available:
+
+```{r learnr-tutes}
+learnr::available_tutorials("migraph")
+```
+
+You can then choose to begin a tutorial using the following command: e.g.
+`learnr::run_tutorial("equivalence", "migraph")`.
+For more details on the `{learnr}` package, see [here](https://rstudio.github.io/learnr/).
+
 ## Relationship to other packages
 
 It draws together, updates, and builds upon many functions currently available in

README.md

@@ -161,8 +161,9 @@ function names wherever possible.
 
 #### Motifs
 
--   Censuses: `node_path_census()`, `node_quad_census()`,
-    `node_tie_census()`, `node_triad_census()`, `network_dyad_census()`,
+-   Censuses: `node_brokerage_census()`, `node_path_census()`,
+    `node_quad_census()`, `node_tie_census()`, `node_triad_census()`,
+    `network_brokerage_census()`, `network_dyad_census()`,
     `network_mixed_census()`, `network_triad_census()`
 
 #### Models
@@ -250,6 +251,31 @@ This gives you access to the compiled vignettes in html form, as well as
 the original source (an Rmarkdown file), and just the R code without any
 of the annotations.
 
+### Tutorials
+
+We are however moving away from the use of vignettes in this package, in
+favour of smaller and more interactive `{learnr}` tutorials. Since
+version 0.12.3, many of the previous vignettes are instead available as
+tutorials, more will be converted soon, and those that have been
+converted will continue to be updated and enriched.
+
+To access the tutorials, you will need to have the additional package
+`{learnr}` installed: `install.packages("learnr")`. Then we would first
+suggest that you check to see which vignettes are currently available:
+
+``` r
+learnr::available_tutorials("migraph")
+#> Available tutorials:
+#> * migraph
+#>   - community   : "Equivalence"
+#>   - equivalence : "Equivalence"
+```
+
+You can then choose to begin a tutorial using the following command:
+e.g. `learnr::run_tutorial("equivalence", "migraph")`. For more details
+on the `{learnr}` package, see
+[here](https://rstudio.github.io/learnr/).
+
 ## Relationship to other packages
 
 It draws together, updates, and builds upon many functions currently

inst/tutorials/community/community.Rmd

@@ -1,5 +1,5 @@
 ---
-title: "Equivalence"
+title: "Community"
 author: "James Hollway"
 output: learnr::tutorial
 runtime: shiny_prerendered