realize_degseq: Creating a graph from a given degree sequence, deterministically

Description

It is often useful to create a graph with given vertex degrees. This function creates such a graph in a deterministic manner.

Usage

realize_degseq(
  out.deg,
  in.deg = NULL,
  allowed.edge.types = c("simple", "loops", "multi", "all"),
  method = c("smallest", "largest", "index")
)

Arguments

out.deg

Numeric vector, the sequence of degrees (for undirected graphs) or out-degrees (for directed graphs). For undirected graphs its sum should be even. For directed graphs its sum should be the same as the sum of in.deg.

in.deg

For directed graph, the in-degree sequence. By default this is NULL and an undirected graph is created.

allowed.edge.types

Character, specifies the types of allowed edges. “simple” allows simple graphs only (no loops, no multiple edges). “multiple” allows multiple edges but disallows loop. “loops” allows loop edges but disallows multiple edges (currently unimplemented). “all” allows all types of edges. The default is “simple”.

method

Character, the method for generating the graph; see above.

Value

The new graph object.

Details

Simple undirected graphs are constructed using the Havel-Hakimi algorithm (undirected case), or the analogous Kleitman-Wang algorithm (directed case). These algorithms work by choosing an arbitrary vertex and connecting all its stubs to other vertices. This step is repeated until all degrees have been connected up.

The ‘method’ argument controls in which order the vertices are selected during the course of the algorithm.

The “smallest” method selects the vertex with the smallest remaining degree. The result is usually a graph with high negative degree assortativity. In the undirected case, this method is guaranteed to generate a connected graph, regardless of whether multi-edges are allowed, provided that a connected realization exists. In the directed case it tends to generate weakly connected graphs, but this is not guaranteed. This is the default method.

The “largest” method selects the vertex with the largest remaining degree. The result is usually a graph with high positive degree assortativity, and is often disconnected.

The “index” method selects the vertices in order of their index.

Examples

Run this code

# NOT RUN {
g <- realize_degseq(rep(2,100))
degree(g)
is_simple(g)

## Exponential degree distribution, with high positive assortativity.
## Loop and multiple edges are explicitly allowed.
## Note that we correct the degree sequence if its sum is odd.
degs <- sample(1:100, 100, replace=TRUE, prob=exp(-0.5*(1:100)))
if (sum(degs) %% 2 != 0) { degs[1] <- degs[1] + 1 }
g4 <- realize_degseq(degs, method="largest", allowed.edge.types="all")
all(degree(g4) == degs)

## Power-law degree distribution, no loops allowed but multiple edges
## are okay.
## Note that we correct the degree sequence if its sum is odd.
degs <- sample(1:100, 100, replace=TRUE, prob=(1:100)^-2)
if (sum(degs) %% 2 != 0) { degs[1] <- degs[1] + 1 }
g5 <- realize_degseq(degs, allowed.edge.types="multi")
all(degree(g5) == degs)
# }