Add the ability to draw hypergraphs as a bipartite graph

tests/drawing/test_draw_utils.py

@@ -3,11 +3,7 @@
 from matplotlib import cm
 
 import xgi
-from xgi.drawing.draw import (
-    _CCW_sort,
-    _draw_arg_to_arr,
-    _interp_draw_arg,
-)
+from xgi.drawing.draw import _CCW_sort, _draw_arg_to_arr, _interp_draw_arg
 
 
 def test_CCW_sort():

xgi/drawing/draw.py

@@ -5,7 +5,6 @@
 import matplotlib as mpl
 import matplotlib.pyplot as plt
 import numpy as np
-import seaborn as sb  # for cmap "crest"
 from matplotlib import cm
 from matplotlib.patches import FancyArrowPatch
 from mpl_toolkits.mplot3d.art3d import (
@@ -19,6 +18,7 @@
 
 from .. import convert
 from ..algorithms import max_edge_order, unique_edge_sizes
+from ..convert import to_bipartite_edgelist
 from ..core import DiHypergraph, Hypergraph, SimplicialComplex
 from ..exception import XGIError
 from ..utils import subfaces
@@ -30,7 +30,11 @@
     _parse_color_arg,
     _update_lims,
 )
-from .layout import _augmented_projection, barycenter_spring_layout
+from .layout import (
+    _augmented_projection,
+    barycenter_spring_layout,
+    bipartite_spring_layout,
+)
 
 __all__ = [
     "draw",
@@ -41,6 +45,7 @@
     "draw_hyperedge_labels",
     "draw_multilayer",
     "draw_dihypergraph",
+    "draw_bipartite",
 ]
 
 
@@ -392,7 +397,7 @@ def draw_nodes(
         * "max_node_size" (default: 30)
         * "min_node_lw" (default: 0)
         * "max_node_lw" (default: 5)
-    
+
     kwargs : optional keywords
         See `draw_node_labels` for a description of optional keywords.
 
@@ -595,7 +600,7 @@ def draw_hyperedges(
         Default parameters. Keys that may be useful to override default settings:
         * "min_dyad_lw" (default: 1)
         * "max_dyad_lw" (default: 10)
-    
+
     kwargs : optional keywords
         See `draw_hyperedge_labels` for a description of optional keywords.
 
@@ -839,7 +844,7 @@ def draw_simplices(
         Default parameters. Keys that may be useful to override default settings:
         * "min_dyad_lw" (default: 1)
         * "max_dyad_lw" (default: 10)
-    
+
     kwargs : optional keywords
         See `draw_hyperedge_labels` for a description of optional keywords.
 
@@ -1916,3 +1921,231 @@ def to_marker_edge(marker_size, marker):
     _update_lims(pos_nodes, ax)
 
     return ax, (node_collection, phantom_node_collection)
+
+
+def draw_bipartite(
+    H,
+    node_pos=None,
+    edge_pos=None,
+    ax=None,
+    node_fc="white",
+    node_ec="black",
+    node_shape="o",
+    node_lw=1,
+    node_size=10,
+    edge_marker_fc="blue",
+    edge_marker_ec="black",
+    edge_marker_shape="s",
+    edge_marker_lw=1,
+    edge_marker_size=10,
+    dyad_color="black",
+    dyad_lw=1,
+    max_order=None,
+    rescale_sizes=True,
+    **kwargs,
+):
+    """Draw a hypergraph as a bipartite network.
+
+    Parameters
+    ----------
+    H : Hypergraph
+        The hypergraph to draw.
+    ax : matplotlib.pyplot.axes, optional
+        Axis to draw on. If None (default), get the current axes.
+    lines_fc : str, dict, iterable, optional
+        Color of the hyperedges (lines). If str, use the same color for all hyperedges.
+        If a dict, must contain (hyperedge_id: color_str) pairs. If other iterable,
+        assume the colors are specified in the same order as the hyperedges are found
+        in DH.edges. If None (default), use the size of the hyperedges.
+    lines_lw : int, float, dict, iterable, optional
+        Line width of the hyperedges (lines). If int or float, use the same width for
+        all hyperedges. If a dict, must contain (hyperedge_id: width) pairs. If other
+        iterable, assume the widths are specified in the same order as the hyperedges
+        are found in DH.edges. By default, 1.5.
+    line_head_width : float, optional
+        Length of arrows' heads. By default, 0.05
+    node_fc : str, dict, iterable, or NodeStat, optional
+        Color of the nodes.  If str, use the same color for all nodes.  If a dict, must
+        contain (node_id: color_str) pairs.  If other iterable, assume the colors are
+        specified in the same order as the nodes are found in H.nodes. If NodeStat, use
+        the colormap specified with node_fc_cmap. By default, "white".
+    node_ec : str, dict, iterable, or NodeStat, optional
+        Color of node borders.  If str, use the same color for all nodes.  If a dict,
+        must contain (node_id: color_str) pairs.  If other iterable, assume the colors
+        are specified in the same order as the nodes are found in H.nodes. If NodeStat,
+        use the colormap specified with node_ec_cmap. By default, "black".
+    node_lw : int, float, dict, iterable, or NodeStat, optional
+        Line width of the node borders in pixels.  If int or float, use the same width
+        for all node borders.  If a dict, must contain (node_id: width) pairs.  If
+        iterable, assume the widths are specified in the same order as the nodes are
+        found in H.nodes. If NodeStat, use a monotonic linear interpolation defined
+        between min_node_lw and max_node_lw. By default, 1.
+    node_size : int, float, dict, iterable, or NodeStat, optional
+        Radius of the nodes in pixels.  If int or float, use the same radius for all
+        nodes.  If a dict, must contain (node_id: radius) pairs.  If iterable, assume
+        the radiuses are specified in the same order as the nodes are found in
+        H.nodes. If NodeStat, use a monotonic linear interpolation defined between
+        min_node_size and max_node_size. By default, 15.
+    edge_marker_toggle: bool, optional
+        If True then marker representing the hyperedges are drawn. By default True.
+    edge_marker_fc: str, dict, iterable, optional
+        Filling color of the hyperedges (markers). If str, use the same color for all hyperedges.
+        If a dict, must contain (hyperedge_id: color_str) pairs. If other iterable,
+        assume the colors are specified in the same order as the hyperedges are found
+        in DH.edges. If None (default), use the size of the hyperedges.
+    edge_marker_ec: str, dict, iterable, optional
+        Edge color of the hyperedges (markers). If str, use the same color for all hyperedges.
+        If a dict, must contain (hyperedge_id: color_str) pairs. If other iterable,
+        assume the colors are specified in the same order as the hyperedges are found
+        in DH.edges. If None (default), use the size of the hyperedges.
+    edge_marker: str, optional
+        Marker used for the hyperedges. By default 's' (square marker).
+    max_order : int, optional
+        Maximum of hyperedges to plot. If None (default), plots all orders.
+    node_labels : bool or dict, optional
+        If True, draw ids on the nodes. If a dict, must contain (node_id: label) pairs.
+        By default, False.
+    hyperedge_labels : bool or dict, optional
+        If True, draw ids on the hyperedges. If a dict, must contain (edge_id: label)
+        pairs.  By default, False.
+    **kwargs : optional args
+        Alternate default values. Values that can be overwritten are the following:
+        * min_node_size
+        * max_node_size
+        * min_node_lw
+        * max_node_lw
+        * min_edge_marker_size
+        * max_edge_marker_size
+        * min_edge_marker_lw
+        * max_edge_marker_lw
+        * node_fc_cmap
+        * node_ec_cmap
+        * edge_marker_fc_cmap
+        * edge_marker_ec_cmap
+        * min_dyad_lw
+        * max_dyad_lw
+        * dyad_color_cmap
+
+
+    Returns
+    -------
+    ax : matplotlib.pyplot.axes
+
+    Raises
+    ------
+    XGIError
+        If something different than a DiHypergraph is passed.
+
+    See Also
+    --------
+    draw
+    draw_nodes
+    draw_node_labels
+
+    """
+    if not isinstance(H, Hypergraph):
+        raise XGIError("The input must be a Hypergraph")
+
+    settings = {
+        "min_node_lw": 10.0,
+        "max_node_lw": 30.0,
+        "min_node_size": 10.0,
+        "max_node_size": 30.0,
+        "min_edge_marker_lw": 10.0,
+        "max_edge_marker_lw": 30.0,
+        "min_edge_marker_size": 10.0,
+        "max_edge_marker_size": 30.0,
+        "min_dyad_lw": 1.0,
+        "max_dyad_lw": 5.0,
+        "node_fc_cmap": cm.Reds,
+        "node_ec_cmap": cm.RdBu,
+        "dyad_color_cmap": cm.Blues,
+        "edge_marker_fc_cmap": cm.Greys,
+        "edge_marker_ec_cmap": cm.Blues,
+    }
+
+    settings.update(kwargs)
+
+    node_settings = {
+        "min_node_lw": settings["min_node_lw"],
+        "max_node_lw": settings["max_node_lw"],
+        "min_node_size": settings["min_node_size"],
+        "max_node_size": settings["max_node_size"],
+        "node_fc_cmap": settings["node_fc_cmap"],
+        "node_ec_cmap": settings["node_ec_cmap"],
+    }
+
+    edge_marker_settings = {
+        "min_node_lw": settings["min_edge_marker_lw"],
+        "max_node_lw": settings["max_edge_marker_lw"],
+        "min_node_size": settings["min_edge_marker_size"],
+        "max_node_size": settings["max_edge_marker_size"],
+        "node_fc_cmap": settings["edge_marker_fc_cmap"],
+        "node_ec_cmap": settings["edge_marker_ec_cmap"],
+    }
+
+    if not node_pos or not edge_pos:
+        node_pos, edge_pos = bipartite_spring_layout(H)
+
+    if ax is None:
+        ax = plt.gca()
+
+    ax, node_collection = draw_nodes(
+        H=H,
+        pos=node_pos,
+        ax=ax,
+        node_fc=node_fc,
+        node_ec=node_ec,
+        node_lw=node_lw,
+        node_size=node_size,
+        node_shape=node_shape,
+        zorder=2,
+        params=node_settings,
+        node_labels=None,
+        rescale_sizes=rescale_sizes,
+        **kwargs,
+    )
+
+    ax, edge_marker_collection = draw_nodes(
+        H=H.dual(),
+        pos=edge_pos,
+        ax=ax,
+        node_fc=edge_marker_fc,
+        node_ec=edge_marker_ec,
+        node_lw=edge_marker_lw,
+        node_size=edge_marker_size,
+        node_shape=edge_marker_shape,
+        zorder=1,
+        params=edge_marker_settings,
+        node_labels=None,
+        rescale_sizes=rescale_sizes,
+        **kwargs,
+    )
+
+    dyads = to_bipartite_edgelist(H)
+    dyad_lw = _draw_arg_to_arr(dyad_lw)
+    # dyad_color, dyad_c_mapped = _parse_color_arg(dyad_color, list(dyads)
+    # check validity of input values
+    if np.any(dyad_lw < 0):
+        raise ValueError("dyad_lw cannot contain negative values.")
+
+    # interpolate if needed
+    if rescale_sizes and isinstance(dyad_lw, np.ndarray):
+        dyad_lw = _interp_draw_arg(
+            dyad_lw, settings["min_dyad_lw"], settings["max_dyad_lw"]
+        )
+
+    dyad_pos = np.asarray([(node_pos[list(e)[0]], edge_pos[list(e)[1]]) for e in dyads])
+
+    dyad_collection = LineCollection(
+        dyad_pos,
+        colors=dyad_color,
+        linewidths=dyad_lw,
+        antialiaseds=(1,),
+        cmap=settings["dyad_color_cmap"],
+        zorder=0,
+    )
+
+    ax.add_collection(dyad_collection)
+
+    return ax, (node_collection, edge_marker_collection, dyad_collection)

xgi/drawing/draw_utils.py

@@ -1,18 +1,9 @@
 """Draw hypergraphs and simplicial complexes with matplotlib."""
 
-from collections.abc import Iterable
-
 import matplotlib.pyplot as plt
 import numpy as np
-from matplotlib.colors import (
-    LinearSegmentedColormap,
-    ListedColormap,
-    is_color_like,
-    to_rgba_array,
-)
-from numpy import ndarray
-
-from ..exception import XGIError
+from matplotlib.colors import is_color_like, to_rgba_array
+
 from ..stats import EdgeStat, IDStat, NodeStat
 from .layout import barycenter_spring_layout