Builds a new sbm_network object from data

Constructs an object with the sbm_network class. Takes as input at a minumum an edge dataframe and will also accept a nodes dataframe that can contain addition information about the nodes in the network. A helper for allowing bipartite structure is provided which will treat either side of passed edges dataframe as two different types of nodes.

new_sbm_network(
  edges = dplyr::tibble(),
  nodes = NULL,
  edges_from_column = from,
  edges_to_column = to,
  bipartite_edges = FALSE,
  setup_model = TRUE,
  allowed_edge_types = NULL,
  default_node_type = "node",
  show_warnings = interactive(),
  random_seed = NULL,
  remove_isolated_nodes = TRUE
)

Arguments

edges	Dataframe with a from and two column encoding edges between string node ids (direction does not matter).
nodes	Optional dataframe that links a node `id` to its `type`, for when model is polypartite.
edges_from_column	Name of the from column for edges
edges_to_column	Name of the to column for edges
bipartite_edges	Do the passed edges reflect a bipartite struture? I.e. are nodes in from `from` column of a different type to those in the `to` column?
setup_model	Should an SBM model object be added? Set to `FALSE` if network is just being visualized or described.
allowed_edge_types	A dataframe in the same format of as `edges` that contains allowed pairs (order does not matter) of possible node type combinations across edges. For instance: nodes of type pollinator are allowed to connect to flower nodes but not to other pollinator nodes. If this is left undefined, it is inferred from edges.
default_node_type	What should nodes that the type is generated for be called?
show_warnings	Do you want to be warned when minor problems are detected by function? Useful to disable when not running in an interactive mode etc.
random_seed	Integer seed to be passed to model's internal random sampling engine. Note that if the model is restored from a saved state this seed will be initialized again to the start value which will harm reproducability.
remove_isolated_nodes	Should the network filter out nodes that have no edges? This option should only be set to `FALSE` for visualization purposes as the SBM model needs at least one edge for every node to work.

Value

An S3 object of class sbm_network. For details see new_sbm_network section "Class structure."

Class structure

The sbm_network class is an S3 class with two minimum components:

$edges: Edges that the network is built out of. This is simply the passed edges input to the function.
$nodes: Nodes that the edges connect. This is either the passed nodes input or is created from the edges input automatically by listing the unique node ids seen in the edges.

If the method mcmc_sweep has been run on the sbm_network object then a $sweep_result slot will be added. For more info see mcmc_sweep.

If either of the methods collapse_blocks or collapse_run have been applied to the sbm_network object then the slot $collapse_result will be append.

A few attributes are contained by the class as well:

n_nodes: Number of unique nodes in the current model. Equivalent to nrow(sbm_network$nodes).
n_edges: Number of edges in the current model. Equivalent to nrow(sbm_network$edges).
node_types: "Vector of the unique types for nodes in network"
from_column: Raw quosure representing the edges_from_column argument. This is kept so bipartite network types can be inferred and no modification of the passed edges dataframe needs to take place.
to_column: Same as from_column
model: S4 class that is exported by the C++ code used to implement all the modeling algorithms. Most of the time the user should not have to interact with this object and thus it can be ignored.

Examples


# Build small object from simple edge dataframe
edges <- dplyr::tribble(
  ~a_node, ~b_node,
  "a1"   , "b1"   ,
  "a1"   , "b2"   ,
  "a1"   , "b3"   ,
  "a2"   , "b1"   ,
  "a2"   , "b4"   ,
  "a3"   , "b1"
)

new_sbm_network(edges, edges_from_column = a_node, edges_to_column = b_node)
#> SBM Network with 7 nodes of a single type and 6 edges. 
#>  
#> Nodes: # A tibble: 6 x 2
#>   id    type 
#>   <chr> <chr>
#> 1 a1    node 
#> 2 a2    node 
#> 3 a3    node 
#> 4 b1    node 
#> 5 b2    node 
#> 6 b3    node 
#> ... 
#>  
#> Edges: # A tibble: 6 x 2
#>   a_node b_node
#>   <chr>  <chr> 
#> 1 a1     b1    
#> 2 a1     b2    
#> 3 a1     b3    
#> 4 a2     b1    
#> 5 a2     b4    
#> 6 a3     b1    
#> ... 
#>  

# Builds network from nodes and edges
nodes <- dplyr::tribble(
  ~id, ~type,
  "a1", "node",
  "a2", "node",
  "a3", "node",
  "b1", "node",
  "b2", "node",
  "b3", "node",
  "b4", "node"
)

new_sbm_network(edges = edges,
                nodes = nodes,
                edges_from_column = a_node,
                edges_to_column = b_node)
#> SBM Network with 7 nodes of a single type and 6 edges. 
#>  
#> Nodes: # A tibble: 6 x 2
#>   id    type 
#>   <chr> <chr>
#> 1 a1    node 
#> 2 a2    node 
#> 3 a3    node 
#> 4 b1    node 
#> 5 b2    node 
#> 6 b3    node 
#> ... 
#>  
#> Edges: # A tibble: 6 x 2
#>   a_node b_node
#>   <chr>  <chr> 
#> 1 a1     b1    
#> 2 a1     b2    
#> 3 a1     b3    
#> 4 a2     b1    
#> 5 a2     b4    
#> 6 a3     b1    
#> ... 
#>  

# Can build a bipartite network just from an edge list
new_sbm_network(edges, bipartite_edges = TRUE,
                edges_from_column = a_node,
                edges_to_column = b_node)
#> SBM Network with 7 nodes of 2 types and 6 edges. 
#>  
#> Nodes: # A tibble: 6 x 2
#>   id    type  
#>   <chr> <chr> 
#> 1 a1    a_node
#> 2 a2    a_node
#> 3 a3    a_node
#> 4 b1    b_node
#> 5 b2    b_node
#> 6 b3    b_node
#> ... 
#>  
#> Edges: # A tibble: 6 x 2
#>   a_node b_node
#>   <chr>  <chr> 
#> 1 a1     b1    
#> 2 a1     b2    
#> 3 a1     b3    
#> 4 a2     b1    
#> 5 a2     b4    
#> 6 a3     b1    
#> ... 
#>  

# Or if adding a node dataframe as well, arbitrary polypartite structure is possible
edges_tripartite <- dplyr::tribble(
  ~from,    ~to,
     "a1", "b1",
     "a1", "b2",
     "a2", "b1",
     "b1", "c1",
     "b2", "c1",
     "b2", "c2"
)

nodes_tripartite <- dplyr::tribble(
  ~id, ~type,
  "a1", "a",
  "a2", "a",
  "b1", "b",
  "b2", "b",
  "c1", "c",
  "c2", "c"
)

new_sbm_network(edges = edges_tripartite,
                nodes = nodes_tripartite)
#> SBM Network with 6 nodes of 3 types and 6 edges. 
#>  
#> Nodes: # A tibble: 6 x 2
#>   id    type 
#>   <chr> <chr>
#> 1 a1    a    
#> 2 a2    a    
#> 3 b1    b    
#> 4 b2    b    
#> 5 c1    c    
#> 6 c2    c    
#> ... 
#>  
#> Edges: # A tibble: 6 x 2
#>   from  to   
#>   <chr> <chr>
#> 1 a1    b1   
#> 2 a1    b2   
#> 3 a2    b1   
#> 4 b1    c1   
#> 5 b2    c1   
#> 6 b2    c2   
#> ... 
#>  

# the allowed_edge_types argument lets you explicitely tell the
# model what each type of node is allowed to connect to.
# Here we use it to enforce tripartite structure where nodes of
# the a type can connect to either b or c but b and c can only
# connect to a.

allowed_edge_types <- dplyr::tribble(~from, ~to,
                               "a", "b",
                               "a", "c")
if (FALSE) {
new_sbm_network(edges = edges_tripartite,
                nodes = nodes_tripartite,
                allowed_edge_types = allowed_edge_types)
}

Arguments

Value

Class structure

See also

Examples

Contents