= `betweenness_centrality_clustering`

Graph clustering based on edge betweenness centrality.

*Complexity:* _O(VE)_ per iteration (unweighted) +
*Defined in:* `<boost/graph/bc_clustering.hpp>`

== Example

[source,cpp]
----
include::example$algorithms/utility/bc_clustering.cpp[]
----

[,text]
----
include::example$algorithms/utility/bc_clustering.txt[]
----

'''

=== (1) Full version

[source,cpp]
----
template<typename MutableGraph, typename Done,
         typename EdgeCentralityMap, typename VertexIndexMap>
void betweenness_centrality_clustering(
    MutableGraph& g, Done done,
    EdgeCentralityMap edge_centrality,
    VertexIndexMap vertex_index);
----

[cols="1,2,5"]
|===
| Direction | Parameter | Description

| IN
| `MutableGraph& g`
| The graph object on which the algorithm will be applied.
  The type `MutableGraph` must be a model of
  xref:concepts/VertexListGraph.adoc[Vertex List Graph] and
  xref:concepts/IncidenceGraph.adoc[Incidence Graph].
  When an edge centrality map is supplied, it must also model
  xref:concepts/EdgeListGraph.adoc[Edge List Graph] and
  xref:concepts/MutableGraph.adoc[MutableGraph].

| IN
| `Done done`
| The function object that indicates termination of the algorithm.
  It must be a ternary function object that accepts the maximum
  centrality, the descriptor of the edge that will be removed,
  and the graph `g`.

| OUT/UTIL
| `EdgeCentralityMap edge_centrality`
| This property map is used to accumulate the betweenness centrality of
  each edge, and is a secondary form of output for the algorithm.
  The type `EdgeCentralityMap` must be a model of
  link:../../property_map/doc/ReadWritePropertyMap.html[Read/Write Property Map],
  with the graph's edge descriptor type as its key type.
  The value type of this property map should be the same as the value type
  of the `CentralityMap` property map.

| IN
| `VertexIndexMap vertex_index`
| This maps each vertex to an integer in the range
  `[0, num_vertices(g))`. This is necessary for efficient updates
  of the heap data structure when an edge is relaxed.
  The type `VertexIndexMap` must be a model of
  link:../../property_map/doc/ReadablePropertyMap.html[Readable Property Map].
  The value type of the map must be an integer type.
  The vertex descriptor type of the graph needs to be usable as the key
  type of the map.

|===

'''

=== (2) Edge centrality version (default vertex index)

[source,cpp]
----
template<typename MutableGraph, typename Done,
         typename EdgeCentralityMap>
void betweenness_centrality_clustering(
    MutableGraph& g, Done done,
    EdgeCentralityMap edge_centrality);
----

[cols="1,2,5"]
|===
| Direction | Parameter | Description

| IN
| `MutableGraph& g`
| See (1) `MutableGraph& g`.

| IN
| `Done done`
| See (1) `Done done`.

| OUT/UTIL
| `EdgeCentralityMap edge_centrality`
| See (1) `EdgeCentralityMap edge_centrality`.

|===

The vertex index defaults to `get(vertex_index, g)`.
Note: if you use this default, make sure your graph has an internal `vertex_index` property.
For example, `adjacency_list` with `VertexList=listS` does not have an internal `vertex_index` property.

'''

=== (3) Minimal version (default edge centrality and vertex index)

[source,cpp]
----
template<typename MutableGraph, typename Done>
void betweenness_centrality_clustering(
    MutableGraph& g, Done done);
----

[cols="1,2,5"]
|===
| Direction | Parameter | Description

| IN
| `MutableGraph& g`
| See (1) `MutableGraph& g`.

| IN
| `Done done`
| See (1) `Done done`.

|===

The edge centrality map defaults to a `dummy_property_map`, which requires no work to compute and returns no answer.
The vertex index defaults to `get(vertex_index, g)`.

== Description

This algorithm implements graph clustering based on edge betweenness centrality.
It is an iterative algorithm, where in each step it computes the edge betweenness
centrality (via
xref:algorithms/metrics/betweenness_centrality.adoc[brandes_betweenness_centrality])
and removes the edge with the maximum betweenness centrality. The `done`
function object determines when the algorithm terminates (the edge found
when the algorithm terminates will not be removed).

