\HeaderA{permPower}{Function to compute estimated probability of detecting preferential
connection of intracluster nodes}{permPower}
\keyword{htest}{permPower}
\begin{Description}\relax
This function simulates graphs from the alternative hypothesis
of preferential connection of intracluster nodes.  For each graph, it runs a node and edge permutation test.  The estimated ``power'' of each test is the proportion of graphs that the test rejects the null hypothesis of no preferential connection of intracluster edges.
\end{Description}
\begin{Usage}
\begin{verbatim}
permPower(psi=1,clsizes, nedge, nhyper=100, nperms=1000)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{psi}] The non-centrality parameter for the noncentral hypergeometric distribution used to simulate the graphs.
\item[\code{clsizes}] A vector of cluster sizes.
\item[\code{nedge}] The number of edges in each graph.
\item[\code{nhyper}] The number of noncentral hypergeometric graphs simulated to estimate "power".
\item[\code{nperms}] The number of permutations used for each run of the edge and node permutation tests.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The function first generates nhyper realizations of a noncentral hypergeometric(nedge,n,k,psi) random variable, where n is the number of node pairs and k is the number of intracluster node pairs.  For each realization x, a graph with n edges, x of which are intracluster, is generated.  The edge and node permutation tests (with nperms permutations each) are performed on each graph.  The estimated ``power'' of each test is the proportion of graphs for which the test rejects the null hypothesis of no preferential connection of intracluster nodes (at the 5\% level).  The 95\% confidence intervals for the power levels are also computed.
\end{Details}
\begin{Value}
A list with four components:
\begin{ldescription}
\item[\code{power.permedge}] Estimated ``power'' for edge permutation test.
\item[\code{power.permnode}] Estimated ``power'' for node permutation test.
\item[\code{CI.permedge}] Vector giving 95\% confidence interval for edge permutation test power.
\item[\code{CI.permnode}] Vector giving 95\% confidence interval for node permutation test power.
\end{ldescription}
\end{Value}
\begin{Author}\relax
Tom LaFramboise \email{tlaframb@hsph.harvard.edu}
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{permEdgesM2M}{permEdgesM2M}}, \code{\LinkA{permNodesM2M}{permNodesM2M}}, \code{\LinkA{makeClustM}{makeClustM}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
permPower(psi=5,clsizes=c(1,2,3,4),nedge=10,nhyper=100,nperms=100)
\end{ExampleCode}
\end{Examples}

