\documentclass[11pt]{article}
\usepackage{natbib,amssymb,amsmath,fullpage,hyperref}

%\VignetteIndexEntry{Dyadic data analysis with amen}
%\VignetteDepends{network}
%\VignetteKeyword{regression} 
%\VignetteKeyword{multivariate} 
%\VignetteEngine{knitr::knitr} 


\renewcommand{\baselinestretch}{1.5}
\newcommand{\bl}[1]{{\mathbf #1}}
\newcommand{\bs}[1]{{\boldsymbol #1}}
\newcommand{\Exp}[1]{{\text{E}}[ \ensuremath{ #1 } ]  }
\newcommand{\Var}[1]{{\text{Var}}[ \ensuremath{ #1 } ]  }
\newcommand{\Cov}[1]{{\text{Cov}}[ \ensuremath{ #1 } ]  }
\newcommand{\Cor}[1]{{\text{Cor}}[ \ensuremath{ #1 } ]  }


<<echo=FALSE,purl=FALSE,message=FALSE>>=
library(knitr)
library(amen) 
#library(devtools) ; load_all("../")

pdf.options(pointsize=10)
opts_chunk$set(size="footnotesize",message=FALSE,warning=FALSE,tidy=FALSE,
               comment=NA,dev.args=list(pdf=list(family="Times")))
@



\begin{document}


\title{Dyadic data analysis with  {\tt amen}}
\author{Peter D. Hoff
\thanks{Departments of Statistics and Biostatistics, University of Washington, Seattle. 
\url{http://www.stat.washington.edu/\~pdhoff/}. 
Development of this software and tutorial was supported  by
NIH grant R01HD067509. } }
\maketitle

\begin{abstract} 
Dyadic data on pairs of objects, such as relational  or social network data, 
%
%Measurements on pairs of objects 
%Dyadic data 
often exhibit
strong statistical dependencies. Certain types of 
second-order dependencies, such as 
degree heterogeneity and reciprocity, can be well represented with 
additive random effects models. 
Higher-order dependencies, 
such as transitivity and stochastic equivalence, can often be represented with  multiplicative effects. 
The {\tt amen} package for the {\sf R} statistical 
computing environment
provides estimation and inference 
for a class of additive and multiplicative random effects models 
%of 
%dyadic data of a variety of types, 
for 
ordinal, continuous, binary and other types of 
dyadic data. 
The package also provides methods 
for missing, censored and fixed-rank nomination data, as well 
as longitudinal dyadic data.  This tutorial illustrates the 
use of the {\tt amen} package 
via  example statistical analyses of several of these different  data types.

\smallskip

\noindent {\it Keywords:}
Bayesian estimation, dyadic data, latent factor model, MCMC, random effects, 
regression, relational data, social network. 

\end{abstract}



\tableofcontents

\section{The Gaussian AME model}

A variable that is measured or observed on pairs of objects
is called a \emph{dyadic variable}.
Data on such a variable may be referred to as 
dyadic data, relational data, or 
network data (particularly if the variable is 
binary). 
Dyadic data for 
a population of  $n$  objects, individuals or nodes 
may be represented as 
a \emph{sociomatrix}, an $n\times n$  square matrix $\bl Y$ 
with an undefined diagonal. 
The $i,j$th entry of $\bl Y$, 
denoted  $y_{i,j}$, 
gives the 
value of the variable for nodes $i$ and $j$ 
from the perspective of node $i$, or in the direction 
from $i$ to $j$. 
For example, in a dataset describing friendship relations, 
$y_{i,j}$ might represent a quantification of 
how much person $i$ likes person $j$.  
A running example in this 
section will be  an analysis of international 
trade data,  where 
%In a relational dataset on international trade, 
$y_{i,j}$ is the (log) dollar-value of exports from country $i$ to 
country $j$. These 
data can be obtained 
from the 
{\tt IR90s} dataset included in the {\tt amen} package.  
Specifically, we will analyze 
trade data between the
30 countries having the highest
GDPs:
<<>>=
#### ---- obtain trade data from top 30 countries in terms of GDP
data(IR90s)

gdp<-IR90s$nodevars[,2]
topgdp<-which(gdp>=sort(gdp,decreasing=TRUE)[30] )
Y<-log( IR90s$dyadvars[topgdp,topgdp,2] + 1 ) 

Y[1:5,1:5] 
@
 


\subsection{The social relations model}
Dyadic
data often exhibit 
certain types of statistical dependencies.    
For example, it is often  the case that
observations in a given row of the sociomatrix are
similar to or correlated with each other. 
This should not
be too surprising, as these  observations all share a
common ``sender,'' or row index. 
If a sender $i_1$ is more ``sociable'' than sender $i_2$, we would 
expect the values in row $i_1$ to be larger than 
those in row $i_2$, on average. 
%Positive correlation 
%of observations 
%within a row can equivalently be described as heterogeneity 
%of observations across rows.  
%If nodes are heterogeneous in terms of  
In this way, heterogeneity of the nodes in terms of their 
``sociability'' corresponds to a
%their ``sociability,'' then we would expect to see a
large variance of the row means of the sociomatrix. 
Similarly, 
nodal heterogeneity in ``popularity'' corresponds to 
a large variance in the column means. 

A classical approach to evaluating across-row and across-column 
heterogeneity in a data matrix is the ANOVA decomposition. 
A model-based version of the ANOVA decomposition posits that 
the variability of 
the $y_{i,j}$'s around some overall mean is well-represented by 
additive row and column effects:
\[ 
y_{i,j} = \mu + a_i +b_j + \epsilon_{i,j}. 
\] 
In this model, 
heterogeneity among the parameters 
$\{a_i: i=1,\ldots, n\}$ and 
$\{b_j : j=1,\ldots, n\}$ give correspond to 
observed heterogeneity in the row means 
and column means of the sociomatrix, respectively. 
If the $\epsilon_{i,j}$'s are assumed to be 
i.i.d.\ from a mean-zero normal distribution, 
the hypothesis of no row heterogeneity 
(all $a_i$'s equal to zero) or 
no row heterogeneity (all $b_j$'s equal to zero) 
can be evaluated with normal-theory $F$-tests. 
For the trade data, this can be done in {\sf R} as follows:

<<>>=
#### ---- ANOVA for trade data

Rowcountry<-matrix(rownames(Y),nrow(Y),ncol(Y)) 
Colcountry<-t(Rowcountry) 

anova(lm( c(Y) ~ c(Rowcountry) + c(Colcountry) ) ) 
@

The results indicate a large degree of heterogeneity 
of the 
countries as both exporters and importers - much more than 
would be expected if the ``true'' $a_i$'s were all zero, 
or the ``true'' $b_j$'s were all zero  (and the 
$\epsilon_{i,j}$'s were i.i.d.). 
Based on this result, the next steps in a data analysis might 
include comparisons of the row means or of the column means, that is, 
comparisons of the countries in terms of their total or average 
imports and exports. This can equivalently be done via 
comparisons among estimates of the row and column effects:
<<>>=
#### ---- comparison of countries in terms of row and column means
rmean<-rowMeans(Y,na.rm=TRUE) ; cmean<-colMeans(Y,na.rm=TRUE)

muhat<-mean(Y,na.rm=TRUE)
ahat<-rmean-muhat
bhat<-cmean-muhat

# additive "exporter" effects
head( sort(ahat,decreasing=TRUE)  ) 

# additive "importer" effects
head( sort(bhat,decreasing=TRUE)  ) 
@
We note that these simple estimates here are 
very close to, but not exactly 
the same as, the least-squares/maximum likelihood estimates
(this is because of the undefined diagonal in the sociomatrix). 

While straightforward to implement, this classical ANOVA analysis ignores 
a fundamental characteristic of dyadic data: Each node
appears in the dataset as both a sender and a receiver of 
relations, or equivalently, the 
row and column labels of the data matrix refer to the same set of 
objects. 
In the context of the ANOVA model, 
this means that 
each node $i$ has two additive effects: a row effect 
$a_i$  and a column effect $b_i$.  
Often it is of interest to evaluate the extent to which 
these effects are correlated, for example, to 
evaluate if sociable nodes in the network are also 
popular. 
Additionally, 
each  (unordered) pair of nodes $i,j$ has two 
outcomes, $y_{i,j}$ and $y_{j,i}$.  
It is often the case that
$y_{i,j}$ and $y_{j,i}$ are correlated, as these 
two observations come from the same \emph{dyad}, or pair of nodes. 

Correlations between the additive effects can be evaluated empirically  
simply by computing the sample covariance of the 
row means and column means, or 
alternatively, the $\hat a_i$'s and 
$\hat b_i$'s. 
Dyadic correlation can be evaluated by computing the
correlation between the  matrix of residuals from the ANOVA 
model and its transpose:

<<>>=
#### ---- covariance and correlation between row and column effects
cov( cbind(ahat,bhat) ) 
cor( ahat, bhat) 
@

<<>>=
#### ---- an estimate of dyadic covariance and correlation
R <- Y - ( muhat + outer(ahat,bhat,"+") )
cov( cbind( c(R),c(t(R)) ), use="complete") 
cor( c(R),c(t(R)), use="complete") 
@

\begin{figure}
<<echo=FALSE,fig.height=3,fig.width=6,out.width='6in',fig.align='center'>>=
par(mfrow=c(1,1),mar=c(3,3,1,1),mgp=c(1.75,.75,0))
plot(rmean*1.1,cmean*1.1,type="n",xlab="average log exports",
                                  ylab="average log imports")
abline(h=0,col="gray",lty=2) ; abline(v=0,col="gray",lty=2)
abline(0,1,col="gray",lty=2)
text(rmean,cmean,dimnames(Y)[[1]],cex=.7)
@
\caption{Scatterplot of country-level average imports versus exports.} 
\label{fig:trade_rmvcm}
\end{figure}

As shown by these calculations and in Figure \ref{fig:trade_rmvcm}, 
country-level export and import volumes are highly correlated, 
as are the export and import volumes within country pairs. 
A foundational model for analyzing such 
within-node and within-dyad 
 dependence is 
the \emph{social relations model}, or SRM \citep{warner_kenny_stoto_1979}, 
a type of ANOVA decomposition that describes variability among the
 entries of the sociomatrix $\bl Y$ in terms of within-row, 
within-column and within-dyad variability.  
A normal random-effects version of the SRM has been studied by 
\citet{wong_1982} and  \citet{li_loken_2002}, among others, and 
takes the following form:
\begin{align} 
y_{i,j} & = \mu+ a_i + b_j + \epsilon_{i,j} \label{eqn:srm} \\
%  y_{i,j} & =  \mu  + \epsilon_{i,j}  \\ 
%  \epsilon_{i,j} &= a_i + b_j +e_{i,j} \\
 \{ (a_1,b_1) ,\ldots, (a_n,b_n) \} &\sim  \text{i.i.d.} \ N(0,\Sigma_{ab})\nonumber  \\
 \{ (\epsilon_{i,j},\epsilon_{j,i}) : i\neq j \} &\sim  \text{i.i.d.} \ N(0,\Sigma_{e}) ,  \nonumber
\end{align}
where 
\[ 
\Sigma_{ab} = \begin{pmatrix} \sigma^2_a & \sigma_{ab} \\ 
    \sigma_{ab} & \sigma_b^2 \end{pmatrix} \ \  \text{and} \ \
\Sigma_\epsilon = \sigma^2_\epsilon \begin{pmatrix}  1 & \rho \\ \rho & 1 \end{pmatrix}. 
\]


Note that conditional on the row effects $\{a_1,\ldots, a_n\}$, 
the mean in the $i$th row of $\bl Y$ is given by $\mu+a_i$, 
and the variability of these row-specific  means is given by $\sigma^2_a$. 
In this way, the row effects represent across-row heterogeneity in the 
sociomatrix, and $\sigma_a^2$ is a single-number summary of this 
heterogeneity. 
Similarly, the column effects $\{b_1,\ldots, b_n\}$ 
represent heterogeneity in the column means, and 
$\sigma^2_b$ summarizes this heterogeneity. 
The covariance $\sigma_{ab}$ 
describes the linear association 
between 
these row and column effects, or equivalently, 
the association between the row means and column means of the sociomatrix. 
Additional variability across dyads is described by $\sigma^2_\epsilon$, 
and within dyad correlation  (beyond that 
  described by $\sigma_{ab}$) is captured by $\rho$. 
More precisely, straightforward calculations show that, 
under this random effects model, 
\begin{align} 
\Var{ y_{i,j} } &= \sigma^2_a + 2 \sigma_{ab} + \sigma^2_b + \sigma_\epsilon^2 
  & \text{(across-dyad variance)}  \label{eqn:srmcov} \\
\Cov{ y_{i,j} ,y_{i,k} } & =  \sigma_a^2  & \text{(within-row covariance)} \nonumber  \\ 
\Cov{ y_{i,j} ,y_{k,j} } & =  \sigma_b^2 & \text{(within-column covariance)}  \nonumber  \\
 \Cov{ y_{i,j} ,y_{j,k} } & =  \sigma_{ab} & \text{(row-column covariance) }    \nonumber   \\
 \Cov{ y_{i,j} ,y_{j,i} } & =  2 \sigma_{ab} + \rho \sigma^2_e & \text{(row-column covariance plus reciprocity) },  \nonumber
\end{align}
with all other covariances between elements of $\bl Y$ being zero. 
We refer to this covariance model as the \emph{social relations covariance
model}. 

The {\tt amen} package provides model fitting and evaluation tools 
for the SRM via the default values of the  {\tt ame} command:
<<IR90s_fit_srm,cache=TRUE,fig.keep='last',results='hide',fig.cap='Default plots generated by the ame command.',fig.height=6,fig.width=5,fig.align='center'>>=
fit_SRM<-ame(Y) 
@

Running this command initiates an iterative Markov chain Monte Carlo  (MCMC) 
algorithm that provides Bayesian inference for the parameters in the  
SRM model. The progress of the algorithm is 
displayed via a sequence of plots,  
the last of 
which is shown in Figure \ref{fig:IR90s_fit_srm}. 
The top row gives
traceplots of the
parameter values
simulated from the posterior distribution, 
including covariance parameters on the
left and regression parameters on the right.
The covariance parameters include $\Sigma_{ab}$,
$\rho$, and $\sigma^2$, and are stored as
the list component \text{VC} in the fitted object.
The only regression parameter for this model is the
intercept $\mu$, which is included by default for the Gaussian SRM.
The intercept, and any other regression parameters are
stored as \text{BETA} in the fitted object.
We can compare these estimates obtained from {\tt amen}
to the estimates from the
ANOVA-style approach as follows:
<<>>=
muhat                                # empirical overall mean  
mean(fit_SRM$BETA)                   # model-based estimate

cov( cbind(ahat,bhat))               # empirical row/column mean covariance 
apply(fit_SRM$VC[,1:3],2,mean)       # model-based estimate    

cor( c(R), c(t(R)) ,use="complete")  # empirical residual dyadic correlation
mean(fit_SRM$VC[,4] )                # model-based estimate
@
Posterior mean estimates of the row and column effects can be accessed
from {\tt fit\_SRM\$APM}  and {\tt fit\_SRM\$BPM}, respectively.
These estimates are plotted in Figure \ref{fig:bvols}, against the corresponding
ANOVA estimates. 
\begin{figure}
<<echo=FALSE,fig.height=2.7,fig.width=5.2,out.width='5.2in',fig.align='center'>>=
par(mfrow=c(1,2),mar=c(3,3,1,1),mgp=c(1.75,.75,0))
plot( ahat, fit_SRM$APM,xlab=expression(paste("ANOVA ",hat(a)) ) ,
                        ylab=expression(paste("Bayes ",hat(a)) )  )
abline(0,1)

plot( bhat, fit_SRM$BPM,xlab=expression(paste("ANOVA ",hat(b)) ) ,
                        ylab=expression(paste("Bayes ",hat(b)) )  )
abline(0,1)
@ 
\caption{Bayes versus least-squares parameter estimates.} 
\label{fig:bvols}
\end{figure}


The second two rows of Figure  \ref{fig:IR90s_fit_srm}
 give posterior predictive
goodness of fit summaries for four network statistics:
(1) the empirical standard deviation of the row means;
(2) the empirical standard deviation of the column means;
(3) the empirical within-dyad  correlation;
(4)  a normalized measure of triadic dependence.
Details on how these are computed can be obtained by examining the
{\tt gofstats} function of the {\tt amen} package. 
The blue histograms in the figure represent values of
{\tt gofstats(Ysim)}, where {\tt Ysim} is simulated from the
posterior predictive distribution. These histograms
should be compared to the observed statistics {\tt gofstats(Y)},
which for these data are
\Sexpr{round(gofstats(Y),3) }, given by vertical red lines in the figure.
Generally speaking,
large discrepancies between the posterior predictive distributions
(histograms) and the observed statistics (red lines) suggest
model lack of fit.
For these data, the model does well at representing the data 
with respect to the first three statistics, but shows a discrepancy with 
regard to 
the triadic dependence statistic. 
This is not too surprising, as the SRM only captures second-order 
dependencies (variances and covariances). 


\subsection{Social relations regression modeling}
Often we wish to quantify the association between  
a particular dyadic variable and  
some other dyadic or nodal variables. 
Useful for such situations is a type of linear mixed effects 
model we refer to as the \emph{social relations regression model} (SRRM), 
which combines a linear regression model with the covariance 
structure of the SRM as follows:
\begin{equation}
 y_{i,j} = \beta_d^T \bl x_{d,i,j} + \beta_r^T \bl x_{r,i} +\beta_c^T \bl x_{c,j} +  a_i + b_j +  \epsilon_{i,j} ,  
\label{eqn:srrm}
\end{equation}
where $\bl x_{d,i,j}$ is a vector of characteristics of dyad $\{i,j\}$, 
    $\bl x_{r,i}$ is a vector of characteristics 
of node $i$ as  a sender, 
and $\bl x_{c,j}$ is a vector of characteristics of node $j$ 
as a receiver. 
We refer to $\bl x_{d,i,j}$, $\bl x_{r,i}$ and $\bl x_{c,i}$ 
as dyadic, row and column covariates, respectively. 
In many applications the row and column 
characteristics are the same so that $\bl x_{r,i} = \bl x_{c,i} = \bl x_i $, 
in which case they are simply referred to as nodal covariates. 
However, it can sometimes be useful to distinguish $\bl x_{r,i}$ from $\bl x_{c,i}$:
In the context 
of friendships among students, for example, it is conceivable that some 
characteristic  of a person 
(such as athletic or academic success) 
may affect their popularity (how much they are liked  by others), 
but not their sociability (how much they like others). 

We illustrate parameter estimation for the SRRM by fitting the model to the 
trade data. Nodal covariates include (log) population, (log) GDP, and polity, 
a measure of democracy. 
Dyadic covariates include the number the number of conflicts, (log) geographic 
distance between countries, the number of shared IGO memberships, and a polity 
interaction (the product of the nodal polity scores). 
<<>>=
#### ---- nodal covariates
dimnames(IR90s$nodevars)[[2]]
Xn<-IR90s$nodevars[topgdp,]
Xn[,1:2]<-log(Xn[,1:2])

#### ---- dyadic covariates
dimnames(IR90s$dyadvars)[[3]]
Xd<-IR90s$dyadvars[topgdp,topgdp,c(1,3,4,5)] 
Xd[,,3]<-log(Xd[,,3]) 
@
Note that dyadic covariates are stored in an $n\times n \times p_d$ array, 
where $n$ is the number of nodes and $p_d$ is the number of dyadic covariates. 


The SRRM can be fit using the {\tt ame} function by just specifying the 
covariates:
<<IR90s_fit_srrm,cache=TRUE,fig.keep='none',results='hide'>>=
fit_srrm<-ame(Y,Xd=Xd,Xr=Xn,Xc=Xn)
@ 
Posterior mean estimates, standard deviations, nominal $z$-scores and $p$-values
may be obtained with the {\tt summary} command:
<<>>=
summary(fit_srrm) 
@
The column {\tt z-stat} is obtained by dividing the posterior means by their 
posterior standard deviations, and each {\tt p-val} is the
the probability that a standard normal random variable 
exceeds the corresponding {\tt z-stat} in absolute value. 
Based on these calculations, there appears to be strong evidence for 
associations between countries' export and import levels with  both population and GDP. 
Additionally, there is evidence that geographic proximity and the number of 
shared IGOs are both positively associated with trade between country pairs. 


It is instructive to compare these results to those that would be obtained 
under an ordinary linear regression model that assumed i.i.d.\ residual standard error. 
Such a model can be fit in the {\tt amen} package by opting 
to fit a model with no row variance, column variance or dyadic correlation:
<<IR90s_fit_rm,cache=TRUE,fig.keep='none',results='hide'>>=
fit_rm<-ame(Y,Xd=Xd,Xr=Xn,Xc=Xn,rvar=FALSE,cvar=FALSE,dcor=FALSE)
@


<<>>=
summary(fit_rm)
@

The parameter standard deviations (i.e., standard errors) under this i.i.d.\  model are 
almost all larger than those under the SRM fit. The explanation for this is that 
the i.i.d.\ model wrongly assumes independent observations, and thus 
overrepresents the precision of the parameter estimates. 
The inappropriateness of the i.i.d.\ model can be seen via 
%This can be seen in 
the posterior predictive goodness of fit plots given in 
Figure \ref{fig:gof_srrm}. The plots show, in particular, that the data exhibit 
much more dyadic correlation than can be explained by the i.i.d.\ model. In 
contrast, the SRRM does not show such a discrepancy with regard to this statistic. 
However, both models fail to represent the amount of triadic dependence in the data, 
as shown in the fourth goodness of fit plot. 


\begin{figure}
<<echo=FALSE,fig.height=3,fig.width=6,out.width='6in',fig.align='center'>>=
ht<-c(30,30,50,30) 
GOF<-gofstats(Y) 
par(mfrow=c(2,2),mar=c(3,3,1,1),mgp=c(1.75,.75,0))
for(k in 1:4)
{
  xlim<-range(c(fit_rm$GOF[,k],fit_srrm$GOF[,k],GOF[k]))*c(.9,1.1)         
  hist(fit_rm$GOF[-1,k],prob=TRUE,col="pink",xlim=xlim,main="",ylab="",
        xlab=names(GOF)[k],ylim=c(0,ht[k]))

  clr<-c(col2rgb("lightblue")/255,.75)
  hist(fit_srrm$GOF[-1,k],prob=TRUE,add=TRUE, 
        col=rgb(clr[1],clr[2],clr[3],clr[4])) 
   abline(v=GOF[k],col="red")
}
@
\caption{Posterior predictive distributions of goodness of fit statistics for the 
ordinary regression model (pink) and the SRRM (blue).}
\label{fig:gof_srrm}
\end{figure}




\subsection{Transitivity and stochastic equivalence via multiplicative 
effects}
It is often observed that the similarity of two nodes $i$ and $j$ in terms 
of their individual characteristics $\bl x_i$ and $\bl x_j$ 
is associated with the 
value of the relationship $y_{i,j}$ between them. 
For example, suppose  for each node $i$  that $x_i$ 
is the indicator that person $i$ 
is a member of a particular  group or organization. 
Then $x_{i}x_{j}$ is the indicator that $i$ and $j$ are 
co-members of this organization, and this fact may have 
some effect on their relationship $y_{i,j}$. 
A positive effect of $x_ix_j$ on $y_{i,j}$ is 
referred to as homophily, and a negative effect 
as anti-homophily. 
Measuring homophily on an observed 
characteristic can be done within the context of the SRRM 
by creating a dyadic covariate  $x_{d,i,j}$ 
from a nodal covariate $x_i$ through multiplication 
($x_{d,i,j} = x_i x_j$) or some other operation. 
Homophily on nodal characteristics can lead to certain types of 
patterns  often seen in network and dyadic data, 
sometimes referred to as transitivity, balance and clustering
\citep{hoff_2005a,hoff_2009c}. 
For example, in a binary network where people prefer to form 
ties to others who are similar to them,  
there tend to be a lot of 
 ``transitive triples,'' that is, triples of indices $i,j,k$ having a link 
between each pair. One explanation of this is that links 
from $i$ to $j$ and from $i$ to $k$ occur because $i$ is similar to 
both $j$ and to $k$. If this is the case, then 
$j$ and $k$ must also be somewhat similar, and so there 
is a high probability of a link between $j$ and $k$, which would form
a triangle of ties among nodes $i$, $j$ and $k$. Multiple linked 
triangles result in visual ``clusters'' in graphs of social networks. 

More generally, in the case of multiple sender and 
receiver covariates, 
we are interested in how a person with characteristics 
$\bl x_{r,i}$ relates to a person with characteristics 
$\bl x_{c,j}$. 
This can be evaluated in the SRRM by including a set of regression 
terms equivalent to 
$\bl x_{r,i}^T \bl B \bl x_{c,i}$
Although this term is multiplicative in the 
covariates, it is linear in the parameters, as 
\[ 
 \bl x_{r,i}^T \bl B \bl x_{c,i} = \sum_{k} \sum_l b_{k,l} x_{r,i,k} x_{c,j,l} 
\] 
and so the 
matrix of parameters may be estimated within the context of 
a linear regression model simply by including 
all products of the elements of $\bl x_{r,i}$ and $\bl x_{c,j}$ as 
dyadic covariates. In practice, 
if $\bl x_{r,i}$ and $\bl x_{c,j}$ are of the same length
(for example, if they are the same), 
then  it is 
common to take $\bl B$  to be a diagonal matrix, in which case  
\[ 
  \bl x_{r,i}^T \bl B \bl x_{c,i} = b_1 x_{r,i,1} x_{c,j,1}  + \cdots 
    b_p x_{r,i,p} x_{c,j,p}. 
\] 
Such terms in the regression model can often account 
for network patterns such as transitivity and clustering, 
as described above. 
They can also account for another type of network pattern, 
known as stochastic equivalence, where it is 
observed that a group of nodes 
all relate to the other nodes (and each other) in a similar way. 
If such groups are related to the observed nodal covariates, then often 
the stochastic equivalence in the data  may be estimated and represented by 
these multiplicative regression terms. 

This can be seen to a limited degree in the trade data: 
Note that the number of shared IGOs and the polity interaction can both 
be viewed as dyadic covariates obtained by multiplication of 
nodal covariates. We can fit an SRRM without these effects:
<<cache=TRUE,fig.keep='none',results='hide'>>=
fit_srrm0<-ame(Y,Xd[,,1:2],Xn,Xn)
@

\begin{figure}
<<echo=FALSE,fig.height=3,fig.width=6>>=
hist(fit_srrm0$GOF[-1,4],main="",yaxt="n",ylab="",prob=TRUE,col="lightgreen",breaks=12,
      xlab=names(GOF)[4] ,xlim=range(fit_srrm0$GOF[,4]),ylim=c(0,17) )
hist(fit_srrm$GOF[-1,4],prob=TRUE,add=TRUE, 
        col=rgb(clr[1],clr[2],clr[3],clr[4])) 
abline(v=GOF[4],col="red")
@
\caption{Comparison of the SRRM with (blue) and without (green) nodal 
interaction effects, in terms of the triadic dependence statistic.}  
\label{fig:mdcomp}
\end{figure}


A comparison of the resulting posterior predictive distribution of the transitivity statistic
to that under the full SRRM (which included the multiplicative effects)
is given  in Figure \ref{fig:mdcomp}:
The figure shows that, while both models do not fully represent the triadic dependence 
in the data, the model that includes the nodal interactions does slightly better. 
This raises the possibility that there may exist other nodal attributes, not given 
in the dataset, whose multiplicative interaction might help further describe the 
triadic dependence observed in the data. 
%It is often the case that a network or relational dataset exhibits patterns 
%such as transitivity, clustering and stochastic equivalence, but we lack 
%any observed nodal covariates that might explain such patterns. 
In such cases, 
it can be useful to include \emph{latent} nodal 
characteristics into the regression model, resulting in the following:
\begin{equation}
 y_{i,j} = \beta_d^T \bl x_{d,i,j} + \beta_r^T \bl x_{r,i} +\beta_c^T \bl x_{c,j} +  a_i + b_j +  \bl u_i^T \bl v_j  +  \epsilon_{i,j} ,  
\label{eqn:ame}
\end{equation}
Here,  $\bl u_i$  is a vector of latent, unobserved factors or characteristics 
that describe node $i$'s behavior as a sender, and 
similarly $\bl v_j$  describes node $j$'s behavior as a receiver. 
In this model, the mean of $y_{i,j}$ 
depends on how ``similar'' $\bl u_i$ and $\bl v_j$ are (i.e., the extent to 
which the vectors point in the same direction) as well as the magnitudes of the 
vectors. 
Note also
 that  basic results from matrix algebra indicate that 
any type of network pattern that could be described by a regression 
term of the form  $\bl x_{r,i} \bl B \bl x_{c,j}$ can also 
be described by the multiplicative effects term $\bl u_i^T \bl v_j$. 


We call a model of the form (\ref{eqn:ame}) an 
\emph{additive and multiplicative effects} model, or 
AME model for network and dyadic data. 
An AME model essentially combines two models for 
matrix-valued data: 
an \emph{additive main effects, multiplicative interaction} (AMMI) model
\citep{gollob_1968, bradu_gabriel_1974} - a class of 
models developed in the psychometric and agronomy literature; 
and the SRM covariance model that recognizes the dyadic 
aspect of the data. 
An AME model, like other latent factor models, requires the specification of the 
dimension of the latent factors. In the {\tt amen} package, this can be 
set with the option {\tt R} in the {\tt ame} command
The letter {\tt R} here stands for ``rank'':  If $\bl U$ and $\bl V$ are $n\times R$ matrices 
of the latent factors, then $\bl U\bl V^T$ has rank {\tt R}. 
For example, 
a rank-2 AME model  may be fit as follows:
<<trade_ame2,cache=TRUE,fig.keep='last',results='hide',fig.cap='Diagnostic plots for the rank-2 AME model.',fig.height=6,fig.width=5,fig.align='center'>>=
fit_ame2<-ame(Y,Xd,Xn,Xn,R=2)
@
The diagnostic plots for this model  are given in Figure \ref{fig:trade_ame2}. 
Note that, unlike all previous models considered, this model provides an adequate fit in terms 
of the triadic dependence statistic. 
The regression parameter estimates and their standard errors lead to more or
less similar conclusions as in the SRRM, except that the number of shared IGOs
no longer has a large effect after controlling for the triadic dependence with the
latent factors.
<<>>=
summary(fit_ame2) 
@

In some cases it is of interest to examine the estimated latent factors 
and compare them across nodes. Some ways to do this include clustering the 
latent factors or simply plotting them. The function {\tt circplot} in the 
{\tt amen} package provides a circle plot that can describe the estimated latent factors 
of a rank-2 model. A circle plot for the trade data is shown graphically in 
Figure \ref{fig:trade_circplot}. 
\begin{figure}
<<echo=FALSE,fig.height=4.75,fig.width=4.75,fig.align='center'>>=
mu<-mean(fit_ame2$BETA[,1])
br<-apply(fit_ame2$BETA[,1+1:3] ,2,mean)
bc<-apply(fit_ame2$BETA[,1+3+1:3],2,mean)  
bd<-apply(fit_ame2$BETA[,1+6+1:4] ,2,mean)

EY2<-  mu+
       Xbeta(Xd,bd) +  
     ( Xn%*%br + fit_ame2$APM)%*%rep(1,nrow(Y)) +
  t( ( Xn%*%bc + fit_ame2$BPM)%*%rep(1,nrow(Y)) ) 

par(mar=c(0,0,0,0),mgp=c(0,0,0)) 
circplot(1*( Y - EY2 > 0 ) , fit_ame2$U ,  fit_ame2$V ,pscale=1.1 )   
@
\caption{Circle plot of estimated latent factors. Directions of 
$\hat {\bl u}_{i}$'s and $\hat {\bl v}_{i}$'s are given in red and 
blue, respectively, with the plotting size being a function of the 
magnitudes of the vectors.  Dashed lines between countries indicate 
greater than expected trade based on the regression terms 
and additive effects. }
\label{fig:trade_circplot}
\end{figure}
Such a figure can help identify groups of nodes that are similar to each 
other in terms of exporting and importing behavior, after controlling for 
regression and additive row and column effects. 
For example, the plot identifies the high trade volume between countries 
on the Pacific rim. 


%\paragraph{Summary:}
%The {\tt amen} package 
%provides model fitting and evaluation tools for the 
% basic AME model, and extends these tools to accommodate 
%relational data of a variety of types, including 
%binary and ordinal  relational data, and allows for  
%missing data and 
%certain types of censoring. The remainder of this tutorial 
%illustrates the use of the {\tt amen} package in the analysis of 
%several relational datasets of a variety of types. 




\section{AME models for ordinal data} 
Often we wish to analyze a dyadic outcome variable 
%Dyadic datasets often include variables that are
that is 
not well-represented by a normal model. 
In some cases, such as with trade data, the variable of interest can be transformed 
so that the 
Gaussian 
AME model is reasonable.  In other cases, 
such as with binary, ordinal, discrete or sparse relations, 
 no such transformation is available.  
Examples of such data include measures of friendship that 
are binary (not friends/friends) or ordinal (dislike/neutral/like), 
discrete counts of conflictual events between countries, or the amount of time 
two people spend on the phone with each other  (which might be zero 
for most pairs in a population). 

In this section we describe extensions of the Gaussian AME model 
to accommodate ordinal dyadic data, where in what follows, 
ordinal means any outcome for which the possible values 
can be put in some order. This includes discrete outcomes 
(such as binary indicators or counts), ordered qualitative 
outcomes (such as low/medium/high, i.e.\  the
``traditional'' definition of ordinal), and even continuous outcomes. 
The extensions are based on latent variable 
representations of probit and ordinal probit regression models. 

\subsection{Example: Analysis of a binary outcome}
The simplest type of ordinal dyadic variable is a binary indicator of some 
type of relationship between $i$ and $j$, 
so that $y_{i,j} = $ 0 or 1 depending on whether the 
relationship  is absent or present, respectively. 
Data on such relations, particularly those indicating 
a  social interaction or friendship, are often called 
\emph{social networks}. For example, 
the {\tt amen} dataset {\tt lazegalaw} 
%included in the {\tt amen} package
includes a social network of friendship ties between 71 members 
of a law firm, 
along with two other dyadic variables and several nodal 
characteristics. The friendship data are displayed as a graph in Figure 
\ref{fig:llaw_graph}, where the nodes are colored according to which 
of three offices each lawyer works. 

%\begin{figure}
<<llaw_graph,fig.height=4.75,fig.width=4.75,fig.align='center',fig.cap='Graph of the friendship network between 71 lawyers. Node colors represent at which of the three offices each lawyer works.'>>=
data(lazegalaw) 

Y<-lazegalaw$Y[,,2]  
Xd<-lazegalaw$Y[,,-2]
Xn<-lazegalaw$X

dimnames(Xd)[[3]]
dimnames(Xn)[[2]]

netplot(lazegalaw$Y[,,2],ncol=Xn[,3])
@
%\caption{Graph of the friendship network between 71 lawyers. Node colors represent 
%at which of the three offices each lawyer works. } 
%\label{fig:llaw_graph}
%\end{figure}

We first consider fitting a probit SRM model to 
these binary data, without including any explanatory covariates. 
This model can be written as
\begin{align}
z_{i,j} & = \mu + a_i + b_j + \epsilon_{i,j}  \label{eqn:psrm} \\
y_{i,j} & = 1(z_{i,j}>0), 
\end{align}
where the distributions of the random effects $a_i$, $b_j$, 
and $\epsilon_{i,j}$ follow the Gaussian SRM covariance 
model as described previously. 
In words, this model expresses
the observed binary variable $y_{i,j}$ as the indicator that some 
continuous latent variable $z_{i,j}$ exceeds zero. 
Assuming the SRM for the latent variable
yields a model for the observed binary data that allows for 
within-row, within-column and within-dyad dependence. 
This model can be fit with the {\tt ame} command by specifying 
that the variable type is binary:
<<cache=TRUE,fig.keep='none',results='hide'>>=
fit_SRM<-ame(Y,model="bin")
@
It is instructive to compare the fit of this model to that provided 
by a reduced model that lacks the SRM terms:
<<cache=TRUE,fig.keep='none',results='hide'>>=
fit_SRG<-ame(Y,model="bin",rvar=FALSE,cvar=FALSE,dcor=FALSE)  
@
This is a probit model that contains only an intercept, 
and so is equivalent to the simple random graph model (SRG). 
The fits of these two models in terms of the four 
goodness of fit statistics computed by 
{\tt gofstats} are compared in 
Figure 
\ref{fig:ll_fcomp}. 
As might be expected, the SRG fails in terms of all four statistics. 
In contrast, the SRM model provides a good fit in terms 
of the three statistics that represent second-order dependencies. 
Both models fail in terms of representing third-order 
dependence. 

\begin{figure}
<<echo=FALSE,fig.height=3,fig.width=6,fig.align='center'>>=
gY<-gofstats(Y) 

clr<-c(col2rgb("lightblue")/255,.75)
par(mfrow=c(2,2),mar=c(3,3,1,1),mgp=c(1.75,.75,0))
for(k in 1:4)
{
  hist(fit_SRG$GOF[-1,k],main="",yaxt="n",ylab="",prob=TRUE,col="lightgreen",
       xlab=names(gY)[k] ,xlim=range(c(fit_SRM$GOF[,k],fit_SRG$GOF[,k]) ) )
  hist(fit_SRM$GOF[-1,k],prob=TRUE,add=TRUE,
        col=rgb(clr[1],clr[2],clr[3],clr[4])) 

  abline(v=gY[k],col="red")
}
@
\caption{Comparison of SRM (blue) and SRG (green) for the 
Lazega law friendship network.} 
\label{fig:ll_fcomp}
\end{figure}

A common empirical description of row and column heterogeneity 
in network data are 
the row and column sums, typically referred to as the 
\emph{outdegrees} and \emph{indegrees}. 
Based on the form of the model in (\ref{eqn:psrm}),
we might expect that the outdegrees and indegrees would be positively 
associated with the estimates of the $a_i$'s and $b_j$'s 
respectively. For example, the larger $a_i$ is, the larger the 
entries of $z_{i,j}$ for each $j$, thereby making more of the 
$y_{i,j}$'s equal to one rather than zero. 
This relationship between the degrees and the parameter estimates 
is illustrated in Figure 
\ref{fig:ll_degrees}. 
The figure does indeed show a strong positive association between these 
quantities, but note that the relationship is not 
strictly monotonic. The reason for this can be explained
by the fact that it is both the $a_i$ parameters \emph{and} 
the $b_j$ parameters that are used to describe nodal heterogeneity. 
For example, 
suppose two nodes have the same outdegree, but the 
first links to several nodes that have low indegrees, 
whereas a second node links to the same number of 
nodes but ones having high indegrees. 
The first node will have an $a_i$ estimate that is 
higher than that of the second, because the $b_j$'s 
of the nodes that the first links to will be lower 
than those of the nodes that the second links to. 


\begin{figure}
<<echo=FALSE,fig.height=3,fig.width=6,fig.align='center'>>=
par(mfrow=c(1,2),mar=c(3,3,1,1),mgp=c(1.75,.75,0)) 

plot(rowSums(Y,na.rm=TRUE), fit_SRM$APM,xlab="outdegrees",
     ylab="additive row effects")
plot( colSums(Y,na.rm=TRUE), fit_SRM$BPM,xlab="indegrees",
     ylab="additive column effects")
@
%\caption{Comparison of SRM (blue) and SRG (green) for the
%Lazega law friendship network.} 
\caption{Estimated row and column effects versus
outdegrees and indegrees.}
\label{fig:ll_degrees}
\end{figure}

We next consider a probit SRRM that includes the SRM terms
and 
linear regression effects for some 
%binary or  ordinal
 nodal and dyadic covariates. 
%and the other dyadic covariates. 
This model is formulated as 
in the SRM probit model, except that $z_{i,j}$ follows an 
SRRM rather than an SRM. 

<<cache=TRUE,fig.keep='none',results='hide'>>=
Xno<-Xn[,c(1,2,4,5,6)] 
fit_SRRM<-ame(Y, Xd=Xd, Xr=Xno, Xc=Xno, model="bin")  
@ 

<<>>=
summary(fit_SRRM) 
@
There is not much evidence for effects of the 
nodal characteristics, at least in terms of  effects  
that appear linearly in the SRRM. 
Additionally, goodness-of-fit plots 
indicate lack of fit in terms of triadic dependence, 
as with the SRM model. 
Thus, we consider instead a model with the 
``non-significant'' regressors removed, and 
include a rank-3 multiplicative effect. 


<<cache=TRUE,fig.keep='none',results='hide'>>=
fit_AME<-ame(Y, Xd=Xd[,,2], R=3, model="bin")  
@


\begin{figure}
<<echo=FALSE,fig.height=3,fig.width=6,fig.align='center'>>=
par(mfrow=c(2,2),mar=c(3,3,1,1),mgp=c(1.75,.75,0))
for(k in 1:4)
{
  hist(fit_AME$GOF[-1,k],main="",yaxt="n",ylab="",prob=TRUE,col="lightblue",
       xlab=names(gY)[k] ,xlim=range(fit_AME$GOF[,k])  )
  abline(v=gY[k],col="red")
}
@
\caption{ Checks of the fit of the rank-3 AME model to the 
Lazega law friendship network.}
\label{fig:ll_fame3}
\end{figure}


The goodness-of-fit plots in Figure \ref{fig:ll_fame3}
indicate no strong discrepancy between this model and 
the data in terms of these statistics. 
Inference then proceeds via 
examination of the estimates of regression effects, 
random effects and covariance parameters. 
Interpretation of the multiplicative effects 
can proceed by plotting, looking for clusters, and 
identification of nodes with large effects. 
Additionally, it can be useful to look for associations between the 
multiplicative effects and any nodal characteristics available. 
For example, we can compute correlations between the
multiplicative effects $(\bl u_i,\bl v_i)$ and any 
numerical or ordinal nodal characteristics $\bl x_i$. 
Associations between multiplicative effects and categorical variables can be examined via plots. 

<<>>=
U<-fit_AME$U
V<-fit_AME$V 

round(cor(U, Xno),2)
round(cor(V, Xno),2)
@

These correlations, and the plots in 
Figure \ref{fig:ll_fplot}, 
indicate that these nodal characteristics 
do play a role in network formation, although in 
a multiplicative rather than additive manner. 
If desired, one could use these results to 
construct multiplicative functions of these 
nodal attributes for inclusion into a SRRM, 
or possibly an 
AME model of lower rank. 


\begin{figure}
<<echo=FALSE,fig.height=3,fig.width=8.25>>=
par(mfrow=c(1,3),mar=c(3,3,1,1),mgp=c(1.75,.75,0))

xlb<-c(expression(u[1]),expression(u[2]),expression(u[3]) ) 
ylb<-c(expression(v[1]),expression(v[2]),expression(v[3]) ) 
par(mfcol=c(1,3))
for(k in 1:3)
{
  plot(U[,k],V[,k] , xlab=xlb[k],ylab=ylb[k],
  pch=1+(Xn[,1]-1)*15,
  col=Xn[,3]+2 ,
  xlim=range(U),ylim=range(V)) 
  abline(h=0,lty=2,col="gray") ; abline(v=0,lty=2,col="gray")
}
@
\caption{Estimated latent factors plotted in terms of   
the nodal characteristics
  {\tt status} (partner=unfilled circle, associate=filled circle) and 
  {\tt office} (Boston=green, Hartford=blue, Providence=light blue).  }
\label{fig:ll_fplot}
\end{figure}



\subsection{Example: Analysis of an ordinal outcome}
The probit AME model 
for binary data 
extends in a natural way to accommodate 
ordinal data with more than two levels. 
As with binary data, we model the 
sociomatrix $\bl Y =\{ y_{i,j} \}$ as being 
a function of a latent sociomatrix $\bl Z$ 
that follows a Gaussian AME model. Specifically, our model is 
\begin{align}
z_{i,j} & = \beta_d^T \bl x_{d,i,j} + \beta_r^T \bl x_{r,i} +\beta_c^T \bl x_{c,j} +  a_i + b_j +  \epsilon_{i,j} ,   \label{eqn:lame} \\
y_{i,j} & = g( z_{i,j} ) ,  \nonumber
\end{align}
where 
$g$ is some unknown non-decreasing function. 
The {\tt amen} package takes a 
semiparametric approach to this model, 
providing estimation and inference for the
parameters in the model (\ref{eqn:lame}) for $\bl Z$, 
but treating 
the function $g$ as a nuisance parameter. 
This is done using a variant of the 
\emph{extended 
rank likelihood} for ordinal data, described 
in \citet{hoff_2007a} and \citet{hoff_2008b}. 
While this approach is somewhat limiting
(as estimation of $g$ is not specifically provided for), 
it simplifies some aspects of model 
specification and parameter estimation. 
In particular, the semiparametric approach 
allows for 
modeling of 
more general types of ordinal variables  $y_{i,j}$, such as
those that are
continuous, or those for which the number of 
levels is not pre-specified. 
However, we caution that the computation time required by the MCMC 
algorithm used by {\tt amen} is increasing in the number of 
levels of $y_{i,j}$. 


We illustrate this model fitting procedure with an analysis of 
dominance relations between 28 female bighorn sheep, 
available via the {\tt sheep} dataset included with
{\tt amen}. 
The dyadic variable $y_{i,j}$ records the number of times 
sheep $i$ was observed dominating sheep $j$. 

<<>>=
data(sheep) 

Y<-sheep$dom 

gofstats(Y) 
@

Note that the dyadic dependence and triadic dependence 
statistics are negative. This makes sense in light of 
the nature of the variable: 
Heterogeneity among the sheep in terms of strength 
or assertiveness would lead to 
powerful sheep dominating but not being dominated by  others, 
thus leading to negative reciprocity. 
Additionally, under this scenario, if sheep $i$ dominated $j$, 
and $j$ dominated $k$, then it is unlikely that 
$k$ would be able to dominate $i$. Such a scenario would lead to negative 
triadic dependence. 




Data on the ages of the sheep are also available. 
Plots of row and column means versus age are given in 
Figure \ref{fig:sheep}, and indicate some evidence of an 
age effect. Particularly, the number of times that 
a sheep is dominated is decreasing on average with age. 
We examine this effect more fully with a ordinal probit regression, 
fitting a second-degree polynomial in the ages of the sheep:
\begin{figure}
<<echo=FALSE,fig.height=2.75,fig.width=7.5,fig.align='center'>>=
par(mfrow=c(1,3),mar=c(3,3,1,1),mgp=c(1.75,.75,0)) 
hist(Y,main="",col="brown",xlab="number of encounters",ylab="",prob=TRUE)
plot(sheep$age,apply(Y,1,mean,na.rm=TRUE ),xlab="age",ylab="row mean")
plot(sheep$age,apply(Y,2,mean,na.rm=TRUE ),xlab="age",ylab="column mean"  )
@
\caption{Plots of the sheep dominance data. From left to right,
a histogram of the number of dominance encounters,
age versus row mean, and age versus column mean.}
\label{fig:sheep}
\end{figure}
<<cache=TRUE,fig.keep='none',results='hide'>>=
x<-sheep$age - mean(sheep$age)

Xd<-outer(x,x)

Xn<-cbind(x,x^2) ; colnames(Xn)<-c("age","age2") 

fit<-ame(Y, Xd, Xn, Xn, model="ord")
@ 

<<>>=
summary(fit) 
@
The results indicate evidence for a positive effect 
of age on dominance - older sheep are more likely 
to dominate and less likely to be dominated. 
The dyadic effect reflects some residual effect of homophily 
by age: A young sheep's dominance encounters are typically 
with other young sheep, and older sheep are more likely to 
be dominated by another older sheep than a younger sheep. 

Also note that the summary of the model fit does not include an intercept. 
This is because the intercept is not identifiable using the rank likelihood
approach used to obtain the parameter estimates. Specifically, 
an intercept term can be thought of as part of the transformation 
function $g$, which is being treated as a nuisance parameter. 


\section{Censored and fixed rank nomination data}
Data on human social networks are often  
obtained by asking 
members of a study population to name 
a fixed number of people with whom they are friends, 
and possibly  to rank their friends in terms of their affinities. 
Such a survey method is called a \emph{fixed rank nomination} (FRN) 
scheme, and is commonly used in studies of institutions such as 
schools or businesses. For example, 
the National Longitudinal Study of Adolescent Health (AddHealth,
\citet{harris_2009}) asked middle and high-school students to nominate and 
rank up to five members of the same sex as friends, and five members 
of the opposite sex as friends. 

Data obtained from FRN schemes are similar to ordinal data, 
in that the ranks of a person's friends may be viewed as 
an ordinal response. However, FRN data are also censored
in a complicated way. 
Consider a study where people were asked to name and rank up to 
and including their top five friends. If person $i$ 
nominates five people but doesn't nominate person $j$, then $y_{i,j}$ is 
censored: The data cannot tell us whether $j$ is $i$'s sixth best 
friend, or whether $j$ is not liked by $i$ at all. 
On the other hand, if person $i$ nominates four people as friends 
but could have nominated five, then 
person $i$'s data are not censored -  the absence of a nomination 
by $i$ of $j$ indicates that $i$ does not consider $j$ a friend. 

A likelihood-based approach to modeling 
FRN data was developed in 
\citet{hoff_fosdick_volfovsky_stovel_2013}. 
Similar to the approach for ordinal dyadic data described above, 
this methodology treats the observed ranked outcomes $\bl Y$ 
as a function of an underlying continuous sociomatrix $\bl Z$ of affinities 
that 
is generated from an 
AME model. 
Letting $m$ be the maximum number of nominations allowed, and 
coding $y_{i,j} \in \{ m,m-1,\ldots, 1,0\} 
$ so that $y_{i,j}=m$ indicates that $j$ is $i$'s most liked friend, 
the FRN likelihood is derived from the following constraints that the 
observed ranks $\bl Y$ tell us about the underlying dyadic variables $\bl Z$:
\begin{eqnarray}
y_{i,j}> 0 &\Rightarrow & z_{i,j}>0  \label{eqn:porc}\\
y_{i,j}  > y_{i,k} & \Rightarrow &  z_{i,j} > z_{i,k} 
  \label{eqn:rnkc}\\ 
y_{i,j} = 0  \ \mbox{and} \  
 d_i < m &\Rightarrow & 
    z_{i,j}\leq 0  \label{eqn:degc}. 
\end{eqnarray}
Constraint (\ref{eqn:porc}) 
indicates that 
if $i$ ranks $j$, then $i$ has a positive relation with $j$ ($z_{i,j}>0$), 
and constraint (\ref{eqn:rnkc})  indicates that 
a higher rank corresponds to a more positive relation. 
Letting $d_i\in \{ 0,\ldots, m\}$ be the number of people 
that $i$ ranks, constraint (\ref{eqn:degc})  
indicates that if 
$i$ could have made additional friendship nominations 
but chose not to nominate $j$, 
they then must not consider $j$ a friend. 
On the other hand, if
$y_{i,j}=0$ but $d_i = m$ then person $i$'s unranked relationships
are censored, and so $z_{i,j}$ could be positive
even though
$y_{i,j}=0$.  In this case, all that is known about
$z_{i,j}$ is that it is less than $z_{i,k}$ for any person
$k$ that is ranked by $i$.

\subsection{Example: Analysis of fixed rank nomination data}
The {\tt amen} package implements a Bayesian model fitting 
algorithm based on the FRN likelihood. 
We illustrate its use with an analysis of  data from the classic 
study on relationships  between monks 
described in \citet{sampson_1969}, in which each monk was asked to rank 
up to three other monks in terms of a variety of relations. 
<<>>=
Y<-sampsonmonks[,,3] 

apply(Y>0,1,sum,na.rm=T)
@
Notice that two of the monks didn't follow the survey instructions, and 
nominated more than three other monks. We treat the maximum 
number of nominations for these two monks as four. 
This can be done using the {\tt ame} fitting function, and 
specifying the FRN likelihood and the number of maximum nominations as follows:
<<cache=TRUE,fig.keep='none',results='hide'>>=
odmax<-rep(3,nrow(Y)) 
odmax[ apply(Y>0,1,sum,na.rm=T)>3 ]<-4 

fit<-ame(Y,R=2,model="frn",odmax=odmax) 
@

<<>>=
summary(fit) 
@

Goodness of fit plots for these data appear in Figure 
\ref{fig:smonk}. Notice that the fit in terms of row heterogeneity is 
very good. This is not too surprising: 
The simulated sociomatrices used to produce this plot 
are generated to satisfy the constraint imposed 
the outdegree constraint imposed by {\tt odmax}, which 
greatly limits the possible amount of outdegree heterogeneity. 

\begin{figure}
<<echo=FALSE,fig.height=6,fig.width=5,fig.align='center'>>=
plot(fit)
@
\caption{Model fitting plots for Sampson's monk data.} 
\label{fig:smonk}
\end{figure}

\subsection{Other approaches to censored or ranked data}
Some dyadic survey designs ask participants to nominate 
up to a certain number of friends, but not to rank them. Such dyadic data
are binary, but censored in the same way as are data from an FRN survey: 
Observing that $y_{i,j}=0$ indicates that $i$ is not friends with $j$ 
only if person $i$ has made less than the maximum number  of nominations. 
A likelihood-based approach to analyzing such 
censored binary data is described in 
\citet{hoff_fosdick_volfovsky_stovel_2013} and 
is also implemented in the {\tt amen} package
using the {\tt model="cbin"} option in the 
{\tt ame} command. 

In other situations the dyadic outcomes in each 
row are ordinal, but on completely different scales. 
In such cases, we may wish to treat the heterogeneity of 
ties across rows in a semiparametric way, and only 
estimate the parameters in the AME model based on the 
ranks of the outcomes within each row.  
This can be done by using a likelihood 
for which the ordinal dyadic data $\bl Y$ only imposes 
constraint (\ref{eqn:rnkc}) on the unobserved underlying 
variables  $\bl Z$.  
This ``relative rank likelihood'' is described more fully in 
\citet{hoff_fosdick_volfovsky_stovel_2013}, 
and can be implemented in {\tt amen} using the {\tt model="rrl"} option in the
{\tt ame} command.



\section{Sampled or missing dyadic data}
Some dyadic datasets are only partially observed, in that 
the value of $y_{i,j}$ is not observed for all pairs 
$i,j$.  This can happen unintentionally or by design. 
For example, to avoid the cost of measuring $y_{i,j}$ for 
all $n(n-1)$ pairs of nodes, some researchers will use 
multi-stage link-tracing designs, in which 
nodes are selected into the study in one stage of the 
design based on their links to nodes included in previous 
stages. 


Given a nodeset, partially observed dyadic data 
can be represented by a sociomatrix in which the 
pairs for which data are not observed  are distinguished 
from pairs for which data are observed. 
In {\sf R}, this is done by 
filling each entry of the sociomatrix 
corresponding to a missing value with an ``{\tt NA}''. 
Doing so distinguishes
pairs $i,j$ for which we do not know the  dyadic value 
$(y_{i,j} = {\tt NA})$ from those, for example,  
for which we know there is no link $(y_{i,j}=0)$. 

When some (non-diagonal) entries of the sociomatrix $\bl Y$ are missing, 
the MCMC approximation algorithm used by {\tt amen}
proceeds by iteratively simulating
model parameters 
along with 
values for the missing values in a way that 
approximates their joint posterior distribution.
Roughly speaking, at each iteration  of the MCMC algorithm, 
values for the missing values are simulated from 
their probability distribution conditional on the observed 
data and the current values of the model parameters. 
Such a procedure is appropriate if the missing values 
are \emph{missing at random}, or more specifically, if the 
study design is \emph{ignorable}. 
A study design is ignorable if 
the probability that the variable value for a dyad is 
missing is independent of the model parameters and missing 
values, conditional on the observed data values. 
Many types of link tracing designs, such as egocentric and snowball sampling, 
are ignorable \citep{thompson_frank_2000}. 

\subsection{Example: Analysis of an egocentric sample}
One popular and relatively inexpensive design for gathering 
dyadic data is with an egocentric sample, in which nodes 
(or ``egos'') are randomly sampled from a population and then 
asked about their ties and the ties between their friends. For example, 
one type of egocentric study design might ask participants
``whom are you friends with'' and ``which of your friends are friends 
with each other.''  Data from such a design can be sufficient to estimate 
parameters in an AME model. 

We illustrate this with an example analysis of the effect of 
sex (male/female) on friendships among a small group of Dutch college 
students, available in {\tt amen} from the {\tt dutchcollege} dataset. 
<<cache=TRUE,fig.keep='last',results='hide'>>=
data(dutchcollege) 

Y<-1*( dutchcollege$Y[,,7] > 1 ) # indicator of positive relationship at the last timepoint

Xn<-dutchcollege$X[,1]           # nodal indicator of male sex
Xd<-1*(outer(Xn,Xn,"=="))        # dyadic indicator of same sex
@

We will fit a simple SRRM to these data, and then compare the resulting parameter
estimates to those based on data obtained 
from the egocentric design described above.
In our design, we 
first randomly sample several nodes (egos), 
record their relationships to the other nodes, and then 
record the relationships between alters having a common ego. 
{\sf R}-code that generates such a design is as follows:
<<echo=FALSE>>= 
set.seed(3) 
@
<<>>=
n<-nrow(Y) 
Ys<-matrix(NA,n,n)      # sociomatrix for sampled data

egos<-sort(sample(n,5)) # ego sample
Ys[egos,]<-Y[egos,]     # relations of egos are observed

for(i in egos)
{ 
  ai<-which(Ys[i,]==1)  # alters of i  
  Ys[ai,ai]<-Y[ai,ai]   # relations between alters of i are observed
} 

mean(is.na(Ys)) 
@
This particular instance of the design results in a sociomatrix 
where about \Sexpr{round(100*mean(is.na(Ys)))} 
percent of the entries are missing
(note that the diagonal is  already ``missing'' by definition). 
Under this design, relations between alters and non-alters
are missing, as are relations between alters that do not share an ego.
<<>>=
egos
Ys[1:10,1:10]
@

We now fit an SRRM  model to the complete data and the subsampled data, and compare 
parameter estimates. 
<<cache=TRUE,fig.keep='none',results='hide'>>=
fit_pop<-ame(Y,Xd,Xn,Xn,model="bin")   # fit based on full data (population) 

fit_ess<-ame(Ys,Xd,Xn,Xn,model="bin")  # fit based on egocentric subsample
@


<<>>=
apply(fit_pop$BETA,2,mean)

apply(fit_ess$BETA,2,mean)
@
The estimates  are similar, even though the second fit is from  
a dataset with \Sexpr{round(100*mean(is.na(Ys)))} 
missing values. 

%\begin{figure}
%<<echo=FALSE,fig.height=2.5, fig.width=3,fig.align='center'>>=
%yobs<-c(Y[is.na(Ys)])
%yprd<-c(fit_ess$YPM[is.na(Ys)] ) 
%par(mar=c(3,3,1,1),mgp=c(1.75,.75,0))
%boxplot(yprd~yobs,xlab="true relational value",ylab="predicted relational value") 
%@
%\caption{Boxplots of predictive probabilities of a friendship 
%link between pairs for which the true value of the relation 
%is missing, using an incomplete egocentrically-sampled dataset.} 
%\label{fig:ess_pp}
%\end{figure}


The output of the {\tt ame} fitting procedure also includes a posterior 
predictive mean for all entries of the sociomatrix $\bl Y$, 
including those entries for which the data are missing. 
This sociomatrix of predicted values can be used for prediction 
or imputation of dyadic data from 
incomplete datasets. In our example on modeling friendship 
relations from the {\tt dutchcollege} dataset, we can 
use this sociomatrix of predicted values to evaluate 
how well the parameter estimates obtained from  the sampled dataset  
compare to those obtained from the full dataset, in terms of 
prediction:
<<>>=
miss<-which(is.na(Ys)) 

mean( ( fit_pop$YPM[miss] - Y[miss] )^2, na.rm=TRUE ) 

mean( ( fit_ess$YPM[miss] - Y[miss] )^2, na.rm=TRUE )
@
The first and second numbers reflects ``within-sample'' 
and ``out-of-sample'' goodness of fit, respectively. The 
small discrepancy between these numbers indicates that
reasonable parameter estimates  for this model 
(in terms of out-of-sample predictive squared error) can be obtained from 
this egocentric sample. 






<<mdsimstudy,cache=TRUE,echo=FALSE,results='hide'>>=
BETA_SS<-NULL
for(sim in 1:100)
{ 
  set.seed(sim) 
  Ys<-matrix(NA,n,n)      # sociomatrix for sampled data
  s<-sort(sample(n,5))    # ego sample
  Ys[s,]<-Y[s,]           # relations of egos are observed
  for(i in s)
  {
    ai<-which(Ys[i,]==1)  # alters of i  
    Ys[ai,ai]<-Y[ai,ai]   # relations between alters of i are observed
  }
  fit<-ame(Ys,Xd,Xn,Xn,nscan=5000,model="bin",print=FALSE,plot=FALSE,gof=FALSE) 
  BETA_SS<-rbind(BETA_SS,apply(fit$BETA,2,mean))
  cat(sim,"\n") 
}
@  


Finally, we consider the variability of the  parameter estimates 
across egocentric samples with a small simulation study: For each 
of 100 egocentric samples randomly generated as previously described, we obtained 
parameter estimates for the probit SRRM, 
\begin{align*} 
z_{i,j} &= \beta_0 +\beta_r x_i+\beta_c x_j +\beta_d x_{i,j}+\epsilon_{i,j}\\
y_{i,j} &= 1( z_{i,j}>0 ),
\end{align*}
where $x_i$ is a binary indicator that node $i$ is male, 
and $x_{i,j}$ is the indicator that $i$ and $j$ are of the same sex. 
The variability of the parameter estimates across
egocentric samples are  illustrated with histograms in 
Figure \ref{fig:ess_betas}. An illustrative exercise would be to 
see how increasing or decreasing the amount of missing data in the samples 
(by increasing or decreasing the number of egos sampled) would 
affect the concentration of the egocentric estimates around the 
population estimates. 

\begin{figure}
<<echo=FALSE,fig.height=4,fig.width=7,fig.align='center'>>=
cnames<-c(expression(beta[0]),expression(beta[r]), expression(beta[c]),
          expression(beta[d])) 
beta_pop<-apply(fit_pop$BETA,2,mean) 
par(mfrow=c(2,2),mar=c(3,3,1,1),mgp=c(1.75,.75,0))
for(k in 1:4)
{
  hist( BETA_SS[,k] ,col="lightgreen", main="",ylab="",xlab=cnames[k],yaxt="n",
         xlim=1.2*range(c(beta_pop[k],BETA_SS[,k])) ) 
  abline(v=beta_pop[k],lwd=2,col="blue")
}
@
\caption{Variability of probit SRRM regression estimates across 
egocentric samples. Vertical blue  lines indicate the estimates 
obtained from the full (population) dataset. }
\label{fig:ess_betas}
\end{figure}







\section{Repeated measures data}
Some types of dynamic dyadic datasets include 
repeated measurements of dyadic 
and nodal variables at discrete points in time. 
The {\tt amen} package provides a rudimentary 
method of analyzing such data, 
based on the following simple extension of the 
AME model to accommodate 
replicated dyadic measurements:
For (latent) sociomatrices $\bl Z_1,\ldots, \bl Z_T$, 
the model expresses $z_{i,j,t}$, the $(i,j)$th element of the
$t$th sociomatrix, as 
\begin{equation} 
z_{i,j,t} =  \beta_d^T\bl x_{d,i,j,t} +
 \beta_r^T\bl x_{r,i,j,t} +\beta_c^T\bl x_{c,i,j,t} + 
a_i +b_j + \bl u_i^T \bl v_j + \epsilon_{i,j,t}. 
\label{eqn:llame}
\end{equation}
Across nodes, dyads and time points,  this model extension  further
assumes the same covariance model for the random effects  $\{(a_i,b_i)\}$ 
as before, 
allows for 
dyadic correlation between $\epsilon_{i,j,t}$ and  
$\epsilon_{j,i,t}$ as before, but 
assumes 
$\epsilon_{i,j,t}$'s that involve 
different dyads \emph{or} different time points are independent. 
In other words, the data under this 
model are treated as 
independent observations from a common AME distribution. 

At first glance it may seem that such a model is inappropriate for 
dynamic dyadic data, as it doesn't seem to allow for the 
possibility of dependence over time. 
However, 
certain types of dependence can be incorporated into this model 
via the 
time-dependent 
regression terms. For example, autoregressive
dependence can be modeled by including lagged values of the 
sociomatrix as regressors. Additionally, 
time-varying regression parameters can be included in the 
model by construction of interactions. 


\subsection{Example: Analysis of a longitudinal binary outcome}

We illustrate these possibilities with an analysis 
of data from the longitudinal study of friendship relations 
among a small group of Dutch college students, available 
in {\tt amen} via the {\tt dutchcollege} dataset. 
Our response $y_{i,j,t}$ is the indicator that  
person $i$ reports being friendly (or having friendship) 
with person $j$ at time point 
$t$. 
The graphs of this variable for each of  the seven different time points 
in the dataset are given in 
Figure \ref{fig:dcln}. 
\begin{figure}
<<echo=FALSE,fig.height=3,fig.width=7>>=
data(dutchcollege) 

Y<-1*( dutchcollege$Y >= 2 ) 
xnode<-xnet(Y[,,dim(Y)[3]],fm=FALSE)
xnode[18,]<-.5*( xnode[18,] + apply(xnode[-18,],2,mean))
par(mar=c(1,1,1.25,1),mgp=c(1.75,75,0),mfrow=c(2,4))
for(k in 1:dim(Y)[3])
{
  netplot(Y[,,k],xnode)  
  mtext(side=3,paste("Time",k-1)) 
}
@
\caption{Friendliness network of the Dutch college students, 
across seven time points.} 
\label{fig:dcln}
\end{figure}
The figure reflects the fact that 
the students were mostly unknown to each other before the 
study period, and so not surprisingly, the densities of the graphs
increase over time. 

The data also include (static) information on 
the sex and smoking status of the students, as 
well as which one of three programs each student was a member. 
We will examine the effects of these nodal 
attributes on friendship in using a probit 
SRRM, where $y_{i,j,t}$ is modeled 
as the indicator that the latent affinity 
$z_{i,j,t}$ exceeds zero, where 
$z_{i,j,t}$ follows model 
(\ref{eqn:llame}). 
Our analysis will include the 
binary indicators of male sex and 
smoking status as row and column regressors, 
products of these variables as dyadic regressors, 
and a dyadic binary indicator of whether or 
not members of a dyad belong to the same program.  
Finally, we will also include lagged values 
$y_{i,j,t-1}$ and $y_{j,i,t-1}$ as dyadic predictors
of $z_{i,j,t}$ to
reflect the possibility of temporal dependence among 
values  within a dyad.  To summarize, our model 
for the $z_{i,j,t}$'s is as follows:
\begin{align*}
 z_{i,j,t}  = &   \beta_0 +  \\ 
 & \beta_{r,1} \text{male}_i + \beta_{r,2} \text{smoke}_i +  \\
 & \beta_{c,1} \text{male}_j + \beta_{c,2} \text{smoke}_j +  \\
 & \beta_{d_1} y_{i,j,t-1} + \beta_{d_2} y_{j,i,t-1} +  \\
 & \beta_{d_3} \text{male}_i \text{male}_j +
  \beta_{d_4} \text{smoke}_i \text{smoke}_j + 
  \beta_{d_5} \text{sameprogram}_{i,j} +  \\
 &  a_i +b_j + \epsilon_{i,j,t} 
\end{align*}

The {\tt ame\_rep} function in the {\tt amen} package 
provides parameter estimation and inference  for this model
using a similar syntax as the {\tt ame} function, 
except now the 
nodal attributes {\tt Xrow} and {\tt Xcol} are
three-dimensional arrays, with dimensions corresponding 
to nodes, variables and time points, respectively, 
and the dyadic regressor array {\tt Xdyad} is now four-dimensional, 
 with dimensions corresponding 
to nodes, nodes,  variables and time points. 
These arrays for this data analysis can be set up as follows:
<<>>=
# outcome
Y<-1*( dutchcollege$Y >= 2 )[,,2:7]                    
n<-dim(Y)[1] ; t<-dim(Y)[3]

# nodal covariates
Xnode<-dutchcollege$X[,1:2]                                       # sex and smoking status
Xnode<-array(Xnode,dim=c(n,ncol(Xnode),t))
dimnames(Xnode)[[2]]<-c("male","smoker")

# dyadic covariates
Xdyad<-array(dim=c(n,n,5,t))        
Xdyad[,,1,]<-1*( dutchcollege$Y >= 2 )[,,1:6]                     # lagged value
Xdyad[,,2,]<-array(apply(Xdyad[,,1,],3,t),dim=c(n,n,t))           # lagged reciprocal value 
Xdyad[,,3,]<-tcrossprod(Xnode[,1,1])                              # both male
Xdyad[,,4,]<-tcrossprod(Xnode[,2,1])                              # both smokers 
Xdyad[,,5,]<-outer( dutchcollege$X[,3],dutchcollege$X[,3],"==")   # same program
dimnames(Xdyad)[[3]]<-c("Ylag","tYlag","bothmale","bothsmoke","sameprog")
@

The model can be fit using the same syntax as the 
{\tt ame} command discussed previously, and results can 
summarized before with the {\tt summary} function:
<<dc_ar1, cache=TRUE,fig.keep='none',results='hide'>>=
fit_ar1<-ame_rep(Y,Xdyad,Xnode,Xnode,model="bin",plot=FALSE)
@

<<>>=
summary(fit_ar1) 
@
The 
parameter estimates and standard deviations for 
$\beta_{d,1}$ and $\beta_{d,2}$ ({\tt Ylag.dyad} and 
{\tt tYlag.dyad} in the output) 
indicate strong evidence 
of large 
temporal correlation. 
There also appears to be strong homophily effects in 
terms of sex, smoking status and program. 
The nodal effect parameters indicate some evidence 
that smokers are a bit less social than non-smokers. 

Finally, we note that the time interval between 
the first four measurements was three weeks, whereas the 
interval between the last three measurements was six weeks. 
As such, we may want to consider whether or not the 
effects of the regressors might vary depending on the 
measurement. Such a possibility can be evaluated simply 
by adding interaction terms to the regressors. 
For example, to evaluate whether or not the effect of 
$y_{i,j,t-1}$ on $z_{i,j,t}$ varies with measurement interval, 
we can create a new dyadic covariate 
$y_{i,j,t-1} w_{t}$ where 
$w_t$ is a binary indicator that $t$ is in the 
among the last three measurements. 
Adding such terms for all of our regressors can be done as follows:
<<>>=
Wnode<-Xnode 
Wnode[,,1:3]<-0 

XWnode<-array( dim=dim(Xnode)+c(0,2,0))
XWnode[,1:2,]<-Xnode ; XWnode[,3:4,]<-Wnode
dimnames(XWnode)[[2]]<-c(dimnames(Xnode)[[2]],paste0(dimnames(Xnode)[[2]],".w"))


Wdyad<-Xdyad 
Wdyad[,,,1:3]<-0 
XWdyad<-array( dim=dim(Xdyad)+c(0,0,5,0) ) 
XWdyad[,,1:5,]<-Xdyad ; XWdyad[,,6:10,]<-Wdyad 
dimnames(XWdyad)[[3]]<-c(dimnames(Xdyad)[[3]],paste0(dimnames(Xdyad)[[3]],".w"))
@

<<dc_ar1_vb, cache=TRUE,fig.keep='none',results='hide'>>=
fit_ar1_vb<-ame_rep(Y,XWdyad,XWnode,XWnode,model="bin") 
@

<<>>=
summary(fit_ar1_vb) 
@
These results do not indicate much evidence that the 
regression coefficients should vary by time period, 
except possibly the effect on the lagged 
dyadic variable $y_{i,j,t}$. The negative 
estimate of this coefficient 
(corresponding to {\tt Ylag.w.dyad} in the output) 
makes sense, 
as it 
indicates  that the effect of the lagged variable is 
decreased when the interval between times points is longer. 



\section{Symmetric data}
It is sometimes the case that dyadic
observations are \emph{symmetric} or 
\emph{undirected} by design, in that there is 
only one  value $y_{i,j}$ for the 
dyad $\{i,j\}$. Such observations can 
be represented by a 
symmetric sociomatrix $\bl Y$, so that 
$y_{i,j}= y_{j,i}$ for all dyads $\{i,j\}$. 
In this case, 
a natural simplification of the AME  model 
(\ref{eqn:ame})  is given by 
\begin{align}
 y_{i,j}  & = \beta_d^T \bl x_{i,j} + \beta_n^T ( \bl x_{i} + \bl x_{j} ) +  a_i + a_j +  \bl u_i^T \bl \Lambda  \bl u_j +  \epsilon_{i,j} ,  \label{eqn:same}  \\ 
 a_1,\ldots, a_n & \sim  \text{i.i.d.} \  N(0,\sigma^2_a) \nonumber  \\
 \{ \epsilon_{i,j} \}  & \sim  \text{i.i.d.}  \ N(0,\sigma^2_e),  \nonumber
\end{align}
for $i<j$, with $y_{j,i} = y_{i,j}$ by design. 
Most of the simplifications leading to this symmetric case are 
easy to understand, with the possible exception of the 
change from $\bl u_i^T\bl v_j$ in the asymmetric case 
to $\bl u_i^T \bs \Lambda \bl u_j$ here. 
In the former case, this representation can be justified 
by the singular value decomposition theorem, 
%a theorem 
%from linear algebra that states that 
which states that
any $n\times n$ rank-$R$ matrix $\bl M$ can be expressed 
as $\bl U \bl V^T$, where 
$\bl U$ and $\bl V$ are  ${n\times R}$ matrices. 
This means that $m_{i,j}$, the $i,j$th entry of $\bl M$ 
can be expressed as $m_{i,j} = \bl u_i^T \bl v_j$, where 
$\bl u_i$ and $\bl v_j$ are the $i$th and $j$th rows of 
$\bl U$ and $\bl V$, respectively. 
In other words, the $\bl u_i^T\bl v_j$ 
in the asymmetric AME model can represent any residual 
low-rank patterns $\bl M$ in the sociomatrix  $\bl Y$ that aren't explained 
by the known regressors. 
Similarly, in the symmetric case 
the term $\bl u_i^T \bs \Lambda \bl u_j$ in 
(\ref{eqn:same}) can represent any residual low-rank patterns 
$\bl M$  in the symmetric sociomatrix $\bl Y$. 
This follows from the eigenvalue decomposition theorem, 
which states that 
any symmetric rank-$R$
matrix $\bl M$ can be expressed as $\bl U \bs \Lambda \bl U^T$, or 
equivalently, 
the elements $m_{i,j}$ of $\bl M$ 
can be expressed as 
$m_{i,j} = \bl  u_i^T \bs \Lambda \bl u_j$. 
Furthermore, as with the asymmetric case, 
such a latent factor model can
represent patterns of transitivity and stochastic equivalence 
in network data \citep{hoff_2008}. 

\subsection{Example: Analysis of a symmetric ordinal outcome}


Symmetric versions of the  normal, probit and other AME models discussed  
in the previous sections can be fit using the {\tt ame} command 
by simply specifying the option  {\tt symmetric=TRUE}. 
We illustrate the use of this option with an analysis 
of Cold War cooperation and conflict data, available 
via the {\tt coldwar} dataset. 
These data include 
dyadic 
 counts of military cooperation and conflict between countries, 
geographic distances between countries, 
and country-level measures of GDP and polity. 
These variables were recorded every five years from 1950 to 1985. 
For simplicity, we analyze a time-averaged version of the dataset:
<<>>=
data(coldwar)

# response
Y<-sign( apply(coldwar$cc,c(1,2), mean ) )         

# nodal covariates
Xn<-cbind( apply( log(coldwar$gdp),1,mean ) ,       # log gdp
           sign(apply(coldwar$polity ,1,mean ) ) )  # sign of polity      
Xn[,1]<-Xn[,1]-mean(Xn[,1]) 
dimnames(Xn)[[2]]<-c("lgdp","polity")

# dyadic covariates
Xd<-array(dim=c(nrow(Y),nrow(Y),3))
Xd[,,1]<- tcrossprod(Xn[,1])                        # gdp interaction
Xd[,,2]<- tcrossprod(Xn[,2])                        # polity interaction
Xd[,,3]<-log(coldwar$distance)                      # log distance
dimnames(Xd)[[3]]<-c("igdp","ipol","ldist") 
@

The response $y_{i,j}$ takes values in $\{-1,0,1\}$. 
As such, we view this as an ordinal outcome, to  which 
we fit an  ordinal version of a rank-1 symmetric  AME  model 
 using the {\tt ame} command:
<<cwfitR1,cache=TRUE,fig.keep='none',results='hide'>>=
fit_cw_R1<-ame(Y,Xd,Xn,R=1,model="ord",symmetric=TRUE,burn=1000,nscan=100000,odens=100)
@ 

%<<cwfitR2,cache=TRUE,fig.keep='none',results='hide'>>=
%fit_cw_R2<-ame(Y,Xd,Xn,R=2,model="ord",symmetric=TRUE,burn=1000,nscan=100000,odens=100)
%@


\begin{figure}
<<echo=FALSE>>=
plot(fit_cw_R1)
#plot(fit_cw_R2)
@
\caption{Diagnostic plots for the rank-1 AME model of the {\tt coldwar} data.}
\end{figure}


Note that for this symmetric model, 
the row regressors must be the same as the 
column regressors, and so it is sufficient to 
specify these just once. 
We also note that for technical reasons, the mixing  of the MCMC 
algorithm for estimating the low-rank matrix 
$\bl U \bs \Lambda \bl U^T$ is slower than that 
for the asymmetric matrix $\bl U\bl V^T$. For this reason
we lengthened the burn-in period for the Markov chain, and increased 
the number of iterations to 20,000 from the default value of 10,000. 

<<>>=
summary(fit_cw_R1) 

fit_cw_R1$L       # eigenvalues
@
The results indicate no strong association between 
country-specific levels  of $z_{i,j}$ 
with the nodal attributes. 
At the dyadic level however, 
there appears to be homophily in terms of 
polity. 
Furthermore, 
the parameter for {\tt ldist.dyad} suggests that 
large geographic distance is positively associated 
with cooperation. However,  a better interpretation might be 
that large distance is negatively associated 
with conflict, as most conflicts are regional.
More refined hypotheses abut conflict and 
cooperation could be evaluated by 
fitting separate models 
for the conflict network $(y_{i,j}<0)$  and the 
cooperation network $(y_{i,j}>0)$. 



We now describe the estimate of
the low-rank latent factor term $\bl U \bs\Lambda \bl U^T$. 
This term describes heterogeneity in the dataset that is not 
explained by the nodal or dyadic regressors, or the terms in the 
social relations covariance model.  
As shown above, 
the estimated ``eigenvalue'' {\tt fit\_cw\$L} is positive.
Since $y_{i,j}$ is increasing in $\bl u_i^T \bs \Lambda \bl u_j$
 (which is  $\lambda u_i u_j$  in this rank-1 model) 
%the fact that the entries of $\bl \Lambda$ are both positive
this means that countries that cooperate should 
on average have 
estimated  $\bl u$-vectors pointing in the same 
direction, and countries in conflict 
should have estimates pointing in opposite directions. 
A plot of the latent factors in 
Figure \ref{fig:cwfplot} confirms this, showing that 
cooperative pairs (linked by green lines) 
 essentially all have $u$-values that are on the same side of the origin
(the one exception involves  Egypt, which was cooperative with both the 
USA and USSR). 
Conflictual pairs (linked by red lines)
are generally on opposite sides of the origin. 


%\begin{figure}
%<<echo=FALSE,fig.height=5,fig.width=5,fig.align='center'>>=
%set.seed(1) 
%circplot(Y>0, fit_cw$U,lcol="green",jitter=.2) 
%set.seed(1) 
%circplot(Y<0, fit_cw$U,lcol="red",add=TRUE,jitter=.2)
%@
%\caption{Latent factor plot for the {\tt coldwar} analysis. 
%Green  and red lines indicate cooperation and conflict, 
%respectively.} 
%\label{fig:cwfplot}
%\end{figure}


\begin{figure}
<<fig.height=5,fig.width=7,echo=FALSE>>=
u<-fit_cw_R1$U
cnames<-rownames(u)
urank<-rank(u) 

plot(urank,u,type="n",xlab="rank order of u")
abline(h=0,col="gray") 
addlines(Y>0 , cbind(urank,u),col="green")
addlines(Y<0 , cbind(urank,u),col="pink")
text(urank,u,cnames,srt=-45,cex=1.0) 
@
\caption{One-dimensional latent factor plot for the {\tt coldwar} analysis. 
Green  and red lines indicate cooperation and conflict, 
respectively.} 
\label{fig:cwfplot}
\end{figure}


%\bibliographystyle{chicago}
%\bibliography{/Users/pdhoff/Cloud/Common/refs}
%\bibliography{amen}

\begin{thebibliography}{}

\bibitem[\protect\citeauthoryear{Bradu and Gabriel}{Bradu and
  Gabriel}{1974}]{bradu_gabriel_1974}
Bradu, D. and K.~R. Gabriel (1974).
\newblock Simultaneous statistical inference on interactions in two-way
  analysis of variance.
\newblock {\em J. Amer. Statist. Assoc.\/}~{\em 69}, 428--436.

\bibitem[\protect\citeauthoryear{Gollob}{Gollob}{1968}]{gollob_1968}
Gollob, H.~F. (1968).
\newblock A statistical model which combines features of factor analytic and
  analysis of variance techniques.
\newblock {\em Psychometrika\/}~{\em 33}, 73--115.

\bibitem[\protect\citeauthoryear{Harris, Halpern, Whitsel, Hussey, Tabor,
  Entzel, and Udry}{Harris et~al.}{2009}]{harris_2009}
Harris, K., C.~Halpern, E.~Whitsel, J.~Hussey, J.~Tabor, P.~Entzel, and J.~Udry
  (2009).
\newblock The national longitudinal study of adolescent health: Research
  design.

\bibitem[\protect\citeauthoryear{Hoff, Fosdick, Volfovsky, and Stovel}{Hoff
  et~al.}{2013}]{hoff_fosdick_volfovsky_stovel_2013}
Hoff, P., B.~Fosdick, A.~Volfovsky, and K.~Stovel (2013).
\newblock Likelihoods for fixed rank nomination networks.
\newblock {\em Network Science\/}~{\em 1\/}(3), 253--277.

\bibitem[\protect\citeauthoryear{Hoff}{Hoff}{2005}]{hoff_2005a}
Hoff, P.~D. (2005).
\newblock Bilinear mixed-effects models for dyadic data.
\newblock {\em J. Amer. Statist. Assoc.\/}~{\em 100\/}(469), 286--295.

\bibitem[\protect\citeauthoryear{Hoff}{Hoff}{2007}]{hoff_2007a}
Hoff, P.~D. (2007).
\newblock Extending the rank likelihood for semiparametric copula estimation.
\newblock {\em Ann. Appl. Stat.\/}~{\em 1\/}(1), 265--283.

\bibitem[\protect\citeauthoryear{Hoff}{Hoff}{2008a}]{hoff_2008}
Hoff, P.~D. (2008a).
\newblock Modeling homophily and stochastic equivalence in symmetric relational
  data.
\newblock In J.~Platt, D.~Koller, Y.~Singer, and S.~Roweis (Eds.), {\em
  Advances in Neural Information Processing Systems 20}, pp.\  657--664.
  Cambridge, MA: MIT Press.

\bibitem[\protect\citeauthoryear{Hoff}{Hoff}{2008b}]{hoff_2008b}
Hoff, P.~D. (2008b).
\newblock Rank likelihood estimation for continuous and discrete data.
\newblock {\em ISBA Bulletin\/}~{\em 15\/}(1), 8--10.

\bibitem[\protect\citeauthoryear{Hoff}{Hoff}{2009}]{hoff_2009c}
Hoff, P.~D. (2009).
\newblock Multiplicative latent factor models for description and prediction of
  social networks.
\newblock {\em Computational and Mathematical Organization Theory\/}~{\em
  15\/}(4), 261--272.

\bibitem[\protect\citeauthoryear{Li and Loken}{Li and
  Loken}{2002}]{li_loken_2002}
Li, H. and E.~Loken (2002).
\newblock A unified theory of statistical analysis and inference for variance
  component models for dyadic data.
\newblock {\em Statist. Sinica\/}~{\em 12\/}(2), 519--535.

\bibitem[\protect\citeauthoryear{Sampson}{Sampson}{1969}]{sampson_1969}
Sampson, S. (1969).
\newblock Crisis in a cloister.
\newblock {\em Unpublished doctoral dissertation, Cornell University\/}.

\bibitem[\protect\citeauthoryear{Thompson and Frank}{Thompson and
  Frank}{2000}]{thompson_frank_2000}
Thompson, S.~K. and O.~Frank (2000).
\newblock Model-based estimation with link-tracing sampling designs.
\newblock {\em Survey Methodology\/}~{\em 26\/}(1), 87--98.

\bibitem[\protect\citeauthoryear{Warner, Kenny, and Stoto}{Warner
  et~al.}{1979}]{warner_kenny_stoto_1979}
Warner, R., D.~A. Kenny, and M.~Stoto (1979).
\newblock A new round robin analysis of variance for social interaction data.
\newblock {\em Journal of Personality and Social Psychology\/}~{\em 37},
  1742--1757.

\bibitem[\protect\citeauthoryear{Wong}{Wong}{1982}]{wong_1982}
Wong, G.~Y. (1982).
\newblock Round robin analysis of variance via maximum likelihood.
\newblock {\em J. Amer. Statist. Assoc.\/}~{\em 77\/}(380), 714--724.

\end{thebibliography}




\end{document} 



