Network Objects

Construct, coerce to, test for and print network objects.

is.network(x)

as.network(x, ...)

network(
  x,
  vertex.attr = NULL,
  vertex.attrnames = NULL,
  directed = TRUE,
  hyper = FALSE,
  loops = FALSE,
  multiple = FALSE,
  bipartite = FALSE,
  ...
)

network.copy(x)

# S3 method for class 'data.frame'
as.network(
  x,
  directed = TRUE,
  vertices = NULL,
  hyper = FALSE,
  loops = FALSE,
  multiple = FALSE,
  bipartite = FALSE,
  bipartite_col = "is_actor",
  ...
)

# S3 method for class 'network'
print(
  x,
  matrix.type = which.matrix.type(x),
  mixingmatrices = FALSE,
  na.omit = TRUE,
  print.adj = FALSE,
  ...
)

# S3 method for class 'network'
summary(object, na.omit = TRUE, mixingmatrices = FALSE, print.adj = TRUE, ...)

Arguments

x

for network, a matrix giving the network structure in adjacency, incidence, or edgelist form; otherwise, an object of class network.

...

additional arguments.

vertex.attr

optionally, a list containing vertex attributes.

vertex.attrnames

optionally, a list containing vertex attribute names.

directed

logical; should edges be interpreted as directed?

hyper

logical; are hyperedges allowed?

loops

logical; should loops be allowed?

multiple

logical; are multiplex edges allowed?

bipartite

count; should the network be interpreted as bipartite? If present (i.e., non-NULL, non-FALSE) it is the count of the number of actors in the bipartite network. In this case, the number of nodes is equal to the number of actors plus the number of events (with all actors preceeding all events). The edges are then interpreted as nondirected. Values of bipartite==0 are permited, indicating a bipartite network with zero-sized first partition.

vertices

If x is a data.frame, vertices is an optional data.frame containing the vertex attributes. The first column is assigned to the "vertex.names" and additional columns are used to set vertex attributes using their column names. If bipartite is TRUE, a logical column named "is_actor" (or the name of a column specified using the bipartite_col parameter) can be provided indicating which vertices should be considered as actors. If not provided, vertices referenced in the first column of x are assumed to be the network's actors. If your network has isolates (i.e. there are vertices referenced in vertices that are not referenced in x), the "is_actor" column is required.

bipartite_col

character(1L), default: "is_actor". The name of the logical column indicating which vertices should be considered as actors in bipartite networks.

matrix.type

one of "adjacency", "edgelist", "incidence". See edgeset.constructors for details and optional additional arguments

mixingmatrices

logical; print the mixing matrices for the discrete attributes?

na.omit

logical; omit summarization of missing attributes in network?

print.adj

logical; print the network adjacency structure?

object

an object of class network.

Value

network, as.network, and print.network all return a network class object; is.network returns TRUE or FALSE.

Details

network constructs a network class object from a matrix representation. If the matrix.type parameter is not specified, it will make a guess as to the intended edgeset.constructors function to call based on the format of these input matrices. If the class of x is not a matrix, network construction can be dispatched to other methods. For example, If the ergm package is loaded, network() can function as a shorthand for as.network.numeric with x as an integer specifying the number of nodes to be created in the random graph.

If the ergm package is loaded, network can function as a shorthand for as.network.numeric if x is an integer specifying the number of nodes. See the help page for as.network.numeric in ergm package for details.

network.copy creates a new network object which duplicates its supplied argument. (Direct assignment with <- should be used rather than network.copy in most cases.)

as.network tries to coerce its argument to a network, using the as.network.matrix functions if x is a matrix. (If the argument is already a network object, it is returned as-is and all other arguments are ignored.)

is.network tests whether its argument is a network (in the sense that it has class network).

print.network prints a network object in one of several possible formats. It also prints the list of global attributes of the network.

summary.network provides similar information.

Note

Between versions 0.5 and 1.2, direct assignment of a network object created a pointer to the original object, rather than a copy. As of version 1.2, direct assignment behaves in the same manner as network.copy. Direct use of the latter is thus superfluous in most situations, and is discouraged.

Many of the network package functions modify their network object arguments in-place. For example, set.network.attribute(net,"myVal",5) will have the same effect as net<-set.network.attribute(net,"myVal",5). Unfortunately, the current implementation of in-place assignment breaks when the network argument is an element of a list or a named part of another object. So set.network.attribute(myListOfNetworks[[1]],"myVal",5) will silently fail to modify its network argument, likely leading to incorrect output.

References

Butts, C. T. (2008). “network: a Package for Managing Relational Data in R.” Journal of Statistical Software, 24(2). doi:10.18637/jss.v024.i02

See also

network.initialize, attribute.methods, as.network.matrix, as.matrix.network, deletion.methods, edgeset.constructors, network.indicators, plot.network

Author

Carter T. Butts buttsc@uci.edu and David Hunter dhunter@stat.psu.edu

Examples

m <- matrix(rbinom(25,1,.4),5,5)
diag(m) <- 0
g <- network(m, directed=FALSE)
summary(g)
#> Network attributes:
#>   vertices = 5
#>   directed = FALSE
#>   hyper = FALSE
#>   loops = FALSE
#>   multiple = FALSE
#>   bipartite = FALSE
#>  total edges = 8 
#>    missing edges = 0 
#>    non-missing edges = 8 
#>  density = 0.8 
#> 
#> Vertex attributes:
#>   vertex.names:
#>    character valued attribute
#>    5 valid vertex names
#> 
#> No edge attributes
#> 
#> Network adjacency matrix:
#>   1 2 3 4 5
#> 1 0 1 1 1 1
#> 2 1 0 0 1 1
#> 3 1 0 0 0 1
#> 4 1 1 0 0 1
#> 5 1 1 1 1 0

h <- network.copy(g)       #Note: same as h<-g
summary(h)
#> Network attributes:
#>   vertices = 5
#>   directed = FALSE
#>   hyper = FALSE
#>   loops = FALSE
#>   multiple = FALSE
#>   bipartite = FALSE
#>  total edges = 8 
#>    missing edges = 0 
#>    non-missing edges = 8 
#>  density = 0.8 
#> 
#> Vertex attributes:
#>   vertex.names:
#>    character valued attribute
#>    5 valid vertex names
#> 
#> No edge attributes
#> 
#> Network adjacency matrix:
#>   1 2 3 4 5
#> 1 0 1 1 1 1
#> 2 1 0 0 1 1
#> 3 1 0 0 0 1
#> 4 1 1 0 0 1
#> 5 1 1 1 1 0

# networks from data frames ===========================================================
#* simple networks ====================================================================
simple_edge_df <- data.frame(
  from = c("b", "c", "c", "d", "a"),
  to = c("a", "b", "a", "a", "b"),
  weight = c(1, 1, 2, 2, 3),
  stringsAsFactors = FALSE
)
simple_edge_df
#>   from to weight
#> 1    b  a      1
#> 2    c  b      1
#> 3    c  a      2
#> 4    d  a      2
#> 5    a  b      3

as.network(simple_edge_df)
#>  Network attributes:
#>   vertices = 4 
#>   directed = TRUE 
#>   hyper = FALSE 
#>   loops = FALSE 
#>   multiple = FALSE 
#>   bipartite = FALSE 
#>   total edges= 5 
#>     missing edges= 0 
#>     non-missing edges= 5 
#> 
#>  Vertex attribute names: 
#>     vertex.names 
#> 
#>  Edge attribute names: 
#>     weight 

# simple networks with vertices =======================================================
simple_vertex_df <- data.frame(
  name = letters[1:5],
  residence = c("urban", "rural", "suburban", "suburban", "rural"),
  stringsAsFactors = FALSE
)
simple_vertex_df
#>   name residence
#> 1    a     urban
#> 2    b     rural
#> 3    c  suburban
#> 4    d  suburban
#> 5    e     rural

as.network(simple_edge_df, vertices = simple_vertex_df)
#>  Network attributes:
#>   vertices = 5 
#>   directed = TRUE 
#>   hyper = FALSE 
#>   loops = FALSE 
#>   multiple = FALSE 
#>   bipartite = FALSE 
#>   total edges= 5 
#>     missing edges= 0 
#>     non-missing edges= 5 
#> 
#>  Vertex attribute names: 
#>     residence vertex.names 
#> 
#>  Edge attribute names: 
#>     weight 

as.network(simple_edge_df,
  directed = FALSE, vertices = simple_vertex_df,
  multiple = TRUE
)
#>  Network attributes:
#>   vertices = 5 
#>   directed = FALSE 
#>   hyper = FALSE 
#>   loops = FALSE 
#>   multiple = TRUE 
#>   bipartite = FALSE 
#>   total edges= 5 
#>     missing edges= 0 
#>     non-missing edges= 5 
#> 
#>  Vertex attribute names: 
#>     residence vertex.names 
#> 
#>  Edge attribute names: 
#>     weight 

#* splitting multiplex data frames into multiple networks =============================
simple_edge_df$relationship <- c(rep("friends", 3), rep("colleagues", 2))
simple_edge_df
#>   from to weight relationship
#> 1    b  a      1      friends
#> 2    c  b      1      friends
#> 3    c  a      2      friends
#> 4    d  a      2   colleagues
#> 5    a  b      3   colleagues

lapply(split(simple_edge_df, f = simple_edge_df$relationship),
  as.network,
  vertices = simple_vertex_df
)
#> $colleagues
#>  Network attributes:
#>   vertices = 5 
#>   directed = TRUE 
#>   hyper = FALSE 
#>   loops = FALSE 
#>   multiple = FALSE 
#>   bipartite = FALSE 
#>   total edges= 2 
#>     missing edges= 0 
#>     non-missing edges= 2 
#> 
#>  Vertex attribute names: 
#>     residence vertex.names 
#> 
#>  Edge attribute names: 
#>     relationship weight 
#> 
#> $friends
#>  Network attributes:
#>   vertices = 5 
#>   directed = TRUE 
#>   hyper = FALSE 
#>   loops = FALSE 
#>   multiple = FALSE 
#>   bipartite = FALSE 
#>   total edges= 3 
#>     missing edges= 0 
#>     non-missing edges= 3 
#> 
#>  Vertex attribute names: 
#>     residence vertex.names 
#> 
#>  Edge attribute names: 
#>     relationship weight 
#> 

#* bipartite networks without isolates ================================================
bip_edge_df <- data.frame(
  actor = c("a", "a", "b", "b", "c", "d", "d", "e"),
  event = c("e1", "e2", "e1", "e3", "e3", "e2", "e3", "e1"),
  actor_enjoyed_event = rep(c(TRUE, FALSE), 4),
  stringsAsFactors = FALSE
)
bip_edge_df
#>   actor event actor_enjoyed_event
#> 1     a    e1                TRUE
#> 2     a    e2               FALSE
#> 3     b    e1                TRUE
#> 4     b    e3               FALSE
#> 5     c    e3                TRUE
#> 6     d    e2               FALSE
#> 7     d    e3                TRUE
#> 8     e    e1               FALSE

bip_node_df <- data.frame(
  node_id = c("a", "e1", "b", "e2", "c", "e3", "d", "e"),
  node_type = c(
    "person", "event", "person", "event", "person",
    "event", "person", "person"
  ),
  color = c(
    "red", "blue", "red", "blue", "red", "blue",
    "red", "red"
  ),
  stringsAsFactors = FALSE
)
bip_node_df
#>   node_id node_type color
#> 1       a    person   red
#> 2      e1     event  blue
#> 3       b    person   red
#> 4      e2     event  blue
#> 5       c    person   red
#> 6      e3     event  blue
#> 7       d    person   red
#> 8       e    person   red

as.network(bip_edge_df, directed = FALSE, bipartite = TRUE)
#>  Network attributes:
#>   vertices = 8 
#>   directed = FALSE 
#>   hyper = FALSE 
#>   loops = FALSE 
#>   multiple = FALSE 
#>   bipartite = 5 
#>   total edges= 8 
#>     missing edges= 0 
#>     non-missing edges= 8 
#> 
#>  Vertex attribute names: 
#>     vertex.names 
#> 
#>  Edge attribute names: 
#>     actor_enjoyed_event 
as.network(bip_edge_df, directed = FALSE, vertices = bip_node_df, bipartite = TRUE)
#> Warning: `vertices` were not provided in the order required for bipartite networks. Reordering.
#> 
#> This is the first and last time you will be warned during this session.
#>  Network attributes:
#>   vertices = 8 
#>   directed = FALSE 
#>   hyper = FALSE 
#>   loops = FALSE 
#>   multiple = FALSE 
#>   bipartite = 5 
#>   total edges= 8 
#>     missing edges= 0 
#>     non-missing edges= 8 
#> 
#>  Vertex attribute names: 
#>     color node_type vertex.names 
#> 
#>  Edge attribute names: 
#>     actor_enjoyed_event 

#* bipartite networks with isolates ===================================================
bip_nodes_with_isolates <- rbind(
  bip_node_df,
  data.frame(
    node_id = c("f", "e4"),
    node_type = c("person", "event"),
    color = c("red", "blue"),
    stringsAsFactors = FALSE
  )
)
# indicate which vertices are actors via a column named `"is_actor"`
bip_nodes_with_isolates$is_actor <- bip_nodes_with_isolates$node_type == "person"
bip_nodes_with_isolates
#>    node_id node_type color is_actor
#> 1        a    person   red     TRUE
#> 2       e1     event  blue    FALSE
#> 3        b    person   red     TRUE
#> 4       e2     event  blue    FALSE
#> 5        c    person   red     TRUE
#> 6       e3     event  blue    FALSE
#> 7        d    person   red     TRUE
#> 8        e    person   red     TRUE
#> 9        f    person   red     TRUE
#> 10      e4     event  blue    FALSE

as.network(bip_edge_df,
  directed = FALSE, vertices = bip_nodes_with_isolates,
  bipartite = TRUE
)
#>  Network attributes:
#>   vertices = 10 
#>   directed = FALSE 
#>   hyper = FALSE 
#>   loops = FALSE 
#>   multiple = FALSE 
#>   bipartite = 5 
#>   total edges= 8 
#>     missing edges= 0 
#>     non-missing edges= 8 
#> 
#>  Vertex attribute names: 
#>     color is_actor node_type vertex.names 
#> 
#>  Edge attribute names: 
#>     actor_enjoyed_event 

#* hyper networks from data frames ====================================================
hyper_edge_df <- data.frame(
  from = c("a/b", "b/c", "c/d/e", "d/e"),
  to = c("c/d", "a/b/e/d", "a/b", "d/e"),
  time = 1:4,
  stringsAsFactors = FALSE
)
tibble::as_tibble(hyper_edge_df)
#> # A tibble: 4 × 3
#>   from  to       time
#>   <chr> <chr>   <int>
#> 1 a/b   c/d         1
#> 2 b/c   a/b/e/d     2
#> 3 c/d/e a/b         3
#> 4 d/e   d/e         4

# split "from" and "to" at `"/"`, coercing them to list columns
hyper_edge_df$from <- strsplit(hyper_edge_df$from, split = "/")
hyper_edge_df$to <- strsplit(hyper_edge_df$to, split = "/")
tibble::as_tibble(hyper_edge_df)
#> # A tibble: 4 × 3
#>   from      to         time
#>   <list>    <list>    <int>
#> 1 <chr [2]> <chr [2]>     1
#> 2 <chr [2]> <chr [4]>     2
#> 3 <chr [3]> <chr [2]>     3
#> 4 <chr [2]> <chr [2]>     4

as.network(hyper_edge_df,
  directed = FALSE, vertices = simple_vertex_df,
  hyper = TRUE, loops = TRUE
)
#>  Network attributes:
#>   vertices = 5 
#>   directed = FALSE 
#>   hyper = TRUE 
#>   loops = TRUE 
#>   multiple = FALSE 
#>   bipartite = FALSE 
#>   total edges= 4 
#>     missing edges= 0 
#>     non-missing edges= 4 
#> 
#>  Vertex attribute names: 
#>     residence vertex.names 
#> 
#>  Edge attribute names: 
#>     time 

# convert network objects back to data frames =========================================
simple_g <- as.network(simple_edge_df, vertices = simple_vertex_df)
as.data.frame(simple_g)
#>   .tail .head weight relationship
#> 1     b     a      1      friends
#> 2     c     b      1      friends
#> 3     c     a      2      friends
#> 4     d     a      2   colleagues
#> 5     a     b      3   colleagues
as.data.frame(simple_g, unit = "vertices")
#>   vertex.names residence
#> 1            a     urban
#> 2            b     rural
#> 3            c  suburban
#> 4            d  suburban
#> 5            e     rural

bip_g <- as.network(bip_edge_df,
  directed = FALSE, vertices = bip_node_df,
  bipartite = TRUE
)
as.data.frame(bip_g)
#>   .tail .head actor_enjoyed_event
#> 1     a    e1                TRUE
#> 2     a    e2               FALSE
#> 3     b    e1                TRUE
#> 4     b    e3               FALSE
#> 5     c    e3                TRUE
#> 6     d    e2               FALSE
#> 7     d    e3                TRUE
#> 8     e    e1               FALSE
as.data.frame(bip_g, unit = "vertices")
#>   vertex.names node_type color
#> 1            a    person   red
#> 2            b    person   red
#> 3            c    person   red
#> 4            d    person   red
#> 5            e    person   red
#> 6           e1     event  blue
#> 7           e2     event  blue
#> 8           e3     event  blue

hyper_g <- as.network(hyper_edge_df,
  directed = FALSE, vertices = simple_vertex_df,
  hyper = TRUE, loops = TRUE
)
as.data.frame(hyper_g)
#>     .tail      .head time
#> 1    a, b       c, d    1
#> 2    b, c a, b, e, d    2
#> 3 c, d, e       a, b    3
#> 4    d, e       d, e    4
as.data.frame(hyper_g, unit = "vertices")
#>   vertex.names residence
#> 1            a     urban
#> 2            b     rural
#> 3            c  suburban
#> 4            d  suburban
#> 5            e     rural