\documentclass[a4paper,11pt]{article} \renewcommand{\baselinestretch}{1} %\usepackage[a4paper,top=2.5cm,bottom=2.5cm,left=2.5cm,right=2.5cm]{geometry} \usepackage[top=2.6cm, bottom=3cm, left=2.5cm, right=3cm]{geometry} %\linespread{2} %\usepackage[top=2.5cm, bottom=2.5cm, outer=4.5cm, inner=2cm, heightrounded, marginparwidth=2.5cm, marginparsep=0.5cm]{geometry} \usepackage{graphicx} \usepackage{color} \usepackage{natbib} \renewcommand\labelitemi{--} \renewcommand\labelitemii{--} \renewcommand\labelitemiii{-} \newcommand{\sfn}[1]{\textsf{#1}} \newcommand{\SI}{{\sf SIENA }} \setlength{\bibsep}{0.02in} \renewcommand\bibsection{\section{\refname}} \usepackage{listings} \usepackage{bera} \lstset{basicstyle=\ttfamily, escapeinside={||}, mathescape=true} \title{Changes in RSiena for implementing the GMoM} \author{Viviana Amati} \date{February 2021} \begin{document} \maketitle This file reports all the changes that have been implemented in\texttt{ RSiena} for the GMoM estimation. Changes for the Robbins-Monro algorithm concern mainly the R code, while changes for the definition of the statistics concern the C++ code. \subsection*{Folder Data} Basic GMoM effects have been included in the file \texttt{alleffects.csv}. They are fixed by default to 0 because the GMoM statistics are only used to evaluate the moment conditions and are not part of the probability model. \subsection*{Folder src} \begin{itemize} \item Added the files for the computation of the statistics for the network evolution only in the folder model/effects\\ (Files: \texttt{AgreementTransitivityGMMEffect.h, RealTransitivityGMMEffect.h},\\\texttt{ReciprocityGMMEffect.h}) \item Files Model.cpp, Model.h, siena07internals.cpp, Stattisticscalculator.cpp: declaration of the effect type ``gmm'' and computation of the GMoM statistics \item \texttt{model/AllEffects.h}: inclusion of the gmom effects for the network evolution only \item \texttt{model/EffectFactory.h, model/EffectFactory.cpp}: implementation of the effect of type gmm, change short name of the statistics from simX\_sim to simX\_gmm \item \texttt{model/AverageAlterEffect.h, model/AverageAlterEffect.cpp}: implementation of the GMoM statistic averageAlter \item \texttt{model/MaxAlterEffect.h, model/MaxAlterEffect.cpp}: implementation of the GMoM statistics maxAlter and minAlter \item \texttt{model/SimilarityEffect.h, model/SimilarityEffect.cpp}: implementation of the GMoM statistic simX \end{itemize} \subsection*{Folder R} \begin{itemize} \item \texttt{effects.R}: replacement text for the GMoM statistics \smallskip \item \texttt{effectsMethods.R}: in function \texttt{print.sienaEffects}, when one or more GMoM statistics are included, and the effects object is printed in the console, both model effects and statistics are shown. {\footnotesize \begin{verbatim} Effects and statistics for estimation by the Generalized Method of Moments Effects name effectName include fix test initialValue parm type 1 mynet constant mynet rate (period 1) TRUE FALSE FALSE 4.69604 0 rate 2 mynet constant mynet rate (period 2) TRUE FALSE FALSE 4.32885 0 rate 3 mynet outdegree (density) TRUE FALSE FALSE -1.46770 0 eval 4 mynet reciprocity TRUE FALSE FALSE 0.00000 0 eval 5 mynet transitive triplets TRUE FALSE FALSE 0.00000 0 eval 6 mynet 3-cycles TRUE FALSE FALSE 0.00000 0 eval 7 mynet mybeh ego TRUE FALSE FALSE 0.00000 0 eval 8 mynet mybeh similarity TRUE FALSE FALSE 0.00000 0 eval 9 mybeh rate mybeh (period 1) TRUE FALSE FALSE 0.70571 0 rate 10 mybeh rate mybeh (period 2) TRUE FALSE FALSE 0.84939 0 rate 11 mybeh mybeh linear shape TRUE FALSE FALSE 0.32237 0 eval 12 mybeh mybeh quadratic shape TRUE FALSE FALSE 0.00000 0 eval 13 mybeh mybeh total similarity TRUE FALSE FALSE 0.00000 0 eval Regular and GMoM statistics name effectName Statistic 1 mynet constant mynet rate (period 1) Regular 2 mynet constant mynet rate (period 2) Regular 3 mynet outdegree (density) Regular 4 mynet reciprocity Regular 5 mynet transitive triplets Regular 6 mynet 3-cycles Regular 7 mynet mybeh ego Regular 8 mynet mybeh similarity Regular 9 mybeh rate mybeh (period 1) Regular 10 mybeh rate mybeh (period 2) Regular 11 mybeh mybeh linear shape Regular 12 mybeh mybeh quadratic shape Regular 13 mybeh mybeh total similarity Regular 14 mynet mybeh ego GMoM 15 mynet mybeh similarity GMoM \end{verbatim}} \item \texttt{sienaEffects.R}:\\ Inclusion of the function \texttt{includeGMoMStatistics}. The function allows specifying the GMoM statistics. GMoM statistics are implemented as effects of type ``gmm'', with fixed value 0. In this way, they are not part of the probability model but are used to evaluate the moment condition. The documentation of the function is in the file \texttt{includeGMoMStatistics.Rd}. \item \texttt{effectsDocumentation.R}:\\ Changes so that the GMoM statistics do not appear in the list of possible effects for the evaluation/creation/endowment functions. \item \texttt{initializeFRAN.R}:\\ Created objects for GMoM statistics. Prevented the diagonalization of the scaling matrix $D^{-1}B$ in the Robbins-Monro step. Defined the requested effect when preVans is used with GMoM. Adjusted code for conditional estimation. \item \texttt{phase1.R}:\\ The GMoM estimate for $\theta$ is the value $\hat{\theta}$ such that \[B\;E_{\theta}\,[\,s^*(X,Z)-s^*(x,z)\,]=0\quad,\] \noindent The changes in the code relate to the computation of \begin{itemize} \item matrix of first-order derivatives of the statistics \[\Gamma\ = \ \frac{\partial}{\partial\theta}E_{\theta}[s(X,Z)-s(x,z)]\] \medskip \item matrix of GMoM weights \[W=\rm{Cov}[s(X,Z)]\] \medskip \item matrix \[B=\frac{\partial}{\partial\theta}\;E_{\theta}\,[\,s^*(X,Z)- s^*(x,z)\,]'\:W=\Gamma\; W\] \medskip \item matrix $D^{-1}B$ which is equivalent to the matrix $D^{-1}$ in the Newton-Raphson/Robbins-Monro step for the regular MoM, i.e. \medskip\\ Regular MoM:\\ $\theta_{i+1}=\theta_{i}-\underbrace{D^{-1}}_{\rm{dinvv}}E[S-s]$\\ $\theta_{i+1}=\theta_{i}-\alpha\underbrace{D^{-1}}_{\rm{dinvv}}(S-s)$ \medskip\\ GMoM:\\ $\theta_{i+1}=\theta_{i}-\underbrace{D^{-1}B}_{\rm{dinvv}}E[S-s]$\\ $\theta_{i+1}=\theta_{i}-\alpha\underbrace{D^{-1}B}_{\rm{dinvv}}(S-s)$ \bigskip\\ This equivalence reduces the number of changes in phase 2, though now dinvv is not the inverse of the first order derivative matrix of the statistics anymore. \end{itemize} \item \texttt{phase2.R}:\\ The GMoM statistics are fixed at 0 by default. Thus, all the conditions involving \texttt{z\$fixed} are changed into \texttt{z\$fixed \& !z\$gmmEffects} so that they apply to the GMoM statistics as well. The term \texttt{z\$gmmEffects} is a logical variable taking value TRUE if the effect is a GMoM statistic, and FALSE otherwise. Similar changes are required to compute the change step and set it to 0 for the GMoM statistics. \item \texttt{phase3.R}:\\ \begin{itemize} \item Added message: ``Generalized Method of Moments estimation'' for printing the results \item Computation of the matrices: $\Gamma$, $W$ and $B$ as described in \texttt{phase1.r} \item Computation of the t-ratios for convergence and tmax \[t-\rm{ratio} = \frac{\hat{B}(s(X,Z)-s(x,z))} {\sqrt{ \left(\hat{B}\;\hat{\Sigma}\;\hat{B}' \right)}} \ .\] \item Computation the covariance matrix of the GMoM estimator as \[\Sigma_{\widehat{\theta}_{GMoM}}=(\hat{B}\;\hat{\Gamma})^{- 1}(\hat{B}\;\hat{\Sigma}\;\hat{B}')((\hat{B}\;\hat{\Gamma})^{-1})'\] \end{itemize} \item \texttt{robmon.R}: \begin{itemize} \item Creation of a binary variable \texttt{z\$gmm} indicating whether the GMoM is used. \begin{itemize} \item If gmm=TRUE and no gmm effects are included, the algorithm stops and asks the user to select the regular MoM estimation \item If gmm=FALSE and gmm effects are included, the algorithm stops and asks the user to select the GMoM estimation \end{itemize} \item Specification of the number of steps in phase 1 for the GMoM ($n1=100 + 7 *p$) with $p$ the number of parameters \end{itemize} \item \texttt{print07Report.R}:\\ Format the GMoM statistics and standard errors for printing in the Rconsole. \item \texttt{printDataReport.R}:\\ Formatting for the GMoM statistics \item \texttt{sienaModelCreate.R}: \begin{itemize} \item Include the argument \texttt{z\$gmm}=TRUE for the GMoM estimation \item Dolby is not implemented for the GMoM estimation \end{itemize} \item \texttt{sienaprint.R}:\\ Changes for printing the GMoM results in the console (theta, standard error) \item \texttt{sienatable.R}:\\ Changes for printing the GMoM results in html or tex \end{itemize} \subsection*{Folder man} \begin{itemize} \item \texttt{sienaAlgorithmCreate.Rd}:\\ Inclusion of the argument gmm for the generalized method of moments and corresponding documentation. \item \texttt{includeGMoMStatistics.Rd}:\\ Documentation for the new function \texttt{includeGMoMStatistics} \end{itemize} \subsection*{Folder tests} \texttt{parallel.R}:\\ Inclusion of a test for the GMoM implementation (test15). \section*{List of GMoM effects implemented} The GMoM estimator uses more statistics than parameters and is computed by minimizing the distance between observed statistics and their expected values. Several GMoM statistics have been implemented for the evolution of networks and co-evolution of networks and behaviors. We denote by $X$ the network and by $Z$ the behavior. The statistics for the network evolution complement the information provided by the regular statistics by considering two consecutive observations of the network, i.e., the statistics depend on both the network at time $t_m$ and that at time $t_{m-1}$, $s^{*}(X(t_m),X(t_{m-1}))$. The GMoM statistics for the co-evolution of networks and behaviors supplement the information of the cross-lagged statistics depending jointly on the network and behavior by considering the network and behavior at the same time point, i.e., $s^{*}(X(t_m),Z(t_{m}))$. Essentially, the implemented effects are those in the two published papers and a few more. The complete list and corresponding definitions are describe in Table~\ref{tab:one}. Other effects can be implemented following the procedure described in the next section. \begin{table}% \footnotesize \begin{tabular}{ll} \hline Evolution & Formula of the statistic\\ \hline \emph{Network evolution} & \\[2ex] New reciprocity & $s^{*}(X)=\sum_{m}\sum_{ij}(1-X_{ij}(t_{m-1}))\cdot (1-X_{ji}(t_{m-1}))\cdot X_{ij}(t_{m})\cdot X_{ji}(t_{m})$\\[5ex] Persistent reciprocity & $s^{*}(X)=\sum_{m}\sum_{ij}X_{ij}(t_{m-1})\cdot X_{ji}(t_{m-1})\cdot X_{ij}(t_{m})\cdot X_{ji}(t_{m})$\\[5ex] Real reciprocity & $s^{*}(X)=\sum_{m}\sum_{ij}(1-X_{ij}(t_{m-1}))\cdot X_{ji}(t_{m-1})\cdot X_{ij}(t_{m})\cdot X_{ji}(t_{m}) $\\[5ex] Real Transitivity & $s^{*}(X)=\sum_{m}\sum_{ijh}(1-X_{ij}(t_{m-1}))\cdot X_{ih}(t_{m-1})\cdot X_{hj}(t_{m-1})\cdot X_{ij}(t_{m})\cdot X_{ih}(t_{m})\cdot X_{hj}(t_{m})$\\[5ex] Agree transitivity & $s^{*}(X)=\sum_{m}\sum_{ijh}(1-X_{ij}(t_{m-1}))\cdot X_{ih}(t_{m-1})\cdot X_{jh}(t_{m-1})\cdot X_{ij}(t_{m})\cdot X_{ih}(t_{m})\cdot X_{jh}(t_{m})$\\[2ex] \hline\\ \emph{Network-behavior evolution} & \\[2ex] Covariate ego & $s^{*}(X,Z) = \sum_{m}\sum_i Z_i(t_m) \, \sum_j X_{ij}(t_m) $\\[5ex] Total similarity & $s^{*}(X,Z) = \sum_{m}\sum_{ij} X_{ij}(t_m) ({\rm sim}^Z_{ij}(t_m) - \widehat{{\rm sim}^Z}) $\\[5ex] Average similarity & $s^{*}(X,Z) = \sum_{m}\sum_{ij} X_{ij}(t_m) ({\rm sim}^Z_{ij}(t_m) - \widehat{{\rm sim}^Z})/ \big (\sum_j X_{ij}(t_m)\big) $\\[5ex] Total alter & $s^{\rm beh}_{i}(X, Z) = \sum_{m}\sum_i Z_i(t_m) \big( \sum_j X_{ij}(t_m)\, Z_j(t_m) \big) $\\[5ex] Average alter & $s^{\rm beh}_{i}(X, Z) = \sum_{m}\sum_i Z_i(t_m) \big( \sum_j X_{ij}(t_m)\, Z_j(t_m) \big)/ \big (\sum_j X_{ij}(t_m)\big) $\\[5ex] Minimum alter & $s^{\rm beh}_{i}(X, Z) = \sum_{m}\sum_i Z_i(t_m) \big( \min_j \, X_{ij}(t_m)\, Z_j(t_m) \big) $\\[5ex] Maximum alter & $s^{\rm beh}_{i}(X, Z) = \sum_{m}\sum_i Z_i(t_m) \big( \max_j \, X_{ij}(t_m)\, Z_j(t_m) \big) $\\[5ex] \hline \end{tabular} \caption{Implemented GMoM statistics and corresponding formulas} \label{tab:one} \end{table} \newpage \section*{How to implement a gmom effect} The following lines explain how to implement a GMoM effect. The code for the \texttt{egoX\_gmm} statistic is used as an illustration. \begin{enumerate} \item Start from the CPP and H files of the regular statistic corresponding to the GMoM statistic that one wants to implement. Those files are in the folder \texttt{src/model/effects}. \item In the file .CPP duplicate the constructor and include the \texttt{simulatedState} flag. When the \texttt{simulatedState} flag is set to TRUE the value of the behaviour or the network is taken at the end of the period. \begin{lstlisting}[language=R] CovariateEgoEffect::CovariateEgoEffect(const EffectInfo * pEffectInfo, const bool leftThresholded, const bool rightThresholded, |\textbf{const bool simulatedState}|) : CovariateDependentNetworkEffect(pEffectInfo, |\textbf{simulatedState}|) { this->lleftThresholded = leftThresholded; this->lrightThresholded = rightThresholded; this->lthreshold = pEffectInfo->internalEffectParameter(); } \end{lstlisting} \item Declare the \texttt{simulatedState} flag in the file .H \begin{lstlisting}[language=R] CovariateEgoEffect(const EffectInfo * pEffectInfo, const bool leftThresholded, const bool rightThresholded, |\textbf{const bool simulatedState}|); \end{lstlisting} \item Include the new effect in the file \texttt{EffectFactory.cpp}. \begin{lstlisting}[language=R] else if (effectName == "egoX_gmm") { pEffect = new CovariateEgoEffect(pEffectInfo, false, false, |\textbf{true}|); } \end{lstlisting} \item Include the new effect in the file \texttt{allEffects.csv}. This can be done by copying the line of the regular statistic, changing the short name by adding the suffix \texttt{\_gmm}, and setting the value of the columns type and fix to ``gmm'' and ``TRUE'', respectively. \end{enumerate} \end{document}