iplotx 0.11.1__tar.gz → 0.12.0__tar.gz

{iplotx-0.11.1 → iplotx-0.12.0}/PKG-INFO

@@ -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 → iplotx-0.12.0}/README.md

@@ -15,13 +15,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.
 
@@ -52,15 +53,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.12.0/docs/source/_static/custom-icons.js

@@ -0,0 +1,30 @@
+FontAwesome.library.add(
+  /**
+   * Custom icon definitions
+   *
+   * see https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/header-links.html#svg-image-icons
+   */
+  {
+    prefix: "fa-custom",
+    iconName: "pypi",
+    icon: [
+      17.313,
+      19.807,
+      [],
+      "e001",
+      // https://simpleicons.org/icons/pypi.svg
+      "m10.383 0.2-3.239 1.1769 3.1883 1.1614 3.239-1.1798zm-3.4152 1.2411-3.2362 1.1769 3.1855 1.1614 3.2369-1.1769zm6.7177 0.00281-3.2947 1.2009v3.8254l3.2947-1.1988zm-3.4145 1.2439-3.2926 1.1981v3.8254l0.17548-0.064132 3.1171-1.1347zm-6.6564 0.018325v3.8247l3.244 1.1805v-3.8254zm10.191 0.20931v2.3137l3.1777-1.1558zm3.2947 1.2425-3.2947 1.1988v3.8254l3.2947-1.1988zm-8.7058 0.45739c0.00929-1.931e-4 0.018327-2.977e-4 0.027485 0 0.25633 0.00851 0.4263 0.20713 0.42638 0.49826 1.953e-4 0.38532-0.29327 0.80469-0.65542 0.93662-0.36226 0.13215-0.65608-0.073306-0.65613-0.4588-6.28e-5 -0.38556 0.2938-0.80504 0.65613-0.93662 0.068422-0.024919 0.13655-0.038114 0.20156-0.039466zm5.2913 0.78369-3.2947 1.1988v3.8247l3.2947-1.1981zm-10.132 1.239-3.2362 1.1769 3.1883 1.1614 3.2362-1.1769zm6.7177 0.00213-3.2926 1.2016v3.8247l3.2926-1.2009zm-3.4124 1.2439-3.2947 1.1988v3.8254l3.2947-1.1988zm-6.6585 0.016195v3.8275l3.244 1.1805v-3.8254zm16.9 0.21143-3.2947 1.1988v3.8247l3.2947-1.1981zm-3.4145 1.2411-3.2926 1.2016v3.8247l3.2926-1.2009zm-3.4145 1.2411-3.2926 1.2016v3.8247l3.2926-1.2009zm-3.4124 1.2432-3.2947 1.1988v3.8254l3.2947-1.1988zm-6.6585 0.019027v3.8247l3.244 1.1805v-3.8254zm13.485 1.4497-3.2947 1.1988v3.8247l3.2947-1.1981zm-3.4145 1.2411-3.2926 1.2016v3.8247l3.2926-1.2009zm2.4018 0.38127c0.0093-1.83e-4 0.01833-3.16e-4 0.02749 0 0.25633 0.0085 0.4263 0.20713 0.42638 0.49826 1.97e-4 0.38532-0.29327 0.80469-0.65542 0.93662-0.36188 0.1316-0.65525-0.07375-0.65542-0.4588-1.95e-4 -0.38532 0.29328-0.80469 0.65542-0.93662 0.06842-0.02494 0.13655-0.03819 0.20156-0.03947zm-5.8142 0.86403-3.244 1.1805v1.4201l3.244 1.1805z",
+    ],
+  },
+  {
+    prefix: "fa-custom",
+    iconName: "pydata",
+    icon: [
+      24,
+      24,
+      [],
+      "e002",
+      "M12.1,17.8v5.8l-5-2.9v-5.8L12.1,17.8z M12.1,12v5.8l-5-2.9V9.1L12.1,12z M17,9.1L12.1,12v5.8l4.9-2.9V9.1z M12.1,6.2L7,9.1l5,2.9L17,9.1L12.1,6.2z M17,9.1V3.3l-4.9-2.8v5.8L17,9.1z",
+    ],
+  },
+);

{iplotx-0.11.1 → iplotx-0.12.0}/docs/source/api/complete_style_specification.md

@@ -37,6 +37,8 @@
         "edgecolor": str | Any,  # Color of the vertex edge (e.g. 'black', '#000000')
         "alpha": float,  # Opacity of the vertex (0.0 for fully transparent, 1.0 for fully opaque)
 
+        "depthshade": bool,  # Whether to shade the color based on depth (3D only)
+
         # Vertex label style
         "label": {
             "color": str | Any,  # Color of the vertex label (e.g. 'white', '#FFFFFF')
@@ -91,11 +93,13 @@
         # onto what color.
         "norm": tuple[float, float] | matplotlib.colors.Normalize,
 
-        # Opacity of the vertex (0.0 for fully transparent, 1.0 for fully opaque).
+        # Opacity of the edge (0.0 for fully transparent, 1.0 for fully opaque).
         # If a colormap is used and this option is also set, this opacity takes
         # priority and finally determines the transparency of the edges.
         "alpha": float,
 
+        "depthshade": bool,  # Whether to shade the color based on depth (3D only)
+
         "curved": bool,  # Whether the edge is curved (True) or straight (False)
 
         # Tension for curved edges (0.0 for straight, higher values position the
@@ -189,7 +193,7 @@
             # unintuitive and interpret it the other way around, so think carefully.
             "rotate": bool,
 
-            "color": str | Any,  # Color of the vertex label (e.g. 'white', '#FFFFFF')
+            "color": str | Any,  # Color of the edge label (e.g. 'white', '#FFFFFF')
             "horizontalalignment": str,  # Horizontal alignment of the label ('left', 'center', 'right')
             "verticalalignment": str,  # Vertical alignment of the label ('top', 'center', 'bottom', 'baseline', 'center_baseline')
             "hpadding": float,  # Horizontal padding around the label

{iplotx-0.11.1 → iplotx-0.12.0}/docs/source/conf.py

@@ -67,8 +67,28 @@ exclude_patterns = []
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = "sphinx_rtd_theme"
+html_theme = "pydata_sphinx_theme"
 html_static_path = ["_static"]
+html_js_files = [
+    ("custom-icons.js", {"defer": "defer"}),
+]
+
+html_theme_options = {
+    "header_links_before_dropdown": 4,
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/fabilab/iplotx",
+            "icon": "fa-brands fa-github",
+            "type": "fontawesome",
+        },
+        {
+            "name": "PyPI",
+            "url": "https://pypi.org/project/iplotx",
+            "icon": "fa-custom fa-pypi",
+        },
+    ],
+}
 
 # -----------------------------------------------------------------------------
 # Source code links (credit to the matplotlib project for this part)

{iplotx-0.11.1 → iplotx-0.12.0}/docs/source/index.md

@@ -1,6 +1,6 @@
 # iplotx documentation
 
-`iplotx` is a Python library to display graphs, networks and trees using `matplotlib` as a backend. It supports multiple network analysis libraries including `networkx` and `igraph` for networks and `biopython`, `scikit-bio`, `cogent3`, and `ete4` for trees.
+[iplotx](https://github.com/fabilab/iplotx) is a Python library to display graphs/networks and trees with [matplotlib](https://matplotlib.org/). It natively supports [networkx](https://networkx.org/) and [igraph](https://python.igraph.org/) networks and [biopython](https://biopython.org/), [scikit-bio](https://scikit.bio/), [cogent3](https://cogent3.org/), [ETE4](https://etetoolkit.github.io/ete/), and [dendropy](https://jeetsukumaran.github.io/DendroPy/index.html) trees.
 
 `iplotx` guarantees the **exact same visual appearance** independently of what library you used to construct the network/tree.
 
@@ -54,12 +54,6 @@ Either way, the result is the same:
 See <project:gallery/index.rst> for examples of plots made with `iplotx`. Feel free to suggest new examples on GitHub by opening a new issue or pull request!
 
 ## Features
-```{important}
-    If you are the maintainer of a network/graph/tree analysis library and would like
-    to propose improvements or see support for it, please reach out with an issue/PR
-    on GitHub!
-```
-
 `iplotx`'s features' include:
 - per-edge and per-vertex styling using sequences or dictionaries
 - labels
@@ -77,12 +71,13 @@ See <project:gallery/index.rst> for examples of plots made with `iplotx`. Feel f
 - correct HiDPI scaling (e.g. retina screens) including for vertex sizes, arrow sizes, and edge offsets
 - a consistent `matplotlib` artist hierarchy
 - post-plot editability (e.g. for animations)
-- plays well with other charting tools (e.g. `seaborn`)
+- interoperability with other charting tools (e.g. `seaborn`)
 - chainable style contexts
 - vertex clusterings and covers with convex hulls and rounding
-- a plugin mechanism for additional libraries (WIP)
-- animations (see <project:gallery/plot_animation.rst>)
-- mouse/keyboard interaction and events (e.g. hover, click, see <project:gallery/plot_mouse_hover.rst>)
+- a plugin mechanism for additional libraries
+- animations (see <project:gallery/other/plot_animation.rst>)
+- 3D visualisations
+- mouse/keyboard interaction and events (e.g. hover, click, see <project:gallery/other/plot_mouse_hover.rst>)
 - ... and probably more by the time you read this.
 
 ## Styles
@@ -110,17 +105,25 @@ See <project:api.md> for reference documentation of all functions and classes in
 ## Rationale
 We believe graph **analysis**, graph **layouting**, and graph **visualisation** to be three separate tasks. `iplotx` currently focuses on visualisation. It can also compute simple tree layouts and might expand towards network layouts in the future.
 
+## Contributing
+Open an [issue on GitHub](https://github.com/fabilab/iplotx/issues) to request features, report bugs, or show intention in contributing. Pull requests are very welcome.
+
+```{important}
+  If you are the maintainer of a network/graph/tree analysis library and would like
+  to propose improvements or see support for it, please reach out with an issue/PR
+  on GitHub!
+```
+
+## Sitemap
 ```{toctree}
 :maxdepth: 2
 :caption: Contents
 
 gallery/index
 style
-Data providers <providers>
 API <api>
-Plotting API <api/plotting>
-Styling API <api/style>
 Complete style specification <api/complete_style_specification>
+Data providers <providers>
 Artist hierarchy <api/artists>
 Data provider protocols <api/providers>
 ```

{iplotx-0.11.1 → iplotx-0.12.0}/docs/source/providers.md

@@ -51,7 +51,7 @@ A straightforward `NetworkDataProvider` implementation for this network data str
     )
 ```
 
-See <project:gallery/plot_simpledataprovider.md> for the full gallery example including vertex labels and styling.
+See <project:gallery/zero_dependencies/plot_simpledataprovider.md> for the full gallery example including vertex labels and styling.
 
 ```{tip}
   This example also shows how to use `iplotx` without installing any network analysis

{iplotx-0.11.1 → iplotx-0.12.0}/docs/source/sg_execution_times.rst

@@ -6,7 +6,7 @@
 
 Computation times
 =================
-**00:00.095** total execution time for 73 files **from all galleries**:
+**00:00.525** total execution time for 75 files **from all galleries**:
 
 .. container::
 
@@ -32,8 +32,8 @@ Computation times
    * - Example
      - Time
      - Mem (MB)
-   * - :ref:`sphx_glr_gallery_basic_plot_grouping.py` (``../../gallery/basic/plot_grouping.py``)
-     - 00:00.095
+   * - :ref:`sphx_glr_gallery_tree_plot_dendropy.py` (``../../gallery/tree/plot_dendropy.py``)
+     - 00:00.525
      - 0.0
    * - :ref:`sphx_glr_gallery_basic_plot_3d.py` (``../../gallery/basic/plot_3d.py``)
      - 00:00.000
@@ -50,6 +50,9 @@ Computation times
    * - :ref:`sphx_glr_gallery_basic_plot_directed.py` (``../../gallery/basic/plot_directed.py``)
      - 00:00.000
      - 0.0
+   * - :ref:`sphx_glr_gallery_basic_plot_grouping.py` (``../../gallery/basic/plot_grouping.py``)
+     - 00:00.000
+     - 0.0
    * - :ref:`sphx_glr_gallery_basic_plot_house.py` (``../../gallery/basic/plot_house.py``)
      - 00:00.000
      - 0.0
@@ -164,6 +167,9 @@ Computation times
    * - :ref:`sphx_glr_gallery_style_plot_arrows.py` (``../../gallery/style/plot_arrows.py``)
      - 00:00.000
      - 0.0
+   * - :ref:`sphx_glr_gallery_style_plot_depthshade.py` (``../../gallery/style/plot_depthshade.py``)
+     - 00:00.000
+     - 0.0
    * - :ref:`sphx_glr_gallery_style_plot_edgepadding.py` (``../../gallery/style/plot_edgepadding.py``)
      - 00:00.000
      - 0.0

{iplotx-0.11.1 → iplotx-0.12.0}/gallery/basic/plot_grouping.py

@@ -63,6 +63,11 @@ plt.gca().set_aspect(1.0)
 #
 # This can also be achieved with two separate calls, the first one to draw the network and the second to draw the grouping.
 
+import igraph as ig
+import matplotlib.pyplot as plt
+import iplotx as ipx
+
+g = ig.Graph.Ring(8)
 layout = g.layout("circle")
 fig, ax = plt.subplots(figsize=(5, 5))
 ipx.network(

iplotx-0.12.0/gallery/style/plot_depthshade.py

@@ -0,0 +1,46 @@
+"""
+3D depth shading
+================
+
+This example shows to to use depth shading in 3D plots to reduce the opacity (increase transparency) of
+vertices and edges that are further away from the viewer. This gives a better sense of depth but can be
+confusing in some cases, so there are style options to turn it off.
+"""
+
+import igraph as ig
+import iplotx as ipx
+
+g = ig.Graph.Erdos_Renyi(15, m=20)
+
+layout = g.layout_fruchterman_reingold_3d()
+
+ipx.network(
+    g,
+    layout,
+    vertex_alpha=0.9,
+    figsize=(8, 8),
+)
+
+# %%
+# Notice that depth shading is a 0-1 multiplier on top of the existing alpha value, so no vertex will have
+# alpha (opacity) greater than 0.9 in this example, but vertices that are further back will have values
+# below 0.9 (the minimum is usually 0.1).
+#
+# .. tip::
+#   To get a better sense of depth shading, use Matplotlib with an interactive backend and rotate the
+#   plot using the mouse.
+#
+# You can turn off depth shading by setting ``depthshade=False`` for vertices and/or edges:
+
+ipx.network(
+    g,
+    layout,
+    vertex_alpha=0.9,
+    figsize=(8, 8),
+    vertex_depthshade=False,
+    edge_depthshade=False,
+)
+
+# %%
+# In this case all vertices have the same opacity (0.9) regardless of their depth, and all edges have an
+# opacity of 1.0 (no transparency).

iplotx-0.12.0/gallery/tree/plot_dendropy.py

@@ -0,0 +1,50 @@
+"""
+Dendropy tree
+=============
+
+This example shows how to use ``iplotx`` to plot trees from ``dendropy``.
+"""
+
+from dendropy import Tree
+import iplotx as ipx
+
+tree = Tree.get(data="((,(,((,),(,)))));", schema="newick")
+
+ipx.plotting.tree(
+    tree,
+    aspect=1,
+    edge_color="grey",
+    edge_linestyle=["--", "-"],
+)
+
+# %%
+# `iplotx` can compute a radial tree layout as well, and usual style modifications
+# work for trees same as networks.
+
+# sphinx_gallery_thumbnail_number = 2
+ipx.plotting.tree(
+    tree,
+    layout="radial",
+    layout_orientation="right",
+    style=[
+        "tree",
+        {
+            "edge": {
+                "color": "navy",
+                "linewidth": 4,
+            },
+            "leaf": {
+                "label": {
+                    "hmargin": 15,
+                }
+            },
+            "leafedge": {
+                "color": "steelblue",
+                "linewidth": 2,
+            },
+        },
+    ],
+    leaf_labels={leaf: str(i + 1) for i, leaf in enumerate(tree.leaf_nodes())},
+    aspect=1,
+    margin=(0.3, 0.1),
+)

{iplotx-0.11.1 → iplotx-0.12.0}/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-0.11.1 → iplotx-0.12.0}/iplotx/edge/__init__.py

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

iplotx-0.12.0/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