% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/network-summary.R
\name{trophic_incoherence}
\alias{trophic_incoherence}
\title{Trophic Incoherence Parameter}
\usage{
trophic_incoherence(x, cannibalism = TRUE)
}
\arguments{
\item{x}{Directed network input.}

\item{cannibalism}{Logical. If \code{FALSE}, self-loops are removed before
computing trophic differences. Default \code{TRUE}.}
}
\value{
A single numeric value (\code{NA_real_} for empty edge sets or
undirected input).
}
\description{
The trophic incoherence parameter \eqn{q} is a measure of how "vertically
ordered" a directed network is (Johnson et al. 2014). For each edge
\eqn{(u, v)}, the trophic difference is \eqn{x_{uv} = s_v - s_u} where
\eqn{s_i} is the trophic level of node \eqn{i}. The trophic incoherence
parameter is the (population) standard deviation of these differences:
\deqn{q = \sqrt{\frac{1}{|E|} \sum_{(u,v) \in E} (x_{uv} - \bar{x})^2}}
}
\details{
Low values (\eqn{q \approx 0}) indicate a perfectly coherent network
(e.g., a pure food web where every edge goes up one level). High values
indicate an incoherent network with many level-skipping or downward
edges. Johnson et al. 2014 showed that low-\eqn{q} food webs are
dynamically more stable.

Matches \code{networkx.trophic_incoherence_parameter} at machine epsilon.
Directed-only; requires at least one basal node (node with no incoming
edges) for trophic levels to be well-defined.
}
\examples{
# Small directed 3-node chain: 1 -> 2 -> 3 (perfectly coherent, q = 0)
adj <- matrix(c(0,1,0, 0,0,1, 0,0,0), 3, 3, byrow = TRUE)
rownames(adj) <- colnames(adj) <- c("A", "B", "C")
trophic_incoherence(adj)
}
\references{
Johnson, S., Dominguez-Garcia, V., Donetti, L., & Munoz, M. A. (2014).
Trophic coherence determines food-web stability. \emph{PNAS}, 111(50),
17923-17928.
}
\seealso{
\code{\link{centrality}} (the \code{trophic_level} measure) for
the per-node levels used in the incoherence calculation.
}
