iplotx 0.11.1__py3-none-any.whl → 1.0.0__py3-none-any.whl

iplotx/art3d/edge/__init__.py

@@ -2,13 +2,26 @@
 Module containing code to manipulate edge visualisations in 3D, especially the Edge3DCollection class.
 """
 
-from mpl_toolkits.mplot3d import Axes3D
+import numpy as np
+from matplotlib import (
+    colors as mcolors,
+)
+from matplotlib.collections import (
+    LineCollection,
+)
+from mpl_toolkits.mplot3d import (
+    Axes3D,
+)
 from mpl_toolkits.mplot3d.art3d import (
     Line3DCollection,
+    _viewlim_mask,
 )
 
 from ...utils.matplotlib import (
     _forwarder,
+    _proj_transform_vectors,
+    _zalpha,
+    _get_data_scale,
 )
 from ...edge import (
     EdgeCollection,
@@ -73,11 +86,113 @@ class Edge3DCollection(Line3DCollection):
             segments3d.append(segment)
         self.set_segments(segments3d)
 
+    def do_3d_projection(self):
+        """
+        Project the points according to renderer matrix.
+        """
+        segments = np.asanyarray(self._segments3d)
+
+        mask = False
+        if np.ma.isMA(segments):
+            mask = segments.mask
+
+        if self._axlim_clip:
+            viewlim_mask = _viewlim_mask(
+                segments[..., 0], segments[..., 1], segments[..., 2], self.axes
+            )
+            if np.any(viewlim_mask):
+                # broadcast mask to 3D
+                viewlim_mask = np.broadcast_to(
+                    viewlim_mask[..., np.newaxis], (*viewlim_mask.shape, 3)
+                )
+                mask = mask | viewlim_mask
+        xyzs = np.ma.array(_proj_transform_vectors(segments, self.axes.M), mask=mask)
+        segments_2d = xyzs[..., 0:2]
+        LineCollection.set_segments(self, segments_2d)
+
+        # Use the average projected z value of each line for depthshade
+        xyzs_mean = xyzs.mean(axis=1)
+        self._data_scale = _get_data_scale(*(xyzs_mean.T))
+        self._vzs = xyzs_mean[..., 2]
+
+        # FIXME
+        if len(xyzs) > 0:
+            minz = min(xyzs[..., 2].min(), 1e9)
+        else:
+            minz = np.nan
+        return minz
+
+    def _maybe_depth_shade_and_sort_colors(self, color_array):
+        color_array = (
+            _zalpha(
+                color_array,
+                self._vzs,
+                min_alpha=self._depthshade_minalpha,
+                _data_scale=self._data_scale,
+            )
+            if self._vzs is not None and self._depthshade
+            else color_array
+        )
+        return mcolors.to_rgba_array(color_array, self._alpha)
+
+    def set_edgecolor(self, color):
+        """Set the edge color of the collection."""
+        self._edgecolors = mcolors.to_rgba_array(color, self._alpha)
+        self._edgecolors_noshade = self._edgecolors.copy()
+
+    def get_edgecolor(self):
+        """Set the edge color of the collection, including depth shading."""
+        # We need this check here to make sure we do not double-apply the depth
+        # based alpha shading when the edge color is "face" which means the
+        # edge colour should be identical to the face colour.
+        if not hasattr(self, "_edgecolors_noshade"):
+            self._edgecolors_noshade = self._edgecolors.copy()
+        return self._maybe_depth_shade_and_sort_colors(self._edgecolors_noshade)
+
+    set_edgecolors = set_edgecolor
+    get_edgecolors = get_edgecolor
+
+    def get_depthshade(self):
+        """Get whether depth shading is performed on collection members."""
+        return self._depthshade
+
+    def get_depthshade_minalpha(self):
+        """The minimum alpha value used by depth-shading."""
+        return self._depthshade_minalpha
+
+    def set_depthshade(
+        self,
+        depthshade,
+        depthshade_minalpha=0.1,
+    ):
+        """
+        Set whether depth shading is performed on collection members.
+
+        Parameters
+        ----------
+        depthshade : bool
+            Whether to shade the patches in order to give the appearance of
+            depth.
+        depthshade_minalpha : float
+            Sets the minimum alpha value used by depth-shading.
+
+            .. versionadded:: 3.11
+        """
+        self._depthshade = depthshade
+        self._depthshade_minalpha = depthshade_minalpha
+        self.stale = True
+
     def _update_before_draw(self) -> None:
         """Update the collection before drawing."""
         if isinstance(self.axes, Axes3D) and hasattr(self, "do_3d_projection"):
             self.do_3d_projection()
 
+        if not hasattr(self, "_edgecolors_noshade"):
+            self._edgecolors_noshade = self._edgecolors.copy()
+        self._edgecolors = self._maybe_depth_shade_and_sort_colors(
+            self._edgecolors_noshade,
+        )
+
         # TODO: Here's where we would shorten the edges to fit the vertex
         # projections from 3D onto 2D, if we wanted to do that. Because edges
         # in 3D are chains of segments rathen than splines, the shortening
@@ -111,6 +226,7 @@ def edge_collection_2d_to_3d(
     col: EdgeCollection,
     zdir: str = "z",
     axlim_clip: bool = False,
+    depthshade: bool = True,
 ):
     """Convert a 2D EdgeCollection to a 3D Edge3DCollection.
 
@@ -127,6 +243,9 @@ def edge_collection_2d_to_3d(
     # NOTE: after this line, none of the EdgeCollection methods will work
     # It's become a static drawer now. It uses segments instead of paths.
     col.__class__ = Edge3DCollection
+    col._depthshade = depthshade
+    col._depthshade_minalpha = 0.1
+
     col._compute_edge_segments()
 
     col._axlim_clip = axlim_clip

iplotx/artists.py

@@ -3,19 +3,21 @@ All artists defined in iplotx.
 """
 
 from .network import NetworkArtist
-from .tree import TreeArtist
+from .network.groups import GroupingCollection
 from .vertex import VertexCollection
 from .edge import EdgeCollection
 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
+from .tree import TreeArtist
+from .tree.cascades import CascadeCollection
 
 
 ___all__ = (
     NetworkArtist,
+    GroupingCollection,
     TreeArtist,
     VertexCollection,
     EdgeCollection,

iplotx/edge/__init__.py

@@ -705,6 +705,7 @@ def make_stub_patch(**kwargs):
         "norm",
         "split",
         "shrink",
+        "depthshade",
         # DEPRECATED
         "padding",
     ]

iplotx/ingest/providers/tree/dendropy.py

@@ -0,0 +1,59 @@
+from typing import (
+    Any,
+    Optional,
+    Sequence,
+)
+import importlib
+
+from ...typing import (
+    TreeDataProvider,
+)
+
+
+class DendropyDataProvider(TreeDataProvider):
+    def is_rooted(self) -> bool:
+        return True
+
+    def get_root(self) -> Any:
+        """Get the root of the tree."""
+        return next(self.preorder())
+
+    def preorder(self) -> Any:
+        """Preorder traversal of the tree.
+
+        NOTE: This will work on both entire Trees and Nodes (which means a subtree including self).
+        """
+        if hasattr(self.tree, "preorder_node_iter"):
+            return self.tree.preorder_node_iter()
+        return self.tree.preorder_iter()
+
+    def postorder(self) -> Any:
+        """Preorder traversal of the tree.
+
+        NOTE: This will work on both entire Trees and Nodes (which means a subtree including self).
+        """
+        if hasattr(self.tree, "postorder_node_iter"):
+            return self.tree.postorder_node_iter()
+        return self.tree.postorder_iter()
+
+    def get_leaves(self) -> Sequence[Any]:
+        """Get a list of leaves."""
+        return self.tree.leaf_nodes()
+
+    @staticmethod
+    def get_children(node: Any) -> Sequence[Any]:
+        return node.child_nodes()
+
+    @staticmethod
+    def get_branch_length(node: Any) -> Optional[float]:
+        return node.edge.length
+
+    @staticmethod
+    def check_dependencies() -> bool:
+        return importlib.util.find_spec("dendropy") is not None
+
+    @staticmethod
+    def tree_type():
+        import dendropy
+
+        return dendropy.Tree

iplotx/{network.py → network/__init__.py}

@@ -7,33 +7,33 @@ import numpy as np
 import pandas as pd
 import matplotlib as mpl
 
-from .typing import (
+from ..typing import (
     GraphType,
     LayoutType,
 )
-from .style import (
+from ..style import (
     get_style,
     rotate_style,
 )
-from .utils.matplotlib import (
+from ..utils.matplotlib import (
     _stale_wrapper,
     _forwarder,
     _build_cmap_fun,
 )
-from .ingest import (
+from ..ingest import (
     ingest_network_data,
 )
-from .vertex import (
+from ..vertex import (
     VertexCollection,
 )
-from .edge import (
+from ..edge import (
     EdgeCollection,
     make_stub_patch as make_undirected_edge_patch,
 )
-from .art3d.vertex import (
+from ..art3d.vertex import (
     vertex_collection_2d_to_3d,
 )
-from .art3d.edge import (
+from ..art3d.edge import (
     Edge3DCollection,
     edge_collection_2d_to_3d,
 )
@@ -279,10 +279,11 @@ class NetworkArtist(mpl.artist.Artist):
         )
 
         if self.get_ndim() == 3:
+            depthshade = get_style(".vertex").get("depthshade", True)
             vertex_collection_2d_to_3d(
                 self._vertices,
                 zs=self.get_layout().iloc[:, 2].values,
-                depthshade=False,
+                depthshade=depthshade,
             )
 
     def _add_edges(self):
@@ -367,8 +368,10 @@ class NetworkArtist(mpl.artist.Artist):
             self._edges.set_array(colorarray)
 
         if self.get_ndim() == 3:
+            depthshade = get_style(".edge").get("depthshade", True)
             edge_collection_2d_to_3d(
                 self._edges,
+                depthshade=depthshade,
             )
 
     @_stale_wrapper

iplotx/{groups.py → network/groups.py}

@@ -1,5 +1,5 @@
 """
-Module for vertex groupings code, especially the GroupingArtist class.
+Module for vertex groupings code, especially the GroupingCollection class.
 """
 
 from typing import Union
@@ -9,22 +9,22 @@ import matplotlib as mpl
 from matplotlib.collections import PatchCollection
 
 
-from .typing import (
+from ..typing import (
     GroupingType,
     LayoutType,
 )
-from .ingest.heuristics import (
+from ..ingest.heuristics import (
     normalise_layout,
     normalise_grouping,
 )
-from .style import get_style, rotate_style
-from .utils.geometry import (
+from ..style import get_style, rotate_style
+from ..utils.geometry import (
     convex_hull,
     _compute_group_path_with_vertex_padding,
 )
 
 
-class GroupingArtist(PatchCollection):
+class GroupingCollection(PatchCollection):
     """Matplotlib artist for a vertex grouping (clustering/cover).
 
     This class is used to plot patches surrounding groups of vertices in a network.

iplotx/plotting.py

@@ -13,7 +13,7 @@ from .typing import (
     TreeType,
 )
 from .network import NetworkArtist
-from .groups import GroupingArtist
+from .network.groups import GroupingCollection
 from .tree import TreeArtist
 from .style import context
 
@@ -101,7 +101,7 @@ def network(
             nwkart = None
 
         if grouping is not None:
-            grpart = GroupingArtist(
+            grpart = GroupingCollection(
                 grouping,
                 layout,
                 network=network,

iplotx/style/leaf_info.py

@@ -42,6 +42,7 @@ nonrotating_leaves = (
     "angular",
     "curved",
     "capstyle",
+    "depthshade",
 )
 
 # Union of all style leaves (rotating and nonrotating)

iplotx/{tree.py → tree/__init__.py}

@@ -10,38 +10,41 @@ import numpy as np
 import pandas as pd
 import matplotlib as mpl
 
-from .style import (
+from ..style import (
     context,
     get_style,
     rotate_style,
     merge_styles,
 )
-from .utils.matplotlib import (
+from ..utils.matplotlib import (
     _stale_wrapper,
     _forwarder,
     _build_cmap_fun,
 )
-from .ingest import (
+from ..ingest import (
     ingest_tree_data,
     data_providers,
 )
-from .vertex import (
+from ..vertex import (
     VertexCollection,
 )
-from .edge import (
+from ..edge import (
     EdgeCollection,
     make_stub_patch as make_undirected_edge_patch,
 )
-from .edge.leaf import (
+from ..edge.leaf import (
     LeafEdgeCollection,
 )
-from .label import (
+from ..label import (
     LabelCollection,
 )
 from .cascades import (
     CascadeCollection,
 )
-from .network import (
+from .scalebar import (
+    TreeScalebarArtist,
+)
+from ..network import (
     _update_from_internal,
 )
 
@@ -663,6 +666,40 @@ class TreeArtist(mpl.artist.Artist):
         """Get the orientation of the tree layout."""
         return self._ipx_internal_data.get("orientation", None)
 
+    def scalebar(
+        self,
+        loc: str = "upper left",
+        **kwargs,
+    ):
+        """Create scalebar for the tree.
+
+        Parameters:
+            legth: Length of the scalebar in data units.
+            loc: Location of the scalebar. Same options as `matplotlib.legend`.
+            kwargs: Additional keyword arguments passed to `TreeScalebarArtist`. These are
+                generally the same options that you would pass to a legend, such as
+                bbox_to_anchor, bbox_transform, etc.
+        Returns:
+            The artist with the tree scale bar.
+        """
+        if self.axes is None:
+            raise RuntimeError("Cannot add a scalebar if the artist is not in an Axes.")
+
+        scalebar = TreeScalebarArtist(
+            self,
+            layout=self.get_layout_name(),
+            loc=loc,
+        )
+
+        # Remove previous scalebars if any
+        for art in self.axes._children:
+            if isinstance(art, TreeScalebarArtist) and art._treeartist == self:
+                art.remove()
+
+        self.axes.add_artist(scalebar)
+
+        return scalebar
+
     def style_subtree(
         self,
         nodes: Sequence[Hashable],

iplotx/{cascades.py → tree/cascades.py}

@@ -5,16 +5,15 @@ from typing import (
 import warnings
 import numpy as np
 import pandas as pd
+import matplotlib as mpl
 
-from .typing import (
+from ..typing import (
     TreeType,
 )
-from .ingest.typing import (
+from ..ingest.typing import (
     TreeDataProvider,
 )
-import matplotlib as mpl
-
-from .style import (
+from ..style import (
     copy_with_deep_values,
     rotate_style,
 )

iplotx/tree/scalebar.py

@@ -0,0 +1,326 @@
+from typing import (
+    Any,
+)
+import numpy as np
+from matplotlib import (
+    _api,
+)
+from matplotlib import collections as mcoll
+from matplotlib.legend import Legend
+from matplotlib.legend_handler import HandlerErrorbar
+from matplotlib.lines import Line2D
+from matplotlib.offsetbox import (
+    HPacker,
+    VPacker,
+    DrawingArea,
+    TextArea,
+)
+
+
+def _update_prop(legend_artist, orig_handle):
+    # NOTE: This is de facto a bug in mpl, because Line2D.set_linestyle()
+    # does two things: it reformats tuple-style dashing, and it sets the
+    # artist as stale. We want to do the former only here, so we reset
+    # the artist as the original stale state after calling it.
+    stale_orig = legend_artist.stale
+    legend_artist.set_linestyle(orig_handle.get_linestyle()[0])
+    legend_artist.stale = stale_orig
+
+    # These other properties can be set directly.
+    legend_artist._linewidth = orig_handle.get_linewidth()[0]
+    legend_artist._color = orig_handle.get_edgecolor()[0]
+    legend_artist._gapcolor = orig_handle._gapcolor
+
+
+class TreeScalebarArtist(Legend):
+    def __init__(
+        self,
+        treeartist,
+        layout: str = "horizontal",
+        frameon=False,
+        **kwargs,
+    ):
+        handles = [treeartist.get_edges()]
+        labels = [""]
+        self._layout = layout
+        self._treeartist = treeartist
+
+        if layout == "vertical":
+            handler_kwargs = dict(xerr_size=0, yerr_size=1)
+        else:
+            handler_kwargs = dict(xerr_size=1)
+        handler = TreeLegendHandler(
+            update_func=_update_prop,
+            **handler_kwargs,
+        )
+
+        super().__init__(
+            treeartist.axes,
+            handles,
+            labels,
+            handler_map={handles[0]: handler},
+            frameon=frameon,
+            **kwargs,
+        )
+
+    def _init_legend_box(self, handles, labels, markerfirst=True):
+        """
+        Create the legend box.
+
+        This is a modified version of the original Legend._init_legend_box
+        method to accommodate a scale bar.
+        """
+
+        fontsize = self._fontsize
+
+        # legend_box is a HPacker, horizontally packed with columns.
+        # Each column is a VPacker, vertically packed with legend items.
+        # Each legend item is a HPacker packed with:
+        # - handlebox: a DrawingArea which contains the legend handle.
+        # - labelbox: a TextArea which contains the legend text.
+
+        text_list = []  # the list of text instances
+        handle_list = []  # the list of handle instances
+        handles_and_labels = []
+
+        # The approximate height and descent of text. These values are
+        # only used for plotting the legend handle.
+        descent = 0.35 * fontsize * (self.handleheight - 0.7)  # heuristic.
+        height = fontsize * self.handleheight - descent
+        # each handle needs to be drawn inside a box of (x, y, w, h) =
+        # (0, -descent, width, height).  And their coordinates should
+        # be given in the display coordinates.
+
+        # The transformation of each handle will be automatically set
+        # to self.get_transform(). If the artist does not use its
+        # default transform (e.g., Collections), you need to
+        # manually set their transform to the self.get_transform().
+        legend_handler_map = self.get_legend_handler_map()
+
+        for orig_handle, label in zip(handles, labels):
+            handler = self.get_legend_handler(legend_handler_map, orig_handle)
+            if handler is None:
+                _api.warn_external(
+                    "Legend does not support handles for "
+                    f"{type(orig_handle).__name__} "
+                    "instances.\nA proxy artist may be used "
+                    "instead.\nSee: https://matplotlib.org/"
+                    "stable/users/explain/axes/legend_guide.html"
+                    "#controlling-the-legend-entries"
+                )
+                # No handle for this artist, so we just defer to None.
+                handle_list.append(None)
+            else:
+                handlebox = DrawingArea(
+                    width=self.handlelength * fontsize,
+                    height=height,
+                    xdescent=0.0,
+                    ydescent=descent,
+                )
+                # Create the artist for the legend which represents the
+                # original artist/handle.
+                handle_list.append(handler.legend_artist(self, orig_handle, fontsize, handlebox))
+
+                # The scale bar line is in this handle
+                bar_handle = handle_list[-1]
+                label = self._get_label_from_bar_handle(bar_handle)
+
+                textbox = TextArea(
+                    label,
+                    multilinebaseline=True,
+                    textprops=dict(
+                        verticalalignment="baseline",
+                        horizontalalignment="left",
+                        fontproperties=self.prop,
+                    ),
+                )
+                text_list.append(textbox._text)
+
+                handles_and_labels.append((handlebox, textbox))
+
+        columnbox = []
+        # array_split splits n handles_and_labels into ncols columns, with the
+        # first n%ncols columns having an extra entry.  filter(len, ...)
+        # handles the case where n < ncols: the last ncols-n columns are empty
+        # and get filtered out.
+        for handles_and_labels_column in filter(
+            len, np.array_split(handles_and_labels, self._ncols)
+        ):
+            # pack handlebox and labelbox into itembox
+            if self._layout == "vertical":
+                itempacker = HPacker
+            else:
+                itempacker = VPacker
+            itemboxes = [
+                itempacker(
+                    pad=0,
+                    sep=self.handletextpad * fontsize,
+                    children=[h, t] if markerfirst else [t, h],
+                    align="center",
+                )
+                for h, t in handles_and_labels_column
+            ]
+            # pack columnbox
+            alignment = "baseline" if markerfirst else "right"
+            columnbox.append(
+                VPacker(
+                    pad=0, sep=self.labelspacing * fontsize, align=alignment, children=itemboxes
+                )
+            )
+
+        mode = "expand" if self._mode == "expand" else "fixed"
+        sep = self.columnspacing * fontsize
+        self._legend_handle_box = HPacker(
+            pad=0, sep=sep, align="baseline", mode=mode, children=columnbox
+        )
+        self._legend_title_box = TextArea("")
+        self._legend_box = VPacker(
+            pad=self.borderpad * fontsize,
+            sep=self.labelspacing * fontsize,
+            align=self._alignment,
+            children=[self._legend_title_box, self._legend_handle_box],
+        )
+        self._legend_box.set_figure(self.get_figure(root=False))
+        self._legend_box.axes = self.axes
+        self.texts = text_list
+        self.legend_handles = handle_list
+
+    def _get_label_from_bar_handle(self, bar_handle: Any) -> str:
+        # Extract the x coordinates of the scale bar
+        p0, p1 = bar_handle.get_segments()[0]
+
+        bar_trans = bar_handle.get_transform()
+        data_trans = self.parent.transData
+        # FIXME: this is off, probably because of some Packer anchor additional transform
+        composite_trans = data_trans.inverted() + bar_trans
+
+        p0_data = composite_trans.transform(p0)
+        p1_data = composite_trans.transform(p1)
+        distance = np.linalg.norm(p1_data - p0_data)
+        label = f"{distance:.2f}"
+        return label
+
+    def draw(self, renderer):
+        bar_handle = self.legend_handles[0]
+        label = self._get_label_from_bar_handle(bar_handle)
+
+        text_handle = (
+            self._legend_box.get_children()[1].get_children()[0].get_children()[0].get_children()[1]
+        )
+        # Bypass stale=True (we are already redrawing)
+        text_handle.set_text(label)
+
+        super().draw(renderer)
+
+
+class TreeLegendHandler(HandlerErrorbar):
+    def __init__(self, marker_size=6, **kw):
+        self.marker_size = marker_size
+        super().__init__(**kw)
+
+    def create_artists(
+        self,
+        legend,
+        orig_handle,
+        xdescent,
+        ydescent,
+        width,
+        height,
+        fontsize,
+        trans,
+    ):
+        # docstring inherited
+        plotline = orig_handle
+
+        xdata, xdata_marker = self.get_xdata(legend, xdescent, ydescent, width, height, fontsize)
+        ydata = np.full_like(xdata, (height - ydescent) / 2)
+
+        xdata_marker = np.asarray(xdata_marker)
+        ydata_marker = np.asarray(ydata[: len(xdata_marker)])
+
+        xerr_size, yerr_size = self.get_err_size(
+            legend, xdescent, ydescent, width, height, fontsize
+        )
+
+        if legend._layout == "vertical":
+            xdata, ydata = np.array(
+                [
+                    ((x, y - yerr_size), (x, y + yerr_size))
+                    for x, y in zip(xdata_marker, ydata_marker)
+                ]
+            ).T
+
+        legline = Line2D(xdata, ydata)
+
+        legline_marker = Line2D(xdata_marker, ydata_marker)
+
+        # when plotlines are None (only errorbars are drawn), we just
+        # make legline invisible.
+        if plotline is None:
+            legline.set_visible(False)
+            legline_marker.set_visible(False)
+        else:
+            self.update_prop(legline, plotline, legend)
+
+            legline.set_drawstyle("default")
+            legline.set_marker("none")
+
+            self.update_prop(legline_marker, plotline, legend)
+            legline_marker.set_linestyle("None")
+
+            if legend.markerscale != 1:
+                newsz = legline_marker.get_markersize() * legend.markerscale
+                legline_marker.set_markersize(newsz)
+
+        handle_barlinecols = []
+        handle_caplines = []
+
+        if legend._layout != "vertical":
+            verts = [
+                ((x - xerr_size, y), (x + xerr_size, y)) for x, y in zip(xdata_marker, ydata_marker)
+            ]
+            coll = mcoll.LineCollection(verts)
+            self.update_prop(coll, plotline, legend)
+            handle_barlinecols.append(coll)
+
+            # Always show the cap lines
+            if True:
+                capline_left = Line2D(xdata_marker - xerr_size, ydata_marker)
+                capline_right = Line2D(xdata_marker + xerr_size, ydata_marker)
+                self.update_prop(capline_left, plotline, legend)
+                self.update_prop(capline_right, plotline, legend)
+                capline_left.set_marker("|")
+                capline_right.set_marker("|")
+
+                handle_caplines.append(capline_left)
+                handle_caplines.append(capline_right)
+
+        else:
+            verts = [
+                ((x, y - yerr_size), (x, y + yerr_size)) for x, y in zip(xdata_marker, ydata_marker)
+            ]
+            coll = mcoll.LineCollection(verts)
+            self.update_prop(coll, plotline, legend)
+            handle_barlinecols.append(coll)
+
+            # Always show the cap lines
+            if True:
+                capline_left = Line2D(xdata_marker, ydata_marker - yerr_size)
+                capline_right = Line2D(xdata_marker, ydata_marker + yerr_size)
+                self.update_prop(capline_left, plotline, legend)
+                self.update_prop(capline_right, plotline, legend)
+                capline_left.set_marker("_")
+                capline_right.set_marker("_")
+
+                handle_caplines.append(capline_left)
+                handle_caplines.append(capline_right)
+
+        artists = [
+            *handle_barlinecols,
+            *handle_caplines,
+            legline,
+            legline_marker,
+        ]
+        for artist in artists:
+            artist.set_transform(trans)
+        return artists

iplotx/utils/matplotlib.py

@@ -4,6 +4,7 @@ from math import atan2
 import numpy as np
 import pandas as pd
 import matplotlib as mpl
+import matplotlib.colors as mcolors
 
 from .geometry import (
     _evaluate_squared_bezier,
@@ -204,3 +205,80 @@ def _build_cmap_fun(
         norm = mpl.colors.Normalize(vmin=vmin, vmax=vmax)
 
     return lambda x: cmap(norm(x))
+
+
+# NOTE: this is polyfill from future matplotlib versions
+# LICENSED UNDER THE MPL LICENSE from:
+# https://github.com/matplotlib/matplotlib/blob/main/lib/mpl_toolkits/mplot3d/proj3d.py
+def _proj_transform_vectors(vecs, M):
+    """
+    Vectorized version of ``_proj_transform_vec``.
+
+    Parameters
+    ----------
+    vecs : ... x 3 np.ndarray
+        Input vectors
+    M : 4 x 4 np.ndarray
+        Projection matrix
+    """
+    vecs_shape = vecs.shape
+    vecs = vecs.reshape(-1, 3).T
+
+    vecs_pad = np.empty((vecs.shape[0] + 1,) + vecs.shape[1:])
+    vecs_pad[:-1] = vecs
+    vecs_pad[-1] = 1
+    product = np.dot(M, vecs_pad)
+    tvecs = product[:3] / product[3]
+
+    return tvecs.T.reshape(vecs_shape)
+
+
+def _zalpha(
+    colors,
+    zs,
+    min_alpha=0.3,
+    _data_scale=None,
+):
+    """Modify the alpha values of the color list according to z-depth."""
+
+    if len(colors) == 0 or len(zs) == 0:
+        return np.zeros((0, 4))
+
+    # Alpha values beyond the range 0-1 inclusive make no sense, so clip them
+    min_alpha = np.clip(min_alpha, 0, 1)
+
+    if _data_scale is None or _data_scale == 0:
+        # Don't scale the alpha values since we have no valid data scale for reference
+        sats = np.ones_like(zs)
+
+    else:
+        # Deeper points have an increasingly transparent appearance
+        sats = np.clip(1 - (zs - np.min(zs)) / _data_scale, min_alpha, 1)
+
+    rgba = np.broadcast_to(mcolors.to_rgba_array(colors), (len(zs), 4))
+
+    # Change the alpha values of the colors using the generated alpha multipliers
+    return np.column_stack([rgba[:, :3], rgba[:, 3] * sats])
+
+
+def _get_data_scale(X, Y, Z):
+    """
+    Estimate the scale of the 3D data for use in depth shading
+
+    Parameters
+    ----------
+    X, Y, Z : masked arrays
+        The data to estimate the scale of.
+    """
+    # Account for empty datasets. Assume that X Y and Z have the same number
+    # of elements.
+    if not np.ma.count(X):
+        return 0
+
+    # Estimate the scale using the RSS of the ranges of the dimensions
+    # Note that we don't use np.ma.ptp() because we otherwise get a build
+    # warning about handing empty arrays.
+    ptp_x = X.max() - X.min()
+    ptp_y = Y.max() - Y.min()
+    ptp_z = Z.max() - Z.min()
+    return np.sqrt(ptp_x**2 + ptp_y**2 + ptp_z**2)

iplotx/version.py

@@ -2,4 +2,4 @@
 iplotx version information module.
 """
 
-__version__ = "0.11.1"
+__version__ = "1.0.0"

iplotx/vertex.py

@@ -398,7 +398,7 @@ def make_patch(
     **kwargs,
 ) -> tuple[Patch, float]:
     """Make a patch of the given marker shape and size."""
-    forbidden_props = ["label", "cmap", "norm", "cascade", "deep"]
+    forbidden_props = ["label", "cmap", "norm", "cascade", "deep", "depthshade"]
     for prop in forbidden_props:
         if prop in kwargs:
             kwargs.pop(prop)

{iplotx-0.11.1.dist-info → iplotx-1.0.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iplotx
-Version: 0.11.1
+Version: 1.0.0
 Summary: Plot networkx from igraph and networkx.
 Project-URL: Homepage, https://github.com/fabilab/iplotx
 Project-URL: Documentation, https://readthedocs.org/iplotx
@@ -10,8 +10,9 @@ Project-URL: Changelog, https://github.com/fabilab/iplotx/blob/main/CHANGELOG.md
 Author-email: Fabio Zanini <fabio.zanini@unsw.edu.au>
 Maintainer-email: Fabio Zanini <fabio.zanini@unsw.edu.au>
 License: MIT
-Keywords: graph,network,plotting,visualisation
+Keywords: graph,network,phylogeny,plotting,tree,visualisation
 Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: Matplotlib
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Education
 Classifier: Intended Audience :: Science/Research
@@ -52,13 +53,14 @@ Supports:
 - **networks**:
   - [networkx](https://networkx.org/)
   - [igraph](igraph.readthedocs.io/)
-  - [minimal network data structure](https://iplotx.readthedocs.io/en/latest/gallery/plot_simplenetworkdataprovider.html#sphx-glr-gallery-plot-simplenetworkdataprovider-py) (for educational purposes)
+  - [minimal network data structure](https://iplotx.readthedocs.io/en/latest/gallery/plot_simplenetworkdataprovider.html#sphx-glr-gallery-plot-simplenetworkdataprovider-py) (zero dependency)
 - **trees**:
   - [ETE4](https://etetoolkit.github.io/ete/)
   - [cogent3](https://cogent3.org/)
   - [Biopython](https://biopython.org/)
   - [scikit-bio](https://scikit.bio)
-  - [minimal tree data structure](https://iplotx.readthedocs.io/en/latest/gallery/tree/plot_simpletreedataprovider.html#sphx-glr-gallery-tree-plot-simpletreedataprovider-py) (for educational purposes)
+  - [dendropy](https://jeetsukumaran.github.io/DendroPy/index.html)
+  - [minimal tree data structure](https://iplotx.readthedocs.io/en/latest/gallery/tree/plot_simpletreedataprovider.html#sphx-glr-gallery-tree-plot-simpletreedataprovider-py) (zero dependency)
 
 In addition to the above, *any* network or tree analysis library can register an [entry point](https://iplotx.readthedocs.io/en/latest/providers.html#creating-a-custom-data-provider) to gain compatibility with `iplotx` with no intervention from our side.
 
@@ -89,15 +91,17 @@ See [gallery](https://iplotx.readthedocs.io/en/latest/gallery/index.html).
 
 ## Features
 - Plot networks from multiple libraries including networkx and igraph, using matplotlib as a backend. ✅
-- Plot trees from multiple libraries such as cogent3, ETE4, skbio, and biopython. ✅
+- Plot trees from multiple libraries such as cogent3, ETE4, skbio, biopython, and dendropy. ✅
 - Flexible yet easy styling, including an internal library of styles ✅
 - Interactive plotting, e.g. zooming and panning after the plot is created. ✅
 - Store the plot to disk thanks to the many matplotlib backends (SVG, PNG, PDF, etc.). ✅
-- Efficient plotting of large graphs using matplotlib's collection functionality. ✅
+- 3D network visualisation with depth shading. ✅
+- Efficient plotting of large graphs (up to ~1 million nodes on a laptop). ✅
 - Edit plotting elements after the plot is created, e.g. changing node colors, labels, etc. ✅
 - Animations, e.g. showing the evolution of a network over time. ✅
 - Mouse and keyboard interaction, e.g. hovering over nodes/edges to get information about them. ✅
 - Node clustering and covers, e.g. showing communities in a network. ✅
+- Edge tension, edge waypoints, and edge ports. ✅
 - Choice of tree layouts and orientations. ✅
 - Tree-specific options: cascades, subtree styling, split edges, etc. ✅
 - (WIP) Support uni- and bi-directional communication between graph object and plot object.🏗️

{iplotx-0.11.1.dist-info → iplotx-1.0.0.dist-info}/RECORD

@@ -1,20 +1,16 @@
 iplotx/__init__.py,sha256=RzSct91jO8abrxOIn33rKEnDUgYpu1oj4olbObgX_hs,489
-iplotx/artists.py,sha256=XNtRwuvQdKkZCAejILydLD3J5B87sg5xPXuZFv_Gkk8,654
-iplotx/cascades.py,sha256=OPqF7Huls-HFmDA5MCF6DEZlUeRVaXsbQcHBoKAgNJs,8182
-iplotx/groups.py,sha256=g6ahm61BSBmd2weIjr40MvPi_GcNRgvNb9YklQsiza4,6784
+iplotx/artists.py,sha256=2dBDT240zGwKb6tIc_y9pXeyU3LuYeF9wjj2tvi4KJo,730
 iplotx/label.py,sha256=7eS8ByadrhdIFOZz19U4VrS-oXY_ndFYNB-D4RZbFqI,9573
 iplotx/layout.py,sha256=KxmRLqjo8AYCBAmXez8rIiLU2sM34qhb6ox9AHYwRyE,4839
-iplotx/network.py,sha256=ae5rZwzWxmcBQXx1Y0q24jaXcM1hT1kip-JKsyk11QY,13385
-iplotx/plotting.py,sha256=icEefWJnS2lEGLp4t1LhDSP40JuvNKgOie3FDLOnTMk,13195
-iplotx/tree.py,sha256=TxbNoBHS0CfswrcMIWCNtnOl_3e4-PwCrVo0goywC0U,28807
+iplotx/plotting.py,sha256=FvV33DCuEjJwO9ytiYJuQmfOywgF-cDANd6nEE5s8R0,13211
 iplotx/typing.py,sha256=QLdzV358IiD1CFe88MVp0D77FSx5sSAVUmM_2WPPE8I,1463
-iplotx/version.py,sha256=BVfqBj50ae0jogJGXsQXi_fML0WjuC4GLFRHZQWawYY,67
-iplotx/vertex.py,sha256=bjvAy9UciPWkA1J-SroWF9ZaTXRzNKtDZXBlZ80VM60,16026
+iplotx/version.py,sha256=Zw6LAvjlzbItG1QBPJb1Tuqkb2PVUYsDwCVRYEJusgc,66
+iplotx/vertex.py,sha256=_yYyvusn4vYvi6RBEW6CHa3vnbv43GnZylnMIaK4bG0,16040
 iplotx/art3d/vertex.py,sha256=Xf8Um30X2doCd8KdNN7332F6BxC4k72Mb_GeRAuzQfQ,2545
-iplotx/art3d/edge/__init__.py,sha256=EzzW06YEeyIu52gXormkGIobae-etwKevZ_PDBr-S9c,4624
+iplotx/art3d/edge/__init__.py,sha256=uw1U_mMXqcZAvea-7JbU1PUKULQD1CMMrbwY02tiWRQ,8529
 iplotx/art3d/edge/arrow.py,sha256=14BFXY9kDOUGPZl2fMD9gRVGyaaN5kyd-l6ikBg6WHU,3601
 iplotx/art3d/edge/geometry.py,sha256=76VUmpPG-4Mls7x_994dMwdDPrWWnjT7nHJsHfwK_hA,2467
-iplotx/edge/__init__.py,sha256=wMKXD1h5SBaUv6HmebIc5wc9k8AuukaXzAOBu7epaqA,26341
+iplotx/edge/__init__.py,sha256=lkrMkQFx9PNzorKc9trQ8MggC-nZSyALhvP78DMvhN4,26363
 iplotx/edge/arrow.py,sha256=U7vvBo7IMwo1qiyU9cyUEwraOaBcJLgdu9oU2OyoHL4,17453
 iplotx/edge/geometry.py,sha256=jkTMvQC5425GjB_fmGLIPJeSDAr_7NZF8zZDLTrSj34,15541
 iplotx/edge/leaf.py,sha256=SyGMv2PIOoH0pey8-aMVaZheK3hNe1Qz_okcyWbc4E4,4268
@@ -27,16 +23,22 @@ iplotx/ingest/providers/network/networkx.py,sha256=ehCg4npL073HX-eAG-VoP6refLPsM
 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
+iplotx/ingest/providers/tree/dendropy.py,sha256=uRMe46PfDPUTeNInUO2Gbp4pVr-WIFIZQvrND2tovsg,1548
 iplotx/ingest/providers/tree/ete4.py,sha256=D7usSq0MOjzrk3EoLi834IlaDGwv7_qG6Qt0ptfKqfI,928
 iplotx/ingest/providers/tree/simple.py,sha256=aV9wGqBomJ5klM_aJQeuL_Q_J1pLCv6AFN98BPDiKUw,2593
 iplotx/ingest/providers/tree/skbio.py,sha256=O1KUr8tYi28pZ3VVjapgO4Uj-YpMuix3GhOH5je8Lv4,822
+iplotx/network/__init__.py,sha256=oEv6f8oFYrtcI_NKabr8a_oIWTc1jXXTl_yO1xox_rE,13575
+iplotx/network/groups.py,sha256=E_eYVXRHjv1DcyA4RupTkMa-rRFrIKkt9Rxn_Elw9Nc,6796
 iplotx/style/__init__.py,sha256=rf1GutrE8hHUhCoe4FGKYX-aNtHuu_U-kYQnqUxZNrY,10282
-iplotx/style/leaf_info.py,sha256=mcd6ewZl3jC0CPshmbeUkNp2geoihJW9515roGy2T8o,1000
+iplotx/style/leaf_info.py,sha256=3xBn7xv9Uy2KAqdhM9S6ew5ZBJrGRTXRL3xXb8atfLw,1018
 iplotx/style/library.py,sha256=58Y8BlllGLsR4pQM7_PVCP5tH6_4GkchXZvJpqGHlcg,8534
+iplotx/tree/__init__.py,sha256=6a8cbTd-OS-x8GEZJeRo3vneVjI98AiQW_gIo1H7h3Y,29969
+iplotx/tree/cascades.py,sha256=on5GyqbWasl1zgK7bYXYQE0LOSfHc1z-1hnm0GWd6aw,8184
+iplotx/tree/scalebar.py,sha256=QC2l-Nx39g8fkO1tHHvbrtzLncfQc9L57BQniSk2h5Q,11849
 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/matplotlib.py,sha256=p_53Oamof0RI4mtV8HrdDtZbgVqUxeUZ_KDvLZSiBUQ,8604
 iplotx/utils/style.py,sha256=vyNP80nDYVinqm6_9ltCJCtjK35ZcGlHvOskNv3eQBc,4225
-iplotx-0.11.1.dist-info/METADATA,sha256=1F0wH64PAw1_Bx-Qv7RSTgz6nwoQfcbRDJjmlR3KYfc,4880
-iplotx-0.11.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-iplotx-0.11.1.dist-info/RECORD,,
+iplotx-1.0.0.dist-info/METADATA,sha256=VsUs2_FiPrGNcfAfnL-T0fB9RObJCdAUvjaEUO46vFg,5086
+iplotx-1.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+iplotx-1.0.0.dist-info/RECORD,,