feat: added more modes for Graph.to_directed(), closes #376

Author: ntamas

CHANGELOG.md

@@ -11,6 +11,12 @@
 
 * Added `Graph.Tree_Game()` to generate random trees with uniform sampling.
 
+* `Graph.to_directed()` now supports a `mode=...` keyword argument.
+
+### Deprecated
+
+* `Graph.to_directed(mutual=...)` is now deprecated, use `mode=...` instead.
+
 ## 0.9.1
 
 ### Changed

src/_igraph/convert.c

@@ -641,6 +641,31 @@ int igraphmodule_PyObject_to_subgraph_implementation_t(PyObject *o,
   return igraphmodule_PyObject_to_enum(o, subgraph_impl_tt, (int*)result);
 }
 
+/**
+ * \ingroup python_interface_conversion
+ * \brief Converts a Python object to an igraph \c igraph_to_directed_t
+ */
+int igraphmodule_PyObject_to_to_directed_t(PyObject *o,
+  igraph_to_directed_t *result) {
+  static igraphmodule_enum_translation_table_entry_t to_directed_tt[] = {
+        {"acyclic",   IGRAPH_TO_DIRECTED_ACYCLIC},
+        {"arbitrary", IGRAPH_TO_DIRECTED_ARBITRARY},
+        {"mutual",    IGRAPH_TO_DIRECTED_MUTUAL},
+        {"random",    IGRAPH_TO_DIRECTED_RANDOM},
+        {0,0}
+  };
+
+  if (o == Py_True) {
+    *result = IGRAPH_TO_DIRECTED_MUTUAL;
+    return 0;
+  } else if (o == Py_False) {
+    *result = IGRAPH_TO_DIRECTED_ARBITRARY;
+    return 0;
+  }
+
+  return igraphmodule_PyObject_to_enum(o, to_directed_tt, (int*)result);
+}
+
 /**
  * \ingroup python_interface_conversion
  * \brief Converts a Python object to an igraph \c igraph_to_undirected_t

src/_igraph/convert.h

@@ -75,6 +75,7 @@ int igraphmodule_PyObject_to_spinglass_implementation_t(PyObject *o, igraph_spin
 int igraphmodule_PyObject_to_spincomm_update_t(PyObject *o, igraph_spincomm_update_t *result);
 int igraphmodule_PyObject_to_star_mode_t(PyObject *o, igraph_star_mode_t *result);
 int igraphmodule_PyObject_to_subgraph_implementation_t(PyObject *o, igraph_subgraph_implementation_t *result);
+int igraphmodule_PyObject_to_to_directed_t(PyObject *o, igraph_to_directed_t *result);
 int igraphmodule_PyObject_to_to_undirected_t(PyObject *o, igraph_to_undirected_t *result);
 int igraphmodule_PyObject_to_transitivity_mode_t(PyObject *o, igraph_transitivity_mode_t *result);
 int igraphmodule_PyObject_to_tree_mode_t(PyObject *o, igraph_tree_mode_t *result);

src/_igraph/graphobject.c

@@ -608,9 +608,9 @@ PyObject *igraphmodule_Graph_delete_vertices(igraphmodule_GraphObject * self,
 
   /*Py_None also means all for now, but it is deprecated */
   if (list == Py_None) {
-        PyErr_Warn(PyExc_DeprecationWarning, "Graph.delete_vertices(None) is "
-                   "deprecated since igraph 0.8.3, please use "
-                   "Graph.delete_vertices() instead");
+    PyErr_Warn(PyExc_DeprecationWarning, "Graph.delete_vertices(None) is "
+               "deprecated since igraph 0.8.3, please use "
+               "Graph.delete_vertices() instead");
   }
 
   /* this already converts no arguments and Py_None to all vertices */
@@ -7850,18 +7850,36 @@ PyObject *igraphmodule_Graph_to_undirected(igraphmodule_GraphObject * self,
 PyObject *igraphmodule_Graph_to_directed(igraphmodule_GraphObject * self,
                                          PyObject * args, PyObject * kwds)
 {
-  PyObject *mutual = Py_True;
+  PyObject *mutual_o = Py_None;
+  PyObject *mode_o = Py_None;
   igraph_to_directed_t mode = IGRAPH_TO_DIRECTED_MUTUAL;
-  static char *kwlist[] = { "mutual", NULL };
-  if (!PyArg_ParseTupleAndKeywords(args, kwds, "|O", kwlist, &mutual))
+  static char *kwlist[] = { "mode", "mutual", NULL };
+
+  if (!PyArg_ParseTupleAndKeywords(args, kwds, "|OO", kwlist, &mode_o, &mutual_o))
     return NULL;
-  mode =
-    (PyObject_IsTrue(mutual) ? IGRAPH_TO_DIRECTED_MUTUAL :
-     IGRAPH_TO_DIRECTED_ARBITRARY);
+
+  if (mode_o == Py_None) {
+    /* mode argument omitted so we fall back to 'mutual' for sake of
+     * compatibility and print a warning */
+    if (mutual_o == Py_None) {
+      /* mutual was not given either, so this is okay */
+      mode = IGRAPH_TO_DIRECTED_MUTUAL;
+    } else {
+      mode = PyObject_IsTrue(mutual_o) ? IGRAPH_TO_DIRECTED_MUTUAL : IGRAPH_TO_DIRECTED_ARBITRARY;
+      PyErr_Warn(PyExc_DeprecationWarning, "The 'mutual' argument is deprecated since "
+                 "igraph 0.9.3, please use mode=... instead");
+    }
+  } else {
+    if (igraphmodule_PyObject_to_to_directed_t(mode_o, &mode)) {
+      return NULL;
+    }
+  }
+
   if (igraph_to_directed(&self->g, mode)) {
     igraphmodule_handle_igraph_error();
     return NULL;
   }
+
   Py_RETURN_NONE;
 }
 
@@ -14802,14 +14820,18 @@ struct PyMethodDef igraphmodule_Graph_methods[] = {
    "Internal function, undocumented.\n\n"
    "@see: Graph.get_incidence()\n\n"},
 
-  // interface to igraph_to_directed
+  /* interface to igraph_to_directed */
   {"to_directed", (PyCFunction) igraphmodule_Graph_to_directed,
    METH_VARARGS | METH_KEYWORDS,
-   "to_directed(mutual=True)\n--\n\n"
+   "to_directed(mode=\"mutual\")\n--\n\n"
    "Converts an undirected graph to directed.\n\n"
-   "@param mutual: C{True} if mutual directed edges should be\n"
-   "  created for every undirected edge. If C{False}, a directed\n"
-   "  edge with arbitrary direction is created.\n"},
+   "@param mode: specifies how to convert undirected edges into\n"
+   "  directed ones. C{True} or C{\"mutual\"} creates a mutual edge pair\n"
+   "  for each undirected edge. C{False} or C{\"arbitrary\"} picks an\n"
+   "  arbitrary (but deterministic) edge direction for each edge.\n"
+   "  C{\"random\"} picks a random direction for each edge. C{\"acyclic\"}\n"
+   "  picks the edge directions in a way that the resulting graph will be\n"
+   "  acyclic if there were no self-loops in the original graph.\n"
 
   // interface to igraph_to_undirected
   {"to_undirected", (PyCFunction) igraphmodule_Graph_to_undirected,

tests/test_conversion.py

@@ -1,5 +1,7 @@
+import random
 import unittest
-from igraph import *
+
+from igraph import Graph, Matrix
 
 
 class DirectedUndirectedTests(unittest.TestCase):
@@ -37,7 +39,7 @@ def testToUndirected(self):
             graph2.es["weight"] == [7, 3, 11] or graph2.es["weight"] == [3, 7, 11]
         )
 
-    def testToDirected(self):
+    def testToDirectedNoModeArg(self):
         graph = Graph([(0, 1), (0, 2), (2, 3), (2, 4)], directed=False)
         graph.to_directed()
         self.assertTrue(graph.is_directed())
@@ -47,6 +49,51 @@ def testToDirected(self):
             == [(0, 1), (0, 2), (1, 0), (2, 0), (2, 3), (2, 4), (3, 2), (4, 2)]
         )
 
+    def testToDirectedMutual(self):
+        graph = Graph([(0, 1), (0, 2), (2, 3), (2, 4)], directed=False)
+        graph.to_directed("mutual")
+        self.assertTrue(graph.is_directed())
+        self.assertTrue(graph.vcount() == 5)
+        self.assertTrue(
+            sorted(graph.get_edgelist())
+            == [(0, 1), (0, 2), (1, 0), (2, 0), (2, 3), (2, 4), (3, 2), (4, 2)]
+        )
+
+    def testToDirectedAcyclic(self):
+        graph = Graph([(0, 1), (2, 0), (3, 0), (3, 0), (4, 2)], directed=False)
+        graph.to_directed("acyclic")
+        self.assertTrue(graph.is_directed())
+        self.assertTrue(graph.vcount() == 5)
+        print(graph.get_edgelist())
+        self.assertTrue(
+            sorted(graph.get_edgelist())
+            == [(0, 1), (0, 2), (0, 3), (0, 3), (2, 4)]
+        )
+
+    def testToDirectedRandom(self):
+        random.seed(0)
+
+        graph = Graph.Ring(200, directed=False)
+        graph.to_directed("random")
+
+        self.assertTrue(graph.is_directed())
+        self.assertTrue(graph.vcount() == 200)
+        edgelist1 = sorted(graph.get_edgelist())
+
+        graph = Graph.Ring(200, directed=False)
+        graph.to_directed("random")
+
+        self.assertTrue(graph.is_directed())
+        self.assertTrue(graph.vcount() == 200)
+        edgelist2 = sorted(graph.get_edgelist())
+
+        self.assertTrue(edgelist1 != edgelist2)
+
+    def testToDirectedInvalidMode(self):
+        graph = Graph([(0, 1), (0, 2), (2, 3), (2, 4)], directed=False)
+        with self.assertRaises(ValueError):
+            graph.to_directed("no-such-mode")
+
 
 class GraphRepresentationTests(unittest.TestCase):
     def testGetAdjacency(self):