Add the ability to draw hypergraphs as a bipartite graph

HOW_TO_CONTRIBUTE.md

@@ -11,7 +11,7 @@ Please note we have a [code of conduct](/CODE_OF_CONDUCT.md), please follow it i
 3. [Optional, but STRONGLY preferred] Add unit tests for features being added or bugs being fixed.
 4. [Optional, but STRONGLY preferred] Include any new method/function in the corresponding docs file.
 5. Run `pytest` to verify all unit tests pass.
-6. [Optional, but STRONGLY preferred] Run `pylint xgi/ --disable all --enable W0611` and remove any unnecessary dependencies.
+6. [Optional, but STRONGLY preferred] Run `pylint xgi/ --disable all --enable W0611` and `nbqa pylint . --disable all --enable W0611` and remove any unnecessary dependencies.
 7. [Optional, but STRONGLY preferred] Run `isort .` and `nbqa isort .` to sort any new import statements in the source code and tutorials.
 8. [Optional, but STRONGLY preferred] Run `black .` for consistent styling.
 9. Update the "Current Version" section of CHANGELOG.md with overview of changes to the interface and add the usernames of all contributors.

benchmarks/hypernetx.ipynb

@@ -18,7 +18,6 @@
     "import time\n",
     "\n",
     "import hypernetx as hnx\n",
-    "import pandas as pd\n",
     "\n",
     "import xgi"
    ]
@@ -223,7 +222,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.6 | packaged by conda-forge | (main, Aug 22 2022, 20:38:29) [Clang 13.0.1 ]"
+   "version": "3.10.0"
   },
   "vscode": {
    "interpreter": {

benchmarks/networkx.ipynb

@@ -146,7 +146,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.4"
+   "version": "3.10.0"
   },
   "orig_nbformat": 4
  },

docs/source/api/drawing/xgi.drawing.draw.rst

@@ -8,10 +8,12 @@ xgi.drawing.draw
    .. rubric:: Functions
 
    .. autofunction:: draw
-   .. autofunction:: draw_dihypergraph
    .. autofunction:: draw_multilayer
+   .. autofunction:: draw_bipartite
    .. autofunction:: draw_nodes
    .. autofunction:: draw_hyperedges
+   .. autofunction:: draw_undirected_dyads
+   .. autofunction:: draw_directed_dyads
    .. autofunction:: draw_simplices
    .. autofunction:: draw_node_labels
    .. autofunction:: draw_hyperedge_labels

docs/source/api/recipes/recipes.ipynb

@@ -15,6 +15,7 @@
    "outputs": [],
    "source": [
     "import networkx as nx\n",
+    "\n",
     "import xgi"
    ]
   },
@@ -52,10 +53,11 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "import xgi\n",
     "import matplotlib.pyplot as plt\n",
     "import numpy as np\n",
-    "from numpy.linalg import eigh"
+    "from numpy.linalg import eigh\n",
+    "\n",
+    "import xgi"
    ]
   },
   {
@@ -112,9 +114,10 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "import xgi\n",
     "from itertools import permutations\n",
     "\n",
+    "import xgi\n",
+    "\n",
     "\n",
     "def adjacency_tensor(H, order):\n",
     "    N = H.num_nodes\n",
@@ -411,10 +414,11 @@
     }
    ],
    "source": [
-    "import xgi\n",
     "import pandas as pd\n",
     "import seaborn as sns\n",
     "\n",
+    "import xgi\n",
+    "\n",
     "H = xgi.load_xgi_data(\"diseasome\")\n",
     "H.merge_duplicate_edges(rename=\"tuple\", multiplicity=\"weight\")\n",
     "\n",
@@ -456,11 +460,11 @@
     }
    ],
    "source": [
-    "import xgi\n",
     "import matplotlib.pyplot as plt\n",
     "import pandas as pd\n",
     "import seaborn as sns\n",
     "\n",
+    "import xgi\n",
     "\n",
     "H = xgi.load_xgi_data(\"diseasome\")\n",
     "df1 = H.nodes.degree.ashist(bin_edges=True)\n",
@@ -546,9 +550,10 @@
     }
    ],
    "source": [
-    "import xgi\n",
     "import matplotlib.pyplot as plt\n",
     "\n",
+    "import xgi\n",
+    "\n",
     "H = xgi.random_hypergraph(N=10, ps=[0.2, 0.05, 0.05], seed=1)\n",
     "\n",
     "_, ax = plt.subplots(figsize=(4, 4), subplot_kw={\"projection\": \"3d\"})\n",

docs/source/api/tutorials/Tutorial 1 - Basic Hypergraph Functionality.ipynb

@@ -24,7 +24,6 @@
     "import random\n",
     "\n",
     "import numpy as np\n",
-    "import pandas as pd\n",
     "\n",
     "import xgi"
    ]

docs/source/api/tutorials/Tutorial 3 - Basic simplicial complex usage.ipynb

@@ -21,9 +21,6 @@
    "source": [
     "import random\n",
     "\n",
-    "import numpy as np\n",
-    "import pandas as pd\n",
-    "\n",
     "import xgi"
    ]
   },

docs/source/api/tutorials/XGI in 15 minutes.ipynb

@@ -18,7 +18,6 @@
    "outputs": [],
    "source": [
     "import matplotlib.pyplot as plt\n",
-    "import numpy as np\n",
     "\n",
     "import xgi"
    ]

docs/source/api/tutorials/XGI in 5 minutes.ipynb

@@ -22,7 +22,6 @@
    "outputs": [],
    "source": [
     "import matplotlib.pyplot as plt\n",
-    "import numpy as np\n",
     "\n",
     "import xgi"
    ]

tests/drawing/test_draw.py

@@ -4,6 +4,7 @@
 import numpy as np
 import pytest
 import seaborn as sb
+from matplotlib.patches import FancyArrowPatch
 
 import xgi
 from xgi.exception import XGIError
@@ -519,63 +520,63 @@ def test_draw_multilayer(edgelist8):
     plt.close("all")
 
 
-def test_draw_dihypergraph(diedgelist2, edgelist8):
+def test_draw_bipartite(diedgelist2, edgelist8):
     DH = xgi.DiHypergraph(diedgelist2)
 
     fig1, ax1 = plt.subplots()
-    ax1, collections = xgi.draw_dihypergraph(DH, ax=ax1)
-    node_coll, phantom_node_coll = collections
+    ax1, collections1 = xgi.draw_bipartite(DH, ax=ax1)
+    node_coll1, edge_marker_coll1, dyad_coll1 = collections1
     fig2, ax2 = plt.subplots()
-    ax2, collections2 = xgi.draw_dihypergraph(
+    ax2, collections2 = xgi.draw_bipartite(
         DH,
         ax=ax2,
         node_fc="red",
         node_ec="blue",
         node_lw=2,
         node_size=20,
-        lines_fc="blue",
-        lines_lw=2,
+        dyad_color="blue",
+        dyad_lw=2,
         edge_marker_fc="red",
         edge_marker_lw=2,
         edge_marker_size=20,
     )
-    node_coll2, phantom_node_coll2 = collections2
+    node_coll2, edge_marker_coll2, dyad_coll2 = collections2
 
     # number of elements
-    assert len(node_coll.get_offsets()) == 6  # number of original nodes
-    assert len(phantom_node_coll.get_offsets()) == 3  # number of original edges
+    assert len(node_coll1.get_offsets()) == 6  # number of original nodes
+    assert len(edge_marker_coll1.get_offsets()) == 3  # number of original edges
     assert len(ax1.patches) == 11  # number of lines
 
     # node face colors
-    assert np.all(node_coll.get_facecolor() == np.array([[1, 1, 1, 1]]))  # white
+    assert np.all(node_coll1.get_facecolor() == np.array([[1, 1, 1, 1]]))  # white
     assert np.all(node_coll2.get_facecolor() == np.array([[1, 0, 0, 1]]))  # red
 
     # node edge colors
-    assert np.all(node_coll.get_edgecolor() == np.array([[0, 0, 0, 1]]))  # black
+    assert np.all(node_coll1.get_edgecolor() == np.array([[0, 0, 0, 1]]))  # black
     assert np.all(node_coll2.get_edgecolor() == np.array([[0, 0, 1, 1]]))  # blue
 
     # node_lw
-    assert np.all(node_coll.get_linewidth() == np.array([1]))
+    assert np.all(node_coll1.get_linewidth() == np.array([1]))
     assert np.all(node_coll2.get_linewidth() == np.array([2]))
 
     # node_size
-    assert np.all(node_coll.get_sizes() == np.array([7**2]))
+    assert np.all(node_coll1.get_sizes() == np.array([7**2]))
     assert np.all(node_coll2.get_sizes() == np.array([20**2]))
 
     # edge face colors
-    assert np.all(phantom_node_coll2.get_facecolor() == np.array([[1, 0, 0, 1]]))  # red
+    assert np.all(edge_marker_coll2.get_facecolor() == np.array([[1, 0, 0, 1]]))  # red
 
     # edge _lw
-    assert np.all(phantom_node_coll.get_linewidth() == np.array([1]))
-    assert np.all(phantom_node_coll2.get_linewidth() == np.array([2]))
+    assert np.all(edge_marker_coll1.get_linewidth() == np.array([1]))
+    assert np.all(edge_marker_coll2.get_linewidth() == np.array([2]))
 
     # edge_size
-    assert np.all(phantom_node_coll.get_sizes() == np.array([7**2]))
-    assert np.all(phantom_node_coll2.get_sizes() == np.array([20**2]))
+    assert np.all(edge_marker_coll1.get_sizes() == np.array([7**2]))
+    assert np.all(edge_marker_coll2.get_sizes() == np.array([20**2]))
 
     # line lw
     for patch in ax1.patches:  # lines
-        assert np.all(patch.get_linewidth() == np.array([1.5]))
+        assert np.all(patch.get_linewidth() == np.array([1]))
     for patch in ax2.patches:  # lines
         assert np.all(patch.get_linewidth() == np.array([2]))
 
@@ -584,29 +585,79 @@ def test_draw_dihypergraph(diedgelist2, edgelist8):
         assert np.all(patch.get_facecolor() == np.array([[0, 0, 1, 1]]))
 
     # zorder
-    assert node_coll.get_zorder() == 4
-    assert phantom_node_coll.get_zorder() == 2
+    assert node_coll1.get_zorder() == 2
+    assert edge_marker_coll1.get_zorder() == 1
     for patch in ax1.patches:  # lines
         assert patch.get_zorder() == 0
 
-    # test toggle for edges
-    fig, ax2 = plt.subplots()
-    ax2, collections = xgi.draw_dihypergraph(DH, edge_marker_toggle=False, ax=ax2)
-    node_coll, phantom_node_coll = collections
-    assert len(ax2.collections) == 1
-    assert phantom_node_coll is None
+    plt.close("all")
+
+    H = xgi.Hypergraph(edgelist8)
+
+    fig3, ax3 = plt.subplots()
+    ax3, collections3 = xgi.draw_bipartite(H, ax=ax3)
+    node_coll3, edge_marker_coll3, dyad_coll3 = collections3
+    fig4, ax4 = plt.subplots()
+    ax4, collections4 = xgi.draw_bipartite(
+        H,
+        ax=ax4,
+        node_fc="red",
+        node_ec="blue",
+        node_lw=2,
+        node_size=20,
+        dyad_color="blue",
+        dyad_lw=2,
+        edge_marker_fc="red",
+        edge_marker_lw=2,
+        edge_marker_size=20,
+    )
+    node_coll4, edge_marker_coll4, dyad_coll4 = collections4
+
+    # number of elements
+    assert len(node_coll3.get_offsets()) == 7  # number of original nodes
+    assert len(edge_marker_coll3.get_offsets()) == 9  # number of original edges
+    assert len(dyad_coll3._paths) == 26  # number of lines
+
+    # # node face colors
+    assert np.all(node_coll3.get_facecolor() == np.array([[1, 1, 1, 1]]))  # white
+    assert np.all(node_coll4.get_facecolor() == np.array([[1, 0, 0, 1]]))  # red
+
+    # node edge colors
+    assert np.all(node_coll3.get_edgecolor() == np.array([[0, 0, 0, 1]]))  # black
+    assert np.all(node_coll4.get_edgecolor() == np.array([[0, 0, 1, 1]]))  # blue
+
+    # # node_lw
+    assert np.all(node_coll3.get_linewidth() == np.array([1]))
+    assert np.all(node_coll4.get_linewidth() == np.array([2]))
+
+    # # node_size
+    assert np.all(node_coll3.get_sizes() == np.array([7**2]))
+    assert np.all(node_coll4.get_sizes() == np.array([20**2]))
+
+    # # edge face colors
+    assert np.all(edge_marker_coll4.get_facecolor() == np.array([[1, 0, 0, 1]]))  # red
+
+    # # edge _lw
+    assert np.all(edge_marker_coll3.get_linewidth() == np.array([1]))
+    assert np.all(edge_marker_coll4.get_linewidth() == np.array([2]))
+
+    # # edge_size
+    assert np.all(edge_marker_coll3.get_sizes() == np.array([7**2]))
+    assert np.all(edge_marker_coll4.get_sizes() == np.array([20**2]))
 
     plt.close("all")
 
-    # test XGI ERROR raise
+    # test type
     with pytest.raises(XGIError):
-        H = xgi.Hypergraph(edgelist8)
-        fig, ax3 = plt.subplots()
-        ax3 = xgi.draw_dihypergraph(H, ax=ax3)
-        plt.close()
+        xgi.draw_bipartite([0, 1, 2])
+
+    # test gca
+    fig3, ax = plt.subplots()
+    ax_gca, collections3 = xgi.draw_bipartite(H)
+    assert ax == ax_gca
 
 
-def test_draw_dihypergraph_with_str_labels_and_isolated_nodes():
+def test_draw_bipartite_with_str_labels_and_isolated_nodes():
     DH1 = xgi.DiHypergraph()
     DH1.add_nodes_from(["one", "two", "three", "four", "five", "six"])
     DH1.add_edges_from(
@@ -617,12 +668,50 @@ def test_draw_dihypergraph_with_str_labels_and_isolated_nodes():
     )
 
     fig, ax4 = plt.subplots()
-    ax4, collections4 = xgi.draw_dihypergraph(DH1, ax=ax4)
-    node_coll4, phantom_node_coll4 = collections4
+    ax4, collections4 = xgi.draw_bipartite(DH1, ax=ax4)
+    node_coll4, edge_marker_coll4, dyad_coll4 = collections4
     assert len(node_coll4.get_offsets()) == 6  # number of original nodes
-    assert len(phantom_node_coll4.get_offsets()) == 2  # number of original edges
+    assert len(edge_marker_coll4.get_offsets()) == 2  # number of original edges
     assert len(ax4.patches) == 7  # number of lines
-    plt.close()
+    plt.close("all")
+
+
+def test_draw_undirected_dyads(edgelist8):
+    H = xgi.Hypergraph(edgelist8)
+
+    fig, ax = plt.subplots()
+    ax, dyad_collection = xgi.draw_undirected_dyads(H)
+    assert len(dyad_collection._paths) == 26  # number of lines
+
+    with pytest.raises(ValueError):
+        fig, ax = plt.subplots()
+        ax, dyad_collection = xgi.draw_undirected_dyads(H, dyad_lw=-1)
+
+    fig, ax = plt.subplots()
+    ax, dyad_collection = xgi.draw_undirected_dyads(
+        H, dyad_color=np.random.random(H.num_edges)
+    )
+    assert len(np.unique(dyad_collection.get_color())) == 9
+    plt.close("all")
+
+
+def test_draw_directed_dyads(diedgelist1):
+    H = xgi.DiHypergraph(diedgelist1)
+
+    fig, ax = plt.subplots()
+    ax, dyad_collection = xgi.draw_directed_dyads(H)
+    assert len(dyad_collection) == 9  # number of lines
+    assert isinstance(dyad_collection[0], FancyArrowPatch)
+
+    with pytest.raises(ValueError):
+        fig, ax = plt.subplots()
+        ax, dyad_collection = xgi.draw_directed_dyads(H, dyad_lw=-1)
+
+    fig, ax = plt.subplots()
+    ax, dyad_collection = xgi.draw_directed_dyads(
+        H, dyad_color=np.random.random(H.num_edges)
+    )
+    plt.close("all")
 
 
 def test_issue_499(edgelist8):