Repository: networkx/networkx

Issue:
Update documentation for geographical_threshold_graph
The documentation state that the return value of `p_dist` must be in the range `[0, 1]`, but the implementation differs from this behavior. The documentation should be updated to remove this discrepancy and better reflect the current implementation.

This was originally raised on the mailing list (thanks jimbo): see the [original post](https://groups.google.com/g/networkx-discuss/c/Z_UXaYZcsxw/m/2c377udtAgAJ) for further details.


Discussion:
Related to the documentation issue there is some counter intuitive behavior with the generator. For a given theta and given node weights, if instead of using 1/r^2 as p_dist, we use 1/r^3, we end up with a lot more edges. 
<img width="1072" alt="Screen Shot 2021-03-31 at 10 22 53 AM" src="https://user-images.githubusercontent.com/49379192/113160039-1b955880-920b-11eb-8307-3e54c9939e03.png">



Counter intuitive doesn't mean wrong but I'm not sure this behavior was intended in the implementation. Do you think it may be worth it to try and make the behavior more in line with expectations? 
Why do you say unexpected?  When you change the p_dist form, you are going to have to adjust the threshold (unless you adjust it implicitly in your p_dist function).  I wouldn't know what to expect unless I thought it through.

In this case, 1/r**3 is going to be much bigger than 1/r**2 because r is the metric on nodes placed within the unit square.
So I would expect many more edges unless theta is similarly divided by some sort of average value for r.

Similarly, if you rescale the metric to use cm instead of m, you would have to rescale theta to use the same units if you want to have the same number of edges. I'm guessing an average value of 1/r is about 2, so either use 0.5/r**3 or set theta to 200.  That's a guess though -- more complete examination of average 1/r would tell you more. 
Yes, of course you are correct. I say unexpected only because normally when I think of going from 1/r^2 to 1/r^3 I think of an effect getting weaker, but here we have the opposite and end up with a lot more connections. Also some of the points within the unit square are separated by more than 1 (consider two points connected by a diagonal across the square), so 1/r^3 is not always going to be bigger than 1/r^2, which adds slightly to the confusion. 

At any rate, I think it's a great idea to update the docs as described in the original comment on the issue. 

Hi guys. I'd like to take a crack at updating these docs over the weekend and hopefully getting this issue closed. Noob question: Just updating the docstrings (in my own forked version and then creating a PR from there) is sufficient, right? 
> Just updating the docstrings (in my own forked version and then creating a PR from there) is sufficient, right?

Yes, this is correct. I'd recommend making a new branch on your fork for the work as well, e.g. `git checkout -b doc/update-p_dist-description` or whatever you'd like to name the branch. Then you can push that branch up to your fork and create a PR from there.

Resolving patch:
diff --git a/networkx/generators/geometric.py b/networkx/generators/geometric.py
--- a/networkx/generators/geometric.py
+++ b/networkx/generators/geometric.py
@@ -290,11 +290,13 @@ def geographical_threshold_graph(
 
     .. math::
 
-       (w_u + w_v)h(r) \ge \theta
+       (w_u + w_v)p_{dist}(r) \ge \theta
 
-    where `r` is the distance between `u` and `v`, h(r) is a probability of
-    connection as a function of `r`, and :math:`\theta` as the threshold
-    parameter. h(r) corresponds to the p_dist parameter.
+    where `r` is the distance between `u` and `v`, `p_dist` is any function of
+    `r`, and :math:`\theta` as the threshold parameter. `p_dist` is used to
+    give weight to the distance between nodes when deciding whether or not
+    they should be connected. The larger `p_dist` is, the more prone nodes
+    separated by `r` are to be connected, and vice versa.
 
     Parameters
     ----------
@@ -326,17 +328,17 @@ def geographical_threshold_graph(
 
         .. _metric: https://en.wikipedia.org/wiki/Metric_%28mathematics%29
     p_dist : function, optional
-        A probability density function computing the probability of
-        connecting two nodes that are of distance, r, computed by metric.
-        The probability density function, `p_dist`, must
-        be any function that takes the metric value as input
-        and outputs a single probability value between 0-1.
-        The scipy.stats package has many probability distribution functions
-        implemented and tools for custom probability distribution
-        definitions [2], and passing the .pdf method of scipy.stats
-        distributions can be used here. If the probability
-        function, `p_dist`, is not supplied, the default exponential function
-        :math: `r^{-2}` is used.
+        Any function used to give weight to the distance between nodes when
+        deciding whether or not they should be connected. `p_dist` was
+        originally conceived as a probability density function giving the
+        probability of connecting two nodes that are of metric distance `r`
+        apart. The implementation here allows for more arbitrary definitions
+        of `p_dist` that do not need to correspond to valid probability
+        density functions. The :mod:`scipy.stats` package has many
+        probability density functions implemented and tools for custom
+        probability density definitions, and passing the ``.pdf`` method of
+        scipy.stats distributions can be used here. If ``p_dist=None``
+        (the default), the exponential function :math:`r^{-2}` is used.
     seed : integer, random_state, or None (default)
         Indicator of random number generation state.
         See :ref:`Randomness<randomness>`.


Test patch: