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

Local community detection using fitness maximization.

This module implements a local community detection algorithm that starts
from a set of seed nodes and iteratively expands (or shrinks) the community
to maximize a local fitness function. It is particularly useful for extracting
the community surrounding a specific node without calculating the global
community structure of the entire graph, making it efficient for massive or
infinite (implicit) graphs.

## Algorithm

The fitness function used is based on Lancichinetti et al. (2009):

    f(S) = k_in / (k_in + k_out)^alpha

where:
- `k_in` is the sum of internal degrees (twice the internal edge weights)
- `k_out` is the sum of external degrees (edges to outside S)
- `alpha` is a resolution parameter controlling community size

## When to Use

| Use Case | Recommendation |
|----------|----------------|
| Focus on specific node's neighborhood | ✓ Ideal |
| Massive graphs | ✓ Only explores local region |
| Streaming/infinite graphs | ✓ No full graph scan needed |
| Global community structure | Use Louvain instead |

## Example

    # Find the local community around node 5
    community = Yog.Community.LocalCommunity.detect(graph, seeds: [5])
    # Returns a MapSet containing node IDs in the local community

    # With custom options
    options = [alpha: 0.8, max_iterations: 500]
    community = Yog.Community.LocalCommunity.detect_with_options(graph, [5], options)

## References

- Lancichinetti et al. (2009). Detecting the overlapping and hierarchical community structure.
- Clauset, A. (2005). Finding local community structure in networks.

# `local_options`

```elixir
@type local_options() :: %{alpha: float(), max_iterations: integer()}
```

Options for local community detection

# `default_options`

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

Returns default options for local community detection.

- `alpha`: 1.0 (resolution parameter)
- `max_iterations`: 1000

# `detect`

```elixir
@spec detect(Yog.graph(), [{:seeds, [Yog.node_id()]}]) :: MapSet.t(Yog.node_id())
```

Detects a local community starting from a list of seed nodes using default options.

## Example

    iex> graph = Yog.undirected() |> Yog.add_edge_ensure(1, 2, 1, default: nil) |> Yog.add_edge_ensure(2, 3, 1, default: nil)
    iex> community = Yog.Community.LocalCommunity.detect(graph, seeds: [2])
    iex> MapSet.member?(community, 2)
    true

# `detect_with`

```elixir
@spec detect_with(Yog.graph(), [Yog.node_id()], local_options(), (any() -> float())) ::
  MapSet.t(Yog.node_id())
```

Detects a local community from seeds using a specific weight function.

The weight function transforms edge weights to floats for calculations.

# `detect_with_options`

```elixir
@spec detect_with_options(Yog.graph(), [Yog.node_id()], keyword()) ::
  MapSet.t(Yog.node_id())
```

Detects a local community from seeds with custom options.

## Options

  * `:alpha` - Resolution parameter (default: 1.0). Larger values yield smaller communities.
  * `:max_iterations` - Maximum iterations (default: 1000)

## Example

    iex> graph = Yog.undirected() |> Yog.add_edge_ensure(1, 2, 1, default: nil) |> Yog.add_edge_ensure(2, 3, 1, default: nil)
    iex> opts = [alpha: 0.5, max_iterations: 100]
    iex> community = Yog.Community.LocalCommunity.detect_with_options(graph, [2], opts)
    iex> MapSet.member?(community, 2)
    true

---

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