% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/smallworldness.R
\name{smallworldness}
\alias{smallworldness}
\title{Computes Various Small-Worldness Metrics}
\usage{
smallworldness(
  network,
  lattice,
  method = c("analytical", "omega", "S", "SWI", "SWP"),
  weighted = FALSE,
  iter = 100
)
}
\arguments{
\item{network}{Matrix or data frame.
A square, symmetric numeric matrix representing a network (e.g., partial
correlations). Absolute values are taken internally, so signed weights are
handled automatically. Non-zero off-diagonal entries are treated as edges.}

\item{lattice}{Matrix (optional).
A pre-computed lattice adjacency matrix to use as the regular-network
reference for the \code{"omega"} and \code{"SWP"} methods.
If not provided, a lattice is generated automatically via
\code{\link[L0ggm]{proxswap_lattice}}. Ignored by \code{"analytical"}
and \code{"S"}}

\item{method}{Character (length = 1).
The method used to compute small-worldness.
Defaults to \code{"SWP"}.
Available options:

\itemize{

\item \code{"analytical"} --- Computes the Humphries & Gurney (2008)
\eqn{S} metric using closed-form approximations for the Erdős–Rényi
random graph baseline:
\deqn{S = \frac{C / C_{\text{rand}}}{L / L_{\text{rand}}}}
where \eqn{C_{\text{rand}} \approx \langle k \rangle / n} and
\eqn{L_{\text{rand}} \approx \ln(n) / \ln(\langle k \rangle)}.
No random graphs are generated. The \code{weighted} argument is ignored.
Values greater than 1 indicate small-world structure

\item \code{"S"} --- Computes the Humphries & Gurney (2008) \eqn{S}
metric by simulation. Random graphs are generated under the
Erdős–Rényi model (\code{\link[igraph]{sample_gnm}}) with the same
number of nodes and edges as \code{network}. The empirical and random
clustering coefficients both use global transitivity (\eqn{C^\Delta}).
When \code{weighted = TRUE}, edge weights are reassigned to each random
graph topology via \code{assign_weights}. Values greater than 1
indicate small-world structure

\item \code{"omega"} --- Computes the \eqn{\omega} metric of
Telesford et al. (2011):
\deqn{\omega = \frac{L_{\text{rand}}}{L} - \frac{C}{C_{\text{latt}}}}
Random graphs preserve the degree sequence via edge-switching
(\code{\link[igraph]{sample_degseq}}, \code{method = "edge.switching.simple"}).
The clustering coefficient uses average local transitivity (\eqn{\bar{C}}).
Note: Telesford et al. (2011) defined and validated \eqn{\omega} exclusively
on binary, unweighted networks. When \code{weighted = TRUE}, edge weights
are reassigned to each random graph topology via \code{assign_weights} and
the lattice is constructed with \code{weighted = TRUE}, following the
approach of Muldoon et al. (2016); this is an extension beyond the original
formulation. Values near zero indicate small-world structure; negative
values indicate lattice-like structure; positive values indicate
random-like structure. Bounded in \eqn{[-1, 1]}

\item \code{"SWI"} --- Computes the Small-World Index of
Neal (2015):
\deqn{\text{SWI} = \frac{L - L_{\text{latt}}}{L_{\text{rand}} - L_{\text{latt}}} \times \frac{C - C_{\text{rand}}}{C_{\text{latt}} - C_{\text{rand}}}}
Each term captures where the observed network's path length and clustering
coefficient fall within the lattice-to-random range, so that SWI = 1
only when \eqn{L = L_{\text{rand}}} and \eqn{C = C_{\text{latt}}}
simultaneously. Because this ideal is mathematically unachievable in a
finite network, SWI = 1 is a conceptual upper bound rather than a
realisable value. Random graphs preserve the degree sequence via
edge-switching (\code{\link[igraph]{sample_degseq}},
\code{method = "edge.switching.simple"}). The clustering coefficient uses
average local transitivity (\eqn{\bar{C}}). When \code{weighted = TRUE},
edge weights are reassigned to each random graph topology and the lattice
is constructed with \code{weighted = TRUE}. Note: SWI and SWP were
developed independently and concurrently; both apply the same
double-normalisation framework but differ in how the two deviation terms
are combined (product vs. Euclidean distance). Values close to 1 indicate
strong small-world structure; values near 0 indicate lattice-like or
random-like structure. Bounded in \eqn{[0, 1]}

\item \code{"SWP"} --- Computes the Small-World Propensity of
Muldoon et al. (2016):
\deqn{\phi = 1 - \sqrt{\frac{\Delta_C^2 + \Delta_L^2}{2}}}
where \eqn{\Delta_C = (C_{\text{latt}} - C) / (C_{\text{latt}} - C_{\text{rand}})}
and \eqn{\Delta_L = (L - L_{\text{rand}}) / (L_{\text{latt}} - L_{\text{rand}})}.
Both \eqn{\Delta_C} and \eqn{\Delta_L} are bounded to \eqn{[0, 1]},
guaranteeing \eqn{\phi \in [0, 1]}. Random graphs preserve the degree
sequence via edge-switching. The clustering coefficient uses average
local transitivity (\eqn{\bar{C}}). When \code{weighted = TRUE}, edge
weights are reassigned to each random graph topology via
\code{assign_weights} and the lattice is constructed with
\code{weighted = TRUE}. Values close to 1 indicate strong small-world
structure; a pragmatic threshold of \eqn{\phi_T = 0.60} has been suggested

}}

\item{weighted}{Logical (length = 1).
Whether to compute small-worldness on the weighted network. When
\code{TRUE}, edge weights from \code{network} are preserved for the
empirical graph and reassigned to random and lattice graph topologies
via \code{assign_weights}, following Muldoon et al. (2016). When
\code{FALSE} (default), all graphs are treated as binary. Ignored when
\code{method = "analytical"}}

\item{iter}{Numeric (length = 1).
Number of random graphs to generate when estimating the null baseline.
Defaults to \code{100}.
Ignored when \code{method = "analytical"}.
Higher values produce more stable estimates at the cost of computation time}
}
\value{
Numeric (length = 1).
The small-worldness value computed using the chosen \code{method}:

\itemize{

\item \code{"analytical"} and \code{"S"} --- \eqn{S > 1} indicates small-world structure

\item \code{"omega"} --- Values near \eqn{|\omega| < 0.50} indicate small-world structure
(ranges between -1 and 1)

\item \code{"SWI"} --- Values close to 1 indicate strong small-world structure;
values near 0 indicate lattice-like or random-like structure
(ranges between 0 and 1)

\item \code{"SWP"} --- Values \eqn{\phi > 0.60} indicate strong small-world structure
(ranges between 0 and 1)

}
}
\description{
Computes the small-worldness of a network using one of five
methods. All simulation-based methods generate degree-preserving random
graphs as the null baseline. The lattice reference network (where required)
is constructed using \code{\link[L0ggm]{proxswap_lattice}}, which produces a
degree-preserving ring lattice that maximizes the clustering coefficient
}
\examples{
# Get network
network <- network_estimation(basic_smallworld)

# Compute SWP (default)
swp <- smallworldness(network)

# Compute omega
omega <- smallworldness(network, method = "omega")

# Compute analytical S
S <- smallworldness(network, method = "analytical")

# Compute simulated S
S_sim <- smallworldness(network, method = "S")

# Compute SWI
swi <- smallworldness(network, method = "SWI")

# Compute weighted SWP
swp_w <- smallworldness(network, weighted = TRUE)

# Compute weighted omega
omega_w <- smallworldness(network, method = "omega", weighted = TRUE)

}
\references{
\strong{omega} \cr
Telesford, Q. K., Joyce, K. E., Hayasaka, S., Burdette, J. H., & Laurienti, P. J. (2011).
The ubiquity of small-world networks.
\emph{Brain Connectivity}, \emph{1}(5), 367--375.

\strong{S and analytical} \cr
Humphries, M. D., & Gurney, K. (2008).
Network 'small-world-ness': A quantitative method for determining canonical network equivalence.
\emph{PLoS ONE}, \emph{3}(4), e0002051.

\strong{SWI} \cr
Neal, Z. P. (2015).
Making big communities small: Using network science to understand the ecological and behavioral requirements for community social capital.
\emph{American Journal of Community Psychology}, \emph{55}(3), 369--380.

\strong{SWP} \cr
Muldoon, S. F., Bridgeford, E. W., & Bassett, D. S. (2016).
Small-world propensity and weighted brain networks.
\emph{Scientific Reports}, \emph{6}(1), 22057.
}
\author{
Alexander P. Christensen <alexpaulchristensen@gmail.com>
}
