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

Result of overlapping community detection (e.g., Clique Percolation).

Unlike standard community detection, nodes can belong to multiple communities
simultaneously, reflecting the reality that individuals often participate in
multiple social groups.

## Fields

- `memberships` - Map from node ID to list of community IDs
- `num_communities` - Total number of distinct communities
- `community_index` - Inverted index: community_id -> MapSet of nodes
- `metadata` - Optional metadata (algorithm name, parameters, etc.)

## Examples

    iex> # Node 1 in communities 0 and 1, node 2 only in 1
    iex> overlapping = Yog.Community.Overlapping.new(%{1 => [0, 1], 2 => [1], 3 => [0]})
    iex> overlapping.num_communities
    2
    iex> overlapping.memberships[1]
    [0, 1]

# `community_id`

```elixir
@type community_id() :: any()
```

# `node_id`

```elixir
@type node_id() :: Yog.Model.node_id()
```

# `t`

```elixir
@type t() :: %Yog.Community.Overlapping{
  community_index: %{required(community_id()) => MapSet.t(node_id())} | nil,
  memberships: %{required(node_id()) => [community_id()]},
  metadata: map(),
  num_communities: non_neg_integer()
}
```

# `communities_for_node`

```elixir
@spec communities_for_node(t(), node_id()) :: [community_id()]
```

Get all communities a node belongs to.

# `from_map`

```elixir
@spec from_map(map()) :: t()
```

Backward compatibility: convert from legacy map format.

# `new`

```elixir
@spec new(%{required(node_id()) => [community_id()]}) :: t()
```

Creates an overlapping community result from a memberships map.

Automatically calculates the number of communities by counting unique community IDs.
Also builds an inverted index for O(1) community queries.

# `new`

```elixir
@spec new(%{required(node_id()) => [community_id()]}, map(), keyword()) :: t()
```

Creates an overlapping community result with explicit metadata and optional pre-computed values.

## Options

- `:num_communities` - Pre-computed community count to avoid re-scanning
- `:community_index` - Pre-computed inverted index for O(1) queries

# `nodes_in_community`

```elixir
@spec nodes_in_community(t(), community_id()) :: MapSet.t(node_id())
```

Get all nodes in a specific community.

Uses inverted index for O(1) lookup.

# `overlap`

```elixir
@spec overlap(t(), community_id(), community_id()) :: non_neg_integer()
```

Calculate the overlap (number of shared nodes) between two communities.

# `to_map`

```elixir
@spec to_map(t()) :: map()
```

Convert to legacy map format.

# `to_result`

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

Convert to non-overlapping result by assigning each node to its first community.

Nodes with no membership are excluded (not assigned to any community).

---

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