@@ -752,45 +752,56 @@ random.graph.game <- erdos.renyi.game
752752# ' It is often useful to create a graph with given vertex degrees. This function
753753# ' creates such a graph in a randomized manner.
754754# '
755- # ' The \dQuote{simple} method connects the out-stubs of the edges (undirected
756- # ' graphs) or the out-stubs and in-stubs (directed graphs) together. This way
757- # ' loop edges and also multiple edges may be generated. This method is not
758- # ' adequate if one needs to generate simple graphs with a given degree
759- # ' sequence. The multiple and loop edges can be deleted, but then the degree
760- # ' sequence is distorted and there is nothing to ensure that the graphs are
761- # ' sampled uniformly.
762- # '
763- # ' The \dQuote{simple.no.multiple} method is similar to \dQuote{simple}, but
764- # ' tries to avoid multiple and loop edges and restarts the generation from
765- # ' scratch if it gets stuck. It is not guaranteed to sample uniformly from the
766- # ' space of all possible graphs with the given sequence, but it is relatively
767- # ' fast and it will eventually succeed if the provided degree sequence is
768- # ' graphical, but there is no upper bound on the number of iterations.
769- # '
770- # ' The \dQuote{simple.no.multiple.uniform} method is a variant of
771- # ' \dQuote{simple.no.multiple} with the added benefit of sampling uniformly
772- # ' from the set of all possible simple graphs with the given degree sequence.
773- # ' Ensuring uniformity has some performance implications, though.
774- # '
775- # ' The \dQuote{vl} method is a more sophisticated generator. The algorithm and
776- # ' the implementation was done by Fabien Viger and Matthieu Latapy. This
777- # ' generator always generates undirected, connected simple graphs, it is an
778- # ' error to pass the `in.deg` argument to it. The algorithm relies on
779- # ' first creating an initial (possibly unconnected) simple undirected graph
780- # ' with the given degree sequence (if this is possible at all). Then some
781- # ' rewiring is done to make the graph connected. Finally a Monte-Carlo
782- # ' algorithm is used to randomize the graph. The \dQuote{vl} samples from the
783- # ' undirected, connected simple graphs uniformly.
755+ # ' The \dQuote{configuration} method (formerly called "simple") implements the
756+ # ' configuration model. For undirected graphs, it puts all vertex IDs in a bag
757+ # ' such that the multiplicity of a vertex in the bag is the same as its degree.
758+ # ' Then it draws pairs from the bag until the bag becomes empty. This method may
759+ # ' generate both loop (self) edges and multiple edges. For directed graphs,
760+ # ' the algorithm is basically the same, but two separate bags are used
761+ # ' for the in- and out-degrees. Undirected graphs are generated
762+ # ' with probability proportional to \eqn{(\prod_{i<j} A_{ij} ! \prod_i A_{ii} !!)^{-1}},
763+ # ' where A denotes the adjacency matrix and !! denotes the double factorial.
764+ # ' Here A is assumed to have twice the number of self-loops on its diagonal.
765+ # ' The corresponding expression for directed graphs is \eqn{(\prod_{i,j} A_{ij}!)^{-1}}.
766+ # ' Thus the probability of all simple graphs
767+ # ' (which only have 0s and 1s in the adjacency matrix)
768+ # ' is the same, while that of non-simple ones depends on their edge and
769+ # ' self-loop multiplicities.
770+ # '
771+ # ' The \dQuote{fast.heur.simple} method (formerly called "simple.no.multiple")
772+ # ' generates simple graphs.
773+ # ' It is similar to \dQuote{configuration} but tries to avoid multiple and
774+ # ' loop edges and restarts the generation from scratch if it gets stuck.
775+ # ' It can generate all simple realizations of a degree sequence,
776+ # ' but it is not guaranteed to sample them uniformly.
777+ # ' This method is relatively fast and it will eventually succeed
778+ # ' if the provided degree sequence is graphical, but there is no upper bound on
779+ # ' the number of iterations.
780+ # '
781+ # ' The \dQuote{configuration.simple} method (formerly called "simple.no.multiple.uniform")
782+ # ' is
783+ # ' identical to \dQuote{configuration}, but if the generated graph is not simple,
784+ # ' it rejects it and re-starts the generation.
785+ # ' It generates all simple graphs with the same probability.
786+ # '
787+ # ' The \dQuote{vl} method samples undirected connected graphs approximately uniformly.
788+ # ' It is a Monte Carlo method based on degree-preserving edge switches.
789+ # ' This generator should be favoured if undirected and connected graphs are to be
790+ # ' generated and execution time is not a concern. igraph uses
791+ # ' the original implementation of Fabien Viger; for the algorithm, see
792+ # ' <https://www-complexnetworks.lip6.fr/~latapy/FV/generation.html>
793+ # ' and the paper <https://arxiv.org/abs/cs/0502085>.
794+ # '
795+ # ' The \dQuote{edge.switching.simple} is an MCMC sampler based on
796+ # ' degree-preserving edge switches. It generates simple undirected or directed graphs.
784797# '
785798# ' @param out.deg Numeric vector, the sequence of degrees (for undirected
786799# ' graphs) or out-degrees (for directed graphs). For undirected graphs its sum
787800# ' should be even. For directed graphs its sum should be the same as the sum of
788801# ' `in.deg`.
789802# ' @param in.deg For directed graph, the in-degree sequence. By default this is
790803# ' `NULL` and an undirected graph is created.
791- # ' @param method Character, the method for generating the graph. Right now the
792- # ' \dQuote{simple}, \dQuote{simple.no.multiple} and \dQuote{vl} methods are
793- # ' implemented.
804+ # ' @param method Character, the method for generating the graph. See Details.
794805# ' @return The new graph object.
795806# ' @author Gabor Csardi \email{csardi.gabor@@gmail.com}
796807# ' @seealso
@@ -909,13 +920,31 @@ random.graph.game <- erdos.renyi.game
909920# ' all(degree(powerlaw_vl_graph) == powerlaw_degrees)
910921# '
911922sample_degseq <- function (out.deg , in .deg = NULL ,
912- method = c(" simple " " vl" " simple.no.multiple " " simple.no.multiple.uniform "
923+ method = c(" configuration " " vl" " fast.heur.simple " " configuration. simple" , " edge.switching.simple "
913924 method <- igraph.match.arg(method )
925+
926+ if (method == " simple"
927+ lifecycle :: deprecate_warn(" 2.0.4" " sample_degseq(method = 'must be configuration instead of simple')"
928+ method <- " configuration"
929+ }
930+
931+ if (method == " simple.no.multiple"
932+ lifecycle :: deprecate_warn(" 2.0.4" " sample_degseq(method = 'must be fast.heur.simple instead of simple.no.multiple')"
933+ method <- " fast.heur.simple"
934+ }
935+
936+ if (method == " simple.no.multiple.uniform"
937+ lifecycle :: deprecate_warn(" 2.0.4" " sample_degseq(method = 'must be configuration.simple instead of simple.no.multiple.uniform')"
938+ method <- " configuration.simple"
939+ }
940+
941+ # numbers from https://github.com/igraph/igraph/blob/640083c88bf85fd322ff7b748b9b4e16ebe32aa2/include/igraph_constants.h#L94
914942 method1 <- switch (method ,
915- " simple " = 0 ,
943+ " configuration " = 0 ,
916944 " vl" = 1 ,
917- " simple.no.multiple" = 2 ,
918- " simple.no.multiple.uniform" = 3
945+ " fast.heur.simple" = 2 ,
946+ " configuration.simple" = 3 ,
947+ " edge.switching.simple" = 4
919948 )
920949 if (! is.null(in .deg )) {
921950 in .deg <- as.numeric(in .deg )
0 commit comments