API: Rm default value from time_delta for cd_index. (networkx#6953)

* API: Rm default value from time_delta for cd_index.

* Update exception message.

Co-authored-by: Mridul Seth <git@mriduls.com>

* TST: modify pytest.raises regex.

* Second cd_index example with integer times

* typo

* warn about leap years

---------

Co-authored-by: Mridul Seth <git@mriduls.com>
Co-authored-by: Dan Schult <dschult@colgate.edu>

Author: 3 people

networkx/algorithms/tests/test_time_dependent.py

@@ -1,11 +1,13 @@
 """Unit testing for time dependent algorithms."""
 
-from datetime import datetime
+from datetime import datetime, timedelta
 
 import pytest
 
 import networkx as nx
 
+_delta = timedelta(days=5 * 365)
+
 
 class TestCdIndex:
     """Unit testing for the cd index function."""
@@ -43,7 +45,7 @@ def test_common_graph(self):
 
         nx.set_node_attributes(G, node_attrs)
 
-        assert nx.cd_index(G, 4) == 0.17
+        assert nx.cd_index(G, 4, time_delta=_delta) == 0.17
 
     def test_common_graph_with_given_attributes(self):
         G = nx.DiGraph()
@@ -78,7 +80,7 @@ def test_common_graph_with_given_attributes(self):
 
         nx.set_node_attributes(G, node_attrs)
 
-        assert nx.cd_index(G, 4, time="date") == 0.17
+        assert nx.cd_index(G, 4, time_delta=_delta, time="date") == 0.17
 
     def test_common_graph_with_int_attributes(self):
         G = nx.DiGraph()
@@ -182,7 +184,7 @@ def test_common_graph_with_weights(self):
         }
 
         nx.set_node_attributes(G, node_attrs)
-        assert nx.cd_index(G, 4, weight="weight") == 0.04
+        assert nx.cd_index(G, 4, time_delta=_delta, weight="weight") == 0.04
 
     def test_node_with_no_predecessors(self):
         G = nx.DiGraph()
@@ -215,7 +217,7 @@ def test_node_with_no_predecessors(self):
         }
 
         nx.set_node_attributes(G, node_attrs)
-        assert nx.cd_index(G, 4) == 0.0
+        assert nx.cd_index(G, 4, time_delta=_delta) == 0.0
 
     def test_node_with_no_successors(self):
         G = nx.DiGraph()
@@ -248,7 +250,7 @@ def test_node_with_no_successors(self):
         }
 
         nx.set_node_attributes(G, node_attrs)
-        assert nx.cd_index(G, 4) == 1.0
+        assert nx.cd_index(G, 4, time_delta=_delta) == 1.0
 
     def test_n_equals_zero(self):
         G = nx.DiGraph()
@@ -282,7 +284,7 @@ def test_n_equals_zero(self):
         with pytest.raises(
             nx.NetworkXError, match="The cd index cannot be defined."
         ) as ve:
-            nx.cd_index(G, 4)
+            nx.cd_index(G, 4, time_delta=_delta)
 
     def test_time_timedelta_compatibility(self):
         G = nx.DiGraph()
@@ -315,9 +317,9 @@ def test_time_timedelta_compatibility(self):
 
         with pytest.raises(
             nx.NetworkXError,
-            match="Addition and comparison are not supported between 'time_delta' and 'time' types, default time_delta = datetime.timedelta",
+            match="Addition and comparison are not supported between",
         ) as ve:
-            nx.cd_index(G, 4)
+            nx.cd_index(G, 4, time_delta=_delta)
 
     def test_node_with_no_time(self):
         G = nx.DiGraph()
@@ -353,7 +355,7 @@ def test_node_with_no_time(self):
         with pytest.raises(
             nx.NetworkXError, match="Not all nodes have a 'time' attribute."
         ) as ve:
-            nx.cd_index(G, 4)
+            nx.cd_index(G, 4, time_delta=_delta)
 
     def test_maximally_consolidating(self):
         G = nx.DiGraph()
@@ -393,7 +395,7 @@ def test_maximally_consolidating(self):
 
         nx.set_node_attributes(G, node_attrs)
 
-        assert nx.cd_index(G, 5) == -1
+        assert nx.cd_index(G, 5, time_delta=_delta) == -1
 
     def test_maximally_destabilizing(self):
         G = nx.DiGraph()
@@ -426,4 +428,4 @@ def test_maximally_destabilizing(self):
 
         nx.set_node_attributes(G, node_attrs)
 
-        assert nx.cd_index(G, 5) == 1
+        assert nx.cd_index(G, 5, time_delta=_delta) == 1

networkx/algorithms/time_dependent.py

@@ -1,7 +1,5 @@
 """Time dependent algorithms."""
 
-from datetime import datetime, timedelta
-
 import networkx as nx
 from networkx.utils import not_implemented_for
 
@@ -11,7 +9,7 @@
 @not_implemented_for("undirected")
 @not_implemented_for("multigraph")
 @nx._dispatch(node_attrs={"time": None, "weight": 1})
-def cd_index(G, node, *, time_delta=timedelta(days=5 * 365), time="time", weight=None):
+def cd_index(G, node, time_delta, *, time="time", weight=None):
     r"""Compute the CD index for `node` within the graph `G`.
 
     Calculates the CD index for the given node of the graph,
@@ -26,12 +24,15 @@ def cd_index(G, node, *, time_delta=timedelta(days=5 * 365), time="time", weight
        `weight` attributes (if a weight is not given, it is considered 1).
     node : node
        The node for which the CD index is calculated.
-    time_delta : timedelta, integer or float (Optional, default is timedelta(days=5*365))
-       Amount of time after the `time` attribute of the `node`.
+    time_delta : numeric or timedelta
+       Amount of time after the `time` attribute of the `node`. The value of
+       `time_delta` must support comparison with the `time` node attribute. For
+       example, if the `time` attribute of the nodes are `datetime.datetime`
+       objects, then `time_delta` should be a `datetime.timedelta` object.
     time : string (Optional, default is "time")
         The name of the node attribute that will be used for the calculations.
     weight : string (Optional, default is None)
-        the name of the node attribute used as weight.
+        The name of the node attribute used as weight.
 
     Returns
     -------
@@ -50,6 +51,7 @@ def cd_index(G, node, *, time_delta=timedelta(days=5 * 365), time="time", weight
 
     Examples
     --------
+    >>> from datetime import datetime, timedelta
     >>> G = nx.DiGraph()
     >>> nodes = {
     ...     1: {"time": datetime(2015, 1, 1)},
@@ -61,7 +63,19 @@ def cd_index(G, node, *, time_delta=timedelta(days=5 * 365), time="time", weight
     >>> G.add_nodes_from([(n, nodes[n]) for n in nodes])
     >>> edges = [(1, 3), (1, 4), (2, 3), (3, 4), (3, 5)]
     >>> G.add_edges_from(edges)
-    >>> cd = nx.cd_index(G, 3, time="time", weight="weight")
+    >>> delta = timedelta(days=5 * 365)
+    >>> nx.cd_index(G, 3, time_delta=delta, time="time")
+    0.5
+    >>> nx.cd_index(G, 3, time_delta=delta, time="time", weight="weight")
+    0.12
+
+    Integers can also be used for the time values:
+    >>> node_times = {1: 2015, 2: 2012, 3: 2010, 4: 2008, 5: 2014}
+    >>> nx.set_node_attributes(G, node_times, "new_time")
+    >>> nx.cd_index(G, 3, time_delta=4, time="new_time")
+    0.5
+    >>> nx.cd_index(G, 3, time_delta=4, time="new_time", weight="weight")
+    0.12
 
     Notes
     -----
@@ -80,6 +94,14 @@ def cd_index(G, node, *, time_delta=timedelta(days=5 * 365), time="time", weight
     of forward citations in `i` and `w_{it}` is a matrix of weight for patent `i`
     at time `t`.
 
+    The `datetime.timedelta` package can lead to off-by-one issues when converting
+    from years to days. In the example above `timedelta(days=5 * 365)` looks like
+    5 years, but it isn't because of leap year days. So it gives the same result
+    as `timedelta(days=4 * 365)`. But using `timedelta(days=5 * 365 + 1)` gives
+    a 5 year delta **for this choice of years** but may not if the 5 year gap has
+    more than 1 leap year. To avoid these issues, use integers to represent years,
+    or be very careful when you convert units of time.
+
     References
     ----------
     .. [1] Funk, Russell J., and Jason Owen-Smith.
@@ -99,7 +121,7 @@ def cd_index(G, node, *, time_delta=timedelta(days=5 * 365), time="time", weight
     except:
         raise nx.NetworkXError(
             "Addition and comparison are not supported between 'time_delta' "
-            "and 'time' types, default time_delta = datetime.timedelta."
+            "and 'time' types."
         )
 
     # -1 if any edge between node's predecessors and node's successors, else 1