adding weight description to centrality metrices (#4610)

Fixes #3921 

* weight description

10 files changed, 30 insertions, 1 deletions

diff --git a/networkx/algorithms/centrality/betweenness.py b/networkx/algorithms/centrality/betweenness.py
index 87a843f0..c78585cf 100644
--- a/networkx/algorithms/centrality/betweenness.py
+++ b/networkx/algorithms/centrality/betweenness.py
@@ -47,6 +47,8 @@ def betweenness_centrality(
     weight : None or string, optional (default=None)
       If None, all edge weights are considered equal.
       Otherwise holds the name of the edge attribute used as weight.
+      Weights are used to calculate weighted shortest paths, so they are
+      interpreted as distances.
 
     endpoints : bool, optional
       If True include the endpoints in the shortest path counts.
@@ -177,6 +179,8 @@ def edge_betweenness_centrality(G, k=None, normalized=True, weight=None, seed=No
     weight : None or string, optional (default=None)
       If None, all edge weights are considered equal.
       Otherwise holds the name of the edge attribute used as weight.
+      Weights are used to calculate weighted shortest paths, so they are
+      interpreted as distances.
 
     seed : integer, random_state, or None (default)
         Indicator of random number generation state.
diff --git a/networkx/algorithms/centrality/betweenness_subset.py b/networkx/algorithms/centrality/betweenness_subset.py
index 2d22398e..273697bc 100644
--- a/networkx/algorithms/centrality/betweenness_subset.py
+++ b/networkx/algorithms/centrality/betweenness_subset.py
@@ -49,6 +49,8 @@ def betweenness_centrality_subset(G, sources, targets, normalized=False, weight=
     weight : None or string, optional (default=None)
       If None, all edge weights are considered equal.
       Otherwise holds the name of the edge attribute used as weight.
+      Weights are used to calculate weighted shortest paths, so they are
+      interpreted as distances.
 
     Returns
     -------
@@ -143,6 +145,8 @@ def edge_betweenness_centrality_subset(
     weight : None or string, optional (default=None)
       If None, all edge weights are considered equal.
       Otherwise holds the name of the edge attribute used as weight.
+      Weights are used to calculate weighted shortest paths, so they are
+      interpreted as distances.
 
     Returns
     -------
diff --git a/networkx/algorithms/centrality/current_flow_betweenness.py b/networkx/algorithms/centrality/current_flow_betweenness.py
index 3b086216..03e735c1 100644
--- a/networkx/algorithms/centrality/current_flow_betweenness.py
+++ b/networkx/algorithms/centrality/current_flow_betweenness.py
@@ -50,6 +50,8 @@ def approximate_current_flow_betweenness_centrality(
     weight : string or None, optional (default=None)
       Key for edge data used as the edge weight.
       If None, then use 1 as each edge weight.
+      The weight reflects the capacity or the strength of the
+      edge.
 
     dtype : data type (float)
       Default data type for internal matrices.
@@ -167,6 +169,8 @@ def current_flow_betweenness_centrality(
     weight : string or None, optional (default=None)
       Key for edge data used as the edge weight.
       If None, then use 1 as each edge weight.
+      The weight reflects the capacity or the strength of the
+      edge.
 
     dtype : data type (float)
       Default data type for internal matrices.
@@ -261,6 +265,8 @@ def edge_current_flow_betweenness_centrality(
     weight : string or None, optional (default=None)
       Key for edge data used as the edge weight.
       If None, then use 1 as each edge weight.
+      The weight reflects the capacity or the strength of the
+      edge.
 
     dtype : data type (default=float)
       Default data type for internal matrices.
diff --git a/networkx/algorithms/centrality/current_flow_betweenness_subset.py b/networkx/algorithms/centrality/current_flow_betweenness_subset.py
index 69ed32e3..78b5247c 100644
--- a/networkx/algorithms/centrality/current_flow_betweenness_subset.py
+++ b/networkx/algorithms/centrality/current_flow_betweenness_subset.py
@@ -40,6 +40,8 @@ def current_flow_betweenness_centrality_subset(
     weight : string or None, optional (default=None)
       Key for edge data used as the edge weight.
       If None, then use 1 as each edge weight.
+      The weight reflects the capacity or the strength of the
+      edge.
 
     dtype: data type (float)
       Default data type for internal matrices.
@@ -147,6 +149,8 @@ def edge_current_flow_betweenness_centrality_subset(
     weight : string or None, optional (default=None)
       Key for edge data used as the edge weight.
       If None, then use 1 as each edge weight.
+      The weight reflects the capacity or the strength of the
+      edge.
 
     dtype: data type (float)
       Default data type for internal matrices.
diff --git a/networkx/algorithms/centrality/current_flow_closeness.py b/networkx/algorithms/centrality/current_flow_closeness.py
index 518b9f59..a3323a8a 100644
--- a/networkx/algorithms/centrality/current_flow_closeness.py
+++ b/networkx/algorithms/centrality/current_flow_closeness.py
@@ -28,6 +28,8 @@ def current_flow_closeness_centrality(G, weight=None, dtype=float, solver="lu"):
     weight : None or string, optional (default=None)
       If None, all edge weights are considered equal.
       Otherwise holds the name of the edge attribute used as weight.
+      The weight reflects the capacity or the strength of the
+      edge.
 
     dtype: data type (default=float)
       Default data type for internal matrices.
diff --git a/networkx/algorithms/centrality/eigenvector.py b/networkx/algorithms/centrality/eigenvector.py
index 3fc43e2a..de66dcfd 100644
--- a/networkx/algorithms/centrality/eigenvector.py
+++ b/networkx/algorithms/centrality/eigenvector.py
@@ -42,6 +42,7 @@ def eigenvector_centrality(G, max_iter=100, tol=1.0e-6, nstart=None, weight=None
     weight : None or string, optional (default=None)
       If None, all edge weights are considered equal.
       Otherwise holds the name of the edge attribute used as weight.
+      In this measure the weight is interpreted as the connection strength.
 
     Returns
     -------
@@ -160,7 +161,7 @@ def eigenvector_centrality_numpy(G, weight=None, max_iter=50, tol=0):
     weight : None or string, optional (default=None)
       The name of the edge attribute used as weight.
       If None, all edge weights are considered equal.
-
+      In this measure the weight is interpreted as the connection strength.
     max_iter : integer, optional (default=100)
       Maximum number of iterations in power method.
 
diff --git a/networkx/algorithms/centrality/group.py b/networkx/algorithms/centrality/group.py
index 87df987c..f6165557 100644
--- a/networkx/algorithms/centrality/group.py
+++ b/networkx/algorithms/centrality/group.py
@@ -52,6 +52,7 @@ def group_betweenness_centrality(G, C, normalized=True, weight=None, endpoints=F
     weight : None or string, optional (default=None)
       If None, all edge weights are considered equal.
       Otherwise holds the name of the edge attribute used as weight.
+      The weight of an edge is treated as the length or distance between the two sides.
 
     endpoints : bool, optional (default=False)
       If True include the endpoints in the shortest path counts.
@@ -271,6 +272,7 @@ def prominent_group(
     weight : None or string, optional (default=None)
        If None, all edge weights are considered equal.
        Otherwise holds the name of the edge attribute used as weight.
+       The weight of an edge is treated as the length or distance between the two sides.
 
     endpoints : bool, optional (default=False)
        If True include the endpoints in the shortest path counts.
@@ -569,6 +571,7 @@ def group_closeness_centrality(G, S, weight=None):
     weight : None or string, optional (default=None)
        If None, all edge weights are considered equal.
        Otherwise holds the name of the edge attribute used as weight.
+       The weight of an edge is treated as the length or distance between the two sides.
 
     Raises
     ------
diff --git a/networkx/algorithms/centrality/katz.py b/networkx/algorithms/centrality/katz.py
index a7de6375..05620611 100644
--- a/networkx/algorithms/centrality/katz.py
+++ b/networkx/algorithms/centrality/katz.py
@@ -75,6 +75,7 @@ def katz_centrality(
     weight : None or string, optional (default=None)
       If None, all edge weights are considered equal.
       Otherwise holds the name of the edge attribute used as weight.
+      In this measure the weight is interpreted as the connection strength.
 
     Returns
     -------
@@ -242,6 +243,7 @@ def katz_centrality_numpy(G, alpha=0.1, beta=1.0, normalized=True, weight=None):
     weight : None or string, optional
       If None, all edge weights are considered equal.
       Otherwise holds the name of the edge attribute used as weight.
+      In this measure the weight is interpreted as the connection strength.
 
     Returns
     -------
diff --git a/networkx/algorithms/centrality/load.py b/networkx/algorithms/centrality/load.py
index 40c21aa0..3e4310ed 100644
--- a/networkx/algorithms/centrality/load.py
+++ b/networkx/algorithms/centrality/load.py
@@ -24,6 +24,7 @@ def newman_betweenness_centrality(G, v=None, cutoff=None, normalized=True, weigh
     weight : None or string, optional (default=None)
       If None, edge weights are ignored.
       Otherwise holds the name of the edge attribute used as weight.
+      The weight of an edge is treated as the length or distance between the two sides.
 
     cutoff : bool, optional (default=None)
       If specified, only consider paths of length <= cutoff.
diff --git a/networkx/algorithms/centrality/percolation.py b/networkx/algorithms/centrality/percolation.py
index f4414ffc..250e5d42 100644
--- a/networkx/algorithms/centrality/percolation.py
+++ b/networkx/algorithms/centrality/percolation.py
@@ -47,6 +47,8 @@ def percolation_centrality(G, attribute="percolation", states=None, weight=None)
     weight : None or string, optional (default=None)
       If None, all edge weights are considered equal.
       Otherwise holds the name of the edge attribute used as weight.
+      The weight of an edge is treated as the length or distance between the two sides.
+
 
     Returns
     -------