iplotx 0.11.1__tar.gz → 1.0.0__tar.gz

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

@@ -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 → iplotx-1.0.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-1.0.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-1.0.0/docs/source/_static/custom.css

@@ -0,0 +1,5 @@
+/* Use full page width without sidebars */
+.bd-content {
+  max-width: 100%;
+  flex-grow: 1;
+}

{iplotx-0.11.1 → iplotx-1.0.0}/docs/source/api/artists.md

@@ -1,5 +1,5 @@
 # Artist hierarchy
-`iplotx.plot` return a list of `matplotlib` artists (1 or 2). When a network is plotted, the first artist is an instance of `iplotx.NetworkArtist`. This class contains the visual elements representing vertices, edges, labels, arrows, etc. and can be used to further edit the plot after `iplotx.plot` returned.
+`iplotx.network` return a list of `matplotlib` artists (1 or 2). When a network is plotted, the first artist is an instance of `iplotx.NetworkArtist`. This class contains the visual elements representing vertices, edges, labels, arrows, etc. and can be used to further edit the plot after `iplotx.plot` returned.
 
 A `NetworkArtist` instance has two notable properties: vertices and edges, which are instances of `VertexCollection` and `EdgeCollection`, respectively. These collections are `matplotlib` artists that can be used to modify the appearance of vertices and edges after the plot has been created.
 
@@ -9,7 +9,6 @@ In turn, a `VertexCollection` or `EdgeCollection` instance **may** contain a `La
 .. autoclass:: iplotx.network.NetworkArtist
     :members:
 
-
 .. autoclass:: iplotx.vertex.VertexCollection
     :members:
 
@@ -22,3 +21,16 @@ In turn, a `VertexCollection` or `EdgeCollection` instance **may** contain a `La
 .. autoclass:: iplotx.edge.arrow.EdgeArrowCollection
     :members:
 ```
+
+
+## 3D artists
+The {py:class}`iplotx.network.NetworkArtist` class is also used for 3D plots. In that case, the `VertexCollection` and `EdgeCollection` instances are substituted by the following:
+
+```{eval-rst}
+.. autoclass:: iplotx.art3d.vertex.Vertex3DCollection
+    :members:
+
+.. autoclass:: iplotx.art3d.edge.Edge3DCollection
+    :members:
+
+```

{iplotx-0.11.1 → iplotx-1.0.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-1.0.0/docs/source/api/plotting.md

@@ -0,0 +1,18 @@
+# Plotting API
+The main user-facing functions are:
+
+- `iplotx.network`to visualise networks/graphs and graph groupings (covers and clusterings)
+- `iplotx.tree` to visualise trees.
+
+```{tip}
+  `iplotx.plot` and `iplotx.graph` are synonyms for `iplotx.network`.
+```
+
+```{warning}
+  `iplotx.plot` is deprecated and will be removed in future versions. Please use `iplotx.network` instead.
+```
+
+```{eval-rst}
+.. autofunction:: iplotx.network
+
+.. autofunction:: iplotx.tree

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

@@ -44,7 +44,10 @@ napoleon_preprocess_types = False
 napoleon_type_aliases = None
 napoleon_attr_annotations = True
 
-myst_enable_extensions = ["colon_fence"]
+myst_enable_extensions = [
+    "colon_fence",
+    "attrs_inline",
+]
 
 sphinx_gallery_conf = {
     "examples_dirs": "../../gallery",  # path to your example scripts
@@ -67,8 +70,35 @@ 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_css_files = ["_static/custom.css"]
+html_js_files = [
+    ("custom-icons.js", {"defer": "defer"}),
+]
+html_sidebars = {"**": []}
+
+
+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",
+        },
+    ],
+    "secondary_sidebar_items": {
+        "**": ["page-toc", "sourcelink"],
+        "index": [],
+    },
+}
 
 # -----------------------------------------------------------------------------
 # Source code links (credit to the matplotlib project for this part)

iplotx-1.0.0/docs/source/index.md

@@ -0,0 +1,39 @@
+# iplotx documentation
+
+```{grid} 4
+:gutter: 1
+
+  :::{grid-item}
+    [![ex1](./_images/sphx_glr_plot_edit_artists_001.png)](gallery/style/plot_ports.rst)
+  :::
+  :::{grid-item}
+    [![ex2](./_images/sphx_glr_plot_animation_thumb.gif)](gallery/other/plot_animation.rst)
+  :::
+  :::{grid-item}
+    [![ex3](./_images/sphx_glr_plot_3d_thumb.png)](gallery/basic/plot_3d.rst)
+  :::
+  :::{grid-item}
+    [![ex4](./_images/sphx_glr_plot_tree_node_background_thumb.png)](gallery/tree/plot_tree_node_background.rst)
+  :::
+```
+
+[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. It can also plot networks and trees from simple, pure Python data structures for zero-dependency visualisation.
+
+`iplotx` guarantees the **exact same visual appearance** independently of what library you used to construct the network/tree.
+
+```{toctree}
+:maxdepth: 1
+:titlesonly:
+:hidden:
+
+installing
+gallery/index
+style
+API <api>
+Complete style specification <api/complete_style_specification>
+Data providers <providers>
+Plotting API <api/plotting>
+Style API <api/style>
+Artist hierarchy <api/artists>
+Data provider protocols <api/providers>
+```

iplotx-0.11.1/docs/source/index.md → iplotx-1.0.0/docs/source/installing.md

@@ -1,10 +1,4 @@
-# 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` guarantees the **exact same visual appearance** independently of what library you used to construct the network/tree.
-
-## Installation
+# Installing
 ```
 pip install iplotx
 ```
@@ -54,12 +48,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 +65,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 +99,11 @@ 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.
 
-```{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>
-Artist hierarchy <api/artists>
-Data provider protocols <api/providers>
+## 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!
 ```

{iplotx-0.11.1 → iplotx-1.0.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-1.0.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.497** total execution time for 76 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_scalebar.py` (``../../gallery/tree/plot_scalebar.py``)
+     - 00:00.497
      - 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
@@ -212,6 +218,9 @@ Computation times
    * - :ref:`sphx_glr_gallery_tree_plot_cogent3_tree.py` (``../../gallery/tree/plot_cogent3_tree.py``)
      - 00:00.000
      - 0.0
+   * - :ref:`sphx_glr_gallery_tree_plot_dendropy.py` (``../../gallery/tree/plot_dendropy.py``)
+     - 00:00.000
+     - 0.0
    * - :ref:`sphx_glr_gallery_tree_plot_elements_tree.py` (``../../gallery/tree/plot_elements_tree.py``)
      - 00:00.000
      - 0.0

{iplotx-0.11.1 → iplotx-1.0.0}/docs/source/style.md

@@ -1,8 +1,8 @@
 # Styles
-Network plots can be customised using styles.
+Visualisations can be customised using styles.
 
 ## What is a style?
-Formally, a style is a **nested dictionary** specifying the visual properties of each graph element. The three top-level keys for a style dictionary are `vertex`, `edge`, and `grouping`. A typical style specification looks like this:
+Formally, a style is a **nested dictionary** specifying the visual properties of each graph element. The main top-level keys for a style dictionary are `vertex` and `edge`. A typical style specification looks like this:
 
 ```python
 mystyle = {
@@ -19,6 +19,7 @@ mystyle = {
 }
 ```
 
+Additional top-level keys exist for networks (e.g. `grouping`) and trees (e.g. `leaf`, `clade`, `internal`). The complete style specification is documented in the [API reference](api/complete_style_specification.md).
 
 `iplotx` has a default style that you can inspect as follows:
 
@@ -30,11 +31,10 @@ print(default_style)
 When a custom style is specified for a plot, it is applied **on top of** the current style, which is usually the default style.
 
 ```{warning}
-  Multiple styling at once might be necessary. For example, the default style has white labels onto black vertex faces. If you want to have white vertices,
-  you should also at the same time specify another color (e.g. black) for the labels, otherwise labels will be drawn white on white and therefore invisible.
+  The default style has black vertices with white vertex labels. If you change the vertex face color, you might want to change the vertex label color as well to ensure readability.
 ```
 
-`iplotx` also has a dictionary of predefined styles to serve as basis in different contexts. You can access these styles as follows:
+`iplotx` also has an internal [library of styles](gallery/style/plot_multistyle.rst) to serve as basis in different contexts. You can access these styles as follows:
 
 ```python
 from iplotx.style import styles
@@ -44,14 +44,14 @@ print(styles)
 For example, the `hollow` style uses vertices with no face color, black edges, black vertex labels, square vertices, and autosizes vertices to fit their text labels. This style is designed to be useful when label boxes are important to visualise the graph (e.g. company tree structures, or block-type diagrams).
 
 ## Applying styles
-There are a few different ways to use a style in `iplotx` (the mechanism is similar to styles in `matplotlib`).
+There are a few different ways to use a style in `iplotx` (the mechanism is similar to styles in `Matplotlib`).
 
-### Function argument
-To apply a style to a single plot, you can pass it to the `iplotx.plot` function as a keyword argument:
+### Single function calls
+To apply a style to a single plot, you can pass it to the {func}`.network` and {func}`.tree` functions as a keyword argument:
 
 ```python
 import iplotx as ipx
-ipx.plot(
+ipx.network(
   ...,
   style={
     "vertex": {'size': 20},
@@ -59,52 +59,29 @@ ipx.plot(
 )
 ```
 
-In addition to the method above, the `iplotx.plot` function accepts an additional syntax for styles, which is similar to how plotting styles work in `networkx` and `igraph`. You can specify each style change as a keyword argument, with underscores `_` used to mean a subdictionary. For instance, you can specify to have vertices with a red face and size 30 as follows:
+These functions also accept individual element styling via keyword arguments, with underscores `_` meant for splitting levels. For instance, you can specify to have vertices with a red face and size 30 as follows:
 
 ```python
-ipx.plot(
+ipx.network(
     ...,
     vertex_facecolor="red",
     vertex_size=30,
 )
 ```
 
-If both `style` and these custom arguments are used in the function, styles are applied first and these additional arguments are applied at the end.
-
-````{important}
-  This last syntax is designed to make short but deep style specifications easier. For instance, to change the background of edge labels to green, you can do:
-
-  ```python
-  ipx.plot(
-      ...,
-      edge_label_bbox_facecolor="grey",
-  )
-  ```
-
-  which is more readable than the equivalent style dictionary:
-  ```python
-  ipx.plot(
-      ...,
-      style={'edge': {'label': {'bbox': {'facecolor': "grey"}}}},
-  )
-  ```
-  However, they can become confusing if many details of the same element are styled at once. Do not do the following:
-  ```python
-  iplotx.plot(
-      ...,
-      vertex_size=20,
-      vertex_facecolor="red",
-      vertex_edgecolor="grey",
-      vertex_linewidth=2,
-      vertex_marker="d",
-      vertex_label_color="black",
-  )
-  ```
-  It is correct syntax, but obviously not very readable; use a dictionary instead.
-````
-
-### Style context
-If you want a style to be applied beyond a single function call, you can use a style context:
+If both `style` and these custom arguments are used in the function, styles are applied first and individual keyword arguments are applied at the end, e.g.:
+
+```python
+ipx.network(
+    ...,
+    style="unicorn",
+    vertex_facecolor="red",
+    vertex_size=30,
+)
+```
+
+### Style contexts
+If you want a style to be applied beyond a single function call, you can use a {func}`.style.context`:
 
 ```python
 import iplotx as ipx
@@ -114,17 +91,17 @@ with iplotx.style.context(
     }
 ):
     # First plot uses this style
-    ipx.plot(...)
+    ipx.network(...)
     # Second plot ALSO uses the same style
-    ipx.plot(...)
+    ipx.network(...)
 ```
 
 ```{note}
   You can also pass the same `style` argument to all functions instead. Both achieve the same effect in practice, though the context is slightly more Pythonic.
 ```
 
-### Permanent style
-To apply a style permanently (in this Python session), you can use the `iplotx.style.use` function:
+### Permanent styles
+To apply a style permanently (in this Python session), you can use the {func}`.style.use` function:
 
 ```python
 import iplotx as ipx
@@ -142,32 +119,34 @@ To specify a predefined style, you can just use its name as a string:
 ipx.style.use("hollow")
 ```
 
-### Chaining styles
-All style specifications can include one style (as shown in the examples above) or a list of styles, which will be applied in order on top of the current style (usually default). For instance, to use a hollow style customised to have red edges, you can do:
+## Reverting to default style
+To reset `iplotx`'s style to the default one, you can use the {func}`.style.reset` function:
+
+```python
+ipx.style.reset()
+```
+
+## Chaining styles
+All three style specifications methods accept both a single style or a list of styles. Multiple styles, if present, are applied in order on top of the current style (usually default). For instance, to use a hollow style customised to have red edges, you can do:
 
 ```python
 with iplotx.style.context([
     "hollow",
     {"edge": {"color": "red"}},
 ]):
-    ipx.plot(...)
+    ipx.network(...)
 ```
 
 This will take the current style (usually default), apply the "hollow" style on top, and then apply the red edge color on top of that. The style will revert when the context exists.
 
 ```{note}
-  The same works for the `iplotx.plot` function, where you can pass a list of styles as the `style` argument.
+  The same works for the {func}`.network` and {func}`.tree` functions, where you can pass a list of styles as the `style` argument.
 ```
 
-### Rotating style leaves
+## Rotating style leaves
 All properties listed in the default style can be modified.
 
-When **leaf properties** are set as list-like objects, they are applied to the graph elements in a cyclic manner (a similar mechanism is in place in `matplotlib` and `seaborn` for color palettes). For example, if you set `facecolor` to `["red", "blue"]`, the first vertex will be red, the second blue, the third red, and so on. This is called **style leaf rotation**.
-
-To see all leaf properties, you can type:
-```python
-print(ipx.styles.style_leaves)
-```
+When **leaf properties** are set as list-like objects, they are applied to the graph elements in a cyclic manner (a similar mechanism is in place in `Matplotlib` and `seaborn` for color palettes). For example, if you set `facecolor` to `["red", "blue"]`, the first vertex will be red, the second blue, the third red, and so on. This is called **style leaf rotation**.
 
 Style leaves can be rotated also using a dictionary instead of a list. In that case, vertex and/or edge IDs are used to match each element to their appearance. Here's an example:
 
@@ -176,10 +155,30 @@ import networkx as nx
 import iplotx as ipx
 
 G = nx.Graph([(0, 1)])
-ipx.plot(
+ipx.network(
     G,
     vertex_size={0: 20, 1: 30},
 )
 ```
 
-This is likely to be useful when plotting objects from `networkx`, which used nested dictionaries to store graph/vertex/edge properties.
+These dictionaries (or dict-like, e.g. `defaultdict`) can be partial, i.e. only specify a custom styling for some elements within a class (e.g. vertex color). The current style will be applied as fallback for elements not specified in the dictionary.
+
+```{note}
+  When using dictionaries for style leaves, make sure that the keys match the vertex/edge IDs exactly. For instance, if your graph has string vertex IDs, using integers as keys might not work.
+```
+
+
+To see all leaf properties, you can type:
+
+```python
+print(ipx.styles.style_leaves)
+```
+
+To see properties that *cannot* be rotated, you can type:
+
+```python
+print(ipx.styles.nonrotating_leaves)
+```
+
+
+Please open a [GitHub issue](https://github.com/fabilab/iplotx/issues) if you would like a property listed in `nonrotating_leaves` to be rotated.