iplotx 0.3.1__tar.gz → 0.5.0__tar.gz

{iplotx-0.3.1 → iplotx-0.5.0}/.github/workflows/test.yml

@@ -35,7 +35,10 @@ jobs:
       run: uv sync --all-extras --group test
 
     - name: Run pytest
-      run: uv run pytest tests
+      run: uv run pytest --cov-report term-missing --cov=iplotx tests
+
+    - name: Coveralls
+      uses: coverallsapp/github-action@v2
 
     - name: Run flake8
-      run: uv run flake8 iplotx --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+      run: uv run flake8 iplotx --count --exit-zero --max-complexity=20 --max-line-length=127 --statistics

iplotx-0.5.0/.pre-commit-config.yaml

@@ -0,0 +1,54 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v5.0.0
+  hooks:
+  -   id: trailing-whitespace
+  -   id: end-of-file-fixer
+  -   id: check-yaml
+  -   id: check-added-large-files
+
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  # Ruff version.
+  rev: v0.12.3
+  hooks:
+    # Run the linter.
+    - id: ruff-check
+      types_or: [ python, pyi ]
+      args: [ --fix ]
+    # Run the formatter.
+    - id: ruff-format
+      types_or: [ python, pyi ]
+
+#- repo: https://github.com/psf/black
+#  rev: 25.1.0
+#  hooks:
+#  -   id: black
+#      args: [--check,--target-version,py311]
+- repo: https://github.com/PyCQA/flake8
+  rev: 7.3.0
+  hooks:
+  -   id: flake8
+      args: [
+          --count,
+          --max-complexity=20,
+          --max-line-length=127,
+          --statistics,
+          --extend-ignore=RST399,
+          --exit-zero,
+      ]
+      additional_dependencies: [
+          'flake8-rst-docstrings>=0.2.3',
+      ]
+#-   repo: https://github.com/pre-commit/mirrors-mypy
+#    rev: v1.16.1
+#    hooks:
+#    -   id: mypy
+#        files: '^(iplotx)/'
+
+- repo: https://github.com/astral-sh/uv-pre-commit
+  # uv version.
+  rev: 0.7.20
+  hooks:
+    - id: uv-lock

{iplotx-0.3.1 → iplotx-0.5.0}/MANIFEST.in

@@ -10,4 +10,3 @@ prune doc/html
 prune doc/source/tutorials
 
 global-exclude .dockerignore .DS_Store .gitattributes .gitignore .gitmodules
-

{iplotx-0.3.1 → iplotx-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iplotx
-Version: 0.3.1
+Version: 0.5.0
 Summary: Plot networkx from igraph and networkx.
 Project-URL: Homepage, https://github.com/fabilab/iplotx
 Project-URL: Documentation, https://readthedocs.org/iplotx
@@ -39,6 +39,7 @@ 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)
+[![Coverage Status](https://coveralls.io/repos/github/fabilab/iplotx/badge.svg?branch=main)](https://coveralls.io/github/fabilab/iplotx?branch=main)
 ![pylint](assets/pylint.svg)
 
 # iplotx

{iplotx-0.3.1 → iplotx-0.5.0}/README.md

@@ -1,6 +1,7 @@
 ![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)
+[![Coverage Status](https://coveralls.io/repos/github/fabilab/iplotx/badge.svg?branch=main)](https://coveralls.io/github/fabilab/iplotx?branch=main)
 ![pylint](assets/pylint.svg)
 
 # iplotx

iplotx-0.3.1/docs/source/api.md → iplotx-0.5.0/docs/source/api/artists.md

@@ -1,40 +1,4 @@
-# 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
+# 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.

iplotx-0.5.0/docs/source/api/complete_style_specification.md

@@ -0,0 +1,254 @@
+# Complete style specification
+```{note}
+  There might be additional matplotlib options not mentioned below (e.g. rotation,
+  font family). Any options not mentioned below are passed directly to matplotlib.
+```
+
+
+```python
+{
+    # Vertex style
+    "vertex": {
+        # Size of the vertex in points. If a pair, it indicates width and height
+        # of the marker. If "label", set the size dynamically based on the vertex
+        # label (a label is needed in this case)
+        "size": float | tuple[float, float] | str,
+
+        # Marker style. Currently supported markers:
+        # o, c, circle: circle
+        # s, square, r, rectangle: rectangle (square if only one size specified)
+        # ^, triangle: upward triangle
+        # v, triangle_down: downward triangle
+        # <, triangle_left: leftward triangle
+        # >, triangle_right: rightward triangle
+        # d, diamond: diamond
+        # e, ellipse: ellipse
+        # p, pentagon: pentagon
+        # h, hexagon: hexagon
+        # 8, octagon: octagon
+        # *, star: 5-point star, upright
+        "marker": str,
+
+        "facecolor": str | Any,  # Color of the vertex face (e.g. 'red', '#FF0000')
+        "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)
+
+        # Vertex label style
+        "label": {
+            "color": str | Any,  # Color of the vertex 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
+            "vpadding": float,  # Vertical padding around the label
+
+            # Bounding box properties for the label
+            "bbox": {
+                "boxstyle": str,  # Style of the bounding box ('round', 'square', etc.)
+                "facecolor": str | Any,  # Color of the bounding box (e.g. 'yellow', '#FFFF00')
+                "edgecolor": str | Any,  # Color of the bounding box edge (e.g. 'black', '#000000')
+                ...  # Any other bounding box property
+
+            },
+            "hmargin": float,  # Horizontal margin around (usually left of) the label
+            "vmargin": float,  # Vertical margin around (usually below) the label. Rarely used.
+        },
+    },
+
+    # Edge style
+    "edge": {
+        "linewidth": float,  # Width of the edge line in points
+
+        # Style of the edge line ('-' for solid, '--' for dashed, etc.). Matplotlib
+        # allows for quite flexible syntax here.
+        "linestyle": str | Any,
+
+        # Color of the edge line (e.g. 'blue', '#0000FF'). This can be a floating
+        # number (usually set on a per-edge basis) to use color mapping. In that case
+        # the "cmap" property needs to be set too (see next option). In that case,
+        # the min/max values of the floats are used as extremes for the colormap,
+        # unless the "norm" option is used.
+        "color": str | float | Any,
+
+        # Matplotlib color map used to map floating numbers into RGBA colors. Only
+        # used when the previous option "color" is set to floats.
+        "cmap": str | matplotlib.colors.Colormap,
+
+        # Matplotlib norm to connect color map and edge floating-point color values.
+        # This is only used when colors are mapped through a color map. In that case,
+        # this option lets the user finely control what floating number will be mapped
+        # onto what color.
+        "norm": tuple[float, float] | matplotlib.colors.Normalize,
+
+        # Opacity of the vertex (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,
+
+        "curved": bool,  # Whether the edge is curved (True) or straight (False)
+
+        # Tension for curved edges (0.0 for straight, higher values position the
+        # Bezier control points further away from the nodes, creating more wiggly lines)
+        # Negative values bend the curve on the other side of the straight line.
+        "tension": float,
+
+        # Tension for self-loops (higher values create more bigger loops).
+        # This is typically a strictly positive value.
+        "looptension": float,
+
+        # The maximum angle for self-loops (in degrees). This is typically a positive
+        # number quite a bit less than 180 degrees to avoid funny-looking self-loops.
+        "loopmaxangle": float,
+
+        # xy offset of the edge coordinate in figure points. This is usually set on a
+        # per-edge basis if specific edges are to be shifted laterally slightly. Large
+        # offsets tend to not play well with the rest of the visualisation.
+        "offset": tuple[float, float],
+
+        # How much (in figure points) to offset parallel straight edges (i.e. in a
+        # multigraph only) along the orthogonal direction to make them more visible.
+        # To obtain a double-headed arrow effect, set this to zero. On the flip side,
+        # you will not know how many parallel edges there are between those two nodes.
+        "paralleloffset": float,
+
+        # Edge ports a la Graphviz, which indicate the attack angle of an edge into
+        # its origin (first element) and target (second element) node. "w" (for
+        # "west") means exiting from/entering into the left side, "e" is the right
+        # side, "n" the top, "s" the bottom. "nw" and similar two-letter combinations
+        # are accepted and indicate 45 degree angles (in figure space). None means
+        # that edge side is free (i.e. no special instruction there). This is almost
+        # universally either unset or set on a per-edge basis to finely control the
+        # appearance of the network (e.g. in organisational charts).
+        "ports": tuple[str | None, str | None],
+
+        # Edge waypoints. This option is usually set together with "ports" to
+        # finely control the appearance of edges. For trees, this option is used
+        # internally to create piecewise-straight connections. This option is
+        # currently experimental, but you can try the following settings:
+        # - xmidy0,xmidy1: Two waypoints with the mid-x and the 1st and 2nd y values.
+        # - ymidx0,ymidx1: The xy swap of the previous option.
+        # - x0y1: One waypoint, with x of the first point and y of the second point.
+        # - x1y0: The xy swap of the previous option.
+        # We are looking into ways to generalise this idea.
+        "waypoints": str,
+
+        # Edge arrow style for directed graphs
+        "arrow": {
+            # Arrow marker style. Currently supported:
+            # |>
+            # |/
+            # |\\ (double slash needed to avoid character escaping)
+            # >
+            # >>
+            # )>
+            # )
+            # |
+            # s
+            # d
+            # p
+            # q
+            "marker": str,
+
+            "width": float,  # Width of the arrow in points
+
+            # Height of the arrow in points. Defaults to 1.3 times the width if not
+            # specified. If the string "width" is used, it is set to the width of
+            # the arrow.
+            "height": float | str,
+
+            # Color of the arrow (e.g. 'black', '#000000'). This means both the
+            # facecolor and edgecolor for full arrows (e.g. "|>"), only the edgecolor
+            # for hollow arrows (e.g. ">"). This specification, like in matplotlib,
+            # takes higher precedence than the "edgecolor" and "facecolor" properties.
+            # If this property is not specified, the color of the edge to which the
+            # arrowhead belongs to is used.
+            "color": str | Any,
+        },
+
+        # Edge label style
+        "label": {
+
+            # Whether to rotate edge labels to be horizontal (True) or to leave them
+            # parallel to their edge (False). Some users find this boolean
+            # 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')
+            "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
+            "vpadding": float,  # Vertical padding around the label
+            "bbox": dict,  # Bounding box properties for the label (see vertex labels)
+
+        },
+    },
+
+    # The following entry is used by networks ONLY (not trees as plotted by `iplotx.tree`)
+    "grouping": {
+        "facecolor": str | Any,  # Color of the grouping face (e.g. 'lightgray', '#D3D3D3')
+        "edgecolor": str | Any,  # Color of the grouping edge (e.g. 'gray', '#808080')
+        "linewidth": float,  # Width of the grouping edge in points
+        "vertexpadding": float,  # Padding around the vertices in the grouping in points
+    },
+
+    ############################################################################
+    # The following entries are used by trees ONLY (as plotted by `iplotx.tree`)
+    "cascade": {
+        # Whether to limit the cascade to the deepest descendant (False),
+        # to the deepest leaf overall (True), or to include the leaf labels
+        # as well "leaf_labels"
+        "extend": bool | str,
+
+        "facecolor": str | Any,  # Color of the cascade face
+        "edgecolor": str | Any,  # Color of the cascade edge
+        "alpha": float,  # Opacity of the cascade patch
+    },
+
+    # Leaf styles are currently only used for their labels
+    "leaf": {
+        # Whether leaf nodes and labels will be aligned to the deepest leaf.
+        # If False, each leaf label will be at the depth of its leaf.
+        "deep": bool,
+        "label": {
+            "color": str | Any,  # Color of the label text
+            "hmargin": float,  # Horizontal offset (before rotation) off the leaf node
+        }
+    },
+
+    # Leaf edge styles are used for the (usually dashed) lines connecting leaves
+    # at less-than-max depth to deep labels (if used).
+    "leafedge": {
+        "color": str | Any,  # Color of the leaf edge (e.g. 'gray', '#808080')
+        "linewidth": float,  # Width of the leaf edge in points
+        "linestyle": str | Any,  # Style of the leaf edge line ('--' for dashed etc.)
+
+        # Leaf edge labels.
+        # NOTE: These lines will NOT exist for leaves that are set at the max depth
+        # (at least one leaf will always be skipped). Therefore, using labels here
+        # can be a little trickier than you might expect.
+        "label": {
+            "color": str | Any,  # Color of the leaf edge label (e.g. 'black')
+            "hmargin": float,  # Horizontal offset (before rotation) off the leaf edge
+            "vmargin": float,  # Vertical offset (before rotation) off the leaf edge
+            # Whether to rotate the label to be horizontal (True) or parallel to the edge (False)
+            "rotate": bool,
+        },
+    },
+
+    # Layout options for trees
+    "layout": {
+        # Orientation of the tree. Accepted values depend on the tree layout:
+        # - "horizontal" layout: "left" or "right"
+        # - "vertical" layout: "ascending" or "descending"
+        # - "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)
+    },
+    ############################################################################
+}
+```
+
+```{tip}
+Most options can be "leaf rotated" to obtain a per-vertex, per-edge, per-label, or per-cascade look. See <project:../style.md> for more info.
+```

iplotx-0.5.0/docs/source/api/plotting.md

@@ -0,0 +1,13 @@
+# Plotting API
+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.
+
+```{tip}
+  `iplotx.plot` is a synonym for `iplotx.network`.
+```
+
+```{eval-rst}
+.. autofunction:: iplotx.network
+    :noindex:
+
+.. autofunction:: iplotx.tree
+    :noindex:

iplotx-0.5.0/docs/source/api/providers.md

@@ -0,0 +1,16 @@
+# Data provider protocols
+```{note}
+  The `NetworkDataProvider` protocol requires individual providers to implement `__call__` which actually processed the network, layout, and label data. We are working on simplifying this situation.
+
+  The `TreeDataProvider` protocol is simpler to implement as this function is standardised and needs not be implemented by individual providers. Only the support functions, which are very simple and small, needs to be implemented by tree providers.
+```
+
+
+```{eval-rst}
+.. autoclass:: iplotx.ingest.typing.NetworkDataProvider
+    :members:
+
+.. autoclass:: iplotx.ingest.typing.TreeDataProvider
+    :members:
+
+```

iplotx-0.5.0/docs/source/api/style.md

@@ -0,0 +1,23 @@
+# Styling
+See also the <project:../style.md> page for an introduction to styles in `iplotx`. See also <project:complete_style_specification.md>.
+
+## Functions
+
+
+```{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
+```

iplotx-0.5.0/docs/source/api.md

@@ -0,0 +1,7 @@
+# Reference API
+This is the reference documentation for `iplotx`. This is split into separate sections:
+
+- <project:api/plotting.md> for the plotting API
+- <project:api/style.md> for the styling API
+- <project:api/artists.md> for the artist hierarchy
+- <project:api/providers.md> for the data providers API

{iplotx-0.3.1 → iplotx-0.5.0}/docs/source/conf.py

@@ -49,7 +49,6 @@ 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,
 }
 
@@ -135,7 +134,7 @@ if link_github:
 
         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}"
+        return f"https://github.com/fabilab/iplotx/blob/{tag}/{fn}{linespec}"
 
 else:
     extensions.append("sphinx.ext.viewcode")

{iplotx-0.3.1 → iplotx-0.5.0}/docs/source/index.md

@@ -116,5 +116,11 @@ We believe graph **analysis**, graph **layouting**, and graph **visualisation**
 
 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>
 ```

iplotx-0.5.0/docs/source/providers.md

@@ -0,0 +1,72 @@
+# Data Providers
+Networks and trees can be represented in different data structures. For instance, in `igraph` nodes are ordered and numbered, while in `networkx` they are neither.
+
+`iplotx` is designed to accept data of any kinds as long as it can understand how to
+process it into a visualisation. This flexibility is achieved through **data providers**.
+
+A **network data provider** is a class that satisfies the `NetworkDataProvider` protocol, i.e. it implements a few functions that help `iplotx` understand how to ingest
+data.
+
+Similarly, a **tree data provider** is a class that satisfies the `TreeDataProvider` protocol, i.e. it implements those few functions. It is the tree-specific equivalent of the previous case.
+
+See <project:api/providers.md> for the exact protocols.
+
+## An example: Simple network data provider
+While `igraph`, `networkx` and the likes can be quite complicated, `iplotx` also provides a simple dict-based `NetworkDataProvider` for educational purposes. The network data structure in this case is the following:
+
+```python
+  network : dict[str, Sequence | bool] = {
+      "vertices": ["alice", "bob", "jago"],
+      "edges": [
+          ("alice", "bob"),
+          ("bob", "jago"),
+          ("alice", "jago"),
+      ],
+      "directed": False,
+  }
+```
+
+It is a simple dictionary with a key for vertices, one for edges, and one for directedness. Only the key for edges is required. If missing, directedness is assumed to be `False`. If vertices are missing, they are inferred from the edges (singletons will be missed - there are none in the example above).
+
+
+A straightforward `NetworkDataProvider` implementation for this network data structure is found in `iplotx/ingest/providers/network/simple.py`. As a result, it is possible to ingest networks in this new format for visualisation:
+
+```python
+    import iplotx as ipx
+    network = {
+        "edges": [
+            ("alice", "bob"),
+            ("bob", "jago"),
+            ("alice", "jago"),
+        ]
+    }
+    layout = {
+        "alice": (0, 0),
+        "bob": (1, 1),
+        "jago": (1, 0),
+    }
+    ipx.plot(
+        network,
+        layout,
+    )
+```
+
+See <project:gallery/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
+  library. You'll still need `matplotlib` for plotting and `numpy` and `pandas` for
+  internal number crunching.
+```
+
+
+## Creating a custom data provider
+`iplotx` is able to seek new data providers at runtime, but they need to be registered in a specific way (keyword: `entry point`).
+
+The expected entry point for a `NetworkDataProvider` is: `iplotx.network_data_providers`.
+
+The expected entry point for a `TreeDataProvider` is: `iplotx.tree_data_providers`.
+
+```{note}
+  If you would like to make a library compatible with `iplotx` (by developing a provider), we are here to help! Just reach out on GitHub issues and we will try to help.
+```