iplotx 0.12.0__tar.gz → 1.0.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iplotx
-Version: 0.12.0
+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

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.12.0 → 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-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.12.0 → 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
@@ -69,9 +72,12 @@ exclude_patterns = []
 
 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,
@@ -88,6 +94,10 @@ html_theme_options = {
             "icon": "fa-custom fa-pypi",
         },
     ],
+    "secondary_sidebar_items": {
+        "**": ["page-toc", "sourcelink"],
+        "index": [],
+    },
 }
 
 # -----------------------------------------------------------------------------

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.12.0/docs/source/index.md → iplotx-1.0.0/docs/source/installing.md

@@ -1,10 +1,4 @@
-# iplotx documentation
-
-[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.
-
-## Installation
+# Installing
 ```
 pip install iplotx
 ```
@@ -113,17 +107,3 @@ Open an [issue on GitHub](https://github.com/fabilab/iplotx/issues) to request f
   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
-API <api>
-Complete style specification <api/complete_style_specification>
-Data providers <providers>
-Artist hierarchy <api/artists>
-Data provider protocols <api/providers>
-```

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

@@ -6,7 +6,7 @@
 
 Computation times
 =================
-**00:00.525** total execution time for 75 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_tree_plot_dendropy.py` (``../../gallery/tree/plot_dendropy.py``)
-     - 00:00.525
+   * - :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
@@ -218,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.12.0 → 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.

iplotx-1.0.0/gallery/GALLERY_HEADER.rst

@@ -0,0 +1,2 @@
+Gallery
+=======

iplotx-1.0.0/gallery/basic/GALLERY_HEADER.rst

@@ -0,0 +1,2 @@
+Basic
++++++

iplotx-1.0.0/gallery/biology/GALLERY_HEADER.rst

@@ -0,0 +1,2 @@
+Biology and Ecology
++++++++++++++++++++

iplotx-1.0.0/gallery/network_science/GALLERY_HEADER.rst

@@ -0,0 +1,2 @@
+Network science
++++++++++++++++

iplotx-1.0.0/gallery/other/GALLERY_HEADER.rst

@@ -0,0 +1,2 @@
+Other
++++++

iplotx-1.0.0/gallery/style/GALLERY_HEADER.rst

@@ -0,0 +1,2 @@
+Style
++++++

iplotx-1.0.0/gallery/tree/GALLERY_HEADER.rst

@@ -0,0 +1,2 @@
+Trees
++++++

iplotx-1.0.0/gallery/tree/plot_scalebar.py

@@ -0,0 +1,19 @@
+"""
+Scale bar
+=========
+
+This example shows how to add a scale bar to an ``iplotx`` tree.
+"""
+
+from dendropy import Tree
+import iplotx as ipx
+
+tree = Tree.get(data="((,(,((,),(,)))));", schema="newick")
+
+tree_artist = ipx.plotting.tree(
+    tree,
+    edge_color="grey",
+)
+tree_artist.scalebar(
+    loc="upper left",
+)

{iplotx-0.12.0 → iplotx-1.0.0}/gallery/tree/plot_split_edges.py

@@ -3,7 +3,7 @@ Split edges
 ===========
 
 This example shows how to use split edges, i.e. how to apply different styles to
-tree edges that are composed of multiple segments. See also :doc:`plot_simpletreedataprovider`
+tree edges that are composed of multiple segments. See also :doc:`../zero_dependency/plot_simpletreedataprovider`
 for the basic example of how to plot a tree with ``iplotx``'s internal tree representation.
 
 .. note::

iplotx-1.0.0/gallery/zero_dependency/GALLERY_HEADER.rst

@@ -0,0 +1,2 @@
+Zero-dependency
++++++++++++++++

{iplotx-0.12.0 → iplotx-1.0.0}/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-0.12.0/iplotx/network.py → iplotx-1.0.0/iplotx/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,
 )

{iplotx-0.12.0/iplotx → iplotx-1.0.0/iplotx/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-0.12.0 → iplotx-1.0.0}/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,