Create a Standard Graph — create.graph • dgraphs

Construct a standard topology or a simple geometric graph. All types return a dgraph() and use compact, 1-based adjacency indices. type is required; type names and names in ... must match exactly.

Usage

create.graph(type, n = NULL, ..., labels = NULL)

Arguments

type: Graph type: "empty", "complete", "chain", "cycle", "complete_bipartite", "star", "random" or "circle".
n: Number of vertices. Required except when inferred from chain x, bipartite sizes or star arms. If supplied alongside those arguments, it must agree. Empty graphs permit zero vertices; chains require at least two, cycles and circles at least three, and other types at least one.
...: Named type-specific arguments, described below. Unknown, duplicated, unnamed and irrelevant arguments error.
labels: Optional unique, nonmissing character or numeric vertex labels, one per vertex. Labels name adjacency lists and are stored in metadata$labels; they never change adjacency indices. For chains with x, supply labels in the original input order.

Value

A dgraph with one final stage and construction information in metadata, including type. Inspect it with graph.adjacency(), graph.lengths(), graph.edges() and graph.order().

Types and arguments

empty, complete, cycle: Only n and labels. These return topology without stored lengths. A cycle closes a chain with one edge.
chain: span = 1 connects up to span positions on each side, giving at most 2 * span neighbors. It must be an integer from 1 to n - 1; it does not use the nearest-neighbor meaning of k. Optional finite numeric x orders vertices by coordinate (ties by input position) and supplies absolute coordinate differences as lengths. Without x, lengths are one. Optional vector y requires x and is reordered with it. Metadata contains order (sorted-to-input indices), x.sorted and y.sorted.
complete_bipartite: Required sizes, two positive integers. All pairs across the two parts are connected; there are no within-part edges or stored lengths. Vertices in the first part come first.
star: Required arms, at least two positive integer edge counts. Chains of those lengths share vertex 1 as their center. Thus n = 1 + sum(arms); all-one arms give an ordinary star. Vertices are numbered along successive arms. No lengths are stored.
circle: sampling = "uniform" or "random" (default), edge.length = "arc" (default) or "chord", and optional seed. Vertices are ordered by angle on the unit circle and consecutive vertices, including last-to-first, are connected. Arc lengths measure the shorter unit-circle arc between endpoints, even when the gap in the sampling order exceeds pi. Chords are Euclidean distances. Metadata contains angles (radians) and coordinates (x/y columns).
random: Required finite mean.degree, connected = TRUE, and optional seed. The edge count is floor(n * mean.degree / 2); 0 <= mean.degree <= n - 1. If connected, this count must be at least n - 1. A randomly ordered growing tree is built first, then a uniform subset of remaining pairs is added. This is not uniform sampling over connected graphs or spanning trees. If disconnected graphs are allowed, a uniform subset of all pairs is sampled. Each undirected edge receives one independent length uniform between 0.5 and 1.5. Candidate-pair storage is quadratic in n; this constructor is intended for small examples. Metadata records requested and realized mean degrees and connectivity.

Random numbers

For random and circle, seed = NULL uses and advances the caller's current random stream. An explicit nonnegative integer seed makes the call reproducible under the current RNG kind and restores the caller's RNG state afterwards, including an initially absent state. Uniform circle sampling consumes no random numbers. The richer geometry sampling API has its own seed/state continuation contract; see sample.synthetic.geometry().

Examples

graph.order(create.graph("empty", n = 4))
#> [1] 4
graph.edges(create.graph("complete", n = 3))
#>   from to
#> 1    1  2
#> 2    1  3
#> 3    2  3
chain <- create.graph("chain", x = c(3, 1, 2), span = 1,
                      labels = c("third", "first", "second"))
graph.adjacency(chain)
#> $first
#> [1] 2
#> 
#> $second
#> [1] 1 3
#> 
#> $third
#> [1] 2
#> 
graph.lengths(chain)
#> $first
#> [1] 1
#> 
#> $second
#> [1] 1 1
#> 
#> $third
#> [1] 1
#> 
graph.edges(create.graph("cycle", n = 4))
#>   from to
#> 1    1  2
#> 2    1  4
#> 3    2  3
#> 4    3  4
graph.order(create.graph("complete_bipartite", sizes = c(2, 3)))
#> [1] 5
graph.order(create.graph("star", arms = c(2, 3, 1)))
#> [1] 7
graph.edges(create.graph("random", n = 6, mean.degree = 2, seed = 10))
#>   from to    length
#> 1    1  3 0.5519033
#> 2    1  5 1.3647212
#> 3    2  3 0.7641777
#> 4    2  6 0.8987907
#> 5    3  5 1.1153524
#> 6    4  6 1.3361341
circle <- create.graph("circle", n = 8, sampling = "uniform",
                       edge.length = "chord")
circle$metadata$coordinates
#>                  x             y
#> [1,]  1.000000e+00  0.000000e+00
#> [2,]  7.071068e-01  7.071068e-01
#> [3,]  6.123234e-17  1.000000e+00
#> [4,] -7.071068e-01  7.071068e-01
#> [5,] -1.000000e+00  1.224647e-16
#> [6,] -7.071068e-01 -7.071068e-01
#> [7,] -1.836970e-16 -1.000000e+00
#> [8,]  7.071068e-01 -7.071068e-01