Merge pull request #92 from stocnet/develop

v1.2.1

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: manynet
 Title: Many Ways to Make, Modify, Map, Mark, and Measure Myriad Networks
-Version: 1.2.0
-Date: 2024-09-28
+Version: 1.2.1
+Date: 2024-10-01
 Description: Many tools for making, modifying, mapping, marking, measuring, 
    and motifs and memberships of many different types of networks.
    All functions operate with matrices, edge lists, and 'igraph', 'network', and 'tidygraph' objects,

NAMESPACE

@@ -634,6 +634,7 @@ export(play_segregation)
 export(read_cran)
 export(read_dynetml)
 export(read_edgelist)
+export(read_gml)
 export(read_graphml)
 export(read_matrix)
 export(read_nodelist)

NEWS.md

@@ -1,3 +1,22 @@
+# manynet 1.2.1
+
+## Making
+
+- All `read_*()` now print the command used to the console if the (default) file.choose() is used
+- Added `read_gml()`
+- Updated references, structure, and DOIs to make and modify documentation
+
+## Measures
+
+- Updated references, structure, and DOIs to centrality, diffusion, and other measures, as well as to marks, motifs, memberships, and models
+- Added more documentation on `node_power()`
+
+## Data
+
+- Added `ison_dolphins`
+- Added `ison_books`
+- Added `ison_blogs`
+
 # manynet 1.2.0
 
 ## Package

R/data_ison.R

@@ -394,6 +394,38 @@
 #'   ```
 "ison_monks"
 
+## Dolphins ####
+
+#' One-mode, undirected network of frequent associations in a dolphin pod (Lusseau et al. 2003)
+#'
+#' @description
+#'   These data contain the frequent associations between the 62 dolphins of a
+#'   pod of dolphins living off Doubtful Sound, New Zealand.
+#'   Additional information can be found in the literature cited below.
+#' @docType data
+#' @keywords datasets
+#' @name ison_dolphins
+#' @references
+#'   Lusseau, David, K. Schneider, O. J. Boisseau, P. Haase, E. Slooten, and S. M. Dawson. 2003. 
+#'   "The bottlenose dolphin community of Doubtful Sound features a large proportion of long-lasting associations", 
+#'   _Behavioral Ecology and Sociobiology_ 54, 396-405.
+#'   
+#'   Lusseau, David. 2003.
+#'   "The emergent properties of a dolphin social network",
+#'   _Proc. R. Soc. London B_ 270(S): S186-S188.
+#'   \doi{10.1098/rsbl.2003.0057}
+#'   
+#'   Lusseau, David. 2007. 
+#'   "Evidence for social role in a dolphin social network". 
+#'   _Evolutionary Ecology_ 21: 357–366. 
+#'   \doi{10.1007/s10682-006-9105-0}
+#' @usage data(ison_dolphins)
+#' @format 
+#'   ```{r, echo = FALSE}
+#'   ison_dolphins
+#'   ```
+"ison_dolphins"
+
 # Fictitious ####
 
 ## Marvel ####
@@ -591,7 +623,8 @@
 #'   \href{https://gweissman.github.io/post/grey-s-anatomy-network-of-sexual-relations/}{Gary Weissman} 
 #'   collected data on the sexual contacts between characters on the television show
 #'   through observation of the story lines in the episodes and fan pages,
-#'   and this data was extended by \href{http://badhessian.org/2012/09/lessons-on-exponential-random-graph-modeling-from-greys-anatomy-hook-ups/}{Benjamin Lind}
+#'   and this data was extended by 
+#'   \href{http://badhessian.org/2012/09/lessons-on-exponential-random-graph-modeling-from-greys-anatomy-hook-ups/}{Benjamin Lind}
 #'   including nodal attributes:
 #'   
 #'   - 'name': first and, where available, surname
@@ -614,3 +647,59 @@
 #'   ison_greys
 #'   ```
 "ison_greys"
+
+# Political ####
+
+## Books ####
+
+#' One-mode undirected network of co-purchased books about US politics on Amazon
+#'
+#' @description
+#'   This network consists of books about US politics sold by Amazon.com.
+#'   Ties represent books that are often purchased together,
+#'   as revealed by Amazon's 'customers who bought this book also bought these other
+#'   books' section on those books' pages on the website.
+#'   
+#'   Information about the book's leaning "Liberal", "Neutral", or "Conservative"
+#'   were added separately by Mark Newman based on the abstracts, descriptions,
+#'   and reviews posted on Amazon.
+#'   
+#'   These data should be cited as V. Krebs, unpublished, http://www.orgnet.com/.
+#'   
+#' @docType data
+#' @keywords datasets
+#' @name ison_books
+#' @author Valdis Krebs, Mark Newman
+#' @usage data(ison_books)
+#' @format 
+#'   ```{r, echo = FALSE}
+#'   ison_books
+#'   ```
+"ison_books"
+
+## Blogs ####
+
+#' One-mode directed network of links between US political blogs (Adamic and Glance 2005)
+#'
+#' @description
+#'   This network consists of the blogosphere around the time of the 2004
+#'   US presidential election until February 2005.
+#'   Ties were constructed from a crawl of the front page of each blog.
+#'   
+#'   Political leaning is indicated as "Liberal" (or left leaning) or 
+#'   "Conservative" (or right leaning), sourced from blog directories.
+#'   Some blogs were labelled manually, 
+#'   based on incoming and outgoing links and posts.
+#' @docType data
+#' @keywords datasets
+#' @name ison_blogs
+#' @references
+#' Adamic, Lada A., and Natalie Glance. 2005.
+#' "The political blogosphere and the 2004 US Election", 
+#' _Proceedings of the WWW-2005 Workshop on the Weblogging Ecosystem_.
+#' @usage data(ison_blogs)
+#' @format 
+#'   ```{r, echo = FALSE}
+#'   ison_blogs
+#'   ```
+"ison_blogs"

R/make_generate.R

@@ -47,7 +47,8 @@ NULL
 #'   should be retained. 
 #'   By default TRUE. 
 #' @references 
-#' Erdos, Paul, and Alfred Renyi. (1959). 
+#' ## On random networks
+#' Erdos, Paul, and Alfred Renyi. 1959. 
 #' "\href{https://www.renyi.hu/~p_erdos/1959-11.pdf}{On Random Graphs I}" 
 #' _Publicationes Mathematicae_. 6: 290–297.
 #' @importFrom igraph sample_bipartite sample_gnp sample_gnm
@@ -101,6 +102,11 @@ generate_random <- function(n, p = 0.5, directed = FALSE, with_attr = TRUE) {
 }
 
 #' @rdname make_random 
+#' @references
+#' ## On configuration models
+#' Bollobas, Bela. 1980.
+#' "A Probabilistic Proof of an Asymptotic Formula for the Number of Labelled Regular Graphs".
+#' _European Journal of Combinatorics_ 1: 311-316.
 #' @importFrom igraph sample_degseq
 #' @export
 generate_configuration <- function(.data){
@@ -132,7 +138,8 @@ generate_configuration <- function(.data){
 #'   or as a count, e.g. `c(10,0,20)`.
 #'   Is inferred from `n` if it is an existing network object.
 #' @references
-#' Holland, P.W. and Leinhardt, S. 1976. 
+#' ## On dyad-census conditioned networks
+#' Holland, Paul W., and Samuel Leinhardt. 1976. 
 #' “Local Structure in Social Networks.” 
 #' In D. Heise (Ed.), _Sociological Methodology_, pp 1-45. 
 #' San Francisco: Jossey-Bass.
@@ -229,6 +236,7 @@ NULL
 #' @param p Proportion of possible ties in the network that are realised or,
 #'   if integer greater than 1, the number of ties in the network.
 #' @references 
+#' ## On small-world networks
 #' Watts, Duncan J., and Steven H. Strogatz. 1998. 
 #' “Collective Dynamics of ‘Small-World’ Networks.” 
 #' _Nature_ 393(6684):440–42.
@@ -256,6 +264,7 @@ generate_smallworld <- function(n, p = 0.05, directed = FALSE, width = 2) {
 #' @param p Power of the preferential attachment, default is 1.
 #' @importFrom igraph sample_pa
 #' @references 
+#' ## On scale-free networks
 #' Barabasi, Albert-Laszlo, and Reka Albert. 1999. 
 #' “Emergence of Scaling in Random Networks.” 
 #' _Science_ 286(5439):509–12. 
@@ -291,6 +300,11 @@ generate_scalefree <- function(n, p = 1, directed = FALSE) {
 #' @param their_in Probability of tieing to a contact's incoming ties.
 #'   By default 1.
 #' @importFrom igraph sample_forestfire
+#' @references
+#' ## On the forest-fire model
+#' Leskovec, Jure, Jon Kleinberg, and Christos Faloutsos. 2007. 
+#' "\href{https://www.cs.cmu.edu/~jure/pubs/powergrowth-tkdd.pdf}{Graph evolution: Densification and shrinking diameters}". 
+#' _ACM transactions on Knowledge Discovery from Data_, 1(1): 2-es.
 #' @examples
 #' generate_fire(10)
 #' @export

R/make_read.R

@@ -69,6 +69,7 @@ NULL
 read_matrix <- function(file = file.choose(),
                         sv = c("comma", "semi-colon"),
                         ...) {
+  if(missing(file)) cli::cli_alert_success("Executing: read_matrix('{file}')")
   sv <- match.arg(sv)
   if (grepl("csv$", file)) {
     if (sv == "comma") {
@@ -96,6 +97,7 @@ read_matrix <- function(file = file.choose(),
 read_edgelist <- function(file = file.choose(),
                           sv = c("comma", "semi-colon"),
                           ...) {
+  if(missing(file)) cli::cli_alert_success("Executing: read_edgelist('{file}')")
   sv <- match.arg(sv)
   if (grepl("csv$", file)) {
     if (sv == "comma") {
@@ -115,6 +117,7 @@ read_edgelist <- function(file = file.choose(),
 read_nodelist <- function(file = file.choose(),
                           sv = c("comma", "semi-colon"),
                           ...) {
+  if(missing(file)) cli::cli_alert_success("Executing: read_nodelist('{file}')")
   sv <- match.arg(sv)
   if (grepl("csv$", file)) {
     if (sv == "comma") {
@@ -138,6 +141,7 @@ read_nodelist <- function(file = file.choose(),
 read_pajek <- function(file = file.choose(), 
                        ties = NULL,
                        ...) {
+  if(missing(file)) cli::cli_alert_success("Executing: read_pajek('{file}')")
   paj <- network::read.paj(file, ...)
   if(!is.network(paj)){
     if(is.null(ties)) 
@@ -178,6 +182,7 @@ read_pajek <- function(file = file.choose(),
 #' @rdname make_read
 #' @export
 read_ucinet <- function(file = file.choose()) {
+  if(missing(file)) cli::cli_alert_success("Executing: read_ucinet('{file}')")
   # Some basic checks of the input file
   # Check if the file is a UCINET header file
   if (!grepl(".##h$", file)) {
@@ -342,6 +347,7 @@ read_ucinet <- function(file = file.choose()) {
 #' @importFrom dplyr bind_rows coalesce filter mutate select everything
 #' @export
 read_dynetml <- function(file = file.choose()) {
+  if(missing(file)) cli::cli_alert_success("Executing: read_dynetml('{file}')")
   thisRequires("xml2")
   name <- type <- nodeset <- target <- value <- NULL
   xmlfile <- xml2::read_xml(file)
@@ -395,9 +401,17 @@ read_dynetml <- function(file = file.choose()) {
 #' @importFrom igraph read_graph
 #' @export
 read_graphml <- function(file = file.choose()) {
+  if(missing(file)) cli::cli_alert_success("Executing: read_graphml('{file}')")
   as_tidygraph(igraph::read_graph(file, format = "graphml"))
 }
 
+#' @rdname make_read
+#' @export
+read_gml <- function(file = file.choose()) {
+  if(missing(file)) cli::cli_alert_success("Executing: read_gml('{file}')")
+  as_tidygraph(igraph::read_graph(file, format = "gml"))
+}
+
 # Write ####
 
 #' Making networks to external files

R/manip_miss.R

@@ -14,9 +14,11 @@
 #' @inheritParams mark_is
 #' @return A data object of the same class as the function was given.
 #' @references 
+#' ## On missing data
 #'   Krause, Robert, Mark Huisman, Christian Steglich, and Tom A.B. Snijders. 2020. 
-#'   "Missing data in cross-sectional networks–An extensive comparison of missing data treatment methods". 
-#'   _Social Networks_, 62, 99-112.
+#'   "Missing data in cross-sectional networks: An extensive comparison of missing data treatment methods". 
+#'   _Social Networks_, 62: 99-112.
+#'   \doi{10.1016/j.socnet.2020.02.004}
 #' @examples 
 #' missTest <- ison_adolescents %>% 
 #'    add_tie_attribute("weight", c(1,NA,NA,1,1,1,NA,NA,1,1)) %>% 

R/manip_nodes.R

@@ -204,7 +204,8 @@ add_info <- function(.data, ...){
     unrecog <- setdiff(names(info), c("name", "nodes", "ties", "doi", 
                                       "collection", "year", "mode", "vertex1", 
                                       "vertex1.total", "vertex2", 
-                           "vertex2.total", "edge.pos", "edge.neg"))
+                           "vertex2.total", 
+                           "edge.pos", "edge.neg", "positive", "negative"))
     if(length(unrecog)>0) 
       cli::cli_alert_warning("{unrecog} are not recognised fields.")
     if("nodes" %in% names(info)){
@@ -214,7 +215,7 @@ add_info <- function(.data, ...){
       info$nodes <- NULL
     }
     if("ties" %in% names(info)){
-      info$edge.pos <- info$ties
+      info$edge.pos <- info$positive <- info$ties
       info$ties <- NULL
     }
     if("collection" %in% names(info)){

R/manip_reformat.R

@@ -94,19 +94,18 @@ to_uniplex.matrix <- function(.data, tie){
 #'   so that any pair of nodes with at least one directed edge will be
 #'   connected by an undirected edge in the new network.
 #'   This is equivalent to the "collapse" mode in `{igraph}`.
-#' @importFrom igraph as.undirected
 #' @export
 to_undirected <- function(.data) UseMethod("to_undirected")
 
 #' @importFrom igraph as.undirected
 #' @export
 to_undirected.igraph <- function(.data) {
-  igraph::as.undirected(.data, edge.attr.comb = "first")
+  igraph::as.undirected(.data)
 }
 
 #' @export
 to_undirected.tbl_graph <- function(.data) {
-  as_tidygraph(igraph::as.undirected(.data, edge.attr.comb = "first"))
+  as_tidygraph(igraph::as.undirected(.data))
 }
 
 #' @export

R/manip_reformed.R

@@ -480,9 +480,11 @@ NULL
 #'   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). 
+#' ## On matching
+#'   Goldberg, Andrew V., and Robert E. Tarjan. 1986. 
 #'   "A new approach to the maximum flow problem". 
-#'   _Proceedings of the eighteenth annual ACM symposium on Theory of computing – STOC '86_. p. 136. 
+#'   _Proceedings of the eighteenth annual ACM symposium on Theory of computing – STOC '86_. 
+#'   136-146. 
 #'   \doi{10.1145/12130.12144}
 #' @param mark A logical vector marking two types or modes.
 #'   By default "type".
@@ -541,9 +543,11 @@ to_matching.matrix <- function(.data, mark = "type"){
 #'   Note that this is a different default behaviour than that
 #'   described in Valente and Davis (1999).
 #' @references
+#' ## On mentoring
 #' Valente, Thomas, and Rebecca Davis. 1999.
 #' "Accelerating the Diffusion of Innovations Using Opinion Leaders",
 #' _Annals of the American Academy of Political and Social Science_ 566: 56-67.
+#' \doi{10.1177/000271629956600105}
 #' @examples
 #' graphr(to_mentoring(ison_adolescents))
 #' @export
@@ -592,6 +596,16 @@ to_mentoring.igraph <- function(.data, elites = 0.1){
 
 #' @rdname manip_paths
 #' @importFrom igraph eulerian_path
+#' @references
+#' ## On Eulerian trails
+#' Euler, Leonard. 1736.
+#' "Solutio problematis ad geometriam situs pertinentis". 
+#' _Comment. Academiae Sci. I. Petropolitanae_ 8: 128–140.
+#' 
+#' Hierholzer, Carl. 1873. 
+#' "Ueber die Möglichkeit, einen Linienzug ohne Wiederholung und ohne Unterbrechung zu umfahren".
+#' _Mathematische Annalen_, 6(1): 30–32.
+#' \doi{10.1007/BF01442866}
 #' @examples
 #'   to_eulerian(delete_nodes(ison_koenigsberg, "Lomse"))
 #'   #graphr(to_eulerian(delete_nodes(ison_koenigsberg, "Lomse")))
@@ -619,6 +633,21 @@ to_eulerian.tbl_graph <- function(.data){
 }
 
 #' @rdname manip_paths 
+#' @references
+#' ## On minimum spanning trees
+#' Boruvka, Otakar. 1926.
+#' "O jistem problemu minimalnim".
+#' _Prace Mor. Prirodoved. Spol. V Brne III_ 3: 37-58.
+#' 
+#' Kruskal, Joseph B. 1956.
+#' "On the shortest spanning subtree of a graph and the travelling salesman problem".
+#' _Proceedings of the American Mathematical Society_ 7(1): 48-50.
+#' \doi{10.1090/S0002-9939-1956-0078686-7}
+#' 
+#' Prim, R.C. 1957.
+#' "Shortest connection networks and some generalizations".
+#' _Bell System Technical Journal_ 36(6):1389-1401.
+#' \doi{10.1002/j.1538-7305.1957.tb01515.x}
 #' @export
 to_tree <- function(.data) {
   .data <- as_igraph(.data)