yog/health

Network health and structural quality metrics.

These metrics measure the overall “health” and structural properties of your graph, including size, compactness, and connectivity patterns.

Overview

Metric	Function	Measures
Diameter	`diameter/5`	Maximum distance (worst-case reachability)
Radius	`radius/5`	Minimum eccentricity (best central point)
Eccentricity	`eccentricity/6`	Maximum distance from a node
Assortativity	`assortativity/1`	Degree correlation (homophily)
Average Path Length	`average_path_length/6`	Typical separation

Example

import gleam/int
import gleam/order
import yog/health

let graph = // ... build your graph

// Check graph compactness
let diam = health.diameter(
  in: graph,
  with_zero: 0,
  with_add: int.add,
  with_compare: int.compare,
  with: fn(w) { w }
)
let rad = health.radius(
  in: graph,
  with_zero: 0,
  with_add: int.add,
  with_compare: int.compare,
  with: fn(w) { w }
)

// Small diameter = well-connected
// High assortativity = nodes cluster with similar nodes
let assort = health.assortativity(graph)

Values

assortativity

</>

pub fn assortativity(graph: model.Graph(n, e)) -> Float

Assortativity coefficient measures degree correlation.

Time Complexity: O(V+E)

Interpreting Assortativity

Value	Meaning
Positive	High-degree nodes preferentially connect to other high-degree nodes (assortative)
Negative	High-degree nodes connect to low-degree nodes (disassortative)
Zero	Random mixing, or all nodes have the same degree (regular graph)

Common real-world patterns:

Social networks tend to be assortative (people with many friends know each other)
Biological and technological networks tend to be disassortative (hubs serve many leaves)

average_path_length

</>

pub fn average_path_length(
  in graph: model.Graph(n, e),
  with_zero zero: e,
  with_add add: fn(e, e) -> e,
  with_compare compare: fn(e, e) -> order.Order,
  with weight_fn: fn(e) -> e,
  with_to_float to_float: fn(e) -> Float,
) -> option.Option(Float)

Average shortest path length across all node pairs. Returns None if the graph is disconnected or empty. Requires a function to convert edge weights to Float for averaging.

Time Complexity: O(V × (V+E) log V)

Interpreting Average Path Length

Value	Meaning
`≈ 1.0`	Dense or highly connected graph (e.g. complete graph)
`≈ 2.0`	Star-like or small-world structure
`≈ V/3`	Chain-like or path-like topology
`None`	Disconnected or empty graph

A low APL relative to the number of nodes indicates a small-world structure: the graph achieves global connectivity through a small number of hops.

diameter

</>

pub fn diameter(
  in graph: model.Graph(n, e),
  with_zero zero: e,
  with_add add: fn(e, e) -> e,
  with_compare compare: fn(e, e) -> order.Order,
  with weight_fn: fn(e) -> e,
) -> option.Option(e)

The diameter is the maximum eccentricity (longest shortest path). Returns None if the graph is disconnected or empty.

Time Complexity: O(V × (V+E) log V)

Interpreting Diameter

Value	Meaning
`1`	Complete graph — everyone is directly connected
`2`	Small world — at most one hop between any pair
`> log(V)`	Relatively sparse or stretched topology
`None`	Disconnected or empty graph

eccentricity

</>

pub fn eccentricity(
  in graph: model.Graph(n, e),
  node node: Int,
  with_zero zero: e,
  with_add add: fn(e, e) -> e,
  with_compare compare: fn(e, e) -> order.Order,
  with weight_fn: fn(e) -> e,
) -> option.Option(e)

Eccentricity is the maximum distance from a node to all other nodes. Returns None if the node cannot reach all other nodes.

Time Complexity: O((V+E) log V)

Interpreting Eccentricity

Value	Meaning
`= radius`	The node is in the graph center
`= diameter`	The node is on the periphery (worst-case reachability)
`1`	The node is adjacent to every other node
`0`	Single-node graph
`None`	The node cannot reach all others (disconnected component)

radius

</>

pub fn radius(
  in graph: model.Graph(n, e),
  with_zero zero: e,
  with_add add: fn(e, e) -> e,
  with_compare compare: fn(e, e) -> order.Order,
  with weight_fn: fn(e) -> e,
) -> option.Option(e)

The radius is the minimum eccentricity. Returns None if the graph is disconnected or empty.

Time Complexity: O(V × (V+E) log V)

Interpreting Radius

Value	Meaning
`= diameter`	Highly symmetric structure (e.g. cycle, complete graph)
`< diameter`	Centralized topology with a clear hub (e.g. star)
`1`	There exists a central node one hop from everyone else
`None`	Disconnected or empty graph