An MCMC routine providing a fit to an additive and multiplicative effects
(AME) regression model to cross-sectional relational data of various types.
This function supports both unipartite (square) and bipartite (rectangular)
networks. For longitudinal networks, use the lame function. Original
implementation by Peter Hoff.
Usage
ame(Y, Xdyad=NULL, Xrow=NULL, Xcol=NULL, rvar = !(family=="rrl") ,
cvar = TRUE, dcor = !symmetric, nvar=TRUE, R = 0, R_row = NULL, R_col = NULL,
mode = c("unipartite", "bipartite"), family="normal",
intercept=!is.element(family,c("rrl","ordinal")),
symmetric=FALSE,
odmax=rep(max(apply(Y>0,1,sum,na.rm=TRUE)),nrow(Y)),
prior=list(), g=NA,
seed = 6886, nscan = 10000, burn = 500, odens = 25,
plot=TRUE, print = TRUE, gof=TRUE,
start_vals=NULL, periodic_save=FALSE, out_file=NULL,
save_interval=0.25, model.name=NULL)Arguments
- Y
For unipartite: an n x n square relational matrix. For bipartite: an nA x nB rectangular relational matrix where nA is the number of row nodes and nB is the number of column nodes. See family below for various data types.
- Xdyad
For unipartite: an n x n x pd array of covariates. For bipartite: an nA x nB x pd array of covariates.
- Xrow
For unipartite: an n x pr matrix of nodal row covariates. For bipartite: an nA x pr matrix of row node covariates.
- Xcol
For unipartite: an n x pc matrix of nodal column covariates. For bipartite: an nB x pc matrix of column node covariates.
- rvar
logical: fit row random effects (asymmetric case)?
- cvar
logical: fit column random effects (asymmetric case)?
- dcor
logical: fit a dyadic correlation (asymmetric case)? Note: not used for bipartite networks.
- nvar
logical: fit nodal random effects (symmetric case)?
- R
integer: dimension of the multiplicative effects (can be zero). For bipartite networks, this is used as the default for both R_row and R_col if they are not specified.
- R_row
integer: for bipartite networks, dimension of row node multiplicative effects (defaults to R)
- R_col
integer: for bipartite networks, dimension of column node multiplicative effects (defaults to R)
- mode
character: either "unipartite" (default) for square networks or "bipartite" for rectangular networks
- family
character: one of "normal","tobit","binary","ordinal","cbin","frn","rrl","poisson" - see the details below
- intercept
logical: fit model with an intercept?
- symmetric
logical: Is the sociomatrix symmetric by design?
- odmax
a scalar integer or vector of length n giving the maximum number of nominations that each node may make - used for "frn" and "cbin" families
- prior
a list containing hyperparameters for the prior distributions. Available options and their defaults:
- Sab0
Prior covariance matrix for additive effects (default: diag(2)). A 2x2 matrix where Sab0\[1,1\] is the prior variance for row effects, Sab0\[2,2\] is the prior variance for column effects, and off-diagonals control correlation between row and column effects.
- eta0
Prior degrees of freedom for covariance of multiplicative effects (default: 4 + 3 \* n/100, where n is the number of actors). Higher values impose stronger shrinkage on the latent factors. Common values: 4-10 for weak shrinkage, 10-20 for moderate, >20 for strong shrinkage.
- etaab
Prior degrees of freedom for covariance of additive effects (default: 4 + 3 \* n/100). Controls shrinkage of row/column random effects. Larger values shrink effects toward zero.
- s20
Prior variance for regression coefficients (default: 1). Larger values allow for larger coefficient values.
- s2u0
Prior variance for multiplicative effects (default: 1).
- Suv0
Prior covariance for multiplicative effects (default: identity matrix).
Common usage: prior = list(Sab0 = diag(c(2, 2)), eta0 = 10) for moderate shrinkage, or prior = list(Sab0 = diag(c(0.5, 0.5))) for tighter control.
- g
optional scalar or vector of length dim(X)\[3\] for g-prior on regression coefficients. If not specified, defaults are: for normal family, g = nvar(Y); for tobit, g = nvar(Y)*4; for other families, g = n, where n is the number of non-missing dyads. The g-prior controls the variance of regression coefficients.
- seed
random seed
- nscan
number of iterations of the Markov chain (beyond burn-in)
- burn
burn in for the Markov chain
- odens
output density for the Markov chain
- plot
logical: plot results while running?
logical: print results while running?
- gof
logical: calculate goodness of fit statistics?
- start_vals
List from previous model run containing parameter starting values for new MCMC
- periodic_save
logical: indicating whether to periodically save MCMC results
- out_file
character vector indicating name and path in which file should be stored if periodic_save is selected. For example, on an Apple OS out_file="~/Desktop/ameFit.rda".
- save_interval
quantile interval indicating when to save during post burn-in phase.
- model.name
optional string for model selection output
Value
- BETA
posterior samples of regression coefficients
- VC
posterior samples of the variance parameters
- APM
posterior mean of additive row effects a
- BPM
posterior mean of additive column effects b
- U
posterior mean of multiplicative row effects u
- V
posterior mean of multiplicative column effects v (asymmetric case)
- UVPM
posterior mean of UV (asymmetric case)
- ULUPM
posterior mean of ULU (symmetric case)
- L
posterior mean of L (symmetric case)
- EZ
estimate of expectation of Z matrix
- YPM
posterior mean of Y (for imputing missing values)
- GOF
observed (first row) and posterior predictive (remaining rows) values of four goodness-of-fit statistics
- model.name
Name of the model (if provided)
Details
This command provides posterior inference for parameters in AME models of cross-sectional relational data, assuming one of eight possible data types/models. The function supports both unipartite networks (square adjacency matrices) and bipartite networks (rectangular adjacency matrices with distinct row and column node sets) for single time point analysis.
Theoretical Foundation:
The AME model decomposes network structure into several components: $$y_{ij} = \beta'x_{ij} + a_i + b_j + u_i'v_j + \epsilon_{ij}$$ where:
\(\beta'x_{ij}\): Fixed effects of dyadic/nodal covariates
\(a_i\): Additive sender (row) effect for node i
\(b_j\): Additive receiver (column) effect for node j
\(u_i'v_j\): Multiplicative interaction between latent factors
\(\epsilon_{ij}\): Dyadic error term (may be correlated)
This specification generalizes the social relations model (Warner et al. 1979) and latent space models (Hoff et al. 2002) within a unified framework.
Prior Distributions:
The model uses conjugate and semi-conjugate priors where possible:
Regression coefficients: \(\beta \sim N(0, g\sigma^2(X'X)^{-1})\) (g-prior)
Additive effects: \((a_i, b_i)' \sim N(0, \Sigma_{ab})\) jointly
Covariance: \(\Sigma_{ab} \sim IW(\eta_0, \eta_0 S_{ab0})\) (inverse-Wishart)
Multiplicative effects: Hierarchical shrinkage via \(\eta_0\)
Dyadic correlation: \(\rho \sim Uniform(-1, 1)\) with Metropolis updates
The inverse-Wishart prior on \(\Sigma_{ab}\) allows learning correlation between sender and receiver effects, capturing reciprocity patterns.
Multiplicative Effects (Latent Factors):
When R > 0, the model includes R-dimensional latent factors:
Asymmetric case: \(u_i, v_j \in \mathbb{R}^R\) with \(u_i'v_j\) interaction
Symmetric case: \(u_i = v_i\) with eigendecomposition \(ULU'\)
Captures homophily, transitivity, and community structure
R chosen via model selection or set to 2-3 for visualization
Estimation Algorithm:
The model uses a Gibbs sampler with the following updates:
Sample latent Z given parameters (data augmentation for non-normal families)
Update regression coefficients \(\beta\) via g-prior conjugate update
Update additive effects (a,b) jointly with \(\beta\)
Update covariance \(\Sigma_{ab}\) from inverse-Wishart
Update multiplicative effects U,V via Gibbs or Metropolis-Hastings
Update dyadic correlation \(\rho\) via Metropolis-Hastings
Update variance \(\sigma^2\) (for continuous families)
Standard Model Types:
The following data types/models are available:
"normal": A normal AME model.
"tobit": A tobit AME model for censored continuous data. Values are censored at zero, appropriate for non-negative continuous relational data.
"binary": A binary probit AME model.
"ordinal": An ordinal probit AME model. An intercept is not identifiable in this model.
"cbin": An AME model for censored binary data. The value of 'odmax' specifies the maximum number of links each row may have.
"frn": An AME model for fixed rank nomination networks. A higher value of the rank indicates a stronger relationship. The value of 'odmax' specifies the maximum number of links each row may have.
"rrl": An AME model based on the row ranks. This is appropriate if the relationships across rows are not directly comparable in terms of scale. An intercept, row random effects and row regression effects are not estimable for this model.
"poisson": An overdispersed Poisson AME model for count data. The latent variable represents the log mean of the Poisson distribution.
Examples
if (FALSE) { # \dontrun{
data(YX_bin)
fit<-ame(YX_bin$Y,YX_bin$X,burn=10,nscan=10,odens=1,family="binary")
# Note: you should run the Markov chain much longer in practice
} # }