a
HlX`&@sTdZddlZddlZddlmZddlmZddgZdddZ ed dd
dZ
dS)
z
Closeness centrality measures.
N)
NetworkXError)not_implemented_forcloseness_centrality incremental_closeness_centralityTc
Csr}dur*tjtjd}ntj}dur@j}ng}i}D]n}}t } t
}
d} dkr
dkrt
d }rt
d
d}9}<qNdurSSdS)aCompute closeness centrality for nodes.
Closeness centrality [1]_ of a node `u` is the reciprocal of the
average shortest path distance to `u` over all `n1` reachable nodes.
.. math::
C(u) = \frac{n  1}{\sum_{v=1}^{n1} d(v, u)},
where `d(v, u)` is the shortestpath distance between `v` and `u`,
and `n` is the number of nodes that can reach `u`. Notice that the
closeness distance function computes the incoming distance to `u`
for directed graphs. To use outward distance, act on `G.reverse()`.
Notice that higher values of closeness indicate higher centrality.
Wasserman and Faust propose an improved formula for graphs with
more than one connected component. The result is "a ratio of the
fraction of actors in the group who are reachable, to the average
distance" from the reachable actors [2]_. You might think this
scale factor is inverted but it is not. As is, nodes from small
components receive a smaller closeness value. Letting `N` denote
the number of nodes in the graph,
.. math::
C_{WF}(u) = \frac{n1}{N1} \frac{n  1}{\sum_{v=1}^{n1} d(v, u)},
Parameters

G : graph
A NetworkX graph
u : node, optional
Return only the value for node u
distance : edge attribute key, optional (default=None)
Use the specified edge attribute as the edge distance in shortest
path calculations
wf_improved : bool, optional (default=True)
If True, scale by the fraction of nodes reachable. This gives the
Wasserman and Faust improved formula. For single component graphs
it is the same as the original formula.
Returns

nodes : dictionary
Dictionary of nodes with closeness centrality as the value.
See Also

betweenness_centrality, load_centrality, eigenvector_centrality,
degree_centrality, incremental_closeness_centrality
Notes

The closeness centrality is normalized to `(n1)/(G1)` where
`n` is the number of nodes in the connected part of graph
containing the node. If the graph is not completely connected,
this algorithm computes the closeness centrality for each
connected part separately scaled by that parts size.
If the 'distance' keyword is set to an edge attribute key then the
shortestpath length will be computed using Dijkstra's algorithm with
that edge attribute as the edge weight.
The closeness centrality uses *inward* distance to a node, not outward.
If you want to use outword distances apply the function to `G.reverse()`
In NetworkX 2.2 and earlier a bug caused Dijkstra's algorithm to use the
outward distance rather than the inward distance. If you use a 'distance'
keyword and a DiGraph, your results will change between v2.2 and v2.3.
References

.. [1] Linton C. Freeman: Centrality in networks: I.
Conceptual clarification. Social Networks 1:215239, 1979.
http://leonidzhukov.ru/hse/2013/socialnetworks/papers/freeman79centrality.pdf
.. [2] pg. 201 of Wasserman, S. and Faust, K.,
Social Network Analysis: Methods and Applications, 1994,
Cambridge University Press.
N)Zweight?)Zis_directedreverse functoolspartialnxZ"single_source_dijkstra_path_length"single_source_shortest_path_lengthnodessumvalueslen)
GuZdistancewf_improvedpath_lengthrrnsptotsplen_G_closeness_centralitysr/Users/cmdms/OneDriveUOB/Development/Projects/2021/samconsensusv3/env/lib/python3.9/sitepackages/networkx/algorithms/centrality/closeness.pyrs2T
ZdirectedcCsndur(ttkr(td\}}tj}r\}} n }} durtS}
i}
D]}vr vrt  dkr<q}
t

}t}d}dkr@dkr@t
d}r@t
dd}9}<qr^nS)a+Incremental closeness centrality for nodes.
Compute closeness centrality for nodes using levelbased work filtering
as described in Incremental Algorithms for Closeness Centrality by Sariyuce et al.
Levelbased work filtering detects unnecessary updates to the closeness
centrality and filters them out.

From "Incremental Algorithms for Closeness Centrality":
Theorem 1: Let :math:`G = (V, E)` be a graph and u and v be two vertices in V
such that there is no edge (u, v) in E. Let :math:`G' = (V, E \cup uv)`
Then :math:`cc[s] = cc'[s]` if and only if :math:`\leftdG(s, u)  dG(s, v)\right \leq 1`.
Where :math:`dG(u, v)` denotes the length of the shortest path between
two vertices u, v in a graph G, cc[s] is the closeness centrality for a
vertex s in V, and cc'[s] is the closeness centrality for a
vertex s in V, with the (u, v) edge added.

We use Theorem 1 to filter out updates when adding or removing an edge.
When adding an edge (u, v), we compute the shortest path lengths from all
other nodes to u and to v before the node is added. When removing an edge,
we compute the shortest path lengths after the edge is removed. Then we
apply Theorem 1 to use previously computed closeness centrality for nodes
where :math:`\leftdG(s, u)  dG(s, v)\right \leq 1`. This works only for
undirected, unweighted graphs; the distance argument is not supported.
Closeness centrality [1]_ of a node `u` is the reciprocal of the
sum of the shortest path distances from `u` to all `n1` other nodes.
Since the sum of distances depends on the number of nodes in the
graph, closeness is normalized by the sum of minimum possible
distances `n1`.
.. math::
C(u) = \frac{n  1}{\sum_{v=1}^{n1} d(v, u)},
where `d(v, u)` is the shortestpath distance between `v` and `u`,
and `n` is the number of nodes in the graph.
Notice that higher values of closeness indicate higher centrality.
Parameters

G : graph
A NetworkX graph
edge : tuple
The modified edge (u, v) in the graph.
prev_cc : dictionary
The previous closeness centrality for all nodes in the graph.
insertion : bool, optional
If True (default) the edge was inserted, otherwise it was deleted from the graph.
wf_improved : bool, optional (default=True)
If True, scale by the fraction of nodes reachable. This gives the
Wasserman and Faust improved formula. For single component graphs
it is the same as the original formula.
Returns

nodes : dictionary
Dictionary of nodes with closeness centrality as the value.
See Also

betweenness_centrality, load_centrality, eigenvector_centrality,
degree_centrality, closeness_centrality
Notes

The closeness centrality is normalized to `(n1)/(G1)` where
`n` is the number of nodes in the connected part of graph
containing the node. If the graph is not completely connected,
this algorithm computes the closeness centrality for each
connected part separately.
References

.. [1] Freeman, L.C., 1979. Centrality in networks: I.
Conceptual clarification. Social Networks 1, 215239.
http://www.soc.ucsb.edu/faculty/friedkin/Syllabi/Soc146/Freeman78.PDF
.. [2] Sariyuce, A.E. ; Kaya, K. ; Saule, E. ; Catalyiirek, U.V. Incremental
Algorithms for Closeness Centrality. 2013 IEEE International Conference on Big Data
http://sariyuce.com/papers/bigdata13.pdf
Nz(prev_cc and G do not have the same nodesrrr)
setkeysrrrr
Zadd_edgeZremove_edgerabsrrr)rZedgeZprev_ccZ insertionrrvrZduZdvrrrrrrrrrrrrs@^
(
)NNT)NTT)__doc__r
ZnetworkxrZnetworkx.exceptionrZnetworkx.utils.decoratorsr__all__rrrrrrs
v