ergmm-terms: Model Terms for Latent Space Random Graph Model

Description

Model terms that can be used in an ergmm formula and their parameter names.

Arguments

Model Terms

The latentnet package itself allows only dyad-independent terms. In the formula for the model, the model terms are various function-like calls, some of which require arguments, separated by + signs.

Latent Space Effects

euclidean(d, G=0, var.mul=1/8, var=NULL, var.df.mul=1, var.df=NULL, mean.var.mul=1, mean.var=NULL, pK.mul=1, pK=NULL)

(Negative) Euclidean distance model term, with optional clustering. Adds a term to the model equal to the negative Eucledean distance \(-||Z_i-Z_j||\), where \(Z_i\) and \(Z_j\) are the positions of their respective actors in an unobserved social space. These positions may optionally have a finite spherical Gaussian mixture clustering structure. This term was previously called latent which now fits negative Euclidean latent space model with a warning. The parameters are as follows:

d: The dimension of the latent space.
G: The number of groups (0 for no clustering).
var.mul: In the absence of var, this argument will be used as a scaling factor for a function of average cluster size and latent space dimension to set var. To set it in the prior argument to ergmm, use Z.var.mul.
var: If given, the scale parameter for the scale-inverse-chi-squared prior distribution of the within-cluster variance. To set it in the prior argument to ergmm, use Z.var.
var.df.mul: In the absence of var.df, this argument is the multiplier for the square root of average cluster size, which serves in place of var.df. To set it in the prior argument to ergmm, use Z.var.df.mul.
var.df: The degrees of freedom parameter for the scale-inverse-chi-squared prior distribution of the within-cluster variance. To set it in the prior argument to ergmm, use Z.var.df.
mean.var.mul: In the absence of mean.var, the multiplier for a function of number of vertices and latent space dimension to set mean.var. To set it in the prior argument to ergmm, use Z.mean.var.mul.
mean.var: The variance of the spherical Gaussian prior distribution of the cluster means. To set it in the prior argument to ergmm, use Z.mean.var.
pK.mul: In the absence of pK, this argument is the multiplier for the square root of the average cluster size, which is used as pK. To set it in the prior argument to ergmm, use Z.pK.
pK: The parameter of the Dirichilet prior distribution of cluster assignment probabilities. To set it in the prior argument to ergmm, use Z.pK.

The following parameters are associated with this term:

Z: Numeric matrix with rows being latent space positions.
Z.K (when \(\code{G}>0\)): Integer vector of cluster assignments.
Z.mean (when \(\code{G}>0\)): Numeric matrix with rows being cluster means.
Z.var (when \(\code{G}>0\)): Depending on the model, either a numeric vector with within-cluster variances or a numeric scalar with the overal latent space variance.
Z.pK (when \(\code{G}>0\)): Numeric vector of probabilities of a vertex being in a particular cluster.

bilinear(d, G=0, var.mul=1/8, var=NULL, var.df.mul=1, var.df=NULL, mean.var.mul=1, mean.var=NULL, pK.mul=1, pK=NULL)

Bilinear latent model term, with optional clustering. Adds a term to the model equal to the inner product of the latent positions: \(Z_i \cdot Z_j\), where \(Z_i\) and \(Z_j\) are the positions of their respective actors in an unobserved social space. These positions may optionally have a finite spherical Gaussian mixture clustering structure. Note: For a bilinear latent space effect, two actors being closer in the clustering sense does not necessarily mean that the expected value of a tie between them is higher. Thus, a warning is printed when this model is combined with clustering. The parameters are as follows:

d: The dimension of the latent space.

G

The number of groups (0 for no clustering).

var.mul

In the absence of var, this argument will be used as a scaling factor for a function of average cluster size and latent space dimension to set var. To set it in the prior argument to ergmm, use Z.var.mul.

var

If given, the scale parameter for the scale-inverse-chi-squared prior distribution of the within-cluster variance. To set it in the prior argument to ergmm, use Z.var.

var.df.mul

In the absence of var.df, this argument is the multiplier for the square root of average cluster size, which serves in place of var.df. To set it in the prior argument to ergmm, use Z.var.df.mul.

var.df

The degrees of freedom parameter for the scale-inverse-chi-squared prior distribution of the within-cluster variance. To set it in the prior argument to ergmm, use Z.var.df.

mean.var.mul

In the absence of mean.var, the multiplier for a function of number of vertices and latent space dimension to set mean.var. To set it in the prior argument to ergmm, use Z.mean.var.mul.

mean.var

The variance of the spherical Gaussian prior distribution of the cluster means. To set it in the prior argument to ergmm, use Z.mean.var.

pK.mul

In the absence of pK, this argument is the multiplier for the square root of the average cluster size, which is used as pK. To set it in the prior argument to ergmm, use Z.pK.

pK

The parameter of the Dirichilet prior distribution of cluster assignment probabilities. To set it in the prior argument to ergmm, use Z.pK.

The following parameters are associated with this term:

Z: Numeric matrix with rows being latent space positions.
Z.K (when \(\code{G}>0\)): Integer vector of cluster assignments.
Z.mean (when \(\code{G}>0\)): Numeric matrix with rows being cluster means.
Z.var (when \(\code{G}>0\)): Depending on the model, either a numeric vector with within-cluster variances or a numeric scalar with the overal latent space variance.
Z.pK (when \(\code{G}>0\)): Numeric vector of probabilities of a vertex being in a particular cluster.

Actor-specific effects

rsender(var=1, var.df=3)

Random sender effect. Adds a random sender effect to the model, with normal prior centered around \(0\) and a variance that is estimated. Can only be used on directed networks. The parameters are as follows:

var: The scale parameter for the scale-inverse-chi-squared prior distribution of the sender effect variance. To set it in the prior argument to ergmm, use sender.var.
var.df: The degrees of freedom parameter for the scale-inverse-chi-squared prior distribution of the sender effect variance. To set it in the prior argument to ergmm, use sender.var.df.

The following parameters are associated with this term:

sender: Numeric vector of values of each vertex's random sender effect.
sender.var: Random sender effect's variance.

rreceiver(var=1, var.df=3)

Random receiver effect. Adds a random receiver effect to the model, with normal prior centered around \(0\) and a variance that is estimated. Can only be used on directed networks. The parameters are as follows:

var: The scale parameter for the scale-inverse-chi-squared prior distribution of the receiver effect variance. To set it in the prior argument to ergmm, use receiver.var.

var.df

The degrees of freedom parameter for the scale-inverse-chi-squared prior distribution of the receiver effect variance. To set it in the prior argument to ergmm, use receiver.var.df.

The following parameters are associated with this term:

receiver: Numeric vector of values of each vertex's random receiver effect.
receiver.var: Random receiver effect's variance.

rsociality(var=1, var.df=3)

Random sociality effect. Adds a random sociality effect to the model, with normal prior centered around \(0\) and a variance that is estimated. Can be used on either a directed or an undirected network. The parameters are as follows:

var: The scale parameter for the scale-inverse-chi-squared prior distribution of the sociality effect variance. To set it in the prior argument to ergmm, use sociality.var.

var.df

The degrees of freedom parameter for the scale-inverse-chi-squared prior distribution of the sociality effect variance. To set it in the prior argument to ergmm, use sociality.var.df.

The following parameters are associated with this term:

sociality: Numeric vector of values of each vertex's random sociality effect.
sociality.var: Random sociality effect's variance.

Fixed Effects
Each coefficient for a fixed effect covariate has a normal prior whose mean and variance are set by the mean and var parameters of the term. For those formula terms that add more than one covariate, a vector can be given for mean and variance. If not, the vectors given will be repeated until the needed length is reached.

ergmm can use model terms implemented for the ergm package and via the ergm.userterms API. See ergmTerm for a list of available terms. If you wish to specify the prior mean and variance, you can add them to the call. E.g.,
TERMNAME(..., mean=0, var=9),
where ... are the arguments for the ergm term, will initialize TERMNAME with prior mean of 0 and prior variance of 9.

Some caveats:

ergm has a binary and a valued mode. Regardless of the family used, the binary variant of the ergm term will be used in the linear predictor of the model.
ergm does not support modeling self-loops, so terms imported in this way will always have predictor x[i,i]==0. This should not affect most situations, but if you absolutely must model self-loops and non-self-edges in one term, use the deprecated terms below.
latentnet only fits models with dyadic independence. Terms that induce dyadic dependence (e.g., triangles) can be used, but then the likelihood of the model will, effectively, be replaced with pseudolikelihood. (Note that under dyadic independence, the two are equal.)

Each parameter in this section adds one element to beta vector.

1(mean=0, var=9) a.k.a. intercept a.k.a. Intercept

Intercept. This term serves as an intercept term, is included by default (though, as in lm, it can be excluded by adding +0 or -1 into the model formula). It adds one covariate to the model, for which x[i,j]=1 for all i and j.

It can be used explicitly to set prior mean and variance for the intercept term.

This term differs from the ergm's edges-ergmTerm term if g has self-loops.

loopcov(attrname, mean=0, var=9)

Covariate effect on self-loops. attrname is a character string giving the name of a numeric (not categorical) attribute in the network's vertex attribute list. This term adds one covariate to the model, for which x[i,i]=attrname(i) and x[i,j]=0 for i!=j. This term only makes sense if g has self-loops.

loopfactor(attrname, base=1, mean=0, var=9)

Factor attribute effect on self-loops. The attrname argument is a character vector giving one or more names of categorical attributes in the network's vertex attribute list. This term adds multiple covariates to the model, one for each of (a subset of) the unique values of the attrname attribute (or each combination of the attributes given). Each of these covariates has x[i,i]=1 if attrname(i)==l, where l is that covariate's level, and x[i,j]=0 otherwise. To include all attribute values se base=0 -- because the sum of all such statistics equals twice the number of self-loops and hence a linear dependency would arise in any model also including loops. Thus, the base argument tells which value(s) (numbered in order according to the sort function) should be omitted. The default value, base=1, means that the smallest (i.e., first in sorted order) attribute value is omitted. For example, if the “fruit” factor has levels “orange”, “apple”, “banana”, and “pear”, then to add just two terms, one for “apple” and one for “pear”, then set “banana” and “orange” to the base (remember to sort the values first) by using nodefactor("fruit", base=2:3). For an analogous term for quantitative vertex attributes, see nodecov.attrname is a character string giving the name of a numeric (not categorical) attribute in the network's vertex attribute list. This term adds one covariate to the model, for which x[i,i]=attrname(i) and x[i,j]=0 for i!=j. This term only makes sense if g has self-loops.

latentcov(x, attrname=NULL, mean=0, var=9)

Edge covariates for the latent model.

Deprecated for networks without self-loops. Use edgecov-ergmTerm instead.

x is either a matrix of covariates on each pair of vertices, a network, or an edge attribute on g; if the latter, optional argument attrname provides the name of the edge attribute to use for edge values. latentcov can be called more than once, to model the effects of multiple covariates. Note that some covariates can be more conveniently specified using the following terms.

sendercov(attrname, force.factor=FALSE, mean=0, var=9)

Sender covariate effect.

Deprecated for networks without self-loops. Use nodeocov-ergmTerm, nodeofactor-ergmTerm, nodecov-ergmTerm or nodefactor-ergmTerm instead.

attrname is a character string giving the name of an attribute in the network's vertex attribute list. If the attribute is numeric, This term adds one covariate to the model equaling attrname(i). If the attribute is not numeric or force.factor==TRUE, this term adds \(p-1\) covariates to the model, where \(p\) is the number of unique values of attrname. The \(k\)th such covariate has the value attrname(i) == value(k+1), where value(k) is the \(k\)th smallest unique value of the attrname attribute. This term only makes sense if g is directed.

receivercov(attrname, force.factor=FALSE, mean=0, var=9)

Receiver covariate effect.

Deprecated for networks without self-loops. Use nodeicov-ergmTerm, nodeifactor-ergmTerm, nodecov-ergmTerm or nodefactor-ergmTerm instead.

attrname is a character string giving the name of an attribute in the network's vertex attribute list. If the attribute is numeric, This term adds one covariate to the model equaling attrname(j). If the attribute is not numeric or force.factor==TRUE, this term adds \(p-1\) covariates to the model, where \(p\) is the number of unique values of attrname. The \(k\)th such covariate has the value attrname(j) == value(k+1), where value(k) is the \(k\)th smallest unique value of the attrname attribute. This term only makes sense if g is directed.

socialitycov(attrname, force.factor=FALSE, mean=0, var=9)

Sociality covariate effect.

Deprecated for networks without self-loops. Use nodecov-ergmTerm instead.

attrname is a character string giving the name of an attribute in the network's vertex attribute list. If the attribute is numeric, This term adds one covariate to the model equaling attrname(i)+attrname(j). If the attribute is not numeric or force.factor==TRUE, this term adds \(p-1\) covariates to the model, where \(p\) is the number of unique values of attrname. The \(k\)th such covariate has the value attrname(i) == value(k+1) + attrname(j) == value(k+1), where value(k) is the \(k\)th smallest unique value of the attrname attribute. This term makes sense whether or not g is directed.

Description

Arguments

Model Terms

See Also