% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/fit-distribution.R
\name{fit_degree_distribution}
\alias{fit_degree_distribution}
\title{Fit Statistical Distributions to Degree Sequence}
\usage{
fit_degree_distribution(
  x,
  distributions = NULL,
  mode = "all",
  directed = NULL,
  xmin = NULL,
  ...
)
}
\arguments{
\item{x}{Network input: matrix, igraph, network, cograph_network, or tna
object.}

\item{distributions}{Character vector of distributions to fit. Options:
\code{"power_law"}, \code{"exponential"}, \code{"poisson"},
\code{"geometric"}. Default \code{NULL} fits all four.}

\item{mode}{For directed networks: \code{"all"}, \code{"in"}, or
\code{"out"}. Determines which degree to extract. Default \code{"all"}.}

\item{directed}{Logical or NULL. If NULL (default), auto-detect from matrix
symmetry. Set TRUE to force directed, FALSE to force undirected.}

\item{xmin}{Minimum degree to include in fitting. For power-law, NULL
triggers automatic estimation (Clauset et al. 2009 via igraph). For other
distributions, NULL defaults to 1.}

\item{...}{Additional arguments (currently unused).}
}
\value{
An object of class \code{"cograph_degree_fit"} containing:
\describe{
\item{fits}{Named list, one entry per distribution, each with:
\code{distribution}, \code{parameters} (named list of fitted params),
\code{loglik}, \code{aic}, \code{bic}, \code{ks_stat}, \code{ks_p}.}
\item{comparison}{Data frame sorted by AIC with columns:
\code{distribution}, \code{aic}, \code{bic}, \code{ks_stat},
\code{ks_p}.}
\item{best}{Name of the best-fitting distribution (lowest AIC).}
\item{degree}{The degree vector used for fitting.}
}
}
\description{
Fits one or more statistical distributions to the degree sequence of a
network via maximum likelihood estimation and evaluates goodness-of-fit
using Kolmogorov-Smirnov tests. Returns a comparison table sorted by AIC.
}
\details{
\strong{Power-law} (Pareto Type I): \eqn{P(k) \sim k^{-\alpha}}. When igraph is
available, uses \code{igraph::fit_power_law()} implementing the Clauset
et al. (2009) method. Otherwise, computes the simple MLE:
\eqn{\alpha = 1 + n / \sum \log(k / k_{min})}.

\strong{Exponential}: \eqn{P(k) \sim e^{-\lambda k}}. MLE:
\eqn{\lambda = 1 / \bar{k}}.

\strong{Poisson}: \eqn{P(k) \sim \lambda^k e^{-\lambda} / k!}. MLE:
\eqn{\lambda = \bar{k}}. Note: the KS test uses a continuous approximation
for a discrete distribution; p-values are approximate.

\strong{Geometric}: \eqn{P(k) \sim (1-p)^k p}. MLE:
\eqn{p = 1 / (1 + \bar{k})}.
}
\examples{
adj <- matrix(c(0, 1, 1, 0, 0,
                1, 0, 1, 1, 0,
                1, 1, 0, 1, 1,
                0, 1, 1, 0, 1,
                0, 0, 1, 1, 0), 5, 5, byrow = TRUE)
rownames(adj) <- colnames(adj) <- LETTERS[1:5]
fit <- cograph::fit_degree_distribution(adj,
  distributions = c("exponential", "poisson"))
print(fit)
}
\references{
Clauset, A., Shalizi, C. R., & Newman, M. E. J. (2009). Power-law
distributions in empirical data. \emph{SIAM Review}, 51(4), 661--703.
}
\seealso{
\code{\link{degree_distribution}}, \code{\link{centrality}}
}
