iplotx 0.2.1__tar.gz → 0.3.1__tar.gz

{iplotx-0.2.1 → iplotx-0.3.1}/.github/workflows/publish.yml

@@ -19,18 +19,33 @@ jobs:
   release-build:
     runs-on: ubuntu-latest
 
+    strategy:
+      matrix:
+        python-version: ["3.11"]
+
     steps:
       - uses: actions/checkout@v4
 
-      - uses: actions/setup-python@v5
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
         with:
-          python-version: "3.x"
+          python-version: ${{ matrix.python-version }}
 
-      - name: Build release distributions
+      - name: Install the project
         run: |
-          # NOTE: put your own distribution build steps here.
-          python -m pip install build
-          python -m build
+          # Copy the release name  into version.py (e.g. v0.3.0 -> 0.3.0)
+          ./scripts/copy_github_release_into_version.sh ${{ github.event.release.name }}
+          # Make sure you are in the right environment
+          uv sync
+          # Clean dist/
+          rm -f dist/*
+          # Build into dist/
+          uv build
 
       - name: Upload distributions
         uses: actions/upload-artifact@v4
@@ -51,7 +66,7 @@ jobs:
     environment:
       name: pypi
       # OPTIONAL: uncomment and update to include your PyPI project URL in the deployment status:
-      # url: https://pypi.org/p/YOURPROJECT
+      url: https://pypi.org/p/iplotx
       #
       # ALTERNATIVE: if your GitHub Release name is the PyPI project version string
       # ALTERNATIVE: exactly, uncomment the following line instead:

{iplotx-0.2.1 → iplotx-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iplotx
-Version: 0.2.1
+Version: 0.3.1
 Summary: Plot networkx from igraph and networkx.
 Project-URL: Homepage, https://github.com/fabilab/iplotx
 Project-URL: Documentation, https://readthedocs.org/iplotx
@@ -79,6 +79,7 @@ See [gallery](https://iplotx.readthedocs.io/en/latest/gallery/index.html).
 - Efficient plotting of large graphs using matplotlib's collection functionality. ✅
 - Support editing plotting elements after the plot is created, e.g. changing node colors, labels, etc. ✅
 - Support animations, e.g. showing the evolution of a network over time. ✅
+- Support mouse interaction, e.g. hovering over or clicking on nodes and edges to get information about them. ✅
 - Support trees from special libraries such as ete3, biopython, etc. This will need a dedicated function and layouting. ✅
 - Support uni- and bi-directional communication between graph object and plot object.🏗️
 

{iplotx-0.2.1 → iplotx-0.3.1}/README.md

@@ -41,6 +41,7 @@ See [gallery](https://iplotx.readthedocs.io/en/latest/gallery/index.html).
 - Efficient plotting of large graphs using matplotlib's collection functionality. ✅
 - Support editing plotting elements after the plot is created, e.g. changing node colors, labels, etc. ✅
 - Support animations, e.g. showing the evolution of a network over time. ✅
+- Support mouse interaction, e.g. hovering over or clicking on nodes and edges to get information about them. ✅
 - Support trees from special libraries such as ete3, biopython, etc. This will need a dedicated function and layouting. ✅
 - Support uni- and bi-directional communication between graph object and plot object.🏗️
 

{iplotx-0.2.1 → iplotx-0.3.1}/docs/source/index.md

@@ -74,13 +74,15 @@ See <project:gallery/index.rst> for examples of plots made with `iplotx`. Feel f
 - compatibility with many GUI frameworks (e.g. Qt, GTK, Tkinter) thanks to `matplotlib`
 - data-driven axes autoscaling
 - consistent behaviour upon zooming and panning
-- correct HiDPI scaling (e.g. retina screens)
+- correct HiDPI scaling (e.g. retina screens) including for vertex sizes, arrow sizes, and edge offsets
 - a consistent `matplotlib` artist hierarchy
 - post-plot editability (e.g. for animations)
 - plays well with other charting tools (e.g. `seaborn`)
 - chainable style contexts
 - vertex clusterings and covers with convex hulls and rounding
 - a plugin mechanism for additional libraries (WIP)
+- animations (see <project:gallery/plot_animation.rst>)
+- mouse/keyboard interaction and events (e.g. hover, click, see <project:gallery/plot_mouse_hover.rst>)
 - ... and probably more by the time you read this.
 
 ## Styles

{iplotx-0.2.1 → iplotx-0.3.1}/docs/source/sg_execution_times.rst

@@ -6,7 +6,7 @@
 
 Computation times
 =================
-**00:01.429** total execution time for 32 files **from all galleries**:
+**00:01.212** total execution time for 36 files **from all galleries**:
 
 .. container::
 
@@ -32,8 +32,11 @@ Computation times
    * - Example
      - Time
      - Mem (MB)
+   * - :ref:`sphx_glr_gallery_plot_ete4.py` (``../../gallery/plot_ete4.py``)
+     - 00:01.212
+     - 0.0
    * - :ref:`sphx_glr_gallery_plot_animation.py` (``../../gallery/plot_animation.py``)
-     - 00:01.429
+     - 00:00.000
      - 0.0
    * - :ref:`sphx_glr_gallery_plot_basic.py` (``../../gallery/plot_basic.py``)
      - 00:00.000
@@ -56,6 +59,9 @@ Computation times
    * - :ref:`sphx_glr_gallery_plot_cogent3_tree.py` (``../../gallery/plot_cogent3_tree.py``)
      - 00:00.000
      - 0.0
+   * - :ref:`sphx_glr_gallery_plot_company_structure.py` (``../../gallery/plot_company_structure.py``)
+     - 00:00.000
+     - 0.0
    * - :ref:`sphx_glr_gallery_plot_complex.py` (``../../gallery/plot_complex.py``)
      - 00:00.000
      - 0.0
@@ -68,9 +74,6 @@ Computation times
    * - :ref:`sphx_glr_gallery_plot_edit_artists.py` (``../../gallery/plot_edit_artists.py``)
      - 00:00.000
      - 0.0
-   * - :ref:`sphx_glr_gallery_plot_ete4.py` (``../../gallery/plot_ete4.py``)
-     - 00:00.000
-     - 0.0
    * - :ref:`sphx_glr_gallery_plot_four_grids.py` (``../../gallery/plot_four_grids.py``)
      - 00:00.000
      - 0.0
@@ -95,6 +98,9 @@ Computation times
    * - :ref:`sphx_glr_gallery_plot_minimum_spanning_trees.py` (``../../gallery/plot_minimum_spanning_trees.py``)
      - 00:00.000
      - 0.0
+   * - :ref:`sphx_glr_gallery_plot_mouse_hover.py` (``../../gallery/plot_mouse_hover.py``)
+     - 00:00.000
+     - 0.0
    * - :ref:`sphx_glr_gallery_plot_multipartite_layout.py` (``../../gallery/plot_multipartite_layout.py``)
      - 00:00.000
      - 0.0
@@ -122,6 +128,12 @@ Computation times
    * - :ref:`sphx_glr_gallery_plot_traveling_salesman.py` (``../../gallery/plot_traveling_salesman.py``)
      - 00:00.000
      - 0.0
+   * - :ref:`sphx_glr_gallery_plot_tree_node_background.py` (``../../gallery/plot_tree_node_background.py``)
+     - 00:00.000
+     - 0.0
+   * - :ref:`sphx_glr_gallery_plot_trees_of_trees.py` (``../../gallery/plot_trees_of_trees.py``)
+     - 00:00.000
+     - 0.0
    * - :ref:`sphx_glr_gallery_plot_voronoi.py` (``../../gallery/plot_voronoi.py``)
      - 00:00.000
      - 0.0

{iplotx-0.2.1 → iplotx-0.3.1}/gallery/plot_biopython_tree.py

@@ -28,6 +28,7 @@ ipx.plotting.tree(
 # Moreover, the plot can be customised further using hmargin (horizontal label margin)
 # and some `matplotlib` settings.
 
+# sphinx_gallery_thumbnail_number = 2
 leaf_labels = {leaf: f"Species {i+1}" for i, leaf in enumerate(tree.get_terminals())}
 fig, ax = plt.subplots(figsize=(4, 4))
 ipx.plotting.tree(

iplotx-0.3.1/gallery/plot_company_structure.py

@@ -0,0 +1,72 @@
+"""
+Company structure
+=================
+
+This example shows how to use `iplotx` to visualise simple logical relationships, for instance the organisational chart of a company.
+"""
+
+import networkx as nx
+import matplotlib.pyplot as plt
+import iplotx as ipx
+
+g = nx.DiGraph()
+g.add_edges_from(
+    [
+        ("CEO", "Manager 1"),
+        ("CEO", "Manager 2"),
+        ("CEO", "Manager 3"),
+        ("Manager 1", "Employee 1"),
+        ("Manager 1", "Employee 2"),
+        ("Manager 2", "Employee 3"),
+        ("Manager 2", "Employee 4"),
+        ("Manager 3", "Employee 4"),
+    ]
+)
+layout = {
+    "CEO": [0, 0],
+    "Manager 1": [1, -1],
+    "Manager 2": [1, 0],
+    "Manager 3": [1, 1],
+    "Employee 1": [2, -1],
+    "Employee 2": [2, -0.5],
+    "Employee 3": [2, 0],
+    "Employee 4": [2, 0.5],
+}
+fig, ax = plt.subplots()
+ipx.network(
+    g,
+    layout=layout,
+    ax=ax,
+    vertex_labels=True,
+    style="hollow",
+    vertex_marker="r",
+    edge_ports=[("e", "w")] * 8,
+    edge_curved=True,
+    edge_tension=[0.65] * 3 + [0.6] * 5,
+    margins=(0.08, 0.05),
+)
+# Show the layout top to bottom for clarity
+ax.invert_yaxis()
+
+# %%
+# If you prefer a more squared look, you can use S-style waypoints with per-edge offsets:
+
+fig, ax = plt.subplots()
+ipx.network(
+    g,
+    layout=layout,
+    ax=ax,
+    vertex_labels=True,
+    style="hollow",
+    vertex_marker="r",
+    edge_ports=[("e", "w")] * 8,
+    edge_waypoints="xmidy0,xmidy1",
+    edge_offset=[(0, 0)] * 7 + [(0, -6)],
+    margins=(0.08, 0.05),
+    edge_linestyle=["-"] * 7 + ["--"],
+)
+ax.invert_yaxis()
+
+# %%
+# The `offset` edge style bypasses any layout coordinate system and acts in figure points directly.
+# Combining edge offsets with noncartesian layout coordinate systems (e.g. `polar`) can lead to unexpected results.

{iplotx-0.2.1 → iplotx-0.3.1}/gallery/plot_edit_artists.py

@@ -33,6 +33,7 @@ artist = ipx.network(
 # %%
 # Now we can change the vertex sizes:
 
+# sphinx_gallery_thumbnail_number = 2
 # SAME BLOCK AS BEFORE, ONLY NEEDED TO MAKE A NEW FIGURE
 artist = ipx.network(
     g,

{iplotx-0.2.1 → iplotx-0.3.1}/gallery/plot_ete4.py

@@ -21,19 +21,32 @@ ipx.plotting.tree(
 
 # %%
 # `iplotx` can compute a radial tree layout as well, and usual style modifications
-# work for trees same as networks:
+# work for trees same as networks. Moreover, trees have a layout style option to
+# choose the starting angle and angular span of the radial layout.
 
+# sphinx_gallery_thumbnail_number = 2
 ipx.plotting.tree(
     tree,
     layout="radial",
+    orientation="right",
     style=[
         "tree",
         {
             "edge": {
-                "color": "black",
+                "color": "deeppink",
                 "linewidth": 4,
             },
+            "layout": {
+                "start": -180,
+                "span": 180,
+            },
+            "vertex": {
+                "label": {
+                    "hmargin": 15,
+                }
+            },
         },
     ],
+    vertex_labels={leaf: str(i + 1) for i, leaf in enumerate(tree.leaves())},
     aspect=1,
 )

{iplotx-0.2.1 → iplotx-0.3.1}/gallery/plot_loops.py

@@ -37,7 +37,7 @@ ipx.plot(
         },
         "edge": {
             "linestyle": linestyle,
-            "offset": 0,
+            "paralleloffset": 0,
             "looptension": 3.5,
             "arrow": {
                 "marker": "|>",
@@ -61,7 +61,7 @@ ipx.plot(
         vertex_edgecolor="none",
         vertex_label_color="black",
         edge_linestyle=linestyle,
-        edge_offset=0,
+        edge_paralleloffset=0,
         edge_looptension=3.5,
         edge_arrow_marker="|>",
     ),
@@ -80,7 +80,7 @@ ipx.plot(
     vertex_edgecolor="none",
     vertex_label_color="black",
     edge_linestyle=linestyle,
-    edge_offset=0,
+    edge_paralleloffset=0,
     edge_looptension=3.5,
     edge_arrow_marker="|>",
 )
@@ -94,7 +94,7 @@ with ipx.style.context(
     vertex_edgecolor="none",
     vertex_label_color="black",
     edge_linestyle=linestyle,
-    edge_offset=0,
+    edge_paralleloffset=0,
     edge_looptension=3.5,
     edge_arrow_marker="|>",
 ):

iplotx-0.3.1/gallery/plot_mouse_hover.py

@@ -0,0 +1,67 @@
+"""
+Mouse event handling
+====================
+
+This example shows how to interact with mouse events (e.g. hovering) in `iplotx`.
+
+.. 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 numpy as np
+import igraph as ig
+import iplotx as ipx
+
+g = ig.Graph.Ring(3, directed=True)
+
+fig, ax = plt.subplots()
+art = ipx.network(
+    g,
+    layout="circle",
+    ax=ax,
+    aspect=1,
+)[0]
+vertex_artist = art.get_vertices()
+
+# Prepare an invisible annotation for hovering
+annot = ax.annotate(
+    "",
+    xy=(0, 0),
+    xytext=(20, 20),
+    textcoords="offset points",
+    bbox=dict(boxstyle="round", fc=(0, 0, 0, 0.2)),
+    arrowprops=dict(arrowstyle="->"),
+)
+annot.set_visible(False)
+
+
+def hover_callback(event):
+    """React to mouse hovering over vertices."""
+    if event.inaxes == ax:
+        vc = art.get_vertices()
+        cont, ind = vc.contains(event)
+        # If mouse is over a vertex, show the buble
+        if cont:
+            i = ind["ind"][0]
+            annot.xy = vc.get_offsets()[i]
+            annot.set_text(f"{i+1}")
+            annot.set_visible(True)
+        # Otherwise, hide the bubble
+        elif annot.get_visible():
+            annot.set_visible(False)
+        # If nothing changed, no need to redraw
+        else:
+            return
+
+        # Redraw to show/hide the bubble
+        fig.canvas.draw_idle()
+
+
+fig.canvas.mpl_connect(
+    "motion_notify_event",
+    hover_callback,
+)

{iplotx-0.2.1 → iplotx-0.3.1}/gallery/plot_simple_path.py

@@ -10,12 +10,12 @@ import iplotx as ipx
 
 G = nx.path_graph(8)
 pos = nx.spring_layout(G, seed=47)  # Seed layout for reproducibility
-ipx.plot(G, layout=pos)
+ipx.network(G, layout=pos)
 
 # %%
 # We can change the color of the vertices and edges with a touch of style:
 
-ipx.plot(
+ipx.network(
     G,
     layout=pos,
     style={

iplotx-0.3.1/gallery/plot_tree_node_background.py

@@ -0,0 +1,55 @@
+"""
+Tree cascades
+=============
+
+This example shows how to use `iplotx` to add cascading backgrounds to trees.
+"Cascading" here means that each patch (rectangle/wedge/etc.) will cover a node
+and all descendants, down to the leaves.
+"""
+
+from Bio import Phylo
+from io import StringIO
+import matplotlib.pyplot as plt
+import iplotx as ipx
+
+# Make a tree from a string in Newick format
+tree = next(
+    Phylo.NewickIO.parse(
+        StringIO(
+            "(()(()((()())(()()))))",
+        )
+    )
+)
+
+backgrounds = {
+    tree.get_nonterminals()[3]: "turquoise",
+    tree.get_terminals()[0]: "tomato",
+    tree.get_terminals()[1]: "purple",
+}
+
+ipx.plotting.tree(
+    tree,
+    vertex_cascade_facecolor=backgrounds,
+)
+
+# %%
+# Cascading patches have a style option "extend" which affects whether the patches extend to the end of the deepest leaf:
+
+ipx.plotting.tree(
+    tree,
+    layout="vertical",
+    vertex_cascade_facecolor=backgrounds,
+    vertex_cascade_extend=True,
+)
+
+# %%
+# Cascading patches work with radial layouts as well:
+
+# sphinx_gallery_thumbnail_number = 3
+ipx.plotting.tree(
+    tree,
+    layout="radial",
+    vertex_cascade_facecolor=backgrounds,
+    vertex_cascade_extend=True,
+    aspect=1,
+)

iplotx-0.3.1/gallery/plot_trees_of_trees.py

@@ -0,0 +1,83 @@
+"""
+Tree of trees
+=============
+
+This example shows how to plot trees at the leaf of a tree, using the `iplotx` library.
+Note that there are a few conceivable ways to do similar things as this in
+`matplotlib` and this is just one such approach, using inset axes.
+"""
+
+from ete4 import Tree
+import matplotlib.pyplot as plt
+import iplotx as ipx
+
+tree = Tree(
+    "(,((),(((),()),((),()))));",
+)
+subtree_strings = [
+    "((a,b),(c,d));",
+    "(a,((b,c),d));",
+    "(a,b,c,d);",
+    "(a,(b,(c,d)));",
+    "(a,b);",
+    "(a,(b,c,d));",
+]
+
+# Plot the initial tree
+fig, ax = plt.subplots(figsize=(8, 5))
+art = ipx.tree(
+    tree,
+    ax=ax,
+    aspect=1,
+    edge_color="grey",
+)
+
+for i, leaf in enumerate(tree.leaves()):
+
+    # Create an axis in the rough proximity
+    # and with the rough diemension of a leaf,
+    # with some padding
+    x, y = art.get_layout().T[leaf].values
+    subax = ax.inset_axes(
+        (x + 0.1, y - 0.4, 1.2, 0.8),
+        transform=ax.transData,
+    )
+
+    # For each leaf, make a tree
+    subtree = Tree(subtree_strings[i])
+    # Plot the tree with dashed lines
+    ipx.tree(
+        subtree,
+        ax=subax,
+        edge_linestyle="--",
+    )
+
+# %%
+# Combining this with other elements, e.g. cascading backgrounds, is possible too:
+
+fig, ax = plt.subplots(figsize=(8, 5))
+art = ipx.tree(
+    tree,
+    ax=ax,
+    aspect=1,
+    edge_color="grey",
+    vertex_cascade_facecolor={
+        list(tree.leaves())[0]: "lightblue",
+        list(tree.traverse("preorder"))[2]: "pink",
+    },
+)
+for i, leaf in enumerate(tree.leaves()):
+    x, y = art.get_layout().T[leaf].values
+    subax = ax.inset_axes(
+        (x + 0.1, y - 0.4, 1.2, 0.8),
+        transform=ax.transData,
+    )
+    # Set the inset axes background transparent
+    subax.patch.set_alpha(0)
+
+    subtree = Tree(subtree_strings[i])
+    ipx.tree(
+        subtree,
+        ax=subax,
+        edge_linestyle="--",
+    )