iplotx 0.11.1__py3-none-any.whl → 0.12.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/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

@@ -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/style/leaf_info.py

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

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__ = "0.12.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-0.12.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iplotx
-Version: 0.11.1
+Version: 0.12.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-0.12.0.dist-info}/RECORD

@@ -4,17 +4,17 @@ iplotx/cascades.py,sha256=OPqF7Huls-HFmDA5MCF6DEZlUeRVaXsbQcHBoKAgNJs,8182
 iplotx/groups.py,sha256=g6ahm61BSBmd2weIjr40MvPi_GcNRgvNb9YklQsiza4,6784
 iplotx/label.py,sha256=7eS8ByadrhdIFOZz19U4VrS-oXY_ndFYNB-D4RZbFqI,9573
 iplotx/layout.py,sha256=KxmRLqjo8AYCBAmXez8rIiLU2sM34qhb6ox9AHYwRyE,4839
-iplotx/network.py,sha256=ae5rZwzWxmcBQXx1Y0q24jaXcM1hT1kip-JKsyk11QY,13385
+iplotx/network.py,sha256=mhR1hwlLrATYJfCZUgk7sfmtw3yEjAE0TtE0b-1N8hE,13567
 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=BVfqBj50ae0jogJGXsQXi_fML0WjuC4GLFRHZQWawYY,67
-iplotx/vertex.py,sha256=bjvAy9UciPWkA1J-SroWF9ZaTXRzNKtDZXBlZ80VM60,16026
+iplotx/version.py,sha256=OAoDyBg_N0NwrLolwb2vnkue-AwN9sTDzRmDcTNfAog,67
+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 +27,17 @@ 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/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/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-0.12.0.dist-info/METADATA,sha256=OcfxvA_JL2GOXYH7_67iDL1N4_U3fDm7--3nXbUHKU8,5087
+iplotx-0.12.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+iplotx-0.12.0.dist-info/RECORD,,