1#' Similarity measures of two vertices
2#'
3#' These functions calculates similarity scores for vertices based on their
4#' connection patterns.
5#'
6#' @details
7#' The Jaccard similarity coefficient of two vertices is the number of common
8#' neighbors divided by the number of vertices that are neighbors of at least
9#' one of the two vertices being considered. The \code{jaccard} method
10#' calculates the pairwise Jaccard similarities for some (or all) of the
11#' vertices.
12#'
13#' The Dice similarity coefficient of two vertices is twice the number of
14#' common neighbors divided by the sum of the degrees of the vertices.
15#' Methof \code{dice} calculates the pairwise Dice similarities for some
16#' (or all) of the vertices.
17#'
18#' The inverse log-weighted similarity of two vertices is the number of their
19#' common neighbors, weighted by the inverse logarithm of their degrees.  It is
20#' based on the assumption that two vertices should be considered more similar
21#' if they share a low-degree common neighbor, since high-degree common
22#' neighbors are more likely to appear even by pure chance.  Isolated vertices
23#' will have zero similarity to any other vertex.  Self-similarities are not
24#' calculated.  See the following paper for more details: Lada A. Adamic and
25#' Eytan Adar: Friends and neighbors on the Web. Social Networks,
26#' 25(3):211-230, 2003.
27#'
28#' @aliases similarity.jaccard similarity.dice similarity.invlogweighted
29#' @param graph The input graph.
30#' @param vids The vertex ids for which the similarity is calculated.
31#' @param mode The type of neighboring vertices to use for the calculation,
32#'   possible values: \sQuote{\code{out}}, \sQuote{\code{in}},
33#'   \sQuote{\code{all}}.
34#' @param loops Whether to include vertices themselves in the neighbor
35#'   sets.
36#' @param method The method to use.
37#' @return A \code{length(vids)} by \code{length(vids)} numeric matrix
38#'   containing the similarity scores. This argument is ignored by the
39#'   \code{invlogweighted} method.
40#' @author Tamas Nepusz \email{ntamas@@gmail.com} and Gabor Csardi
41#'   \email{csardi.gabor@@gmail.com} for the manual page.
42#' @seealso \code{\link{cocitation}} and \code{\link{bibcoupling}}
43#' @references Lada A. Adamic and Eytan Adar: Friends and neighbors on the Web.
44#'   \emph{Social Networks}, 25(3):211-230, 2003.
45#' @keywords graphs
46#' @export
47#' @examples
48#'
49#' g <- make_ring(5)
50#' similarity(g, method = "dice")
51#' similarity(g, method = "jaccard")
52
53similarity <- function(graph, vids = V(graph), mode = c("all", "out", "in",
54                          "total"), loops = FALSE, method = c("jaccard",
55                          "dice", "invlogweighted")) {
56
57  method <- igraph.match.arg(method)
58  if (method == "jaccard") {
59    similarity.jaccard(graph, vids, mode, loops)
60  } else if (method == "dice") {
61    similarity.dice(graph, vids, mode, loops)
62  } else if (method == "invlogweighted") {
63    similarity.invlogweighted(graph, vids, mode)
64  }
65}
66