iplotx 1.5.1__tar.gz → 1.7.0__tar.gz

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: iplotx
-Version: 1.5.1
-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.5.1 → 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.5.1 → 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.5.1 → 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.5.1 → iplotx-1.7.0}/docs/source/sg_execution_times.rst

@@ -6,7 +6,7 @@
 
 Computation times
 =================
-**00:00.069** total execution time for 85 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_custom_vertex.py` (``../../gallery/style/plot_custom_vertex.py``)
-     - 00:00.069
+   * - :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
@@ -152,6 +155,9 @@ Computation times
    * - :ref:`sphx_glr_gallery_other_plot_animation.py` (``../../gallery/other/plot_animation.py``)
      - 00:00.000
      - 0.0
+   * - :ref:`sphx_glr_gallery_other_plot_bundles.py` (``../../gallery/other/plot_bundles.py``)
+     - 00:00.000
+     - 0.0
    * - :ref:`sphx_glr_gallery_other_plot_constellation.py` (``../../gallery/other/plot_constellation.py``)
      - 00:00.000
      - 0.0
@@ -161,25 +167,28 @@ Computation times
    * - :ref:`sphx_glr_gallery_other_plot_feedbacks.py` (``../../gallery/other/plot_feedbacks.py``)
      - 00:00.000
      - 0.0
-   * - :ref:`sphx_glr_gallery_other_plot_filled_edges.py` (``../../gallery/other/plot_filled_edges.py``)
-     - 00:00.000
-     - 0.0
    * - :ref:`sphx_glr_gallery_other_plot_geomap.py` (``../../gallery/other/plot_geomap.py``)
      - 00:00.000
      - 0.0
    * - :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``)
      - 00:00.000
      - 0.0
    * - :ref:`sphx_glr_gallery_style_plot_depthshade.py` (``../../gallery/style/plot_depthshade.py``)
@@ -188,12 +197,18 @@ 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
    * - :ref:`sphx_glr_gallery_style_plot_elements.py` (``../../gallery/style/plot_elements.py``)
      - 00:00.000
      - 0.0
+   * - :ref:`sphx_glr_gallery_style_plot_filled_edges.py` (``../../gallery/style/plot_filled_edges.py``)
+     - 00:00.000
+     - 0.0
    * - :ref:`sphx_glr_gallery_style_plot_four_grids.py` (``../../gallery/style/plot_four_grids.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.5.1 → 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.7.0/gallery/style/plot_curved_waypoints.py

@@ -0,0 +1,43 @@
+"""
+Curved waypoints
+================
+
+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.
+"""
+
+import matplotlib.pyplot as plt
+import numpy as np
+import iplotx as ipx
+
+g = {
+    "edges": [
+        ("A", "B"),
+    ],
+}
+layout = {
+    "A": (0, 0),
+    "B": (1, 2),
+}
+
+fig, axs = plt.subplots(1, 2, figsize=(8, 4))
+for ax, curved in zip(axs, [False, True]):
+    ipx.network(
+        g,
+        layout=layout,
+        ax=ax,
+        vertex_labels=True,
+        edge_waypoints=[[[1, 1], [0, 1.5]]],
+        edge_curved=curved,
+    )
+    if not curved:
+        ax.set_title("Straight waypoints")
+    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.5.1 → 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.5.1 → iplotx-1.7.0}/iplotx/edge/__init__.py

@@ -367,21 +367,13 @@ class EdgeCollection(mpl.collections.PatchCollection):
 
             # Leaf rotation
             edge_stylei = rotate_style(self._style, index=i, key=(v1, v2))
-            if edge_stylei.get("curved", False):
-                tension = edge_stylei.get("tension", 5)
-                ports = edge_stylei.get("ports", (None, None))
-            elif edge_stylei.get("arc", False):
-                tension = edge_stylei.get("tension", 1)
-                ports = None
-            else:
-                tension = 0
-                ports = None
 
             # Scale shrink by dpi
             dpi = self.figure.dpi if hasattr(self, "figure") else 72.0
             shrink = dpi / 72.0 * edge_stylei.pop("shrink", 0)
 
-            # False is a synonym for "none"
+            # Edge geometry and waypoints
+            # waypoints: False is a synonym for "none"
             waypoints = edge_stylei.get("waypoints", "none")
             if waypoints is False or waypoints is np.False_:
                 waypoints = "none"
@@ -391,10 +383,32 @@ class EdgeCollection(mpl.collections.PatchCollection):
                 raise ValueError(
                     "Could not determine automatically type of edge waypoints.",
                 )
-            if waypoints != "none":
-                ports = edge_stylei.get("ports", (None, None))
 
+            # Waypoints, curved, and arc have a complex logic
+            # TODO: This could be simplified I suppose
+            has_waypoints = waypoints != "none"
+            curved = edge_stylei.get("curved", False)
             arc = edge_stylei.get("arc", False)
+            ports = edge_stylei.get("ports", (None, None))
+
+            # For now, we establish a hierarchy from the most specialised to
+            # the most common cases. Each specialisation silences lower levels
+            # Tension and ports are entirely enslaved to the
+            # waypoint/arc/curved geometry settings.
+            # NOTE: The idea here is to not punish users for slight style
+            # inconsistencies that may well stem from fallback libraries
+            if has_waypoints:
+                tension = 0
+                arc = False
+            elif arc:
+                tension = edge_stylei.get("tension", 1)
+                ports = None
+                curved = False
+            elif curved:
+                tension = edge_stylei.get("tension", 5)
+            else:
+                tension = 0
+                ports = None
 
             # Compute actual edge path
             path, angles = _compute_edge_path(
@@ -406,6 +420,7 @@ class EdgeCollection(mpl.collections.PatchCollection):
                 tension=tension,
                 waypoints=waypoints,
                 ports=ports,
+                curved=curved,
                 arc=arc,
                 layout_coordinate_system=self._vertex_collection.get_layout_coordinate_system(),
                 shrink=shrink,

{iplotx-1.5.1 → iplotx-1.7.0}/iplotx/edge/geometry.py

@@ -239,6 +239,7 @@ def _compute_edge_path_straight(
 
 def _compute_edge_path_waypoints(
     waypoints,
+    curved,
     vcoord_data,
     vpath_fig,
     vsize_fig,
@@ -277,8 +278,19 @@ def _compute_edge_path_waypoints(
                 + vcoord_fig[i]
             )
 
-        points = [vshorts[0]] + list(waypoints) + [vshorts[1]]
-        codes = ["MOVETO"] + ["LINETO"] * len(waypoints) + ["LINETO"]
+        if not curved:
+            points = [vshorts[0]] + list(waypoints) + [vshorts[1]]
+            codes = ["MOVETO"] + ["LINETO"] * len(waypoints) + ["LINETO"]
+        else:
+            points = [vshorts[0]]
+            for i, waypoint in enumerate(waypoints):
+                if i != 0:
+                    points.append(0.5 * (points[-1] + waypoint))
+                points.append(waypoint)
+                points.append(waypoint)
+            points.append(vshorts[1])
+            codes = ["MOVETO"] + ["CURVE4"] * (len(points) - 1)
+
         angles = tuple(thetas)
 
     elif waypoints in ("x0y1", "y0x1"):
@@ -587,6 +599,7 @@ def _compute_edge_path(
     tension: float = 0,
     waypoints: str | tuple[float, float] | Sequence[tuple[float, float]] | np.ndarray = "none",
     ports: Pair[Optional[str]] = (None, None),
+    curved: bool = False,
     arc: bool = False,
     layout_coordinate_system: str = "cartesian",
     **kwargs,
@@ -600,6 +613,7 @@ def _compute_edge_path(
     if waypoints != "none":
         return _compute_edge_path_waypoints(
             waypoints,
+            curved,
             *args,
             layout_coordinate_system=layout_coordinate_system,
             ports=ports,