Internal functions and generics for mmsbm package

Description

These are various utilities and generic methods used by the main package function.

Usage

approxB(y, d_id, pi_mat, directed = TRUE)

getZ(pi_mat)

alphaLBound(par, tot_nodes, c_t, x_t, s_mat, t_id, var_beta, mu_beta)

alphaGrad(par, tot_nodes, c_t, x_t, s_mat, t_id, var_beta, mu_beta)

.cbind.fill(...)

.scaleVars(x, keep_const = TRUE)

.transf_muvar(orig, is_var, is_array, des.mat, nblock = NULL, nstate = NULL)

.bar.legend(colPalette, range)

.mpower(mat, p)

.findPerm(block_list, target_mat = NULL, use_perms = TRUE)

.transf(mat)

.compute.alpha(X, beta)

.vcovBeta(
  all_phi,
  beta_coef,
  n.sim,
  n.blk,
  n.hmm,
  n.nodes,
  n.periods,
  mu.beta,
  var.beta,
  est_kappa,
  t_id_n,
  X
)

.e.pi(alpha_list, kappa, C_mat = NULL)

.initPi(
  soc_mats,
  dyads,
  edges,
  nodes_pp,
  dyads_pp,
  n.blocks,
  periods,
  directed,
  ctrl
)

Arguments

Details

These functions are meant for internal use only.

Value

See individual return section for each function:

.cbind.fill

Matrix of cbind'ed elements in ..., with missing values in each vector filled with NA.

.mpower

Matrix; the result of raising mat to the p power.

.findPerm

List of permuted blockmodel matrices.

.transf

Matrix with transformed mixed-membership vectors along its rows, s.t. no element is equal to 0.0 or 1.0.

.compute.alpha

List of predicted alpha matrices, one element per HMM state.

.e.pi

Matrix of predicted mixed-membership vectors along its rows, with expectation computed over marginal distribution over HMM states for each time period.

.missing

Transformed data.frame with missing values list-wise deleted, or expanded with missing indicator variables.

.createSocioB

List of sociomatrices.

.vertboot2

List of bootstrapped sociomatrices.

Author(s)

Santiago Olivella (olivella@unc.edu), Adeline Lo (aylo@wisc.edu), Tyler Pratt (tyler.pratt@yale.edu), Kosuke Imai (imai@harvard.edu)

Extract Regression Coefficients for a Fitted mmsbm Object

Description

Extract Regression Coefficients for a Fitted mmsbm Object

Usage

## S3 method for class 'mmsbm'
coef(object, param = "All", ...)

Arguments

Value

For param="DyadCoef", a numeric vector. For param="MonadCoef", an array with HMM states along the third dimension. For param="All", named list of individual return components.

Author(s)

Santiago Olivella (olivella@unc.edu), Adeline Lo (aylo@wisc.edu), Tyler Pratt (tyler.pratt@yale.edu), Kosuke Imai (imai@harvard.edu)

Examples

library(NetMix)
## Load datasets
data("lazega_dyadic")
data("lazega_monadic")
## Estimate model with 2 groups
lazega_mmsbm <- mmsbm(SocializeWith ~ Coworkers,
                      ~  School,
                      senderID = "Lawyer1",
                      receiverID = "Lawyer2",
                      nodeID = "Lawyer",
                      data.dyad = lazega_dyadic,
                      data.monad = lazega_monadic,
                      n.blocks = 2,
                      mmsbm.control = list(seed = 123,
                                           conv_tol = 1e-2,
                                           hessian = FALSE))

coef(lazega_mmsbm, "MonadCoef")

Generate estimated monadic covariate effects for estimated mmsbm model

Description

The function estimates the effect of a shift in monadic covariate values on the probability of edge formation in the network.

Usage

covFX(fm, cov, shift, max.val = FALSE)

Arguments

Value

List with named components:

Overall Avg. Effect

Overall average effect of the covariate shift on the predicted probability of edge formation.

Avg. Effect by Time

Vector of average effects of the covariate shift on the predicted probability of edge formation for each time period.

Avg. Effect by Node

Vector of average effects of the covariate shift on the predicted probability of edge formation for each node.

Avg. Effect by Dyad

Vector of average effects of the covariate shift on the predicted probability of edge formation for each node dyad.

Avg. Effect Dyad-Time

Vector of estimated effects of the covariate shift on the predicted probability of edge formation for each node dyad-time unit.

Author(s)

Santiago Olivella (olivella@unc.edu), Adeline Lo (aylo@wisc.edu), Tyler Pratt (tyler.pratt@yale.edu), Kosuke Imai (imai@harvard.edu)

Examples

library(NetMix)
## Load datasets
data("lazega_dyadic")
data("lazega_monadic")
## Estimate model with 2 groups
lazega_mmsbm <- mmsbm(SocializeWith ~ Coworkers,
                      ~  Age,
                      senderID = "Lawyer1",
                      receiverID = "Lawyer2",
                      nodeID = "Lawyer",
                      data.dyad = lazega_dyadic,
                      data.monad = lazega_monadic,
                      n.blocks = 2,
                      mmsbm.control = list(seed = 123, 
                                           conv_tol = 1e-2, 
                                           hessian = FALSE))

## Compute effect of decreasing every lawyers' age by 10 years
fx_list <- covFX(lazega_mmsbm, cov = "Age", shift = -10)
fx_list[["Overall Avg. Effect of Age"]]

Posterior predictive checks using structural network charactericts

Description

The function generates a variety of plots that serve as posterior predictive checks on the goodness of fit of a fitted mmsbm object.

Usage

gof(x, ...)

## S3 method for class 'mmsbm'
gof(
  x,
  gof_stat = c("Geodesics", "Degree"),
  level = 0.95,
  samples = 50,
  new.data.dyad = NULL,
  new.data.monad = NULL,
  seed = NULL,
  ...
)

Arguments

Details

Goodness of fit of network models has typically been established by evaluating how the structural characteristics of predicted networks compare to those of the observed network. When estimated in a Bayesian framework, this approach is equivalent to conducting posterior preditive checks on these structural quantities of interest. When new.data.dyad and/or new.data.monad are passed that are different from those used in estimation, this is equivalent to conducting posterior predictive checks out-of-sample.

The set of structural features used to determine goodness of fit is somewhat arbitrary, and chosen mostly to incorporate various first order, second order, and (to the extent possible) third-order characteristics of the network. "Geodesics" focuses on the distribution over observed and predicted geodesic distances between nodes; "Indegree" and "Outdegree" focuses on the distribution over incoming and outgoing connections per node; "3-motifs" focus on a distribution over possible connectivity patterns between triads (i.e. the triadic census); "Dyad Shared Partners" focuses on the distribution over the number of shared partners between any two dayds; "Edge Shared Partners" is similarly defined, but w.r.t. edges, rather than dyads; and finally "Incoming K-stars" focuses on a frequency distribution over stars with k=1,... spokes.

Obtaining samples of the last three structural features can be very computationally expensive, and is discouraged on networks with more than 50 nodes.

Value

A ggplot object.

Author(s)

Santiago Olivella (olivella@unc.edu), Adeline Lo (aylo@wisc.edu), Tyler Pratt (tyler.pratt@yale.edu), Kosuke Imai (imai@harvard.edu)

Examples

library(NetMix)
## Load datasets
data("lazega_dyadic")
data("lazega_monadic")

## Estimate model with 2 groups
lazega_mmsbm <- mmsbm(SocializeWith ~ Coworkers,
                      senderID = "Lawyer1",
                      receiverID = "Lawyer2",
                      nodeID = "Lawyer",
                      data.dyad = lazega_dyadic,
                      data.monad = lazega_monadic,
                      n.blocks = 2,
                      mmsbm.control = list(seed = 123,
                                           conv_tol = 1e-2,
                                           hessian = FALSE))

## Plot observed (red) and simulated (gray) distributions over 
## indegrees
## (typically a larger number of samples would be taken) 
## (strictly requires ggplot2)


gof(lazega_mmsbm, gof_stat = "Indegree", samples = 2)

Identify nodes with most frequent membership in latent groups

Description

The function lists the nodes (optionally, node-time periods) that most frequently instantiate membership in each latent group.

Usage

## S3 method for class 'mmsbm'
head(x, n = 6, t = NULL, node = TRUE, t.correct = FALSE, ...)

Arguments

Value

List of length n.blocks. Each entry contains a sorted vector of average latent membership probabilities of length n.

Author(s)

Santiago Olivella (olivella@unc.edu), Adeline Lo (aylo@wisc.edu), Tyler Pratt (tyler.pratt@yale.edu), Kosuke Imai (imai@harvard.edu)

Examples

library(NetMix)
## Load datasets
data("lazega_dyadic")
data("lazega_monadic")
## Estimate model with 2 groups
set.seed(123)
lazega_mmsbm <- mmsbm(SocializeWith ~ Coworkers,
                      ~  School + Practice + Status,
                      senderID = "Lawyer1",
                      receiverID = "Lawyer2",
                      nodeID = "Lawyer",
                      data.dyad = lazega_dyadic,
                      data.monad = lazega_monadic,
                      n.blocks = 2,
                      mmsbm.control = list(seed = 123,
                                           conv_tol = 1e-2,
                                           hessian = FALSE))

## Show top 6 lawyers in each estimated latent block
head(lazega_mmsbm)

Dyadic predictors in the Lazega friendship network (Lazega 2001).

Description

A dataset containing edges and dyad-level predictors in the network of friendships among lawyers in a New England law firm. More details are available in Lazega (2001).

Usage

data(lazega_dyadic)

Format

A data frame with 5041 rows and 4 variables:

Lawyer1, Lawyer2

lawyer ID, corresponding to identifiers common to those in lazega_monadic; numeric

SocializeWith

value of edge in network; binary

Coworkers

are the corresponding lawyers in the same office? boolean

Source

https://github.com/Z-co/networkdata/blob/master/networkdata/data/lazega.rda

References

Emmanuel Lazega, The Collegial Phenomenon: The Social Mechanisms of Cooperation Among Peers in a Corporate Law Partnership, Oxford University Press (2001).

Monadic predictors in the Lazega friendship network (Lazega 2001).

Description

A dataset containing vertex-level predictors in the network of sought-after advise among lawyers in a New England law firm. More details are available in Lazega (2001).

Usage

data(lazega_monadic)

Format

A data frame with 71 rows and 7 variables:

Lawyer

lawyer ID,corresponding to identifiers common to those in lazega_dyadic; numeric

Age

age, in years; numeric

Gender

1=man; 2=woman; factor

School

1=harvard, yale; 2=ucon; 3= other; factor

Practice

1=litigation; 2=corporate; factor

Seniority

time in the firm, in years; numeric

Status

1=partner; 2=associate; factor

Source

Emmanuel Lazega, The Collegial Phenomenon: The Social Mechanisms of Cooperation Among Peers in a Corporate Law Partnership, Oxford University Press (2001).

https://github.com/Z-co/networkdata/blob/master/networkdata/data/lazega.rda

Dynamic mixed-membership stochastic blockmodel with covariates

Description

The function estimates a dynamic mixed-membership stochastic blockmodel that incorporates covariates.

Usage

mmsbm(
  formula.dyad,
  formula.monad = ~1,
  senderID,
  receiverID,
  nodeID = NULL,
  timeID = NULL,
  data.dyad,
  data.monad = NULL,
  n.blocks,
  n.hmmstates = 1,
  directed = TRUE,
  mmsbm.control = list()
)

Arguments

Value

Object of class mmsbm. List with named components:

MixedMembership

Matrix of variational posterior of mean of mixed-membership vectors. nodes by n.blocks.

BlockModel

n.blocks by n.blocks matrix of estimated tie log-odds between members of corresponding latent groups. The blockmodel.

vcov_blockmodel

If hessian=TRUE, variance-covariance matrix of parameters in blockmodel, ordered in column-major order.

MonadCoef

Array of estimated coefficient values for monadic covariates. Has n.blocks columns, and n.hmmstates slices.

vcov_monad

If hessian=TRUE, variance-covariance matrix of monadic coefficients.

DyadCoef

Vector estimated coefficient values for dyadic covariates.

vcov_dyad

If hessian=TRUE, variance-covariance matrix of dyadic coefficients.

TransitionKernel

Matrix of estimated HMM transition probabilities.

Kappa

Matrix of marginal probabilities of being in an HMM state at any given point in time. n.hmmstates by years (or whatever time interval networks are observed at).

LowerBound

Final LB value

lb

Vector of all LB across iterations, useful to check early convergence issues.

niter

Final number of VI iterations.

converged

Convergence indicator; zero indicates failure to converge.

NodeIndex

Order in which nodes are stored in all return objects.

monadic.data, dyadic.data

Model frames used during estimation (stripped of attributes).

forms

Values of selected formal arguments used by other methods.

seed

The value of RNG seed used during estimation.

call

Original (unevaluated) function call.

Author(s)

Santiago Olivella (olivella@unc.edu), Adeline Lo (aylo@wisc.edu), Tyler Pratt (tyler.pratt@yale.edu), Kosuke Imai (imai@harvard.edu)

Examples

library(NetMix)
## Load datasets
data("lazega_dyadic")
data("lazega_monadic")
## Estimate model with 2 groups
## Setting to `hessian=TRUE` increases computation time
## but is needed if standard errors are to be computed. 
lazega_mmsbm <- mmsbm(SocializeWith ~ Coworkers,
                      ~  School + Practice + Status,
                      senderID = "Lawyer1",
                      receiverID = "Lawyer2",
                      nodeID = "Lawyer",
                      data.dyad = lazega_dyadic,
                      data.monad = lazega_monadic,
                      n.blocks = 2,
                      mmsbm.control = list(seed = 123,
                                           conv_tol = 1e-2,
                                           hessian = FALSE))

Fitter Function for dynamic MMSBM Model

Description

This is the interface to the C++ fitter for the dynamic mixed-membership stochastic blockmodel for network regression.

Arguments

Value

Unclassed list with named components; see Value of mmsbm

Warning

This function is for internal use only. End-users should always resort to mmsbm. In particular, that interface post-processes the return value of this internal in important ways.

Author(s)

Santiago Olivella (olivella@unc.edu), Adeline Lo (adelinel@princeton.edu), Tyler Pratt (tyler.pratt@yale.edu), Kosuke Imai (imai@harvard.edu)

Various visualization tools for 'mmsbm' objects

Description

The function provides a variety of plotting options for a fitted mmsbm object.

Usage

## S3 method for class 'mmsbm'
plot(x, type = "groups", FX = NULL, node = NULL, ...)

Arguments

Value

The requested plot object.

Author(s)

Santiago Olivella (olivella@unc.edu), Adeline Lo (aaylo@wisc.edu), Tyler Pratt (tyler.pratt@yale.edu), Kosuke Imai (imai@harvard.edu)

Examples

library(NetMix)
## Load datasets
data("lazega_dyadic")
data("lazega_monadic")
## Estimate model with 2 groups
lazega_mmsbm <- mmsbm(SocializeWith ~ Coworkers,
                      ~  School + Practice + Status,
                      senderID = "Lawyer1",
                      receiverID = "Lawyer2",
                      nodeID = "Lawyer",
                      data.dyad = lazega_dyadic,
                      data.monad = lazega_monadic,
                      n.blocks = 2,
                      mmsbm.control = list(seed = 123,
                                           conv_tol = 1e-2,
                                           hessian = FALSE))

## Plot blockmodel as network
plot(lazega_mmsbm)

Predict edges based on estimated mmsbm model

Description

The function produces expected posterior edges based on estimated parameters and (optionally new) predictor data

Usage

## S3 method for class 'mmsbm'
predict(
  object,
  new.data.dyad = NULL,
  new.data.monad = NULL,
  forecast = FALSE,
  type = c("link", "response", "mm"),
  ...
)

Arguments

Value

If new.data.dyad = NULL, vector of length nrow(object$dyadic.data). Else, vector of length nrow(new.data.dyad).

Author(s)

Santiago Olivella (olivella@unc.edu), Adeline Lo (aylo@wisc.edu), Tyler Pratt (tyler.pratt@yale.edu), Kosuke Imai (imai@harvard.edu)

Examples

library(NetMix)
## Load datasets
data("lazega_dyadic")
data("lazega_monadic")
## Estimate model with 2 groups
lazega_mmsbm <- mmsbm(SocializeWith ~ Coworkers,
                      ~  School + Practice + Status,
                      senderID = "Lawyer1",
                      receiverID = "Lawyer2",
                      nodeID = "Lawyer",
                      data.dyad = lazega_dyadic,
                      data.monad = lazega_monadic,
                      n.blocks = 2,
                      mmsbm.control = list(seed = 123,
                                           conv_tol = 1e-2, 
                                           hessian = FALSE))

## Get in-sample predicted edge probabilities
lazega_preds <- predict(lazega_mmsbm, type = "response")

Simulate a complete sociomatrix from an mmsbm object

Description

The function generates one sample network from the posterior predictive of the model represented by a fitted mmsbm object.

Usage

## S3 method for class 'mmsbm'
simulate(
  object,
  nsim = 1,
  seed = NULL,
  new.data.dyad = NULL,
  new.data.monad = NULL,
  ...
)

Arguments

Value

List of length nsim of simulated networks. If new.data.dyad = NULL, each element is a vector of length nrow(object$dyadic.data). Else, vector of length nrow(new.data.dyad). If seed is not NULL, return object includes its value as attribute "seed".

Author(s)

Santiago Olivella (olivella@unc.edu), Adeline Lo (aylo@wisc.edu), Tyler Pratt (tyler.pratt@yale.edu), Kosuke Imai (imai@harvard.edu)

Examples

library(NetMix)
## Load datasets
data("lazega_dyadic")
data("lazega_monadic")
## Estimate model with 2 groups
lazega_mmsbm <- mmsbm(SocializeWith ~ Coworkers,
                      ~  School + Practice + Status,
                      senderID = "Lawyer1",
                      receiverID = "Lawyer2",
                      nodeID = "Lawyer",
                      data.dyad = lazega_dyadic,
                      data.monad = lazega_monadic,
                      n.blocks = 2,
                      mmsbm.control = list(seed = 123, 
                                           conv_tol = 1e-2,
                                           hessian = FALSE))

## Simulate 5 new networks
lazega_sim <- simulate(lazega_mmsbm, nsim = 5, seed = 123)

Summarize 'mmsbm' object

Description

The function summarizes the output of a dynMMSBM model object

Usage

## S3 method for class 'mmsbm'
summary(object, ...)

Arguments

Value

List with named components:

N

Total number of dyad-time period observations.

Number of Clusters

Number of latent groups included in the dynMMSBM model.

Percent of Observations in Each Cluster

Average membership in each latent group, across all node-time periods.

Edge Formation Probabilities

n.groups by n.groups matrix of estimated edge formation probabilities between latent groups.

Dyadic Coefficients

Vector of estimated coefficient values for dyadic covariates.

Monadic Coefficients

Array of estimated coefficient values for monadic covariates. Has n.groups columns, and n.hmmstates slices.

Markov State Probabilities

Average HMM state probabilities across all time periods.

Author(s)

Santiago Olivella (olivella@unc.edu), Adeline Lo (aylo@wisc.edu), Tyler Pratt (tyler.pratt@yale.edu), Kosuke Imai (imai@harvard.edu)

Examples

library(NetMix)
## Load datasets
data("lazega_dyadic")
data("lazega_monadic")
## Estimate model with 2 groups
lazega_mmsbm <- mmsbm(SocializeWith ~ Coworkers,
                      ~  School + Practice + Status,
                      senderID = "Lawyer1",
                      receiverID = "Lawyer2",
                      nodeID = "Lawyer",
                      data.dyad = lazega_dyadic,
                      data.monad = lazega_monadic,
                      n.blocks = 2,
                      mmsbm.control = list(seed = 123,
                                           conv_tol = 1e-2,
                                           hessian = TRUE))

## Summarize estimated model
summary(lazega_mmsbm)

Extract Variance-Covariance Matrix for a Fitted mmsbm Object

Description

Extract Variance-Covariance Matrix for a Fitted mmsbm Object

Usage

## S3 method for class 'mmsbm'
vcov(object, param = "All", ...)

Arguments

Value

For param="All", named list of individual return components. For all other values of param, a numeric covariance matrix.

Author(s)

Santiago Olivella (olivella@unc.edu), Adeline Lo (aylo@wisc.edu), Tyler Pratt (tyler.pratt@yale.edu), Kosuke Imai (imai@harvard.edu)

Examples

library(NetMix)
## Load datasets
data("lazega_dyadic")
data("lazega_monadic")
## Estimate model with 2 groups
lazega_mmsbm <- mmsbm(SocializeWith ~ Coworkers,
                      ~  School + Practice + Status,
                      senderID = "Lawyer1",
                      receiverID = "Lawyer2",
                      nodeID = "Lawyer",
                      data.dyad = lazega_dyadic,
                      data.monad = lazega_monadic,
                      n.blocks = 2,
                      mmsbm.control = list(seed = 123, 
                                           conv_tol = 1e-2,
                                           se_sim = 2)) # Usually requires more samples.

vcov(lazega_mmsbm, "MonadCoef")