iplotx 0.1.0__tar.gz → 0.2.1__tar.gz

{iplotx-0.1.0 → iplotx-0.2.1}/.github/workflows/test.yml

@@ -16,7 +16,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.11", "3.12", "3.13"]
 
     steps:
     - uses: actions/checkout@v4
@@ -38,4 +38,4 @@ jobs:
       run: uv run pytest tests
 
     - name: Run flake8
-      run: uv run flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+      run: uv run flake8 iplotx --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics

{iplotx-0.1.0 → iplotx-0.2.1}/.gitignore

@@ -1,3 +1,6 @@
+# Tokens
+pypi-token
+
 # Test images
 result_images
 
@@ -72,7 +75,8 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+docs/build/
+docs/source/gallery
 
 # PyBuilder
 .pybuilder/

iplotx-0.2.1/.readthedocs.yaml

@@ -0,0 +1,25 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/source/conf.py
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+  jobs:
+     pre_create_environment:
+        - asdf plugin add uv
+        - asdf install uv latest
+        - asdf global uv latest
+     create_environment:
+        - uv venv "${READTHEDOCS_VIRTUALENV_PATH}"
+     install:
+        - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv sync --frozen --group docs

iplotx-0.2.1/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: iplotx
+Version: 0.2.1
+Summary: Plot networkx from igraph and networkx.
+Project-URL: Homepage, https://github.com/fabilab/iplotx
+Project-URL: Documentation, https://readthedocs.org/iplotx
+Project-URL: Repository, https://github.com/fabilab/iplotx.git
+Project-URL: Bug Tracker, https://github.com/fabilab/iplotx/issues
+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
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+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-Dist: numpy>=2.0.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: pylint>=3.3.7
+Provides-Extra: igraph
+Requires-Dist: igraph>=0.11.0; extra == 'igraph'
+Provides-Extra: networkx
+Requires-Dist: networkx>=2.0.0; extra == 'networkx'
+Description-Content-Type: text/markdown
+
+![Github Actions](https://github.com/fabilab/iplotx/actions/workflows/test.yml/badge.svg)
+![PyPI - Version](https://img.shields.io/pypi/v/iplotx)
+![RTD](https://readthedocs.org/projects/iplotx/badge/?version=latest)
+![pylint](assets/pylint.svg)
+
+# iplotx
+Plotting networks from igraph and networkx.
+
+**NOTE**: This is currently beta quality software. The API and functionality are settling in and might break occasionally.
+
+## Installation
+```bash
+pip install iplotx
+```
+
+## Quick Start
+```python
+import networkx as nx
+import matplotlib.pyplot as plt
+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)
+```
+
+![Quick start image](docs/source/_static/graph_basic.png)
+
+## Documentation
+See [readthedocs](https://iplotx.readthedocs.io/en/latest/) for the full documentation.
+
+## Gallery
+See [gallery](https://iplotx.readthedocs.io/en/latest/gallery/index.html).
+
+## Roadmap
+- Plot networks from igraph and networkx interchangeably, using matplotlib as a backend. ✅
+- Support interactive plotting, e.g. zooming and panning after the plot is created. ✅
+- Support storing the plot to disk thanks to the many matplotlib backends (SVG, PNG, PDF, etc.). ✅
+- Support flexible yet easy styling. ✅
+- Efficient plotting of large graphs using matplotlib's collection functionality. ✅
+- Support editing plotting elements after the plot is created, e.g. changing node colors, labels, etc. ✅
+- Support animations, e.g. showing the evolution of a network over time. ✅
+- Support trees from special libraries such as ete3, biopython, etc. This will need a dedicated function and layouting. ✅
+- Support uni- and bi-directional communication between graph object and plot object.🏗️
+
+**NOTE:** The last item can probably be achieved already by using `matplotlib`'s existing callback functionality. It is currently untested, but if you manage to get it to work on your graph let me know and I'll add it to the examples (with credit).
+
+## Authors
+Fabio Zanini (https://fabilab.org)

iplotx-0.2.1/README.md

@@ -0,0 +1,50 @@
+![Github Actions](https://github.com/fabilab/iplotx/actions/workflows/test.yml/badge.svg)
+![PyPI - Version](https://img.shields.io/pypi/v/iplotx)
+![RTD](https://readthedocs.org/projects/iplotx/badge/?version=latest)
+![pylint](assets/pylint.svg)
+
+# iplotx
+Plotting networks from igraph and networkx.
+
+**NOTE**: This is currently beta quality software. The API and functionality are settling in and might break occasionally.
+
+## Installation
+```bash
+pip install iplotx
+```
+
+## Quick Start
+```python
+import networkx as nx
+import matplotlib.pyplot as plt
+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)
+```
+
+![Quick start image](docs/source/_static/graph_basic.png)
+
+## Documentation
+See [readthedocs](https://iplotx.readthedocs.io/en/latest/) for the full documentation.
+
+## Gallery
+See [gallery](https://iplotx.readthedocs.io/en/latest/gallery/index.html).
+
+## Roadmap
+- Plot networks from igraph and networkx interchangeably, using matplotlib as a backend. ✅
+- Support interactive plotting, e.g. zooming and panning after the plot is created. ✅
+- Support storing the plot to disk thanks to the many matplotlib backends (SVG, PNG, PDF, etc.). ✅
+- Support flexible yet easy styling. ✅
+- Efficient plotting of large graphs using matplotlib's collection functionality. ✅
+- Support editing plotting elements after the plot is created, e.g. changing node colors, labels, etc. ✅
+- Support animations, e.g. showing the evolution of a network over time. ✅
+- Support trees from special libraries such as ete3, biopython, etc. This will need a dedicated function and layouting. ✅
+- Support uni- and bi-directional communication between graph object and plot object.🏗️
+
+**NOTE:** The last item can probably be achieved already by using `matplotlib`'s existing callback functionality. It is currently untested, but if you manage to get it to work on your graph let me know and I'll add it to the examples (with credit).
+
+## Authors
+Fabio Zanini (https://fabilab.org)

iplotx-0.2.1/assets/pylint.svg

@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="80" height="20">
+    <linearGradient id="b" x2="0" y2="100%">
+        <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+        <stop offset="1" stop-opacity=".1"/>
+    </linearGradient>
+    <mask id="anybadge_1">
+        <rect width="80" height="20" rx="3" fill="#fff"/>
+    </mask>
+    <g mask="url(#anybadge_1)">
+        <path fill="#555" d="M0 0h44v20H0z"/>
+        <path fill="#4C1" d="M44 0h36v20H44z"/>
+        <path fill="url(#b)" d="M0 0h80v20H0z"/>
+    </g>
+    <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
+        <text x="23.0" y="15" fill="#010101" fill-opacity=".3">pylint</text>
+        <text x="22.0" y="14">pylint</text>
+    </g>
+    <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
+        <text x="63.0" y="15" fill="#010101" fill-opacity=".3">9.13</text>
+        <text x="62.0" y="14">9.13</text>
+    </g>
+</svg>

iplotx-0.2.1/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

iplotx-0.2.1/docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

iplotx-0.2.1/docs/source/_templates/layout.html

@@ -0,0 +1,9 @@
+{% extends '!layout.html' %}
+{% block extrahead %}
+{{super()}}
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/github-fork-ribbon-css/0.2.3/gh-fork-ribbon.min.css" />
+{% endblock %}
+{% block document %}
+{{super()}}
+    <a class="github-fork-ribbon" href="https://github.com/fabilab/iplotx" data-ribbon="Fork me on GitHub" title="Fork me on GitHub">Fork me on GitHub</a>
+{% endblock %}

iplotx-0.2.1/docs/source/api.md

@@ -0,0 +1,60 @@
+# Reference API
+This is the reference documentation for `iplotx`.
+
+## Main functions
+The main user-facing function is `iplotx.network`, which can be used to plot graphs and graph groupings (covers and clusterings), and `iplotx.tree` to plot trees. `iplotx.plot` is a synonym for `iplotx.network`.
+
+```{eval-rst}
+.. autofunction:: iplotx.network
+    :noindex:
+
+.. autofunction:: iplotx.tree
+    :noindex:
+```
+
+## Styling
+See also the <project:style.md> for an introduction to styles in `iplotx`.
+
+
+```{eval-rst}
+.. autofunction:: iplotx.style.context
+
+.. autofunction:: iplotx.style.use
+
+.. autofunction:: iplotx.style.reset
+
+.. autofunction:: iplotx.style.get_style
+```
+
+The following functions are reported for completeness but are rarely used by users directly:
+
+```{eval-rst}
+.. autofunction:: iplotx.style.unflatten_style
+
+.. autofunction:: iplotx.style.rotate_style
+```
+
+## 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.
+
+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.
+
+In turn, a `VertexCollection` or `EdgeCollection` instance **may** contain a `LabelCollection` instance if the plot includes labels. Moreover, an `EdgeCollection` instance **may** contain an `EdgeArrowCollection` instance if the graph is directed.
+
+```{eval-rst}
+.. autoclass:: iplotx.network.NetworkArtist
+    :members:
+
+
+.. autoclass:: iplotx.vertex.VertexCollection
+    :members:
+
+.. autoclass:: iplotx.edge.EdgeCollection
+    :members:
+
+.. autoclass:: iplotx.label.LabelCollection
+    :members:
+
+.. autoclass:: iplotx.edge.arrow.EdgeArrowCollection
+    :members:
+```

iplotx-0.2.1/docs/source/conf.py

@@ -0,0 +1,141 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+import sys
+import os
+from pathlib import Path
+from packaging.version import parse as parse_version
+
+import iplotx
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "iplotx"
+copyright = "2025-%Y, Fabio Zanini"
+author = "Fabio Zanini"
+release = iplotx.__version__
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "myst_parser",
+    "sphinx_design",
+    "sphinx_gallery.gen_gallery",
+]
+
+# Napoleon settings
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
+napoleon_include_init_with_doc = False
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = True
+napoleon_use_admonition_for_examples = False
+napoleon_use_admonition_for_notes = False
+napoleon_use_admonition_for_references = False
+napoleon_use_ivar = False
+napoleon_use_param = True
+napoleon_use_rtype = True
+napoleon_preprocess_types = False
+napoleon_type_aliases = None
+napoleon_attr_annotations = True
+
+myst_enable_extensions = ["colon_fence"]
+
+sphinx_gallery_conf = {
+    "examples_dirs": "../../gallery",  # path to your example scripts
+    "gallery_dirs": "./gallery",  # path to where to save gallery generated output
+    #'matplotlib_animations': (True, 'mp4'),
+    "matplotlib_animations": True,
+}
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+    ".myst": "markdown",
+    ".txt": "markdown",
+}
+
+
+templates_path = ["_templates"]
+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_static_path = ["_static"]
+
+# -----------------------------------------------------------------------------
+# Source code links (credit to the matplotlib project for this part)
+# -----------------------------------------------------------------------------
+link_github = True
+# You can add build old with link_github = False
+
+if link_github:
+    import inspect
+
+    extensions.append("sphinx.ext.linkcode")
+
+    def linkcode_resolve(domain, info):
+        """
+        Determine the URL corresponding to Python object
+        """
+        if domain != "py":
+            return None
+
+        modname = info["module"]
+        fullname = info["fullname"]
+
+        submod = sys.modules.get(modname)
+        if submod is None:
+            return None
+
+        obj = submod
+        for part in fullname.split("."):
+            try:
+                obj = getattr(obj, part)
+            except AttributeError:
+                return None
+
+        if inspect.isfunction(obj):
+            obj = inspect.unwrap(obj)
+        try:
+            fn = inspect.getsourcefile(obj)
+        except TypeError:
+            fn = None
+        if not fn or fn.endswith("__init__.py"):
+            try:
+                fn = inspect.getsourcefile(sys.modules[obj.__module__])
+            except (TypeError, AttributeError, KeyError):
+                fn = None
+        if not fn:
+            return None
+
+        try:
+            source, lineno = inspect.getsourcelines(obj)
+        except (OSError, TypeError):
+            lineno = None
+
+        linespec = f"#L{lineno:d}-L{lineno + len(source) - 1:d}" if lineno else ""
+
+        startdir = Path(iplotx.__file__).parent.parent
+        try:
+            fn = os.path.relpath(fn, start=startdir).replace(os.path.sep, "/")
+        except ValueError:
+            return None
+
+        if not fn.startswith("iplotx/"):
+            return None
+
+        version = parse_version(iplotx.__version__)
+        tag = "main" if version.is_devrelease else f"v{version.public}"
+        return "https://github.com/fabilab/iplotx/blob" f"/{tag}/{fn}{linespec}"
+
+else:
+    extensions.append("sphinx.ext.viewcode")

iplotx-0.2.1/docs/source/index.md

@@ -0,0 +1,118 @@
+# 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
+```
+pip install iplotx
+```
+
+
+## Quick Start
+::::{tab-set}
+
+:::{tab-item} igraph
+
+```
+import igraph as ig
+import matplotlib.pyplot as plt
+import iplotx as ipx
+
+g = ig.Graph.Ring(5)
+layout = g.layout("circle").coords
+fig, ax = plt.subplots(figsize=(3, 3))
+ipx.plot(g, ax=ax, layout=layout)
+```
+
+
+
+:::
+
+:::{tab-item} networkx
+```
+import networkx as nx
+import matplotlib.pyplot as plt
+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)
+```
+
+:::
+
+::::
+
+Either way, the result is the same:
+
+![graph_basic](_static/graph_basic.png)
+
+## Gallery
+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
+- arrows
+- tunable offset for parallel (i.e. multi-) edges
+- ports (a la Graphviz)
+- curved edges and self-loops with controllable tension
+- tree layouts
+- label-based vertex autoscaling
+- node label margins and padding
+- export to many formats (e.g. PNG, SVG, PDF, EPS) thanks to `matplotlib`
+- compatibility with many GUI frameworks (e.g. Qt, GTK, Tkinter) thanks to `matplotlib`
+- data-driven axes autoscaling
+- consistent behaviour upon zooming and panning
+- correct HiDPI scaling (e.g. retina screens)
+- a consistent `matplotlib` artist hierarchy
+- post-plot editability (e.g. for animations)
+- plays well 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)
+- ... and probably more by the time you read this.
+
+## Styles
+`iplotx` is designed to produce publication-quality figures using **styles**, which are dictionaries specifying the visual properties of each graph element, including vertices, edges, arrows, labels, and groupings.
+
+An example of style specification is as follows:
+
+```python
+import iplotx as ipx
+with ipx.style.context({
+    'vertex': {
+        'size': 30,
+        'facecolor': 'red',
+        'edgecolor': 'none',
+    }
+}):
+    ipx.plot(...)
+```
+
+See <project:style.md> for more info.
+
+## Reference API
+See <project:api.md> for reference documentation of all functions and classes in `iplotx`.
+
+## 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
+API <api>
+```