iplotx 1.1.0__tar.gz → 1.2.1__tar.gz

{iplotx-1.1.0 → iplotx-1.2.1}/.github/workflows/test.yml

@@ -12,7 +12,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
 
     steps:
     - uses: actions/checkout@v5

{iplotx-1.1.0 → iplotx-1.2.1}/.gitignore

@@ -179,3 +179,7 @@ cython_debug/
 
 # PyPI configuration file
 .pypirc
+
+# vim backup files
+*.swp
+*.swo

{iplotx-1.1.0 → iplotx-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iplotx
-Version: 1.1.0
+Version: 1.2.1
 Summary: Plot networkx from igraph and networkx.
 Project-URL: Homepage, https://github.com/fabilab/iplotx
 Project-URL: Documentation, https://readthedocs.org/iplotx
@@ -26,8 +26,8 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Visualization
 Classifier: Topic :: System :: Networking
 Classifier: Typing :: Typed
-Requires-Python: >=3.11
-Requires-Dist: matplotlib>=2.0.0
+Requires-Python: >=3.10
+Requires-Dist: matplotlib>=3.10.0
 Requires-Dist: numpy>=2.0.0
 Requires-Dist: pandas>=2.0.0
 Provides-Extra: igraph
@@ -78,8 +78,7 @@ import iplotx as ipx
 
 g = nx.Graph([(0, 1), (1, 2), (2, 3), (3, 4), (4, 0)])
 layout = nx.layout.circular_layout(g)
-fig, ax = plt.subplots(figsize=(3, 3))
-ipx.plot(g, ax=ax, layout=layout)
+ipx.plot(g, layout)
 ```
 
 ![Quick start image](/docs/source/_static/graph_basic.png)

{iplotx-1.1.0 → iplotx-1.2.1}/README.md

@@ -40,8 +40,7 @@ import iplotx as ipx
 
 g = nx.Graph([(0, 1), (1, 2), (2, 3), (3, 4), (4, 0)])
 layout = nx.layout.circular_layout(g)
-fig, ax = plt.subplots(figsize=(3, 3))
-ipx.plot(g, ax=ax, layout=layout)
+ipx.plot(g, layout)
 ```
 
 ![Quick start image](/docs/source/_static/graph_basic.png)

{iplotx-1.1.0 → iplotx-1.2.1}/docs/source/api/complete_style_specification.md

@@ -274,8 +274,15 @@
         # - "radial" layout: "clockwise" or "counterclockwise"
         "orientation": str,
         "angular": bool,  # Whether to use an angular or waypoint-based layout
-        "start": float,  # Starting angle for radial layouts (in degrees)
-        "span": float,  # Angle span for radial layouts (in degrees)
+        # The following two parameters are used differently depending on the layout.
+        # For radial layouts:
+        #   start: Starting angle (in degrees, one float)
+        #   span: Angle span (in degrees)
+        # For horizontal and vertical layouts:
+        #   start: Starting position in data units (tuple of two floats)
+        #   span: Breadth in data units (float)
+        "start": float | tuple[float, float],
+        "span": float,
     },
     ############################################################################
 }

iplotx-1.2.1/docs/source/code_of_conduct.rst

@@ -0,0 +1,145 @@
+.. _scipy-coc:
+
+ilpotx Code of Conduct
+======================
+
+
+Introduction
+------------
+
+This code of conduct applies to all spaces managed by the iplotx project,
+including all public and private mailing lists, issue trackers, wikis, blogs,
+and any other communication channel used by our community. The iplotx
+project does not organize in-person events, however, events related to our
+community should have a code of conduct similar in spirit to this one.
+
+This code of conduct should be honored by everyone who participates in
+the iplotx community formally or informally, or claims any affiliation with the
+project, in any project-related activities, and, especially, when representing the
+project, in any role.
+
+This code is neither exhaustive nor complete. It serves to distill our common
+understanding of a collaborative, shared environment and goals. Please try to
+follow this code in spirit as much as in letter, to create a friendly and
+productive environment that enriches the surrounding community.
+
+
+Specific guidelines
+-------------------
+
+We strive to:
+
+1. Be open. We invite anyone to participate in our community. We prefer to use
+   public methods of communication for project-related messages, unless
+   discussing something sensitive. This applies to messages for help or
+   project-related support, too; not only is a public-support request much more
+   likely to result in an answer to a question, it also ensures that any
+   inadvertent mistakes in answering are more easily detected and corrected.
+
+2. Be empathetic, welcoming, friendly, and patient. We work together to resolve
+   conflict, and assume good intentions. We may all experience some frustration
+   from time to time, but we do not allow frustration to turn into a personal
+   attack. A community where people feel uncomfortable or threatened is not a
+   productive one.
+
+3. Be collaborative. Our work will be used by other people, and in turn we will
+   depend on the work of others. When we make something for the benefit of the
+   project, we are willing to explain to others how it works, so that they can
+   build on the work to make it even better. Any decision we make will affect
+   users and colleagues, and we take those consequences seriously when making
+   decisions.
+
+4. Be inquisitive. Nobody knows everything! Asking questions early avoids many
+   problems later, so we encourage questions, although we may direct them to
+   the appropriate forum. We will try hard to be responsive and helpful.
+
+5. Be careful in the words that we choose. We are careful and respectful in
+   our communication and we take responsibility for our own speech. Be kind to
+   others. Do not insult or put down other participants. We will not accept
+   harassment or other exclusionary behavior, such as:
+
+  - Violent threats or language directed against another person.
+  - Sexist, racist, or otherwise discriminatory jokes and language.
+  - Posting sexually explicit or violent material.
+  - Posting (or threatening to post) other people's personally identifying information ("doxing").
+  - Sharing private content, such as emails sent privately or non-publicly,
+    or unlogged forums, such as IRC channel history, without the sender's consent.
+  - Personal insults, especially those using racist or sexist terms.
+  - Unwelcome sexual attention.
+  - Excessive profanity. Please avoid swearwords; people differ greatly in their sensitivity to swearing.
+  - Repeated harassment of others. In general, if someone asks you to stop, then stop.
+  - Advocating for, or encouraging, any of the above behavior.
+
+
+Diversity statement
+-------------------
+
+The iplotx project welcomes and encourages participation by everyone. We are
+committed to being a community that everyone enjoys being part of. Although
+we may not always be able to accommodate each individual's preferences, we try
+our best to treat everyone kindly.
+
+No matter how you identify yourself or how others perceive you: we welcome you.
+Though no list can hope to be comprehensive, we explicitly honor diversity in:
+age, culture, ethnicity, genotype, gender identity or expression, language,
+national origin, neurotype, phenotype, political beliefs, profession, race,
+religion, sexual orientation, socioeconomic status, subculture and technical
+ability, to the extent that these do not conflict with this code of conduct.
+
+
+Though we welcome people fluent in all languages, iplotx development is
+conducted in English.
+
+Standards for behavior in the iplotx community are detailed in the Code of
+Conduct above. Participants in our community should uphold these standards
+in all their interactions and help others to do so as well (see next section).
+
+
+Reporting guidelines
+--------------------
+
+We know that it is painfully common for internet communication to start at or
+devolve into obvious and flagrant abuse. We also recognize that sometimes
+people may have a bad day, or be unaware of some of the guidelines in this Code
+of Conduct. Please keep this in mind when deciding on how to respond to a
+breach of this Code.
+
+For clearly intentional breaches, report those to the Code of Conduct committee
+(see below). For possibly unintentional breaches, you may reply to the person
+and point out this Code of Conduct (either in public or in private, whatever is
+most appropriate). If you would prefer not to do that, please feel free to
+report to the Code of Conduct committee directly, or ask the committee for
+advice, in confidence.
+
+You can report issues to the iplotx core developer Fabio Zanini, at
+fabio.zanini@unsw.edu.au.
+
+
+Incident reporting resolution & Code of Conduct enforcement
+-----------------------------------------------------------
+
+We will investigate and respond to all complaints. This Code of Conduct
+Committee  will protect the identity of the reporter, and treat the content
+of complaints as confidential (unless the reporter requests otherwise).
+
+In case of severe and obvious breaches, e.g., personal threat or violent, sexist
+or racist language, we will immediately do our utmost to disconnect the
+originator from iplotx communication channels; please see the manual for details.
+
+In cases not involving clear severe and obvious breaches of this code of
+conduct, the process for acting on any received code of conduct violation
+report will be:
+
+1. Acknowledgement that the report has been received
+2. Reasonable discussion/feedback
+3. Mediation (if feedback didn't help, and only if both reporter and reportee agree to this)
+4. Enforcement via transparent decision by the Code of Conduct Committee
+
+The committee will respond to any report as soon as possible, and at most
+within 72 hours.
+
+
+Endnotes
+--------
+
+This document was adapted from the `SciPy Code of Conduct <https://scipy.github.io/devdocs/dev/conduct/code_of_conduct.html>`_.

{iplotx-1.1.0 → iplotx-1.2.1}/docs/source/index.md

@@ -36,4 +36,5 @@ Plotting API <api/plotting>
 Style API <api/style>
 Artist hierarchy <api/artists>
 Data provider protocols <api/providers>
+Code of conduct <code_of_conduct>
 ```

{iplotx-1.1.0 → iplotx-1.2.1}/docs/source/sg_execution_times.rst

@@ -6,7 +6,7 @@
 
 Computation times
 =================
-**00:00.542** total execution time for 77 files **from all galleries**:
+**00:00.565** total execution time for 77 files **from all galleries**:
 
 .. container::
 
@@ -33,7 +33,7 @@ Computation times
      - Time
      - Mem (MB)
    * - :ref:`sphx_glr_gallery_tree_plot_double_tree.py` (``../../gallery/tree/plot_double_tree.py``)
-     - 00:00.542
+     - 00:00.565
      - 0.0
    * - :ref:`sphx_glr_gallery_basic_plot_3d.py` (``../../gallery/basic/plot_3d.py``)
      - 00:00.000

{iplotx-1.1.0 → iplotx-1.2.1}/gallery/tree/plot_double_tree.py

@@ -18,7 +18,7 @@ tree2 = Tree(
     "((),((),(),((),())),());",
 )
 
-fig, ax = plt = plt.subplots(figsize=(9, 4))
+fig, ax = plt.subplots(figsize=(9, 4))
 
 # Plot first tree on the left
 ipx.plotting.tree(
@@ -54,3 +54,38 @@ for y1, y2 in matches:
     ax.plot(
         [5.2, 6.8], [y1, y2], color="gray", linewidth=2,
     )
+
+# %%
+# ``iplotx`` has a dedicated function for double trees, which virtually the same result with less code:
+
+fig, ax = plt.subplots(figsize=(9, 4))
+ipx.doubletree(
+    tree1,
+    tree2,
+    ax=ax,
+    kwargs_left=dict(
+        leaf_deep=True,
+        edge_color="tomato",
+    ),
+    kwargs_right=dict(
+        leaf_deep=True,
+        edge_color="steelblue",
+    ),
+    gap=2,
+    aspect=1,
+)
+
+# Add lines connecting corresponding leaves
+# NOTE: The layout is horizontally centered now
+matches = [
+    (0, 0),
+    (1, 4),
+    (2, 5),
+    (3, 2),
+    (4, 1),
+    (5, 5),
+]
+for y1, y2 in matches:
+    ax.plot(
+        [-0.3, 1.3], [y1, y2], color="gray", linewidth=2,
+    )

{iplotx-1.1.0 → iplotx-1.2.1}/iplotx/__init__.py

@@ -11,6 +11,7 @@ from .plotting import (
     network,
     graph,
     tree,
+    doubletree,
     plot,
 )
 import iplotx.artists as artists
@@ -20,6 +21,7 @@ import iplotx.style as style
 __all__ = [
     "network",
     "tree",
+    "doubletree",
     "plot",
     "graph",
     "artists",

{iplotx-1.1.0 → iplotx-1.2.1}/iplotx/edge/__init__.py

@@ -274,6 +274,12 @@ class EdgeCollection(mpl.collections.PatchCollection):
         """Return mappable for colorbar."""
         return self
 
+    def shift(self, x: float, y: float) -> None:
+        """Shift the cascade by a certain amount."""
+        for path in self._paths:
+            path.vertices[:, 0] += x
+            path.vertices[:, 1] += y
+
     def _get_adjacent_vertices_info(self):
         index = self._vertex_collection.get_index()
         index = pd.Series(

{iplotx-1.1.0 → iplotx-1.2.1}/iplotx/edge/arrow.py

@@ -2,7 +2,12 @@
 Module for edge arrows in iplotx.
 """
 
-from typing import Never, Optional
+import sys
+if sys.version_info < (3, 11):
+    from typing_extensions import Never
+else:
+    from typing import Never
+from typing import Optional
 
 from math import atan2, cos, sin
 import numpy as np

{iplotx-1.1.0 → iplotx-1.2.1}/iplotx/ingest/__init__.py

@@ -2,16 +2,24 @@
 This module focuses on how to ingest network/tree data into standard data structures no matter what library they come from.
 """
 
-import pathlib
-import pkgutil
-import importlib
-import warnings
+import sys
 from typing import (
     Optional,
     Sequence,
-    Protocol,
 )
+
+# NOTE: __init__ in Protocols has had a difficult gestation
+# https://github.com/python/cpython/issues/88970
+if sys.version_info < (3, 11):
+    Protocol = object
+else:
+    from typing import Protocol
+
 from collections.abc import Hashable
+import pathlib
+import pkgutil
+import importlib
+import warnings
 import pandas as pd
 
 from ..typing import (
@@ -35,6 +43,9 @@ provider_protocols = {
 data_providers: dict[str, dict[str, Protocol]] = {kind: {} for kind in provider_protocols}
 for kind in data_providers:
     providers_path = pathlib.Path(__file__).parent.joinpath("providers").joinpath(kind)
+    if sys.version_info < (3, 11):
+        providers_path = str(providers_path)
+
     for importer, module_name, _ in pkgutil.iter_modules([providers_path]):
         module = importlib.import_module(f"iplotx.ingest.providers.{kind}.{module_name}")
         for key, val in module.__dict__.items():
@@ -138,11 +149,11 @@ def ingest_tree_data(
 
 
 # INTERNAL FUNCTIONS
-def _update_data_providers(kind):
-    """Update data provieders dynamically from external packages."""
+def _update_data_providers(kind: str):
+    """Update data providers dynamically from external packages."""
     discovered_providers = importlib.metadata.entry_points(group=f"iplotx.{kind}_data_providers")
     for entry_point in discovered_providers:
-        if entry_point.name not in data_providers["network"]:
+        if entry_point.name not in data_providers[kind]:
             try:
                 data_providers[kind][entry_point.name] = entry_point.load()
             except Exception as e:

{iplotx-1.1.0 → iplotx-1.2.1}/iplotx/ingest/providers/tree/simple.py

@@ -3,7 +3,6 @@ from typing import (
     Optional,
     Sequence,
     Iterable,
-    Self,
 )
 
 from ...typing import (
@@ -19,12 +18,12 @@ class SimpleTree:
         branch_length: Length of the branch leading to this node/tree.
     """
 
-    children: Sequence[Self] = []
+    children: Sequence = []
     branch_length: float = 1
     name: str = ""
 
     @classmethod
-    def from_dict(cls, data: dict) -> Self:
+    def from_dict(cls, data: dict):
         """Create a SimpleTree from a dictionary.
 
         Parameters:

{iplotx-1.1.0 → iplotx-1.2.1}/iplotx/ingest/typing.py

@@ -5,15 +5,20 @@ Networkx and trees are treated separately for practical reasons: many tree analy
 work as well on general networks.
 """
 
+import sys
 from typing import (
-    NotRequired,
-    TypedDict,
-    Protocol,
     Optional,
     Sequence,
     Any,
     Iterable,
 )
+# NOTE: __init__ in Protocols has had a difficult gestation
+# https://github.com/python/cpython/issues/88970
+if sys.version_info < (3, 11):
+    Protocol = object
+else:
+    from typing import Protocol
+
 from collections.abc import Hashable
 import numpy as np
 import pandas as pd
@@ -26,6 +31,11 @@ from .heuristics import (
     normalise_tree_layout,
 )
 
+if sys.version_info < (3, 11):
+    from typing_extensions import TypedDict, NotRequired
+else:
+    from typing import TypedDict, NotRequired
+
 
 class NetworkData(TypedDict):
     """Network data structure for iplotx."""

{iplotx-1.1.0 → iplotx-1.2.1}/iplotx/network/__init__.py

@@ -1,7 +1,6 @@
 from typing import (
     Optional,
     Sequence,
-    Self,
 )
 import numpy as np
 import pandas as pd
@@ -103,8 +102,8 @@ class NetworkArtist(mpl.artist.Artist):
     @classmethod
     def from_other(
         cls: "NetworkArtist",  # NOTE: This is fixed in Python 3.14
-        other: Self,
-    ) -> Self:
+        other,
+    ):
         """Create a NetworkArtist as a copy of another one.
 
         Parameters:
@@ -123,7 +122,7 @@ class NetworkArtist(mpl.artist.Artist):
     def from_edgecollection(
         cls: "NetworkArtist",  # NOTE: This is fixed in Python 3.14
         edge_collection: EdgeCollection | Edge3DCollection,
-    ) -> Self:
+    ):
         """Create a NetworkArtist from iplotx artists.
 
         Parameters:

{iplotx-1.1.0 → iplotx-1.2.1}/iplotx/plotting.py

@@ -1,4 +1,8 @@
-from typing import Optional, Sequence
+from typing import (
+    Optional,
+    Sequence,
+    Any,
+)
 from contextlib import nullcontext
 import numpy as np
 import pandas as pd
@@ -269,8 +273,86 @@ def tree(
     return artist
 
 
+def doubletree(
+    tree_left: Optional[TreeType] = None,
+    tree_right: Optional[TreeType] = None,
+    kwargs_left: Optional[dict[Any]] = None,
+    kwargs_right: Optional[dict[Any]] = None,
+    gap: float = 0,
+    ax: Optional[mpl.axes.Axes] = None,
+    title: Optional[str] = None,
+    aspect: Optional[str | float] = None,
+    margins: float | tuple[float, float] = 0,
+    strip_axes: bool = True,
+    figsize: Optional[tuple[float, float]] = None,
+) -> tuple[TreeArtist, TreeArtist]:
+    """Visualize two trees facing each other.
+
+    Parameters:
+        tree_left: The tree to plot on the left side.
+        tree_right: The tree to plot on the right side.
+        kwargs_left: Additional keyword arguments passed to the left tree plotting function.
+        kwargs_right: Additional keyword arguments passed to the right tree plotting function.
+        ax: The axis to plot on. If None, a new figure and axis will be created. Defaults to
+            None.
+        title: If not None, set the axes title to this value.
+        aspect: If not None, set the aspect ratio of the axis to this value. The most common
+            value is 1.0, which proportionates x- and y-axes.
+        margins: How much margin to leave around the plot. A higher value (e.g. 0.1) can be
+            used as a quick fix when some vertex shapes reach beyond the plot edge. This is
+            a fraction of the data limits, so 0.1 means 10% of the data limits will be left
+            as margin.
+        strip_axes: If True, remove axis spines and ticks.
+        figsize: If ax is None, a new matplotlib Figure is created. This argument specifies
+            the (width, height) dimension of the figure in inches. If ax is not None, this
+            argument is ignored. If None, the default matplotlib figure size is used.
+    Returns:
+        A tuple with the left and right TreeArtist objects.
+    """
+    artist1 = tree(
+        tree_left,
+        layout="horizontal",
+        layout_orientation="right",
+        ax=ax,
+        strip_axes=False,
+        figsize=figsize,
+        **kwargs_left or {},
+    )
+
+    ax = artist1.axes
+
+    if kwargs_right is None:
+        kwargs_right = {}
+
+    had_layout_start = "layout_start" in kwargs_right
+
+    artist2 = tree(
+        tree_right,
+        layout="horizontal",
+        layout_orientation="left",
+        ax=ax,
+        title=title,
+        aspect=aspect,
+        strip_axes=False,
+        margins=margins,
+        **kwargs_right,
+    )
+
+    if not had_layout_start:
+        x2min = artist2.get_layout().values[:, 0].min()
+        x1max = artist1.get_layout().values[:, 0].max()
+        xshift = x1max - x2min + gap
+
+        artist2.shift(0.5 * xshift, 0)
+        artist1.shift(-0.5 * xshift, 0)
+
+    _postprocess_axes(ax, [artist1, artist2], strip=strip_axes, ignore_previous=True)
+
+    return (artist1, artist2)
+
+
 # INTERNAL ROUTINES
-def _postprocess_axes(ax, artists, strip=True, had_data=None):
+def _postprocess_axes(ax, artists, strip=True, had_data=None, ignore_previous=False):
     """Postprocess axis after plotting."""
 
     if strip:
@@ -309,7 +391,11 @@ def _postprocess_axes(ax, artists, strip=True, had_data=None):
         for art in artists:
             bboxes.append(art.get_datalim(ax.transData))
         bbox = mpl.transforms.Bbox.union(bboxes)
-        ax.update_datalim(bbox)
+
+        if not ignore_previous:
+            ax.update_datalim(bbox)
+        else:
+            ax.dataLim.update_from_data_xy(bbox.corners(), ignore=True)
 
         # Autoscale for x/y axis limits
         ax.autoscale_view()

{iplotx-1.1.0 → iplotx-1.2.1}/iplotx/tree/__init__.py

@@ -219,6 +219,31 @@ class TreeArtist(mpl.artist.Artist):
         else:
             raise ValueError(f"Unknown layout kind: {kind}. Use 'vertex' or 'edge'.")
 
+    def shift(self, x: float, y: float) -> None:
+        """Shift layout coordinates for all tree elements.
+
+        Paramerers:
+            x: The shift in x direction.
+            y: The shift in y direction.
+        """
+        layout_columns = [f"_ipx_layout_{i}" for i in range(self._ipx_internal_data["ndim"])]
+        self._ipx_internal_data["vertex_df"][layout_columns[0]] += x
+        self._ipx_internal_data["vertex_df"][layout_columns[1]] += y
+
+        self.get_vertices()._layout.values[:, 0] += x
+        self.get_vertices()._layout.values[:, 1] += y
+        self.get_vertices()._update_offsets_from_layout()
+
+        self.get_edges().shift(x, y)
+
+        if hasattr(self, "_leaf_vertices"):
+            self.get_leaf_vertices()._layout.values[:, 0] += x
+            self.get_leaf_vertices()._layout.values[:, 1] += y
+            self.get_leaf_vertices()._update_offsets_from_layout()
+
+        if hasattr(self, "_cascades"):
+            self._cascades.shift(x, y)
+
     def get_datalim(self, transData, pad=0.15):
         """Get limits on x/y axes based on the graph layout data.
 

{iplotx-1.1.0 → iplotx-1.2.1}/iplotx/tree/cascades.py

@@ -158,6 +158,12 @@ class CascadeCollection(mpl.collections.PatchCollection):
             zorder=zorder,
         )
 
+    def shift(self, x: float, y: float) -> None:
+        """Shift the cascade by a certain amount."""
+        for path in self._paths:
+            path.vertices[:, 0] += x
+            path.vertices[:, 1] += y
+
     def get_maxdepth(self) -> float:
         """Get the maxdepth of the cascades.
 

{iplotx-1.1.0 → iplotx-1.2.1}/iplotx/version.py

@@ -2,4 +2,4 @@
 iplotx version information module.
 """
 
-__version__ = "1.1.0"
+__version__ = "1.2.1"

{iplotx-1.1.0 → iplotx-1.2.1}/pyproject.toml

@@ -11,11 +11,11 @@ authors = [
 maintainers = [
   {name = "Fabio Zanini", email = "fabio.zanini@unsw.edu.au"}
 ]
-requires-python = ">=3.11"
+requires-python = ">=3.10"
 readme = "README.md"
 dynamic = ["version"]
 dependencies = [
-  "matplotlib>=2.0.0",
+  "matplotlib>=3.10.0",
   "numpy>=2.0.0",
   "pandas>=2.0.0",
 ]