R/summary_centrality_power.R

In drostlab/edgynode: Comparison of Gene Regulatory Networks

#' Find Bonacich Power Centrality Scores of Network Positions
#'
#' `power_centrality()` takes a graph (`dat`) and returns the Boncich power
#' centralities of positions (selected by `nodes`).  The decay rate for
#' power contributions is specified by `exponent` (1 by default).
#'
#' Bonacich's power centrality measure is defined by
#' \eqn{C_{BP}\left(\alpha,\beta\right)=\alpha\left(\mathbf{I}-\beta\mathbf{A}\right)^{-1}\mathbf{A}\mathbf{1}}{C_BP(alpha,beta)=alpha
#' (I-beta A)^-1 A 1}, where \eqn{\beta}{beta} is an attenuation parameter (set
#' here by `exponent`) and \eqn{\mathbf{A}}{A} is the graph adjacency
#' matrix.  (The coefficient \eqn{\alpha}{alpha} acts as a scaling parameter,
#' and is set here (following Bonacich (1987)) such that the sum of squared
#' scores is equal to the number of vertices.  This allows 1 to be used as a
#' reference value for the ``middle'' of the centrality range.)  When
#' \eqn{\beta \rightarrow }{beta->1/lambda_A1}\eqn{
#' 1/\lambda_{\mathbf{A}1}}{beta->1/lambda_A1} (the reciprocal of the largest
#' eigenvalue of \eqn{\mathbf{A}}{A}), this is to within a constant multiple of
#' the familiar eigenvector centrality score; for other values of \eqn{\beta},
#' the behavior of the measure is quite different.  In particular, \eqn{\beta}
#' gives positive and negative weight to even and odd walks, respectively, as
#' can be seen from the series expansion
#' \eqn{C_{BP}\left(\alpha,\beta\right)=\alpha \sum_{k=0}^\infty \beta^k
#' }{C_BP(alpha,beta) = alpha sum( beta^k A^(k+1) 1, k in 0..infinity )}\eqn{
#' \mathbf{A}^{k+1} \mathbf{1}}{C_BP(alpha,beta) = alpha sum( beta^k A^(k+1) 1,
#' k in 0..infinity )} which converges so long as \eqn{|\beta|
#' }{|beta|<1/lambda_A1}\eqn{ < 1/\lambda_{\mathbf{A}1}}{|beta|<1/lambda_A1}.
#' The magnitude of \eqn{\beta}{beta} controls the influence of distant actors
#' on ego's centrality score, with larger magnitudes indicating slower rates of
#' decay.  (High rates, hence, imply a greater sensitivity to edge effects.)
#'
#' Interpretively, the Bonacich power measure corresponds to the notion that
#' the power of a vertex is recursively defined by the sum of the power of its
#' alters.  The nature of the recursion involved is then controlled by the
#' power exponent: positive values imply that vertices become more powerful as
#' their alters become more powerful (as occurs in cooperative relations),
#' while negative values imply that vertices become more powerful only as their
#' alters become *weaker* (as occurs in competitive or antagonistic
#' relations).  The magnitude of the exponent indicates the tendency of the
#' effect to decay across long walks; higher magnitudes imply slower decay.
#' One interesting feature of this measure is its relative instability to
#' changes in exponent magnitude (particularly in the negative case).  If your
#' theory motivates use of this measure, you should be very careful to choose a
#' decay parameter on a non-ad hoc basis.
#'
#' @param graph the input graph.
#' @param nodes vertex sequence indicating which vertices are to be included in
#'   the calculation.  By default, all vertices are included.
#' @param loops boolean indicating whether or not the diagonal should be
#'   treated as valid data.  Set this true if and only if the data can contain
#'   loops.  `loops` is `FALSE` by default.
#' @param exponent exponent (decay rate) for the Bonacich power centrality
#'   score; can be negative
#' @param rescale if true, centrality scores are rescaled such that they sum to
#'   1.
#' @param tol tolerance for near-singularities during matrix inversion (see
#'   [solve()])
#' @param sparse Logical scalar, whether to use sparse matrices for the
#'   calculation. The \sQuote{Matrix} package is required for sparse matrix
#'   support
#' @return A vector, containing the centrality scores.
#' @note This function was ported (i.e. copied) from the SNA package.
#' @section Warning : Singular adjacency matrices cause no end of headaches for
#' this algorithm; thus, the routine may fail in certain cases.  This will be
#' fixed when I get a better algorithm.  `power_centrality()` will not symmetrize your
#' data before extracting eigenvectors; don't send this routine asymmetric
#' matrices unless you really mean to do so.
#' @author Carter T. Butts
#' (<http://www.faculty.uci.edu/profile.cfm?faculty_id=5057>), ported to
#' igraph by Gabor Csardi \email{csardi.gabor@@gmail.com}, ported to edgynote by Tobias Woertwein
#' @references Bonacich, P.  (1972).  ``Factoring and Weighting Approaches to
#' Status Scores and Clique Identification.'' *Journal of Mathematical
#' Sociology*, 2, 113-120.
#'
#' Bonacich, P.  (1987).  ``Power and Centrality: A Family of Measures.''
#' *American Journal of Sociology*, 92, 1170-1182.
#' @keywords graphs
#' @family centrality
#' @export
summary_centrality_power <- function(graph, nodes = colnames(graph), loops = FALSE, exponent = 1,
  rescale = FALSE, tol = 1e-07, sparse = TRUE){
  igmat <- convert_adj_to_igraph(graph[nodes, nodes])
  igraph::power_centrality(igmat, loops = loops, exponent = exponent,
  rescale = rescale, tol = tol, sparse = sparse)
}