% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/link_prediction.R
\name{predict_links}
\alias{predict_links}
\title{Predict Missing or Future Links in a Network}
\usage{
predict_links(
  x,
  methods = c("common_neighbors", "resource_allocation", "adamic_adar", "jaccard",
    "preferential_attachment", "katz"),
  weighted = TRUE,
  top_n = NULL,
  exclude_existing = TRUE,
  include_self = FALSE,
  katz_damping = NULL
)
}
\arguments{
\item{x}{A \code{netobject}, \code{mcml}, \code{cograph_network}, or
numeric square matrix.}

\item{methods}{Character vector. One or more of:
\code{"common_neighbors"}, \code{"resource_allocation"},
\code{"adamic_adar"}, \code{"jaccard"}, \code{"preferential_attachment"},
\code{"katz"}. Default: all six methods.}

\item{weighted}{Logical. If \code{TRUE}, use the weight matrix directly
instead of binarizing. Default: \code{TRUE}.}

\item{top_n}{Integer or NULL. Return only the top N predictions per method.
Default: \code{NULL} (all pairs).}

\item{exclude_existing}{Logical. If \code{TRUE}, exclude node pairs that
already have an edge. Default: \code{TRUE}.}

\item{include_self}{Logical. If \code{TRUE}, include self-loop predictions.
Default: \code{FALSE}.}

\item{katz_damping}{Numeric or NULL. Attenuation factor for Katz index.
If NULL, auto-computed as \code{0.9 / spectral_radius(A)}.
Default: \code{NULL}.}
}
\value{
An object of class \code{"net_link_prediction"} containing:
\describe{
\item{predictions}{Data frame with columns: from, to, method, score, rank.
Sorted by score (descending) within each method.}
\item{scores}{Named list of score matrices (one per method).}
\item{methods}{Character vector of methods used.}
\item{nodes}{Character vector of node names.}
\item{directed}{Logical.}
\item{weighted}{Logical.}
\item{n_nodes}{Integer.}
\item{n_existing}{Integer. Number of existing edges.}
}
}
\description{
Computes link prediction scores for all node pairs using one or more
structural similarity methods. Accepts \code{netobject}, \code{mcml},
\code{cograph_network}, or a raw weight matrix.

All methods are fully vectorized using matrix operations — no loops.
Supports both weighted and binary adjacency, directed and undirected
networks.
}
\details{
\subsection{Methods}{

\describe{
\item{common_neighbors}{Number of shared neighbors. For directed graphs,
sums shared out-neighbors and shared in-neighbors.
Vectorized as \code{A \%*\% t(A) + t(A) \%*\% A}.}
\item{resource_allocation}{Zhou et al. (2009). Like common neighbors but
weights each shared neighbor z by \code{1/degree(z)}.
Penalizes hubs, rewards rare shared connections.}
\item{adamic_adar}{Adamic & Adar (2003). Like resource allocation but
weights by \code{1/log(degree(z))}. Less aggressive penalty than RA.}
\item{jaccard}{Ratio of shared neighbors to total neighbors.
For directed graphs, computed on combined (out+in) neighbor sets.}
\item{preferential_attachment}{Product of source out-degree and target
in-degree. Captures the "rich-get-richer" effect.}
\item{katz}{Katz (1953). Weighted sum of all paths between nodes,
exponentially damped by path length. Computed via matrix inversion:
\code{(I - beta * A)^{-1} - I}. Captures global structure.}
}
}
}
\examples{
seqs <- data.frame(
  V1 = sample(LETTERS[1:5], 50, TRUE),
  V2 = sample(LETTERS[1:5], 50, TRUE),
  V3 = sample(LETTERS[1:5], 50, TRUE)
)
net <- build_network(seqs, method = "relative")
pred <- predict_links(net)
print(pred)
summary(pred)

}
\references{
Liben-Nowell, D. & Kleinberg, J. (2007). The link-prediction problem for
social networks. \emph{JASIST}, 58(7), 1019--1031.

Zhou, T., Lu, L. & Zhang, Y.-C. (2009). Network topology and link
prediction. \emph{European Physical Journal B}, 71, 623--630.

Adamic, L. A. & Adar, E. (2003). Friends and neighbors on the Web.
\emph{Social Networks}, 25(3), 211--230.

Katz, L. (1953). A new status index derived from sociometric analysis.
\emph{Psychometrika}, 18(1), 39--43.
}
\seealso{
\code{\link{evaluate_links}} for prediction evaluation,
\code{\link{build_network}} for network estimation.
}
