iplotx 1.6.0__tar.gz → 1.7.0__tar.gz

{iplotx-1.6.0 → iplotx-1.7.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: iplotx
-Version: 1.6.0
-Summary: Plot networkx from igraph and networkx.
+Version: 1.7.0
+Summary: Universal network and tree visualisation library.
 Project-URL: Homepage, https://github.com/fabilab/iplotx
 Project-URL: Documentation, https://readthedocs.org/iplotx
 Project-URL: Repository, https://github.com/fabilab/iplotx.git
@@ -41,7 +41,7 @@ Description-Content-Type: text/markdown
 [![RTD](https://readthedocs.org/projects/iplotx/badge/?version=latest)](https://iplotx.readthedocs.io/en/latest/)
 [![Coverage Status](https://coveralls.io/repos/github/fabilab/iplotx/badge.svg?branch=main)](https://coveralls.io/github/fabilab/iplotx?branch=main)
 ![pylint](assets/pylint.svg)
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.16599333.svg)](https://doi.org/10.5281/zenodo.16599333)
+[DOI](https://f1000research.com/articles/14-1377)
 
 
 # iplotx
@@ -90,10 +90,10 @@ See [readthedocs](https://iplotx.readthedocs.io/en/latest/) for the full documen
 See [gallery](https://iplotx.readthedocs.io/en/latest/gallery/index.html).
 
 ## Citation
-If you use `iplotx` for publication figures, please cite the [zenodo preprint](https://doi.org/10.5281/zenodo.16599333):
+If you use `iplotx` for publication figures, please cite:
 
 ```
-F. Zanini. (2025). Unified network visualisation in Python. Zenodo [PREPRINT]. https://doi.org/10.5281/zenodo.16599333
+F. Zanini. A universal tool for visualisation of networks and trees in Python. F1000Research 2025, 14:1377. https://doi.org/10.12688/f1000research.173131.1
 ```
 
 ## Features

{iplotx-1.6.0 → iplotx-1.7.0}/README.md

@@ -3,7 +3,7 @@
 [![RTD](https://readthedocs.org/projects/iplotx/badge/?version=latest)](https://iplotx.readthedocs.io/en/latest/)
 [![Coverage Status](https://coveralls.io/repos/github/fabilab/iplotx/badge.svg?branch=main)](https://coveralls.io/github/fabilab/iplotx?branch=main)
 ![pylint](assets/pylint.svg)
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.16599333.svg)](https://doi.org/10.5281/zenodo.16599333)
+[DOI](https://f1000research.com/articles/14-1377)
 
 
 # iplotx
@@ -52,10 +52,10 @@ See [readthedocs](https://iplotx.readthedocs.io/en/latest/) for the full documen
 See [gallery](https://iplotx.readthedocs.io/en/latest/gallery/index.html).
 
 ## Citation
-If you use `iplotx` for publication figures, please cite the [zenodo preprint](https://doi.org/10.5281/zenodo.16599333):
+If you use `iplotx` for publication figures, please cite:
 
 ```
-F. Zanini. (2025). Unified network visualisation in Python. Zenodo [PREPRINT]. https://doi.org/10.5281/zenodo.16599333
+F. Zanini. A universal tool for visualisation of networks and trees in Python. F1000Research 2025, 14:1377. https://doi.org/10.12688/f1000research.173131.1
 ```
 
 ## Features

{iplotx-1.6.0 → iplotx-1.7.0}/docs/source/api/complete_style_specification.md

@@ -112,6 +112,7 @@
         # means a semicircle, and numbers above 5 create very large arcs, almost full
         # circles. The exact definition of tension for arcs is the tangent of a
         # quarter of the angle spanned by the arc.
+        # Tension is not used if explicit waypoints are set for the edge.
         "tension": float,
 
         # Tension for self-loops (higher values create more bigger loops).
@@ -151,8 +152,17 @@
         # - ymidx0,ymidx1: The xy swap of the previous option.
         # - x0y1: One waypoint, with x of the first point and y of the second point.
         # - x1y0: The xy swap of the previous option.
-        # We are looking into ways to generalise this idea.
-        "waypoints": str,
+        #
+        # Instead of a string you can also specify a per-edge list of waypoints.
+        # Each waypoint is a tuple of two floats (x,y) in data coordinates. Each
+        # edge can have zero, one, or multiple waypoints.
+        # If used in this way, this option will have slightly different appearances
+        # depending of whether the edges are curved or straight (edge_curved). For
+        # straight edges, the edge will always pass through all waypoints. For
+        # curved edges, the waypoints are used as cubic Bezier control points and
+        # the edge will pass through the midpoints between each pair of consecutive
+        # waypoints.
+        "waypoints": str | list[list[tuple[float, float]]],
 
         # Edge arrow style for directed graphs
         "arrow": {

{iplotx-1.6.0 → iplotx-1.7.0}/docs/source/installing.md

@@ -3,6 +3,12 @@
 pip install iplotx
 ```
 
+To also install [ilayoutx](https://ilayoutx.readthedocs.io/en/main/) to compute network layouts before visualising them:
+
+```
+pip install iplotx ilayoutx
+```
+
 
 ## Quick Start
 ::::{tab-set}
@@ -71,10 +77,10 @@ Either way, the result is the same:
 We believe graph **analysis**, graph **layouting**, and graph **visualisation** to be three separate tasks. `iplotx` currently focuses on visualisation. It can also compute simple tree layouts and might expand towards network layouts in the future.
 
 ## Citation
-If you use `iplotx` for publication figures, please cite the [zenodo preprint](https://doi.org/10.5281/zenodo.16599333):
+If you use `iplotx` for publication figures, please cite:
 
 ```
-F. Zanini. (2025). Unified network visualisation in Python. Zenodo [PREPRINT]. https://doi.org/10.5281/zenodo.16599333
+F. Zanini. A universal tool for visualisation of networks and trees in Python. F1000Research 2025, 14:1377. https://doi.org/10.12688/f1000research.173131.1
 ```
 
 ## Contributing

{iplotx-1.6.0 → iplotx-1.7.0}/docs/source/sg_execution_times.rst

@@ -6,7 +6,7 @@
 
 Computation times
 =================
-**00:00.136** total execution time for 87 files **from all galleries**:
+**00:00.068** total execution time for 90 files **from all galleries**:
 
 .. container::
 
@@ -32,8 +32,8 @@ Computation times
    * - Example
      - Time
      - Mem (MB)
-   * - :ref:`sphx_glr_gallery_style_plot_curved_waypoints.py` (``../../gallery/style/plot_curved_waypoints.py``)
-     - 00:00.136
+   * - :ref:`sphx_glr_gallery_fun_plot_67.py` (``../../gallery/fun/plot_67.py``)
+     - 00:00.068
      - 0.0
    * - :ref:`sphx_glr_gallery_basic_plot_3d.py` (``../../gallery/basic/plot_3d.py``)
      - 00:00.000
@@ -92,6 +92,9 @@ Computation times
    * - :ref:`sphx_glr_gallery_biology_plot_tca_cycle.py` (``../../gallery/biology/plot_tca_cycle.py``)
      - 00:00.000
      - 0.0
+   * - :ref:`sphx_glr_gallery_fun_plot_train.py` (``../../gallery/fun/plot_train.py``)
+     - 00:00.000
+     - 0.0
    * - :ref:`sphx_glr_gallery_network_science_plot_arrowlawn.py` (``../../gallery/network_science/plot_arrowlawn.py``)
      - 00:00.000
      - 0.0
@@ -170,16 +173,19 @@ Computation times
    * - :ref:`sphx_glr_gallery_other_plot_graph.py` (``../../gallery/other/plot_graph.py``)
      - 00:00.000
      - 0.0
+   * - :ref:`sphx_glr_gallery_other_plot_hover_neighborhood.py` (``../../gallery/other/plot_hover_neighborhood.py``)
+     - 00:00.000
+     - 0.0
    * - :ref:`sphx_glr_gallery_other_plot_mouse_hover.py` (``../../gallery/other/plot_mouse_hover.py``)
      - 00:00.000
      - 0.0
    * - :ref:`sphx_glr_gallery_other_plot_multiarc.py` (``../../gallery/other/plot_multiarc.py``)
      - 00:00.000
      - 0.0
-   * - :ref:`sphx_glr_gallery_other_plot_train.py` (``../../gallery/other/plot_train.py``)
+   * - :ref:`sphx_glr_gallery_style_plot_arrows.py` (``../../gallery/style/plot_arrows.py``)
      - 00:00.000
      - 0.0
-   * - :ref:`sphx_glr_gallery_style_plot_arrows.py` (``../../gallery/style/plot_arrows.py``)
+   * - :ref:`sphx_glr_gallery_style_plot_curved_waypoints.py` (``../../gallery/style/plot_curved_waypoints.py``)
      - 00:00.000
      - 0.0
    * - :ref:`sphx_glr_gallery_style_plot_custom_vertex.py` (``../../gallery/style/plot_custom_vertex.py``)
@@ -191,6 +197,9 @@ Computation times
    * - :ref:`sphx_glr_gallery_style_plot_edge_geometries.py` (``../../gallery/style/plot_edge_geometries.py``)
      - 00:00.000
      - 0.0
+   * - :ref:`sphx_glr_gallery_style_plot_edge_multicolor.py` (``../../gallery/style/plot_edge_multicolor.py``)
+     - 00:00.000
+     - 0.0
    * - :ref:`sphx_glr_gallery_style_plot_edgepadding.py` (``../../gallery/style/plot_edgepadding.py``)
      - 00:00.000
      - 0.0

iplotx-1.7.0/gallery/GALLERY_HEADER.rst

@@ -0,0 +1,34 @@
+Gallery
+=======
+.. warning::
+  If plots do not show on screen, try adding `show=True` to your function call:
+
+  .. code-block::
+
+    ipx.network(
+      ...,
+      show=True,
+    )
+
+  This is a peculiarity of `matplotlib`_, the plotting engine behind `iplotx`,
+  and depends on your Python environment (e.g., Jupyter notebooks, terminal,
+  interactive mode, backend, etc). You might want to enable `interactive mode`_
+  *before* plotting to ensure everything is rendered immediately:
+
+  .. code-block::
+
+    import matplotlib.pyplot as plt
+    import iplotx as ipx
+
+    ...
+
+    plt.ion()
+    ipx.network(
+      ...,
+    )
+
+  If interactive mode is on, you do not need `show=True` (because plots are
+  always rendered immediately anyway).
+
+.. _matplotlib: https://matplotlib.org/
+.. _interactive mode: https://matplotlib.org/stable/users/explain/figure/interactive.html

iplotx-1.7.0/gallery/fun/GALLERY_HEADER.rst

@@ -0,0 +1,2 @@
+Fun
++++

iplotx-1.7.0/gallery/fun/plot_67.py

@@ -0,0 +1,54 @@
+"""
+6-7
+===
+
+This example shows that yo 6-7.
+"""
+
+import igraph as ig
+import matplotlib.pyplot as plt
+import iplotx as ipx
+
+g6 = ig.Graph.Ring(11, directed=True)
+g0 = ig.Graph.Ring(4, directed=True)
+gdash = ig.Graph(edges=[(0, 1), (1, 0)], directed=True)
+g7 = ig.Graph.Ring(6, directed=True)
+g67 = ig.disjoint_union([g6, g0, gdash, g7])
+
+layout = [
+    # 6
+    [0, 0],
+    [1, 0],
+    [2, 1],
+    [2, 3],
+    [1, 4],
+    [0.8, 4],
+    [2, 6],
+    [1, 6],
+    [0, 4],
+    [-1, 2],
+    [-1, 1],
+    # 0
+    [0.3, 1.5],
+    [1.0, 1.5],
+    [1.0, 2.5],
+    [0.3, 2.5],
+    # dash
+    [3, 2],
+    [5, 2],
+    # 7
+    [6, 0],
+    [7, 0],
+    [8, 6],
+    [6, 6],
+    [6, 5],
+    [7, 5],
+]
+
+with ipx.style.context("unicorn"):
+    ipx.network(
+        g67,
+        layout,
+        node_size=9,
+        edge_linewidth=4,
+    )

iplotx-1.7.0/gallery/other/plot_hover_neighborhood.py

@@ -0,0 +1,83 @@
+"""
+Hover neighborhoods
+===================
+
+This example shows how to highlight a node and its neighborhood by hovering with the mouse on it.
+
+.. warning::
+  This example will run in a Python, IPython, or Jupyter session, however the
+  interactive functionality is not visible on the HTML page. Download the code
+  at the end of this page and run it in a local Python environment to see
+  the results.
+"""
+
+import matplotlib.pyplot as plt
+import igraph as ig
+import iplotx as ipx
+
+g = ig.Graph.Erdos_Renyi(n=40, m=120)
+layout = g.layout()
+
+fig, axs = plt.subplots(1, 2, gridspec_kw={"width_ratios": [1, 0.2]}, figsize=(8, 6))
+art = ipx.network(
+    g,
+    layout=layout,
+    ax=axs[0],
+    aspect=1,
+    vertex_zorder=5,
+)[0]
+base_nodecolors = art.get_vertices().get_facecolors()
+nodecolors = base_nodecolors.copy()
+edgecolors = art.get_edges().get_edgecolors()
+edgewidths = art.get_edges().get_linewidths()
+
+axs[1].set_axis_off()
+txt = axs[1].text(0.5, 0.5, "", ha="center", va="center", wrap=True,
+                  fontsize=40)
+
+
+def hover_callback(event):
+    """React to mouse hovering over vertices."""
+    if event.inaxes == axs[0]:
+        cont, ind = art.get_vertices().contains(event)
+
+        # Reset everyone's color
+        is_base = (nodecolors == base_nodecolors).all()
+
+        # If mouse is over a vertex, change the color around there
+        # and redraw
+        if cont:
+            i = ind["ind"][0]
+            nodecolors[:] = [0, 0, 0, 0.3]
+            nodecolors[g.neighbors(i)] = [1, 0, 0, 0.6]
+            nodecolors[i] = [1, 0, 0, 1]
+            art.get_vertices().set_facecolors(nodecolors)
+            edgecolors[:] = [0, 0, 0, 0.3]
+            edgecolors[g.incident(i)] = [0, 0, 0, 1]
+            art.get_edges().set_edgecolors(edgecolors)
+            edgewidths[:] = 1
+            edgewidths[g.incident(i)] = 2
+            art.get_edges().set_linewidths(edgewidths)
+
+            txt.set_text(str(i))
+        # Otherwise, change back to base and redraw
+        elif not is_base:
+            nodecolors[:] = base_nodecolors
+            vertex_artist.set_facecolors(nodecolors)
+            edgecolors[:] = [0, 0, 0, 1]
+            art.get_edges().set_edgecolors(edgecolors)
+            edgewidths[:] = 1
+            art.get_edges().set_linewidths(edgewidths)
+            txt.set_text("")
+        # If nothing changed, no need to redraw
+        else:
+            return
+
+        # Redraw if needed
+        fig.canvas.draw_idle()
+
+
+fig.canvas.mpl_connect(
+    "motion_notify_event",
+    hover_callback,
+)

{iplotx-1.6.0 → iplotx-1.7.0}/gallery/other/plot_mouse_hover.py

@@ -43,7 +43,7 @@ def hover_callback(event):
     if event.inaxes == ax:
         vc = art.get_vertices()
         cont, ind = vc.contains(event)
-        # If mouse is over a vertex, show the buble
+        # If mouse is over a vertex, show the bubble
         if cont:
             i = ind["ind"][0]
             annot.xy = vc.get_offsets()[i]

{iplotx-1.6.0 → iplotx-1.7.0}/gallery/style/plot_curved_waypoints.py

@@ -6,10 +6,6 @@ This example demonstrates the use of curved edge waypoints.
 For straight waypoints, the edge will pass through each waypoint.
 For curved waypoints, they are used as cubic Bezier points to
 interpolate smoothly between.
-
-
-.. tip:
-  The edge will actually pass through the midpoints between two consecutive waypoints.
 """
 
 import matplotlib.pyplot as plt
@@ -41,3 +37,7 @@ for ax, curved in zip(axs, [False, True]):
     else:
         ax.set_title("Curved waypoints")
 fig.tight_layout()
+
+#%%
+# .. tip:: The edge will actually pass through the midpoints between two consecutive waypoints.
+#

iplotx-1.7.0/gallery/style/plot_edge_multicolor.py

@@ -0,0 +1,29 @@
+"""
+Multicolor edges
+================
+
+Sometimes the need arises to color edges with multiple colors at the same time. That's what multigraphs are for.
+This example shows the concept in action.
+
+"""
+
+import networkx as nx
+import matplotlib.pyplot as plt
+import iplotx as ipx
+
+g = nx.MultiGraph()
+g.add_edges_from([(0, 1), (1, 2), (0, 2), (0, 1)])
+
+layout = [(0, 0), (1, 0), (0.5, 1)]
+
+ipx.network(
+    g,
+    layout,
+    edge_color=["black", "gold", "tomato", "tomato"],
+    edge_paralleloffset=8,
+    edge_linewidth=4,
+    vertex_size=40,
+    vertex_facecolor="none",
+    vertex_edgecolor="black",
+    vertex_linewidth=4,
+)

{iplotx-1.6.0 → iplotx-1.7.0}/gallery/style/plot_waypoints.py

@@ -34,7 +34,3 @@ ipx.network(
     edge_waypoints=["none", [(1, 1), (0.5, 1.5), (1, 1.5)], "none", "none"],
 )
 plt.ion(); plt.show()
-
-# %%
-# .. note::
-#   Edge waypoints are not currently compatible with curved edges.

{iplotx-1.6.0 → iplotx-1.7.0}/iplotx/plotting.py

@@ -20,6 +20,7 @@ from .network import NetworkArtist
 from .network.groups import GroupingCollection
 from .tree import TreeArtist
 from .style import context
+from .utils.matplotlib import _heuristic_show
 
 
 def network(
@@ -36,6 +37,7 @@ def network(
     margins: float | tuple[float, float] | tuple[float, float, float] = 0,
     strip_axes: bool = True,
     figsize: Optional[tuple[float, float]] = None,
+    show: Optional[bool] = None,
     **kwargs,
 ) -> list[mpl.artist.Artist]:
     """Plot this network and/or vertex grouping using the specified layout.
@@ -70,6 +72,9 @@ def network(
         figsize: If ax is None, a new matplotlib Figure is created. This argument specifies
             the (width, height) dimension of the figure in inches. If ax is not None, this
             argument is ignored. If None, the default matplotlib figure size is used.
+        show: If True, call plt.show() after plotting. If False, do not call plt.show(). If
+            None (default), try to guess based on the environment and do not show in case of
+            doubt.
         kwargs: Additional arguments are treated as an alternate way to specify style. If
             both "style" and additional **kwargs are provided, they are both applied in that
             order (style, then **kwargs).
@@ -78,7 +83,12 @@ def network(
         A list of mpl.artist.Artist objects, set as a direct child of the matplotlib Axes.
         The list can have one or two elements, depending on whether you are requesting to
         plot a network, a grouping, or both.
+
+    NOTE: If your plots are now showing to screen, try passing show=True.
     """
+    if show is None:
+        show = _heuristic_show()
+
     # Equivalence of node_labels and vertex_labels
     if node_labels is not None:
         vertex_labels = node_labels
@@ -164,6 +174,9 @@ def network(
         if (margins[0] != 0) or (margins[1] != 0) or ((len(margins) == 3) and (margins[2] != 0)):
             ax.margins(*margins)
 
+        if show:
+            plt.show()
+
         return artists
 
 
@@ -187,6 +200,7 @@ def tree(
     margins: float | tuple[float, float] = 0,
     strip_axes: bool = True,
     figsize: Optional[tuple[float, float]] = None,
+    show: Optional[bool] = None,
     **kwargs,
 ) -> TreeArtist:
     """Plot a tree using the specified layout.
@@ -226,13 +240,21 @@ def tree(
         figsize: If ax is None, a new matplotlib Figure is created. This argument specifies
             the (width, height) dimension of the figure in inches. If ax is not None, this
             argument is ignored. If None, the default matplotlib figure size is used.
+        show: If True, call plt.show() after plotting. If False, do not call plt.show(). If
+            None (default), try to guess based on the environment and do not show in case of
+            doubt.
         kwargs: Additional arguments are treated as an alternate way to specify style. If
             both "style" and additional **kwargs are provided, they are both applied in that
             order (style, then **kwargs).
 
     Returns:
         A TreeArtist object, set as a direct child of the matplotlib Axes.
+
+    NOTE: If your plots are now showing to screen, try passing show=True.
     """
+    if show is None:
+        show = _heuristic_show()
+
     # Equivalence of node_labels and vertex_labels
     if node_labels is not None:
         vertex_labels = node_labels
@@ -270,6 +292,9 @@ def tree(
         if (margins[0] != 0) or (margins[1] != 0):
             ax.margins(*margins)
 
+        if show:
+            plt.show()
+
     return artist
 
 
@@ -285,6 +310,7 @@ def doubletree(
     margins: float | tuple[float, float] = 0,
     strip_axes: bool = True,
     figsize: Optional[tuple[float, float]] = None,
+    show: Optional[bool] = None,
 ) -> tuple[TreeArtist, TreeArtist]:
     """Visualize two trees facing each other.
 
@@ -306,9 +332,26 @@ def doubletree(
         figsize: If ax is None, a new matplotlib Figure is created. This argument specifies
             the (width, height) dimension of the figure in inches. If ax is not None, this
             argument is ignored. If None, the default matplotlib figure size is used.
+        show: If True, call plt.show() after plotting. If False, do not call plt.show(). If
+            None (default), try to guess based on the environment and do not show in case of
+            doubt.
     Returns:
         A tuple with the left and right TreeArtist objects.
+
+    NOTE: If your plots are now showing to screen, try passing show=True.
     """
+    if show is None:
+        show = _heuristic_show()
+
+    if kwargs_left is None:
+        kwargs_left = {}
+    if "show" not in kwargs_left:
+        kwargs_left["show"] = False
+    if kwargs_right is None:
+        kwargs_right = {}
+    if "show" not in kwargs_right:
+        kwargs_right["show"] = False
+
     artist1 = tree(
         tree_left,
         layout="horizontal",
@@ -316,14 +359,11 @@ def doubletree(
         ax=ax,
         strip_axes=False,
         figsize=figsize,
-        **kwargs_left or {},
+        **kwargs_left,
     )
 
     ax = artist1.axes
 
-    if kwargs_right is None:
-        kwargs_right = {}
-
     had_layout_start = "layout_start" in kwargs_right
 
     artist2 = tree(
@@ -348,6 +388,9 @@ def doubletree(
 
     _postprocess_axes(ax, [artist1, artist2], strip=strip_axes, ignore_previous=True)
 
+    if show:
+        plt.show()
+
     return (artist1, artist2)
 
 

{iplotx-1.6.0 → iplotx-1.7.0}/iplotx/utils/matplotlib.py

@@ -282,3 +282,8 @@ def _get_data_scale(X, Y, Z):
     ptp_y = Y.max() - Y.min()
     ptp_z = Z.max() - Z.min()
     return np.sqrt(ptp_x**2 + ptp_y**2 + ptp_z**2)
+
+
+def _heuristic_show():
+    """Try guessing whether plt.show() should be called automatically."""
+    return False

{iplotx-1.6.0 → iplotx-1.7.0}/iplotx/version.py

@@ -2,4 +2,4 @@
 iplotx version information module.
 """
 
-__version__ = "1.6.0"
+__version__ = "1.7.0"

{iplotx-1.6.0 → iplotx-1.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "iplotx"
-description = "Plot networkx from igraph and networkx."
+description = "Universal network and tree visualisation library."
 authors = [
   {name = "Fabio Zanini", email = "fabio.zanini@unsw.edu.au"}
 ]