# `Yog.Community.Metrics`
[🔗](https://github.com/code-shoily/yog_ex/blob/v0.97.0/lib/yog/community/metrics.ex#L1)

Community quality metrics and graph statistics.

Provides functions for measuring:
- Modularity (community structure quality)
- Triangle counts and clustering coefficients
- Graph and community density

# `average_clustering_coefficient`

```elixir
@spec average_clustering_coefficient(Yog.graph()) :: float()
```

Calculates the average clustering coefficient for the entire graph.

# `average_community_density`

Calculates the average density across all communities.

# `clustering_coefficient`

```elixir
@spec clustering_coefficient(Yog.graph(), Yog.node_id()) :: float()
```

Calculates the local clustering coefficient for a node.

Measures how close the node's neighbors are to forming a complete clique.
Range: [0.0, 1.0].

## Examples

    iex> graph = Yog.undirected()
    ...> |> Yog.add_node(1, nil) |> Yog.add_node(2, nil) |> Yog.add_node(3, nil)
    ...> |> Yog.add_edge_ensure(from: 1, to: 2, with: 1)
    ...> |> Yog.add_edge_ensure(from: 2, to: 3, with: 1)
    ...> |> Yog.add_edge_ensure(from: 3, to: 1, with: 1)
    iex> Yog.Community.Metrics.clustering_coefficient(graph, 1)
    1.0

# `community_density`

```elixir
@spec community_density(Yog.graph(), MapSet.t(Yog.node_id())) :: float()
```

Calculates the density of edges within a specific set of nodes.

# `count_triangles`

```elixir
@spec count_triangles(Yog.graph()) :: integer()
```

Counts the total number of triangles in the graph.

A triangle is a set of three nodes where each pair is connected.
Uses neighbor intersection algorithm: O(Σ deg(v)²).

## Examples

    iex> graph = Yog.undirected()
    ...> |> Yog.add_node(1, nil) |> Yog.add_node(2, nil) |> Yog.add_node(3, nil)
    ...> |> Yog.add_edge_ensure(from: 1, to: 2, with: 1)
    ...> |> Yog.add_edge_ensure(from: 2, to: 3, with: 1)
    ...> |> Yog.add_edge_ensure(from: 3, to: 1, with: 1)
    iex> Yog.Community.Metrics.count_triangles(graph)
    1

# `density`

```elixir
@spec density(Yog.graph()) :: float()
```

Calculates the graph density.

# `modularity`

```elixir
@spec modularity(Yog.Graph.t(), any(), any()) :: any()
```

Calculates modularity for a given community partition.

Modularity measures the quality of a division of a network into modules
(communities). High modularity indicates that the community structure
captures significant structural patterns in the graph.

Range: [-0.5, 1.0]. Values > 0.3 indicate significant community structure.

## Examples

    iex> graph = Yog.undirected()
    ...> |> Yog.add_node(1, nil)
    ...> |> Yog.add_node(2, nil)
    ...> |> Yog.add_edge_ensure(from: 1, to: 2, with: 1)
    iex> communities = %{assignments: %{1 => 0, 2 => 0}, num_communities: 1}
    iex> q = Yog.Community.Metrics.modularity(graph, communities)
    iex> is_float(q)
    true

# `transitivity`

```elixir
@spec transitivity(Yog.graph()) :: float()
```

Calculates the transitivity (global clustering coefficient) of the graph.

Formula: T = 3 × number_of_triangles / number_of_connected_triples

# `triangles_per_node`

```elixir
@spec triangles_per_node(Yog.graph()) :: %{required(Yog.node_id()) => integer()}
```

Returns the number of triangles each node participates in.

## Examples

    iex> graph = Yog.undirected()
    ...> |> Yog.add_node(1, nil) |> Yog.add_node(2, nil) |> Yog.add_node(3, nil)
    ...> |> Yog.add_edge_ensure(from: 1, to: 2, with: 1)
    ...> |> Yog.add_edge_ensure(from: 2, to: 3, with: 1)
    ...> |> Yog.add_edge_ensure(from: 3, to: 1, with: 1)
    iex> Yog.Community.Metrics.triangles_per_node(graph)
    %{1 => 1, 2 => 1, 3 => 1}

---

*Consult [api-reference.md](api-reference.md) for complete listing*