C and R docs for stochastic block model generator (#2).

doc/Makefile.am

@@ -80,13 +80,15 @@ generators.xml: generators.xxml \
 		$(SRCDIR)/forestfire.c \
 		$(SRCDIR)/games.c \
 		$(SRCDIR)/structure_generators.c \
-		$(SRCDIR)/structural_properties.c
+		$(SRCDIR)/structural_properties.c \
+		$(SRCDIR)/sbm.c
 	$(DOXROX) -t $< -e $(REGEX) -o $@ \
 	$(SRCDIR)/atlas.c \
 	$(SRCDIR)/forestfire.c \
 	$(SRCDIR)/games.c \
 	$(SRCDIR)/structure_generators.c \
-	$(SRCDIR)/structural_properties.c
+	$(SRCDIR)/structural_properties.c \
+	$(SRCDIR)/sbm.c
 
 structural.xml: structural.xxml $(SRCDIR)/structural_properties.c \
 		$(SRCDIR)/spanning_trees.c \

doc/generators.xxml

@@ -55,6 +55,7 @@
 <!---doxrox-include igraph_lastcit_game -->
 <!-- doxrox-include igraph_cited_type_game -->
 <!-- doxrox-include igraph_citing_cited_type_game -->
+<!-- doxrox-include igraph_sbm_game -->
 </section>
 
 </chapter>

interfaces/R/igraph/man/sbm.game.Rd

@@ -0,0 +1,43 @@
+\name{sbm.game}
+\alias{sbm.game}
+\concept{Stochastic block model}
+\concept{Random graph model}
+\title{Sample stochastic block model}
+\description{Sampling from the stochastic block model of networks}
+\usage{
+sbm.game (n, pref.matrix, block.sizes, directed = FALSE, loops = FALSE) 
+}
+\arguments{
+  \item{n}{Number of vertices in the graph.}
+  \item{pref.matrix}{The matrix giving the Bernoulli rates.
+    This is a \eqn{K\times K}{KxK} matrix, where \eqn{K} is the number
+    of groups. The probability of creating an edge between vertices from
+    groups \eqn{i} and \eqn{j} is given by element \eqn{(i,j)}. For
+    undirected graphs, this matrix must be symmetric.}
+  \item{block.sizes}{Numeric vector giving the number of vertices in
+    each group. The sum of the vector must match the number of vertices.}
+  \item{directed}{Logical scalar, whether to generate a directed
+    graph.}
+  \item{loops}{Logical scalar, whether self-loops are allowed in the
+    graph.}
+}
+\details{
+  This function samples graphs from a stochastic block
+  model by (doing the equivalent of) Bernoulli
+  trials for each potential edge with the probabilities
+  given by the Bernoulli rate matrix, \code{pref.matrix}.
+}
+\value{An igraph graph.}
+\references{
+  Faust, K., & Wasserman, S. (1992a). Blockmodels:
+  Interpretation and evaluation. \emph{Social Networks}, 14, 5-–61.
+}
+\author{Gabor Csardi \email{csardi.gabor@gmail.com}}
+\seealso{\code{\link{random.graph.game}}}
+\examples{
+## Two groups with not only few connection between groups
+pm <- cbind( c(.1, .001), c(.001, .05) )
+g <- sbm.game(1000, pref.matrix=pm, block.sizes=c(300,700))
+g
+}
+\keyword{graphs}

src/sbm.c

@@ -31,6 +31,38 @@
 
 /**
  * \function igraph_sbm_game
+ * Sample from a stochastic block model
+ *
+ * This function samples graphs from a stochastic block
+ * model by (doing the equivalent of) Bernoulli
+ * trials for each potential edge with the probabilities
+ * given by the Bernoulli rate matrix, \p pref_matrix.
+ * See Faust, K., & Wasserman, S. (1992a). Blockmodels:
+ * Interpretation and evaluation. Social Networks, 14, 5-–61.
+ *
+ * </para><para>
+ * The order of the vertex ids in the generated graph corresponds to
+ * the \p block_sizes argument.
+ *
+ * \param graph The output graph.
+ * \param n Number of vertices.
+ * \param pref_matrix The matrix giving the Bernoulli rates.
+ *     This is a KxK matrix, where K is the number of groups.
+ *     The probability of creating an edge between vertices from
+ *     groups i and j is given by element (i,j).
+ * \param block_sizes An integer vector giving the number of
+ *     vertices in each group.
+ * \param directed Boolean, whether to create a directed graph. If
+ *     this argument is false, then \p pref_matrix must be symmetric.
+ * \param loops Boolean, whether to create self-loops.
+ * \return Error code.
+ *
+ * Time complexity: O(|V|+|E|+K^2), where |V| is the number of
+ * vertices, |E| is the number of edges, and K is the number of
+ * groups.
+ *
+ * \sa \ref igraph_erdos_renyi_game() for a simple Bernoulli graph.
+ *
  */
 
 int igraph_sbm_game(igraph_t *graph, igraph_integer_t n,