Merge pull request #239 from snlab-ch/develop

v0.10.4

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: migraph
 Title: Tools for Multimodal Network Analysis
-Version: 0.10.3
+Version: 0.10.4
 Date: 2022-07-03
 Description: A set of tools for analysing multimodal networks.
    All functions operate with matrices, edge lists, 

NEWS.md

@@ -1,3 +1,13 @@
+# migraph 0.10.4
+
+## Package
+
+- Fixed some URL issues
+
+## Manipulation
+
+- Split `to_*()` functions into reformatting (changing properties) and transforming (changing dimensions) documentation
+
 # migraph 0.10.3
 
 ## Package

R/data_mpn.R

@@ -308,7 +308,7 @@ NULL
 #' \href{https://correlatesofwar.org/data-sets/bilateral-trade}{\emph{Trade}}.
 #' 
 #' Barbieri, Katherine and Omar Keshk. 2012. 
-#' \href{https://correlatesofwar.org.}{\emph{Correlates of War Project Trade Data Set Codebook, Version 3.0.}}.
+#' Correlates of War Project Trade Data Set Codebook, Version 3.0.
 #' @format 
 #'   ```{r, echo = FALSE}
 #'   mpn_cow_trade

R/manip_to.R

@@ -1,13 +1,14 @@
+# Reformatting ####
+
 #' Tools for reformatting networks, graphs, and matrices
 #' 
 #' @description
-#' These functions offer tools for transforming certain properties 
-#' of migraph-consistent objects
+#' These functions offer tools for reformatting migraph-consistent objects
 #' (matrices, igraph, tidygraph, or network objects).
 #' Unlike the `as_*()` group of functions,
 #' these functions always return the same object type as they are given,
 #' only transforming these objects' properties.
-#' 
+#' @details
 #' Since some modifications are easier to implement for some objects than others,
 #' here are the currently implemented modifications:
 #' 
@@ -21,12 +22,9 @@
 #' | unnamed  | X | X | X | X | X |
 #' | named  | X | X | X | X | X |
 #' | simplex  |  | X | X | X |   |
-#' | main_component  |  |   | X | X | X |
 #' | onemode  |  |   | X | X |   |
 #' | multilevel  |  | X | X | X |   |
-#' | mode1 | | X | X | X | |
-#' | mode2 | | X | X | X | |
-#' @name to
+#' @name reformat
 #' @family manipulations
 #' @inheritParams is
 #' @param edge Character string naming an edge attribute to retain from a graph.
@@ -41,7 +39,7 @@
 #' with certain modifications as outlined for each function.
 NULL
 
-#' @describeIn to Returns an object that includes only a single type of tie
+#' @describeIn reformat Returns an object that includes only a single type of tie
 #' @importFrom igraph delete_edges edge_attr_names delete_edge_attr
 #' @importFrom igraph E get.edge.attribute edge_attr_names
 #' @examples
@@ -77,31 +75,7 @@ to_uniplex.igraph <- function(object, edge){
   out
 }
 
-#' @describeIn to Returns an object that includes only the main component
-#' without any smaller components or isolates
-#' @export
-to_main_component <- function(object) UseMethod("to_main_component")
-
-#' @export
-to_main_component.tbl_graph <- function(object) {
-  as_tidygraph(to_main_component(as_igraph(object)))
-}
-
-#' @export
-to_main_component.igraph <- function(object) {
-  comps <- igraph::components(object)
-  max.comp <- which.max(comps$csize)
-  igraph::delete.vertices(object, comps$membership != max.comp)
-}
-
-#' @export
-to_main_component.network <- function(object) {
-  network::delete.vertices(object, 
-                           which(!sna::component.largest(object,
-                                                         result = "membership")))
-}
-
-#' @describeIn to Returns an object that has any edge direction removed,
+#' @describeIn reformat Returns an object that has any edge direction removed,
 #'   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}`.
@@ -132,7 +106,7 @@ to_undirected.matrix <- function(object) {
   } else ((object + t(object)) > 0) * 1
 }
 
-#' @describeIn to Returns an object that has any edge direction transposed,
+#' @describeIn reformat Returns an object that has any edge direction transposed,
 #'   or flipped, so that senders become receivers and receivers become senders.
 #'   This essentially has no effect on undirected networks or reciprocated ties.
 #' @export
@@ -168,7 +142,7 @@ to_redirected.matrix <- function(object) {
   t(object)
 }
 
-#' @describeIn to Returns an object that has all edge weights removed
+#' @describeIn reformat Returns an object that has all edge weights removed
 #' @export
 to_unweighted <- function(object, threshold = 1) UseMethod("to_unweighted")
 
@@ -205,7 +179,7 @@ to_unweighted.data.frame <- function(object, threshold = 1) {
   else stop("Not an edgelist")
 }
 
-#' @describeIn to Returns a network with either just the "positive" ties
+#' @describeIn reformat Returns a network with either just the "positive" ties
 #'   or just the "negative" ties
 #' @export
 to_unsigned <- function(object, 
@@ -266,7 +240,7 @@ to_unsigned.igraph <- function(object,
   } else object
 }
 
-#' @describeIn to Returns an object with all vertex names removed
+#' @describeIn reformat Returns an object with all vertex names removed
 #' @export
 to_unnamed <- function(object) UseMethod("to_unnamed")
 
@@ -306,7 +280,7 @@ to_unnamed.data.frame <- function(object) {
   dplyr::as_tibble(out)
 }
 
-#' @describeIn to Returns an object that has random vertex names added
+#' @describeIn reformat Returns an object that has random vertex names added
 #' @export
 to_named <- function(object, names = NULL) UseMethod("to_named")
 
@@ -360,7 +334,7 @@ to_named.matrix <- function(object, names = NULL) {
   object
 }
 
-#' @describeIn to Returns an object that has all loops or self-ties removed
+#' @describeIn reformat Returns an object that has all loops or self-ties removed
 #' @importFrom igraph simplify
 #' @export
 to_simplex <- function(object) UseMethod("to_simplex")
@@ -382,7 +356,84 @@ to_simplex.matrix <- function(object) {
   out
 }
 
-#' @describeIn to Results in a weighted one-mode object
+#' @describeIn reformat Returns an object that has any type/mode attributes removed,
+#'   but otherwise includes all the same nodes and ties.
+#'   Note that this is not the same as `to_mode1()` or `to_mode2()`,
+#'   which return only some of the nodes and new ties established by coincidence.
+#' @importFrom igraph delete_vertex_attr
+#' @export
+to_onemode <- function(object) UseMethod("to_onemode")
+
+#' @export
+to_onemode.tbl_graph <- function(object) {
+  as_tidygraph(to_onemode(as_igraph(object)))
+}
+
+#' @export
+to_onemode.igraph <- function(object) {
+  if ("type" %in% igraph::vertex_attr_names(object)) object <- igraph::delete_vertex_attr(object, "type")
+  object
+}
+
+#' @describeIn reformat Returns a network that is not divided into two mode types
+#'   but embeds two or more modes into a multimodal network structure.
+#' @export
+to_multilevel <- function(object) UseMethod("to_multilevel")
+
+#' @export
+to_multilevel.tbl_graph <- function(object) {
+  as_tidygraph(to_multilevel(as_igraph(object)))
+}
+
+#' @export
+to_multilevel.igraph <- function(object) {
+  if(is_twomode(object)){
+    igraph::V(object)$lvl <- ifelse(igraph::V(object)$type, 2, 1)
+    object <- igraph::delete_vertex_attr(object, "type")
+  }
+  object
+}
+
+#' @export
+to_multilevel.matrix <- function(object) {
+  top <- cbind(matrix(0, nrow(object), nrow(object)), object)
+  bottom <- cbind(t(object), matrix(0, ncol(object), ncol(object)))
+  out <- rbind(top, bottom)
+  colnames(out) <- rownames(out)
+  out
+}
+
+# Transforming ####
+
+#' Tools for transforming networks, graphs, and matrices
+#' 
+#' @description
+#' These functions offer tools for transforming migraph-consistent objects
+#' (matrices, igraph, tidygraph, or network objects).
+#' Transforming means that the returned object may have different dimensions
+#' than the original object.
+#' @details
+#' Since some modifications are easier to implement for some objects than others,
+#' here are the currently implemented modifications:
+#' 
+#' |  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.
+#' @name transform
+#' @family manipulations
+#' @inheritParams reformat
+NULL
+
+#' @describeIn transform Results in a weighted one-mode object
 #' that retains the row nodes from a two-mode object,
 #' and weights the ties between them on the basis of
 #' their joint ties to nodes in the second mode (columns)
@@ -409,7 +460,7 @@ to_mode1.tbl_graph <- function(object) {
   as_tidygraph(igraph::bipartite.projection(object)$proj1)
 }
 
-#' @describeIn to Results in a weighted one-mode object
+#' @describeIn transform Results in a weighted one-mode object
 #' that retains the column nodes from a two-mode object,
 #' and weights the ties between them on the basis of
 #' their joint ties to nodes in the first mode (rows).
@@ -431,54 +482,41 @@ to_mode2.tbl_graph <- function(object) {
   as_tidygraph(igraph::bipartite.projection(object)$proj2)
 }
 
-#' @describeIn to Returns an object that has any type/mode attributes removed,
-#'   but otherwise includes all the same nodes and ties.
-#'   Note that this is not the same as `to_mode1()` or `to_mode2()`,
-#'   which return only some of the nodes and new ties established by coincidence.
-#' @importFrom igraph delete_vertex_attr
-#' @export
-to_onemode <- function(object) UseMethod("to_onemode")
-
+#' @describeIn transform Returns an object that includes only the main component
+#' without any smaller components or isolates
 #' @export
-to_onemode.tbl_graph <- function(object) {
-  as_tidygraph(to_onemode(as_igraph(object)))
-}
+to_main_component <- function(object) UseMethod("to_main_component")
 
 #' @export
-to_onemode.igraph <- function(object) {
-  if ("type" %in% igraph::vertex_attr_names(object)) object <- igraph::delete_vertex_attr(object, "type")
-  object
+to_main_component.tbl_graph <- function(object) {
+  as_tidygraph(to_main_component(as_igraph(object)))
 }
 
-#' @describeIn to Returns a network that is not divided into two mode types
-#'   but embeds two or more modes into a multimodal network structure.
-#' @export
-to_multilevel <- function(object) UseMethod("to_multilevel")
-
 #' @export
-to_multilevel.tbl_graph <- function(object) {
-  as_tidygraph(to_multilevel(as_igraph(object)))
+to_main_component.igraph <- function(object) {
+  comps <- igraph::components(object)
+  max.comp <- which.max(comps$csize)
+  igraph::delete.vertices(object, comps$membership != max.comp)
 }
 
 #' @export
-to_multilevel.igraph <- function(object) {
-  if(is_twomode(object)){
-    igraph::V(object)$lvl <- ifelse(igraph::V(object)$type, 2, 1)
-    object <- igraph::delete_vertex_attr(object, "type")
-  }
-  object
+to_main_component.network <- function(object) {
+  network::delete.vertices(object, 
+                           which(!sna::component.largest(object,
+                                                         result = "membership")))
 }
 
+#' @describeIn transform Returns a network subgraph filtered
+#'   on the basis of some node-related logical statement.
+#' @param ... Arguments passed on to dplyr::filter
+#' @importFrom dplyr filter
 #' @export
-to_multilevel.matrix <- function(object) {
-  top <- cbind(matrix(0, nrow(object), nrow(object)), object)
-  bottom <- cbind(t(object), matrix(0, ncol(object), ncol(object)))
-  out <- rbind(top, bottom)
-  colnames(out) <- rownames(out)
-  out
+to_subgraph <- function(object, ...){
+  dplyr::filter(.data = as_tidygraph(object), ..., 
+                .preserve = FALSE)
 }
 
-#' @describeIn to Returns a matrix (named if possible) 
+#' @describeIn transform Returns a matrix (named if possible) 
 #'   where the edges are the nodes
 #' @importFrom igraph make_line_graph E
 #' @examples
@@ -492,18 +530,7 @@ to_ties <- function(object){
   out
 }
 
-
-#' @describeIn to Returns a network subgraph filtered
-#'   on the basis of some node-related logical statement.
-#' @param ... Arguments passed on to dplyr::filter
-#' @importFrom dplyr filter
-#' @export
-to_subgraph <- function(object, ...){
-  dplyr::filter(.data = as_tidygraph(object), ..., 
-                .preserve = FALSE)
-}
-
-#' @describeIn to Returns a reduced graph from a given
+#' @describeIn transform Returns a reduced graph from a given
 #'   partition membership vector
 #' @param membership A vector of partition memberships
 #' @param FUN A function for summarising block content.
@@ -543,3 +570,6 @@ to_blocks <- function(object, membership, FUN = mean){
   }
   out
 }
+
+
+

R/mark_is.R

@@ -1,4 +1,4 @@
-#' Logical tests of network properties
+#' Marking networks based on their properties
 #' 
 #' These functions implement logical tests for various network
 #' properties.

R/mark_nodes.R

@@ -1,4 +1,4 @@
-#' Logical tests of nodal properties
+#' Marking nodes based on their properties
 #' 
 #' @description 
 #'   These functions return logical vectors the length of the 

R/mark_ties.R

@@ -1,4 +1,4 @@
-#' Logical tests of tie properties
+#' Marking ties based on their properties
 #' 
 #' @description 
 #'   These functions return logical vectors the length of the ties

README.Rmd

@@ -65,7 +65,7 @@ All `{migraph}` measures and models work with data in base formats:
 as well as with objects constructed from the following packages:
 
 - [`{igraph}`](https://igraph.org/r/)
-- [`{network}`](http://statnet.org)
+- [`{network}`](https://statnet.org)
 - [`{tidygraph}`](https://tidygraph.data-imaginist.com/index.html)
 
 `{migraph}`'s `as_*()` functions can be used to translate objects