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

Clique Percolation Method (CPM) for detecting overlapping communities.

Identifies communities by finding "chains" of adjacent k-cliques.
Two k-cliques are adjacent if they share k-1 nodes. Unlike other
algorithms, CPM can identify nodes that belong to multiple communities.

## Algorithm

1. **Find** all maximal cliques (using Bron-Kerbosch)
2. **Extract** all k-cliques from maximal cliques
3. **Build** adjacency between k-cliques (share k-1 nodes)
4. **Find** connected components of k-cliques
5. **Merge** cliques in each component to form communities

## When to Use

| Use Case | Recommendation |
|----------|----------------|
| Overlapping communities | ✓ Only algorithm in this module |
| Dense networks with cliques | ✓ Excellent |
| Sparse graphs | ✗ May find no communities |
| Non-overlapping needed | Convert with `to_communities/1` |

## Complexity

- **Time**: O(3^(V/3)) for maximal clique enumeration (worst case)
- **Space**: O(V + E)

**Note**: Clique enumeration can be expensive on large or dense graphs.

## Example

    # Detect overlapping communities (k=3 finds triangles)
    overlapping = Yog.Community.CliquePercolation.detect_overlapping(graph)

    # Convert to non-overlapping (assigns node to first community)
    communities = Yog.Community.CliquePercolation.to_communities(overlapping)

    # With custom k
    overlapping = Yog.Community.CliquePercolation.detect_overlapping_with_options(graph,
      k: 4
    )

## References

- [Palla et al. 2005 - Uncovering overlapping community structure](https://doi.org/10.1038/nature03607)
- [Wikipedia: Clique Percolation Method](https://en.wikipedia.org/wiki/Clique_percolation_method)

# `cpm_options`

```elixir
@type cpm_options() :: %{k: integer()}
```

Options for Clique Percolation Method

# `default_options`

```elixir
@spec default_options() :: cpm_options()
```

Returns default options for CPM.

## Defaults

- `k`: 3 - Size of the clique (typically 3 or 4)

# `detect_overlapping`

```elixir
@spec detect_overlapping(Yog.graph()) :: Yog.Community.Overlapping.t()
```

Detects overlapping communities using CPM with default options.

Returns overlapping communities where each node can belong to multiple communities.

## Example

    overlapping = Yog.Community.CliquePercolation.detect_overlapping(graph)
    IO.inspect(overlapping.num_communities)

# `detect_overlapping_with_options`

```elixir
@spec detect_overlapping_with_options(Yog.graph(), keyword() | map()) ::
  Yog.Community.Overlapping.t()
```

Detects overlapping communities using CPM with custom options.

## Options

- `:k` - Clique size (default: 3)

## Example

    overlapping = Yog.Community.CliquePercolation.detect_overlapping_with_options(graph,
      k: 4
    )

# `to_communities`

```elixir
@spec to_communities(Yog.Community.Overlapping.t()) :: Yog.Community.Result.t()
```

Converts overlapping communities to standard communities.

Each node is assigned to the first community in its membership list.

## Example

    overlapping = Yog.Community.CliquePercolation.detect_overlapping(graph)
    communities = Yog.Community.CliquePercolation.to_communities(overlapping)
    IO.inspect(communities.num_communities)

---

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