iplotx 0.9.0__py3-none-any.whl → 0.10.0__py3-none-any.whl

iplotx/art3d/edge.py

@@ -0,0 +1,65 @@
+"""
+Module containing code to manipulate edge visualisations in 3D, especially the Edge3DCollection class.
+"""
+
+from mpl_toolkits.mplot3d.art3d import (
+    Line3DCollection,
+)
+
+from ..utils.matplotlib import (
+    _forwarder,
+)
+from ..edge import (
+    EdgeCollection,
+)
+
+
+@_forwarder(
+    (
+        "set_clip_path",
+        "set_clip_box",
+        "set_snap",
+        "set_sketch_params",
+        "set_animated",
+        "set_picker",
+    )
+)
+class Edge3DCollection(Line3DCollection):
+    """Collection of vertex patches for plotting."""
+
+    pass
+
+
+def edge_collection_2d_to_3d(
+    col: EdgeCollection,
+    zdir: str = "z",
+    depthshade: bool = True,
+    axlim_clip: bool = False,
+):
+    """Convert a 2D EdgeCollection to a 3D Edge3DCollection.
+
+    Parameters:
+        col: The 2D EdgeCollection to convert.
+        zs: The z coordinate(s) to use for the 3D vertices.
+        zdir: The axis to use as the z axis (default is "z").
+        depthshade: Whether to apply depth shading (default is True).
+        axlim_clip: Whether to clip the vertices to the axes limits (default is False).
+    """
+    if not isinstance(col, EdgeCollection):
+        raise TypeError("vertices must be a VertexCollection")
+
+    # TODO: if we make Edge3DCollection a dynamic drawer, this will need to change
+    # fundamentally. Also, this currently does not handle labels properly.
+    vinfo = col._get_adjacent_vertices_info()
+
+    segments3d = []
+    for offset1, offset2 in vinfo["offsets"]:
+        segment = [tuple(offset1), tuple(offset2)]
+        segments3d.append(segment)
+
+    # NOTE: after this line, none of the EdgeCollection methods will work
+    # It's become a static drawer now
+    col.__class__ = Edge3DCollection
+
+    col.set_segments(segments3d)
+    col._axlim_clip = axlim_clip

iplotx/art3d/vertex.py

@@ -0,0 +1,69 @@
+"""
+Module containing code to manipulate vertex visualisations in 3D, especially the Vertex3DCollection class.
+"""
+
+from typing import (
+    Sequence,
+)
+import numpy as np
+from matplotlib import (
+    cbook,
+)
+from mpl_toolkits.mplot3d.art3d import Path3DCollection
+
+from ..utils.matplotlib import (
+    _forwarder,
+)
+from ..vertex import (
+    VertexCollection,
+)
+
+
+@_forwarder(
+    (
+        "set_clip_path",
+        "set_clip_box",
+        "set_snap",
+        "set_sketch_params",
+        "set_animated",
+        "set_picker",
+    )
+)
+class Vertex3DCollection(VertexCollection, Path3DCollection):
+    """Collection of vertex patches for plotting."""
+
+    def draw(self, renderer) -> None:
+        """Draw the collection of vertices in 3D.
+
+        Parameters:
+            renderer: The renderer to use for drawing.
+        """
+        with self._use_zordered_offset():
+            with cbook._setattr_cm(self, _in_draw=True):
+                VertexCollection.draw(self, renderer)
+
+
+def vertex_collection_2d_to_3d(
+    col: VertexCollection,
+    zs: np.ndarray | float | Sequence[float] = 0,
+    zdir: str = "z",
+    depthshade: bool = True,
+    axlim_clip: bool = False,
+):
+    """Convert a 2D VertexCollection to a 3D Vertex3DCollection.
+
+    Parameters:
+        col: The 2D VertexCollection to convert.
+        zs: The z coordinate(s) to use for the 3D vertices.
+        zdir: The axis to use as the z axis (default is "z").
+        depthshade: Whether to apply depth shading (default is True).
+        axlim_clip: Whether to clip the vertices to the axes limits (default is False).
+    """
+    if not isinstance(col, VertexCollection):
+        raise TypeError("vertices must be a VertexCollection")
+
+    col.__class__ = Vertex3DCollection
+    col._offset_zordered = None
+    col._depthshade = depthshade
+    col._in_draw = False
+    col.set_3d_properties(zs, zdir, axlim_clip)

iplotx/artists.py

@@ -10,6 +10,8 @@ from .label import LabelCollection
 from .edge.arrow import EdgeArrowCollection
 from .edge.leaf import LeafEdgeCollection
 from .cascades import CascadeCollection
+from .art3d.vertex import Vertex3DCollection
+from .art3d.edge import Edge3DCollection
 
 
 ___all__ = (
@@ -21,4 +23,6 @@ ___all__ = (
     LabelCollection,
     EdgeArrowCollection,
     CascadeCollection,
+    Vertex3DCollection,
+    Edge3DCollection,
 )

iplotx/edge/__init__.py

@@ -193,6 +193,16 @@ class EdgeCollection(mpl.collections.PatchCollection):
         self._update_arrows()
         self._update_labels()
 
+    def set_transform(self, transform: mpl.transforms.Transform) -> None:
+        """Set the transform for the edges and their children."""
+        super().set_transform(transform)
+        if hasattr(self, "_subedges"):
+            self._subedges.set_transform(transform)
+        if hasattr(self, "_arrows"):
+            self._arrows.set_offset_transform(transform)
+        if hasattr(self, "_label_collection"):
+            self._label_collection.set_transform(transform)
+
     @property
     def directed(self) -> bool:
         """Whether the network is directed."""

iplotx/edge/geometry.py

@@ -1,5 +1,7 @@
 """
 Support module with geometry- and path-related functions for edges.
+
+3D geometry is in its separate module :mod:`.geometry3d`.
 """
 
 from typing import (
@@ -14,6 +16,7 @@ from ..typing import (
     Pair,
 )
 from .ports import _get_port_unit_vector
+from .geometry3d import _compute_edge_path_3d
 
 
 def _compute_loops_per_angle(nloops, angles):
@@ -65,6 +68,14 @@ def _compute_loops_per_angle(nloops, angles):
 
 
 def _get_shorter_edge_coords(vpath, vsize, theta, shrink=0):
+    """Get the coordinates of an edge tip such that it touches the vertex border.
+
+    Parameters:
+        vpath: The vertex path, in figure coordinates (so scaled by dpi).
+        vsize: The vertex max size, in figure coordinates (so scaled by dpi).
+        theta: The angle of the edge inpinging into the vertex, in radians, in figure coordinates.
+        shrink: Additional shrinking of the edge, in figure coordinates (so scaled by dpi).
+    """
     # Bound theta from -pi to pi (why is that not guaranteed?)
     theta = (theta + pi) % (2 * pi) - pi
 
@@ -468,7 +479,7 @@ def _compute_edge_path_curved(
     return path, tuple(thetas)
 
 
-def _compute_edge_path(
+def _compute_edge_path_2d(
     *args,
     tension: float = 0,
     waypoints: str | tuple[float, float] | Sequence[tuple[float, float]] | np.ndarray = "none",
@@ -502,3 +513,25 @@ def _compute_edge_path(
         ports=ports,
         **kwargs,
     )
+
+
+def _compute_edge_path(
+    vcoord_data,
+    *args,
+    **kwargs,
+):
+    """Compute the edge path in either 2D or 3D.
+
+    Parameters:
+        vcoord_data: The vertex coordinates in data coordinates. This is used to
+            determine the dimensionality of the layout.
+        *args: Additional arguments passed to the internal functions.
+        **kwargs: Additional keyword arguments passed to the internal functions.
+
+    Returns:
+        The computed edge path and the angles at the start and end of the edge.
+    """
+    ndim = len(vcoord_data[0])
+    if ndim == 2:
+        return _compute_edge_path_2d(vcoord_data, *args, **kwargs)
+    return _compute_edge_path_3d(vcoord_data, *args, **kwargs)

iplotx/edge/geometry3d.py

@@ -0,0 +1,113 @@
+"""
+Support for computing edge paths in 3D.
+"""
+
+from typing import (
+    Optional,
+    Sequence,
+)
+import numpy as np
+import matplotlib as mpl
+
+from ..typing import (
+    Pair,
+)
+
+
+def _compute_edge_path_straight(
+    vcoord_data,
+    vpath_fig,
+    vsize_fig,
+    trans,
+    trans_inv,
+    layout_coordinate_system: str = "cartesian",
+    shrink: float = 0,
+    **kwargs,
+):
+    """Compute straight edge path between two vertices, in 3D.
+
+    Parameters:
+        vcoord_data: Vertex coordinates in data coordinates, shape (2, 3).
+        vpath_fig: Vertex path in figure coordinates.
+        vsize_fig: Vertex size in figure coordinates.
+        trans: Transformation from data to figure coordinates.
+        trans_inv: Inverse transformation from figure to data coordinates.
+        layout_coordinate_system: The coordinate system of the layout.
+        shrink: Amount to shorten the edge at each end, in figure coordinates.
+        **kwargs: Additional keyword arguments (not used).
+    Returns:
+        A pair with the path and a tuple of angles of exit and entry, in radians.
+
+    """
+
+    if layout_coordinate_system not in ("cartesian"):
+        raise ValueError(
+            f"Layout coordinate system not supported for straight edges in 3D: {layout_coordinate_system}.",
+        )
+
+    vcoord_data_cart = vcoord_data
+
+    # Coordinates in figure (default) coords
+    vcoord_fig = trans(vcoord_data_cart)
+
+    points = []
+
+    # Angles of the straight line
+    # FIXME: In 2D, this is only used to make space for loops
+    # let's ignore for now
+    # theta = atan2(*((vcoord_fig[1] - vcoord_fig[0])[::-1]))
+    theta = 0
+
+    # TODO: Shorten at starting vertex (?)
+    vs = vcoord_fig[0]
+    points.append(vs)
+
+    # TODO: Shorten at end vertex (?)
+    ve = vcoord_fig[1]
+    points.append(ve)
+
+    codes = ["MOVETO", "LINETO"]
+    path = mpl.path.Path(
+        points,
+        codes=[getattr(mpl.path.Path, x) for x in codes],
+    )
+    path.vertices = trans_inv(path.vertices)
+    return path, (theta, theta + np.pi)
+
+
+def _compute_edge_path_3d(
+    *args,
+    tension: float = 0,
+    waypoints: str | tuple[float, float] | Sequence[tuple[float, float]] | np.ndarray = "none",
+    ports: Pair[Optional[str]] = (None, None),
+    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":
+        raise NotImplementedError("Waypoints not implemented for 3D edges.")
+        # return _compute_edge_path_waypoints(
+        #    waypoints,
+        #    *args,
+        #    layout_coordinate_system=layout_coordinate_system,
+        #    ports=ports,
+        #    **kwargs,
+        # )
+
+    if np.isscalar(tension) and (tension == 0):
+        return _compute_edge_path_straight(
+            *args,
+            layout_coordinate_system=layout_coordinate_system,
+            **kwargs,
+        )
+
+    raise NotImplementedError("Curved edges not implemented for 3D edges.")
+    # return _compute_edge_path_curved(
+    #    tension,
+    #    *args,
+    #    ports=ports,
+    #    **kwargs,
+    # )

iplotx/groups.py

@@ -4,6 +4,7 @@ Module for vertex groupings code, especially the GroupingArtist class.
 
 from typing import Union
 import numpy as np
+import pandas as pd
 import matplotlib as mpl
 from matplotlib.collections import PatchCollection
 
@@ -64,6 +65,9 @@ class GroupingArtist(PatchCollection):
         self._points_per_curve = points_per_curve
 
         network = kwargs.pop("network", None)
+        self.layout = normalise_layout(layout, network=network)
+        self.ndim = layout.shape[1]
+
         patches, grouping, coords_hulls = self._create_patches(
             grouping,
             layout,
@@ -89,6 +93,21 @@ class GroupingArtist(PatchCollection):
         self._compute_paths(self.get_figure(root=True).dpi)
         return ret
 
+    @property
+    def axes(self):
+        return PatchCollection.axes.__get__(self)
+
+    @axes.setter
+    def axes(self, new_axes):
+        PatchCollection.axes.__set__(self, new_axes)
+        for child in self.get_children():
+            child.axes = new_axes
+        self.set_figure(new_axes.figure)
+
+    def get_layout(self) -> pd.DataFrame:
+        """Get the layout used for this grouping."""
+        return self.layout
+
     def get_vertexpadding(self) -> float:
         """Get the vertex padding of each group."""
         return self._vertexpadding
@@ -98,7 +117,6 @@ class GroupingArtist(PatchCollection):
         return self.get_vertexpadding() * dpi / 72.0 * self._factor
 
     def _create_patches(self, grouping, layout, network, **kwargs):
-        layout = normalise_layout(layout, network=network)
         grouping = normalise_grouping(grouping, layout)
         style = get_style(".grouping")
         style.pop("vertexpadding", None)

iplotx/ingest/providers/network/igraph.py

@@ -30,23 +30,22 @@ class IGraphDataProvider(NetworkDataProvider):
         edge_labels: Optional[Sequence[str] | dict[str]] = None,
     ) -> NetworkData:
         """Create network data object for iplotx from an igraph object."""
-        network = self.network
-        directed = self.is_directed()
 
-        # Recast vertex_labels=False as vertex_labels=None
-        if np.isscalar(vertex_labels) and (not vertex_labels):
-            vertex_labels = None
-
-        # Vertices are ordered integers, no gaps
+        # Get layout
         vertex_df = normalise_layout(
             layout,
-            network=network,
+            network=self.network,
             nvertices=self.number_of_vertices(),
         )
         ndim = vertex_df.shape[1]
         vertex_df.columns = _make_layout_columns(ndim)
 
+        # Vertices are ordered integers, no gaps
+
         # Vertex labels
+        # Recast vertex_labels=False as vertex_labels=None
+        if np.isscalar(vertex_labels) and (not vertex_labels):
+            vertex_labels = None
         if vertex_labels is not None:
             if np.isscalar(vertex_labels):
                 vertex_df["label"] = vertex_df.index.astype(str)
@@ -57,7 +56,7 @@ class IGraphDataProvider(NetworkDataProvider):
 
         # Edges are a list of tuples, because of multiedges
         tmp = []
-        for edge in network.es:
+        for edge in self.network.es:
             row = {"_ipx_source": edge.source, "_ipx_target": edge.target}
             row.update(edge.attributes())
             tmp.append(row)
@@ -76,7 +75,7 @@ class IGraphDataProvider(NetworkDataProvider):
         network_data = {
             "vertex_df": vertex_df,
             "edge_df": edge_df,
-            "directed": directed,
+            "directed": self.is_directed(),
             "ndim": ndim,
         }
         return network_data

iplotx/ingest/providers/network/networkx.py

@@ -33,25 +33,20 @@ class NetworkXDataProvider(NetworkDataProvider):
 
         import networkx as nx
 
-        network = self.network
-
-        directed = self.is_directed()
-
-        # Recast vertex_labels=False as vertex_labels=None
-        if np.isscalar(vertex_labels) and (not vertex_labels):
-            vertex_labels = None
-
-        # Vertices are indexed by node ID
+        # Get layout
         vertex_df = normalise_layout(
             layout,
-            network=network,
+            network=self.network,
             nvertices=self.number_of_vertices(),
-        ).loc[pd.Index(network.nodes)]
+        )
         ndim = vertex_df.shape[1]
         vertex_df.columns = _make_layout_columns(ndim)
 
+        # Vertices are indexed by node ID
+        vertex_df = vertex_df.loc[pd.Index(self.network.nodes)]
+
         # Vertex internal properties
-        tmp = pd.DataFrame(dict(network.nodes.data())).T
+        tmp = pd.DataFrame(dict(self.network.nodes.data())).T
         # Arrays become a single column, which we have already anyway
         if isinstance(layout, str) and (layout in tmp.columns):
             del tmp[layout]
@@ -60,6 +55,9 @@ class NetworkXDataProvider(NetworkDataProvider):
         del tmp
 
         # Vertex labels
+        # Recast vertex_labels=False as vertex_labels=None
+        if np.isscalar(vertex_labels) and (not vertex_labels):
+            vertex_labels = None
         if vertex_labels is None:
             if "label" in vertex_df:
                 del vertex_df["label"]
@@ -78,7 +76,7 @@ class NetworkXDataProvider(NetworkDataProvider):
 
         # Edges are a list of tuples, because of multiedges
         tmp = []
-        for u, v, d in network.edges.data():
+        for u, v, d in self.network.edges.data():
             row = {"_ipx_source": u, "_ipx_target": v}
             row.update(d)
             tmp.append(row)
@@ -112,7 +110,7 @@ class NetworkXDataProvider(NetworkDataProvider):
         network_data = {
             "vertex_df": vertex_df,
             "edge_df": edge_df,
-            "directed": directed,
+            "directed": self.is_directed(),
             "ndim": ndim,
         }
         return network_data

iplotx/label.py

@@ -77,6 +77,17 @@ class LabelCollection(mpl.artist.Artist):
             child.set_figure(fig)
         self._update_offsets(dpi=fig.dpi)
 
+    def set_transform(self, transform: mpl.transforms.Transform) -> None:
+        """Set the transform for this artist and children.
+
+        Parameters:
+            transform: The transform to set.
+        """
+        super().set_transform(transform)
+        if hasattr(self, "_labelartists"):
+            for art in self._labelartists:
+                art.set_transform(transform)
+
     def get_texts(self):
         """Get the texts of the labels."""
         return [child.get_text() for child in self.get_children()]

iplotx/network.py

@@ -30,6 +30,13 @@ from .edge import (
     EdgeCollection,
     make_stub_patch as make_undirected_edge_patch,
 )
+from .art3d.vertex import (
+    vertex_collection_2d_to_3d,
+)
+from .art3d.edge import (
+    Edge3DCollection,
+    edge_collection_2d_to_3d,
+)
 
 
 @_forwarder(
@@ -63,6 +70,10 @@ class NetworkArtist(mpl.artist.Artist):
                 will be drawn. If a list, the labels are taken from the list. If a dict, the keys
                 should be the vertex IDs and the values should be the labels.
             edge_labels: The labels for the edges. If None, no edge labels will be drawn.
+            transform: The transform to use for the vertices. Default is IdentityTransform.
+            offset_transform: The transform to use as offset transform for the vertices and main
+                transform for the edges. Default is None, but this should eventually be set to
+                ax.transData once the artist is added to an Axes.
 
         """
         self.network = network
@@ -111,7 +122,7 @@ class NetworkArtist(mpl.artist.Artist):
     @classmethod
     def from_edgecollection(
         cls: "NetworkArtist",  # NOTE: This is fixed in Python 3.14
-        edge_collection: EdgeCollection,
+        edge_collection: EdgeCollection | Edge3DCollection,
     ) -> Self:
         """Create a NetworkArtist from iplotx artists.
 
@@ -125,7 +136,7 @@ class NetworkArtist(mpl.artist.Artist):
         vertex_collection = edge_collection._vertex_collection
         layout = vertex_collection._layout
         transform = vertex_collection.get_transform()
-        offset_transform = edge_collection.get_transform()
+        offset_transform = vertex_collection.get_offset_transform()
 
         # Follow the steps in the normal constructor
         self = cls(
@@ -134,6 +145,7 @@ class NetworkArtist(mpl.artist.Artist):
             transform=transform,
             offset_transform=offset_transform,
         )
+        # TODO: should we make copies here?
         self._vertices = vertex_collection
         self._edges = edge_collection
 
@@ -150,6 +162,17 @@ class NetworkArtist(mpl.artist.Artist):
         for child in self.get_children():
             child.set_figure(fig)
 
+    @property
+    def axes(self):
+        return mpl.artist.Artist.axes.__get__(self)
+
+    @axes.setter
+    def axes(self, new_axes):
+        mpl.artist.Artist.axes.__set__(self, new_axes)
+        for child in self.get_children():
+            child.axes = new_axes
+        self.set_figure(new_axes.figure)
+
     def get_offset_transform(self):
         """Get the offset transform (for vertices/edges)."""
         return self._offset_transform
@@ -157,6 +180,10 @@ class NetworkArtist(mpl.artist.Artist):
     def set_offset_transform(self, offset_transform):
         """Set the offset transform (for vertices/edges)."""
         self._offset_transform = offset_transform
+        if hasattr(self, "_vertices"):
+            self._vertices.set_offset_transform(offset_transform)
+        if hasattr(self, "_edges"):
+            self._edges.set_transform(offset_transform)
 
     def get_vertices(self):
         """Get VertexCollection artist."""
@@ -210,10 +237,23 @@ class NetworkArtist(mpl.artist.Artist):
         self.axes.autoscale_view(tight=tight)
 
     def get_layout(self):
-        layout_columns = [f"_ipx_layout_{i}" for i in range(self._ipx_internal_data["ndim"])]
+        """Get the vertex layout.
+
+        Returns:
+            The vertex layout as a DataFrame.
+        """
+        layout_columns = [f"_ipx_layout_{i}" for i in range(self.get_ndim())]
         vertex_layout_df = self._ipx_internal_data["vertex_df"][layout_columns]
         return vertex_layout_df
 
+    def get_ndim(self):
+        """Get the dimensionality of the layout.
+
+        Returns:
+            The dimensionality of the layout (2 or 3).
+        """
+        return self._ipx_internal_data["ndim"]
+
     def _get_label_series(self, kind):
         # Equivalence vertex/node
         if kind == "node":
@@ -238,6 +278,13 @@ class NetworkArtist(mpl.artist.Artist):
             offset_transform=self.get_offset_transform(),
         )
 
+        if self.get_ndim() == 3:
+            vertex_collection_2d_to_3d(
+                self._vertices,
+                zs=self.get_layout().iloc[:, 2].values,
+                depthshade=False,
+            )
+
     def _add_edges(self):
         """Add edges to the network artist.
 
@@ -319,6 +366,11 @@ class NetworkArtist(mpl.artist.Artist):
         if "cmap" in edge_style:
             self._edges.set_array(colorarray)
 
+        if self.get_ndim() == 3:
+            edge_collection_2d_to_3d(
+                self._edges,
+            )
+
     @_stale_wrapper
     def draw(self, renderer):
         """Draw each of the children, with some buffering mechanism."""
@@ -333,6 +385,8 @@ class NetworkArtist(mpl.artist.Artist):
         children = list(self.get_children())
         children.sort(key=lambda x: x.zorder)
         for art in children:
+            if (self.get_ndim() == 3) and (art.axes is not None):
+                art.do_3d_projection()
             art.draw(renderer)
 
 

iplotx/plotting.py

@@ -3,6 +3,7 @@ from contextlib import nullcontext
 import numpy as np
 import pandas as pd
 import matplotlib as mpl
+from mpl_toolkits.mplot3d.axes3d import Axes3D
 import matplotlib.pyplot as plt
 
 from .typing import (
@@ -28,7 +29,7 @@ def network(
     style: str | dict | Sequence[str | dict] = (),
     title: Optional[str] = None,
     aspect: Optional[str | float] = None,
-    margins: float | tuple[float, float] = 0,
+    margins: float | tuple[float, float] | tuple[float, float, float] = 0,
     strip_axes: bool = True,
     figsize: Optional[tuple[float, float]] = None,
     **kwargs,
@@ -53,13 +54,15 @@ def network(
         style: Apply this style for the objects to plot. This can be a sequence (e.g. list)
             of styles and they will be applied in order.
         title: If not None, set the axes title to this value.
-        aspect: If not None, set the aspect ratio of the axis to this value. The most common
-            value is 1.0, which proportionates x- and y-axes.
+        aspect: If not None, set the aspect ratio of the axis to this value. In 2D, the most
+            common value is 1.0, which proportionates x- and y-axes. In 3D, only string
+            values are accepted (see the documentation of Axes.set_aspect).
         margins: How much margin to leave around the plot. A higher value (e.g. 0.1) can be
             used as a quick fix when some vertex shapes reach beyond the plot edge. This is
             a fraction of the data limits, so 0.1 means 10% of the data limits will be left
-            as margin.
-        strip_axes: If True, remove axis spines and ticks.
+            as margin. A pair (in 2D) or triplet (in 3D) of floats can also be provided and
+            applied to each axis separately.
+        strip_axes: If True, remove axis spines and ticks. In 3D, only ticks are removed.
         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.
@@ -83,9 +86,6 @@ def network(
         if (network is None) and (grouping is None):
             raise ValueError("At least one of network or grouping must be provided.")
 
-        if ax is None:
-            fig, ax = plt.subplots(figsize=figsize)
-
         artists = []
         if network is not None:
             nwkart = NetworkArtist(
@@ -94,30 +94,58 @@ def network(
                 vertex_labels=vertex_labels,
                 edge_labels=edge_labels,
                 transform=mpl.transforms.IdentityTransform(),
-                offset_transform=ax.transData,
             )
-            ax.add_artist(nwkart)
-
-            # Set the figure, which itself sets the dpi scale for vertices, edges,
-            # arrows, etc. Now data limits can be computed correctly
-            nwkart.set_figure(ax.figure)
-
             artists.append(nwkart)
-
-            # Set normailsed layout since we have it by now
             layout = nwkart.get_layout()
+        else:
+            nwkart = None
 
         if grouping is not None:
             grpart = GroupingArtist(
                 grouping,
                 layout,
                 network=network,
-                transform=ax.transData,
             )
-            ax.add_artist(grpart)
-
-            grpart.set_figure(ax.figure)
+            layout = grpart.get_layout()
             artists.append(grpart)
+        else:
+            grpart = None
+
+        if (nwkart is not None) or (grpart is not None):
+            ndim = layout.shape[1]
+        else:
+            ndim = None
+
+        if ax is None:
+            if ndim == 3:
+                fig = plt.figure(figsize=figsize)
+                ax = fig.add_subplot(111, projection="3d")
+            else:
+                fig, ax = plt.subplots(figsize=figsize)
+                ndim = 2
+        else:
+            # Check that the expected axis projection is used (3d for 3d layouts)
+            if ndim == 3:
+                assert isinstance(ax, Axes3D)
+            elif ndim == 2:
+                # NOTE: technically we probably want it to be cartesian (not polar, etc.)
+                # but let's be flexible for now and let that request bubble up from users
+                assert not isinstance(ax, Axes3D)
+
+        # This is used in 3D for autoscaling
+        had_data = ax.has_data()
+
+        if nwkart is not None:
+            # Set the figure, which itself sets the dpi scale for vertices, edges,
+            # arrows, etc. Now data limits can be computed correctly
+            nwkart.set_offset_transform(ax.transData)
+            ax.add_artist(nwkart)
+            nwkart.axes = ax
+
+        if grpart is not None:
+            grpart.set_transform(ax.transData)
+            ax.add_artist(grpart)
+            grpart.ax = ax
 
         if title is not None:
             ax.set_title(title)
@@ -125,11 +153,11 @@ def network(
         if aspect is not None:
             ax.set_aspect(aspect)
 
-        _postprocess_axes(ax, artists, strip=strip_axes)
+        _postprocess_axes(ax, artists, strip=strip_axes, had_data=had_data)
 
         if np.isscalar(margins):
-            margins = (margins, margins)
-        if (margins[0] != 0) or (margins[1] != 0):
+            margins = [margins] * ndim
+        if (margins[0] != 0) or (margins[1] != 0) or ((len(margins) == 3) and (margins[2] != 0)):
             ax.margins(*margins)
 
         return artists
@@ -223,7 +251,6 @@ def tree(
             show_support=show_support,
         )
         ax.add_artist(artist)
-
         artist.set_figure(ax.figure)
 
         if title is not None:
@@ -243,26 +270,46 @@ def tree(
 
 
 # INTERNAL ROUTINES
-def _postprocess_axes(ax, artists, strip=True):
+def _postprocess_axes(ax, artists, strip=True, had_data=None):
     """Postprocess axis after plotting."""
 
     if strip:
-        # Despine
-        ax.spines["right"].set_visible(False)
-        ax.spines["top"].set_visible(False)
-        ax.spines["left"].set_visible(False)
-        ax.spines["bottom"].set_visible(False)
+        if not isinstance(ax, Axes3D):
+            # Despine
+            ax.spines["right"].set_visible(False)
+            ax.spines["top"].set_visible(False)
+            ax.spines["left"].set_visible(False)
+            ax.spines["bottom"].set_visible(False)
 
         # Remove axis ticks
         ax.set_xticks([])
         ax.set_yticks([])
-
-    # Set new data limits
-    bboxes = []
-    for art in artists:
-        bboxes.append(art.get_datalim(ax.transData))
-    bbox = mpl.transforms.Bbox.union(bboxes)
-    ax.update_datalim(bbox)
-
-    # Autoscale for x/y axis limits
-    ax.autoscale_view()
+        if isinstance(ax, Axes3D):
+            ax.set_zticks([])
+
+    # NOTE: bboxes appear to be not that well defined in 3D axes
+    # instead, there is a dedicated function that is a little
+    # pedestrian
+    if isinstance(ax, Axes3D):
+        for art in artists:
+            XYZ = art.get_layout().values.T
+            if ax._zmargin < 0.05 and XYZ[0].size > 0:
+                ax.set_zmargin(0.05)
+            ax.auto_scale_xyz(
+                *XYZ,
+                had_data=had_data,
+            )
+            # NOTE: breaking is not needed, worst case it will
+            # autoscale twice (for network and grouping), which
+            # is better, at this stage of development, than
+            # trying to be too clever by doing the math outselves
+    else:
+        # Set new data limits
+        bboxes = []
+        for art in artists:
+            bboxes.append(art.get_datalim(ax.transData))
+        bbox = mpl.transforms.Bbox.union(bboxes)
+        ax.update_datalim(bbox)
+
+        # Autoscale for x/y axis limits
+        ax.autoscale_view()

iplotx/version.py

@@ -2,4 +2,4 @@
 iplotx version information module.
 """
 
-__version__ = "0.9.0"
+__version__ = "0.10.0"

iplotx/vertex.py

@@ -119,6 +119,16 @@ class VertexCollection(PatchCollection):
         for child in self.get_children():
             child.set_figure(fig)
 
+    @property
+    def axes(self):
+        return PatchCollection.axes.__get__(self)
+
+    @axes.setter
+    def axes(self, new_axes):
+        PatchCollection.axes.__set__(self, new_axes)
+        for child in self.get_children():
+            child.axes = new_axes
+
     def get_index(self):
         """Get the VertexCollection index."""
         return self._index
@@ -196,7 +206,9 @@ class VertexCollection(PatchCollection):
     def _update_offsets_from_layout(self) -> None:
         """Update offsets in matplotlib coordinates from the layout DataFrame."""
         if self._layout_coordinate_system == "cartesian":
-            self._offsets = self._layout.values
+            # Make sure we accept 3D values and ignore the z component if present
+            # This makes life upstream a little more readable
+            self._offsets = self._layout.values[:, :2]
         elif self._layout_coordinate_system == "polar":
             # Convert polar coordinates (r, theta) to cartesian (x, y)
             r = self._layout.iloc[:, 0].values
@@ -221,6 +233,16 @@ class VertexCollection(PatchCollection):
         self._update_offsets_from_layout()
         self.stale = True
 
+    def set_offset_transform(self, transform: mpl.transforms.Transform) -> None:
+        """Set the offset transform for the vertices.
+
+        Parameters:
+            transform: The matplotlib transform to use for the offsets.
+        """
+        super().set_offset_transform(transform)
+        if hasattr(self, "_label_collection"):
+            self._label_collection.set_transform(transform)
+
     def get_style(self) -> Optional[dict[str, Any]]:
         """Get the style dictionary for the vertices."""
         return self._style

{iplotx-0.9.0.dist-info → iplotx-0.10.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iplotx
-Version: 0.9.0
+Version: 0.10.0
 Summary: Plot networkx from igraph and networkx.
 Project-URL: Homepage, https://github.com/fabilab/iplotx
 Project-URL: Documentation, https://readthedocs.org/iplotx
@@ -29,7 +29,6 @@ Requires-Python: >=3.11
 Requires-Dist: matplotlib>=2.0.0
 Requires-Dist: numpy>=2.0.0
 Requires-Dist: pandas>=2.0.0
-Requires-Dist: pylint>=3.3.7
 Provides-Extra: igraph
 Requires-Dist: igraph>=0.11.0; extra == 'igraph'
 Provides-Extra: networkx

{iplotx-0.9.0.dist-info → iplotx-0.10.0.dist-info}/RECORD

@@ -1,25 +1,28 @@
 iplotx/__init__.py,sha256=RzSct91jO8abrxOIn33rKEnDUgYpu1oj4olbObgX_hs,489
-iplotx/artists.py,sha256=Bpn6NS8S_B_E4OW88JYW6aEu2bIuIQJmbs2paTmBAoY,522
+iplotx/artists.py,sha256=XNtRwuvQdKkZCAejILydLD3J5B87sg5xPXuZFv_Gkk8,654
 iplotx/cascades.py,sha256=OPqF7Huls-HFmDA5MCF6DEZlUeRVaXsbQcHBoKAgNJs,8182
-iplotx/groups.py,sha256=_9KdIiTAi1kXtd2mDywgBJCbqoRq2z-5fzOPf76Wgb8,6287
-iplotx/label.py,sha256=6am3a0ejcW_bWEXSOODE1Ke3AyCU1lJ45RfnXNbHAQw,8923
+iplotx/groups.py,sha256=X0G-EULkd7WBn1j82r-cBgpzZRd7gQ1cfqFoYNweLns,6775
+iplotx/label.py,sha256=76vSaH9zPv8drpzFaWNwuEIMQPEgKmilwfBnA8I_BJ4,9307
 iplotx/layout.py,sha256=KxmRLqjo8AYCBAmXez8rIiLU2sM34qhb6ox9AHYwRyE,4839
-iplotx/network.py,sha256=SGmXXrFxqgOoQcEJSZdL3WiI6rHDlPOGg5loGPrYpDk,11688
-iplotx/plotting.py,sha256=imlJZdx3S9B59TQPqrHEwQwJEnpI9SljthK34n3QJQY,11007
+iplotx/network.py,sha256=_yEArzsqnzm5MefVKKM96q_Od47ZIwjkJb2wuVFnfD8,13486
+iplotx/plotting.py,sha256=icEefWJnS2lEGLp4t1LhDSP40JuvNKgOie3FDLOnTMk,13195
 iplotx/tree.py,sha256=TxbNoBHS0CfswrcMIWCNtnOl_3e4-PwCrVo0goywC0U,28807
 iplotx/typing.py,sha256=QLdzV358IiD1CFe88MVp0D77FSx5sSAVUmM_2WPPE8I,1463
-iplotx/version.py,sha256=rlV8GqlJtRzwlHxPle9bW-H7xuYNreaGGD2bFrax930,66
-iplotx/vertex.py,sha256=hqdlD9fRBSwH5bRvlpaaPu7jgUR4z9nob1SYfPWDxtI,14966
-iplotx/edge/__init__.py,sha256=AVnLsrDWWCkix1LVhrjpWKEKDxOp8joM4tF6RqEHC8I,27115
+iplotx/version.py,sha256=YEqH52lnz6XyxsG7HXlFaHzcWyc3-VsDrQeE7vZtRQQ,67
+iplotx/vertex.py,sha256=rIg1gdxv7ZW8HjqmwJaynm098HqTmlC9XQgB81wjzgk,15775
+iplotx/art3d/edge.py,sha256=cZzI0nPTglU1xA_TsySrdE5GwxVx7smc32mxCE_EP48,1785
+iplotx/art3d/vertex.py,sha256=KhwR60ekPLL1CDYn9jeQFo5kfdCS5Naz7u1kM-_eq7U,1883
+iplotx/edge/__init__.py,sha256=P96eXHECrqHtVeIxdBA0SxJvTMeHlXPP_bqEOi5MsVQ,27589
 iplotx/edge/arrow.py,sha256=ZKt3UNZ7XRa2S3KxpoQfd4q_6eSUHOS476BZNqlf2pw,16462
-iplotx/edge/geometry.py,sha256=wpFTi12-BaUaWr6Ie-nHV_SMAdSGJvjzJaqeEaSPf9w,15053
+iplotx/edge/geometry.py,sha256=G0hze1SQGUiiLMdc8QVO7zr1C9UUIQt-IN17KBk6lkM,16317
+iplotx/edge/geometry3d.py,sha256=HnL1TvMXFegvco6oaiUqDXRKbx9GW3FsT4DUX_Ol94k,3207
 iplotx/edge/leaf.py,sha256=SyGMv2PIOoH0pey8-aMVaZheK3hNe1Qz_okcyWbc4E4,4268
 iplotx/edge/ports.py,sha256=BpkbiEhX4mPBBAhOv4jcKFG4Y8hxXz5GRtVLCC0jbtI,1235
 iplotx/ingest/__init__.py,sha256=S0YfnXcFKseB7ZBQc4yRt0cNDsLlhqdom0TmSY3OY2E,4756
 iplotx/ingest/heuristics.py,sha256=715VqgfKek5LOJnu1vTo7RqPgCl-Bb8Cf6o7_Tt57fA,5797
 iplotx/ingest/typing.py,sha256=61LwNwrTHVh8eqqC778Gr81zPYcUKW61mDgGCCsuGSk,14181
-iplotx/ingest/providers/network/igraph.py,sha256=8dWeaQ_ZNdltC098V2YeLXsGdJHQnBa6shF1GAfl0Zg,2973
-iplotx/ingest/providers/network/networkx.py,sha256=4sPFOx87ipOYlXu0hjJl25Z4So_RnhO1CYYozGp-wJg,4626
+iplotx/ingest/providers/network/igraph.py,sha256=WL9Yx2IF5QhUIoKMlozdyq5HWIZ-IJmNoeS8GOhL0KU,2945
+iplotx/ingest/providers/network/networkx.py,sha256=ehCg4npL073HX-eAG-VoP6refLPsMb3lYG51xt_rNjA,4636
 iplotx/ingest/providers/network/simple.py,sha256=e_aHhiHhN9DrMoNrt7tEMPURXGhQ1TYRPzsxDEptUlc,3766
 iplotx/ingest/providers/tree/biopython.py,sha256=4N_54cVyHHPcASJZGr6pHKE2p5R3i8Cm307SLlSLHLA,1480
 iplotx/ingest/providers/tree/cogent3.py,sha256=JmELbDK7LyybiJzFNbmeqZ4ySJoDajvFfJebpNfFKWo,1073
@@ -33,6 +36,6 @@ iplotx/utils/geometry.py,sha256=6RrC6qaB0-1vIk1LhGA4CfsiMd-9JNniSPyL_l9mshE,9245
 iplotx/utils/internal.py,sha256=WWfcZDGK8Ut1y_tOHRGg9wSqY1bwSeLQO7dHM_8Tvwo,107
 iplotx/utils/matplotlib.py,sha256=wELE73quQv10-1w9uA5eDTgkZkylJvjg7pd3K5tZPOo,6294
 iplotx/utils/style.py,sha256=vyNP80nDYVinqm6_9ltCJCtjK35ZcGlHvOskNv3eQBc,4225
-iplotx-0.9.0.dist-info/METADATA,sha256=HQtb9YO4hhXGn0K8gaXBIAerAu1Eu0b4QiIHWCIZv2c,4908
-iplotx-0.9.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-iplotx-0.9.0.dist-info/RECORD,,
+iplotx-0.10.0.dist-info/METADATA,sha256=BY0tMOjP84ydubHd9ocmpn9LaqdmoqX3VcBEX_6tTWA,4880
+iplotx-0.10.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+iplotx-0.10.0.dist-info/RECORD,,