iplotx 1.3.0__tar.gz → 1.4.1__tar.gz

{iplotx-1.3.0 → iplotx-1.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iplotx
-Version: 1.3.0
+Version: 1.4.1
 Summary: Plot networkx from igraph and networkx.
 Project-URL: Homepage, https://github.com/fabilab/iplotx
 Project-URL: Documentation, https://readthedocs.org/iplotx

{iplotx-1.3.0 → iplotx-1.4.1}/docs/source/api/complete_style_specification.md

@@ -102,9 +102,14 @@
 
         "curved": bool,  # Whether the edge is curved (True) or straight (False)
 
-        # Tension for curved edges (0.0 for straight, higher values position the
-        # Bezier control points further away from the nodes, creating more wiggly lines)
+        # Tension for curved edges and arcs.
+        # For Bezier (curved) edges, 0.0 means straight, higher values position the
+        # Bezier control points further away from the nodes, creating more wiggly lines.
         # Negative values bend the curve on the other side of the straight line.
+        # For arc edges, 0.0 means straight, higher values draw larger arcs. 1.0
+        # 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": float,
 
         # Tension for self-loops (higher values create more bigger loops).
@@ -281,7 +286,7 @@
         # For horizontal and vertical layouts:
         #   start: Starting position in data units (tuple of two floats)
         #   span: Breadth in data units (float)
-        "start": float | tuple[float, float],
+        "start": float | tuple[float            margins=0.2,
         "span": float,
     },
     ############################################################################

{iplotx-1.3.0 → iplotx-1.4.1}/docs/source/installing.md

@@ -11,13 +11,11 @@ pip install iplotx
 
 ```
 import igraph as ig
-import matplotlib.pyplot as plt
 import iplotx as ipx
 
 g = ig.Graph.Ring(5)
 layout = g.layout("circle").coords
-fig, ax = plt.subplots(figsize=(3, 3))
-ipx.plot(g, ax=ax, layout=layout)
+ipx.network(g, layout)
 ```
 
 
@@ -27,13 +25,11 @@ ipx.plot(g, ax=ax, layout=layout)
 :::{tab-item} networkx
 ```
 import networkx as nx
-import matplotlib.pyplot as plt
 import iplotx as ipx
 
 g = nx.Graph([(0, 1), (1, 2), (2, 3), (3, 4), (4, 0)])
 layout = nx.layout.circular_layout(g)
-fig, ax = plt.subplots(figsize=(3, 3))
-ipx.plot(g, ax=ax, layout=layout)
+ipx.network(g, layout)
 ```
 
 :::
@@ -44,9 +40,6 @@ Either way, the result is the same:
 
 ![graph_basic](_static/graph_basic.png)
 
-## Gallery
-See <project:gallery/index.rst> for examples of plots made with `iplotx`. Feel free to suggest new examples on GitHub by opening a new issue or pull request!
-
 ## Features
 `iplotx`'s features' include:
 - per-edge and per-vertex styling using sequences or dictionaries
@@ -72,32 +65,17 @@ See <project:gallery/index.rst> for examples of plots made with `iplotx`. Feel f
 - animations (see <project:gallery/other/plot_animation.rst>)
 - 3D visualisations
 - mouse/keyboard interaction and events (e.g. hover, click, see <project:gallery/other/plot_mouse_hover.rst>)
-- ... and probably more by the time you read this.
+- ... and many more.
 
-## Styles
-`iplotx` is designed to produce publication-quality figures using **styles**, which are dictionaries specifying the visual properties of each graph element, including vertices, edges, arrows, labels, and groupings.
+## Rationale
+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.
 
-An example of style specification is as follows:
+## Citation
+If you use `iplotx` for publication figures, please cite the [zenodo preprint](https://doi.org/10.5281/zenodo.16599333):
 
-```python
-import iplotx as ipx
-with ipx.style.context({
-    'vertex': {
-        'size': 30,
-        'facecolor': 'red',
-        'edgecolor': 'none',
-    }
-}):
-    ipx.plot(...)
 ```
-
-See <project:style.md> for more info.
-
-## Reference API
-See <project:api.md> for reference documentation of all functions and classes in `iplotx`.
-
-## Rationale
-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.
+F. Zanini. (2025). Unified network visualisation in Python. Zenodo [PREPRINT]. https://doi.org/10.5281/zenodo.16599333
+```
 
 ## Contributing
 Open an [issue on GitHub](https://github.com/fabilab/iplotx/issues) to request features, report bugs, or show intention in contributing. Pull requests are very welcome.

{iplotx-1.3.0 → iplotx-1.4.1}/docs/source/sg_execution_times.rst

@@ -6,7 +6,7 @@
 
 Computation times
 =================
-**00:00.514** total execution time for 78 files **from all galleries**:
+**00:00.158** total execution time for 80 files **from all galleries**:
 
 .. container::
 
@@ -32,12 +32,15 @@ Computation times
    * - Example
      - Time
      - Mem (MB)
-   * - :ref:`sphx_glr_gallery_tree_plot_equalangle.py` (``../../gallery/tree/plot_equalangle.py``)
-     - 00:00.514
+   * - :ref:`sphx_glr_gallery_style_plot_edge_geometries.py` (``../../gallery/style/plot_edge_geometries.py``)
+     - 00:00.158
      - 0.0
    * - :ref:`sphx_glr_gallery_basic_plot_3d.py` (``../../gallery/basic/plot_3d.py``)
      - 00:00.000
      - 0.0
+   * - :ref:`sphx_glr_gallery_basic_plot_arcs.py` (``../../gallery/basic/plot_arcs.py``)
+     - 00:00.000
+     - 0.0
    * - :ref:`sphx_glr_gallery_basic_plot_basic.py` (``../../gallery/basic/plot_basic.py``)
      - 00:00.000
      - 0.0
@@ -227,6 +230,9 @@ Computation times
    * - :ref:`sphx_glr_gallery_tree_plot_elements_tree.py` (``../../gallery/tree/plot_elements_tree.py``)
      - 00:00.000
      - 0.0
+   * - :ref:`sphx_glr_gallery_tree_plot_equalangle.py` (``../../gallery/tree/plot_equalangle.py``)
+     - 00:00.000
+     - 0.0
    * - :ref:`sphx_glr_gallery_tree_plot_ete4.py` (``../../gallery/tree/plot_ete4.py``)
      - 00:00.000
      - 0.0

iplotx-1.4.1/gallery/basic/plot_arcs.py

@@ -0,0 +1,47 @@
+"""
+Arcs
+====
+
+This example showcases the ability of `iplotx` to curve edges into arcs, using tension to define the angular span of the arc.
+"""
+
+import igraph as ig
+import matplotlib.pyplot as plt
+import iplotx as ipx
+
+
+g = ig.Graph.Full(4)
+layout = [[0, 0], [1, 0], [2, 0], [3, 0]]
+
+fig, ax = plt.subplots()
+ipx.plot(
+    g,
+    layout=layout,
+    ax=ax,
+    edge_arc=True,
+    edge_tension=-1,
+)
+
+# %%
+#
+# Other values of tension can be used to create different arc shapes:
+
+fig, axs = plt.subplots(2, 2, figsize=(8, 8))
+for tension, ax in zip([0.5, 2.5, -0.5, -2.5], axs.ravel()):
+    ipx.plot(
+        g,
+        layout=layout,
+        ax=ax,
+        edge_arc=True,
+        edge_tension=tension,
+        margins=0.15,
+        title=f"Edge tension = {tension:.2f}",
+    )
+
+# %%
+# .. tip::
+#  Tension is defined as the tangent of the quarter of the angle spanned by the arc. A tension of 0 gives
+#  a straight line, a tension of 1 gives a semicircle, and higher tensions give increasingly larger arcs. A tension of
+#  infinity would give you a straight line away from the target vertex, but is not accepted by the library. Negative
+#  tensions result in arcs curving in the opposite direction.
+#

iplotx-1.4.1/gallery/style/plot_edge_geometries.py

@@ -0,0 +1,61 @@
+"""
+Edge geometries
+===============
+
+This example shows how to use edge geometries and tension to achieve different visualisation styles.
+"""
+
+
+import igraph as ig
+import matplotlib.pyplot as plt
+import iplotx as ipx
+
+
+g = ig.Graph.Full(2)
+layout = [[0, 0], [1, 0]]
+
+fig, axs = plt.subplots(3, 3, figsize=(6, 6), sharex=True, sharey=True)
+tensions = [
+    [1, 5, 10],
+    [0.2, 1, 2],
+]
+for edge_arc, axrow, tensionrow in zip([False, True], axs, tensions):
+    kwargs = {}
+    if not edge_arc:
+        kwargs["edge_curved"] = True
+    for tension, ax in zip(tensionrow, axrow):
+        ipx.plot(
+            g,
+            layout=layout,
+            ax=ax,
+            edge_arc=edge_arc,
+            edge_tension=tension,
+            title=f"Tension {tension:.1f}",
+            node_size=10,
+            **kwargs,
+        )
+axs[0, 0].set_ylabel("Bezier", fontsize=12)
+axs[1, 0].set_ylabel("Arc", fontsize=12)
+ipx.plot(
+    g,
+    layout,
+    ax=axs[2, 0],
+    node_size=10,
+)
+axs[2, 0].set_ylabel("Straight", fontsize=12)
+ipx.plot(
+    g,
+    layout,
+    ax=axs[2, 1],
+    node_size=10,
+    edge_waypoints=[[0.5, -0.15]],
+)
+ipx.plot(
+    g,
+    layout,
+    ax=axs[2, 2],
+    node_size=10,
+    edge_waypoints=[[[0.25, -0.15], [0.75, -0.15]]],
+)
+axs[2, 1].set_ylabel("Waypoints", fontsize=12)
+fig.tight_layout()

{iplotx-1.3.0 → iplotx-1.4.1}/iplotx/edge/__init__.py

@@ -370,6 +370,9 @@ class EdgeCollection(mpl.collections.PatchCollection):
             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
@@ -391,6 +394,8 @@ class EdgeCollection(mpl.collections.PatchCollection):
             if waypoints != "none":
                 ports = edge_stylei.get("ports", (None, None))
 
+            arc = edge_stylei.get("arc", False)
+
             # Compute actual edge path
             path, angles = _compute_edge_path(
                 vcoord_data,
@@ -401,6 +406,7 @@ class EdgeCollection(mpl.collections.PatchCollection):
                 tension=tension,
                 waypoints=waypoints,
                 ports=ports,
+                arc=arc,
                 layout_coordinate_system=self._vertex_collection.get_layout_coordinate_system(),
                 shrink=shrink,
             )
@@ -447,7 +453,7 @@ class EdgeCollection(mpl.collections.PatchCollection):
         # If none found, empty the dictionary already
         if (len(parallel_edges) == 0) or (max(parallel_edges.values(), key=len) == 1):
             parallel_edges = {}
-        if not self._style.get("curved", False):
+        if (not self._style.get("curved", False)) and (not self._style.get("arc", False)):
             while len(parallel_edges) > 0:
                 (v1, v2), indices = parallel_edges.popitem()
                 indices_inv = parallel_edges.pop((v2, v1), [])
@@ -712,6 +718,7 @@ def make_stub_patch(**kwargs):
         "split",
         "shrink",
         "depthshade",
+        "arc",
         # DEPRECATED
         "padding",
     ]

{iplotx-1.3.0 → iplotx-1.4.1}/iplotx/edge/geometry.py

@@ -393,6 +393,108 @@ def _compute_edge_path_waypoints(
     return path, angles
 
 
+def _compute_edge_path_arc(
+    tension,
+    vcoord_data,
+    vpath_fig,
+    vsize_fig,
+    trans,
+    trans_inv,
+    ports: Pair[Optional[str]] = (None, None),
+    shrink: float = 0,
+):
+    """Shorten the edge path along an arc.
+
+    Parameters:
+        tension: the tension of the arc. This is defined, for this function, as the tangent
+            of the angle spanning the arc. For instance, for a semicircle, the angle is
+            180 degrees, so the tension is +-1 (depending on the orientation).
+    """
+
+    # Coordinates in figure (default) coords
+    vcoord_fig = trans(vcoord_data)
+
+    dv = vcoord_fig[1] - vcoord_fig[0]
+
+    # Tension is the fraction of the semicircle covered by the
+    # arc. Values are clipped between -1 (left-hand semicircle)
+    # and 1 (right-hand semicircle). 0 means a straight line,
+    # which is a (degenerate) arc too.
+    if tension == 0:
+        vs = [None, None]
+        thetas = [atan2(dv[1], dv[0])]
+        thetas.append(-thetas[0])
+        for i in range(2):
+            vs[i] = (
+                _get_shorter_edge_coords(vpath_fig[i], vsize_fig[i], thetas[i], shrink)
+                + vcoord_fig[i]
+            )
+        auxs = []
+
+    else:
+        edge_straight_length = np.sqrt((dv**2).sum())
+        theta_straight = atan2(dv[1], dv[0])
+        theta_tension = 4 * np.arctan(tension)
+        # print(f"theta_straight: {np.degrees(theta_straight):.2f}")
+        # print(f"theta_tension: {np.degrees(theta_tension):.2f}")
+        # NOTE: positive tension means an arc shooting off to the right of the straight
+        # line, same convensio as for tension elsewhere in the codebase.
+        thetas = [theta_straight - theta_tension / 2, np.pi + theta_straight + theta_tension / 2]
+        # This is guaranteed to be finite because tension == 0 is taken care of above,
+        # and tension = np.inf is not allowed.
+        mid = vcoord_fig.mean(axis=0)
+        # print(f"theta_s: {thetas}")
+        # print(f"mid: {mid}")
+        theta_offset = theta_straight + np.pi / 2
+        if np.abs(tension) <= 1:
+            offset_length = edge_straight_length / 2 / np.tan(theta_tension / 2)
+        else:
+            # print("Large tension arc")
+            offset_length = -edge_straight_length / 2 * np.tan(theta_tension / 2 - np.pi / 2)
+        # print(f"theta_offset: {np.degrees(theta_offset):.2f}")
+        offset = offset_length * np.array([np.cos(theta_offset), np.sin(theta_offset)])
+        # print(f"offset: {offset}")
+        center = mid + offset
+        # print(f"center: {center}")
+
+        # Compute shorter start and end points
+        vs = [None, None]
+        for i in range(2):
+            vs[i] = (
+                _get_shorter_edge_coords(vpath_fig[i], vsize_fig[i], thetas[i], shrink)
+                + vcoord_fig[i]
+            )
+        angle_start = atan2(*(vs[0] - center)[::-1])
+        angle_end = atan2(*(vs[1] - center)[::-1])
+        if (np.abs(tension) > 1) and (np.abs(angle_end - angle_start) < np.pi):
+            if angle_end > angle_start:
+                angle_start += 2 * np.pi
+            else:
+                angle_end += 2 * np.pi
+        # print(f"angle_start: {np.degrees(angle_start):.2f}")
+        # print(f"angle_end: {np.degrees(angle_end):.2f}")
+
+        naux = 30
+        angles = np.linspace(angle_start, angle_end, naux + 2)[1:-1]
+        auxs = center + np.array([np.cos(angles), np.sin(angles)]).T * np.linalg.norm(
+            vs[0] - center
+        )
+
+    path = {
+        "vertices": [vs[0]] + list(auxs) + [vs[1]],
+        "codes": ["MOVETO"] + ["LINETO"] * (len(auxs) + 1),
+    }
+
+    path = mpl.path.Path(
+        path["vertices"],
+        codes=[getattr(mpl.path.Path, x) for x in path["codes"]],
+    )
+
+    # Return to data transform
+    path.vertices = trans_inv(path.vertices)
+    return path, tuple(thetas)
+
+
 def _compute_edge_path_curved(
     tension,
     vcoord_data,
@@ -483,12 +585,15 @@ 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),
+    arc: bool = False,
     layout_coordinate_system: str = "cartesian",
     **kwargs,
 ):
     """Compute the edge path in a few different ways."""
     if (waypoints != "none") and (tension != 0):
         raise ValueError("Waypoints not supported for curved edges.")
+    if (waypoints != "none") and arc:
+        raise ValueError("Waypoint not supported for arc edges.")
 
     if waypoints != "none":
         return _compute_edge_path_waypoints(
@@ -506,6 +611,14 @@ def _compute_edge_path(
             **kwargs,
         )
 
+    if arc:
+        return _compute_edge_path_arc(
+            tension,
+            *args,
+            ports=ports,
+            **kwargs,
+        )
+
     return _compute_edge_path_curved(
         tension,
         *args,