Plotting

Plotting helpers from annnet.utils.plotting.

plot(..., backend="auto") selects the first installed plotting backend in preference order: Graphviz, pydot, then matplotlib. The matplotlib path is a minimal native fallback that does not require NetworkX, Graphviz, or pydot. Use set_default_plot_backend to configure the process-wide default used when plot(..., backend=None).

annnet.utils.plotting

Functions

build_vertex_labels

build_vertex_labels(graph, key=None)

Build display labels for graph vertices.

build_edge_labels

build_edge_labels(
    graph, *, use_weight=True, extra_keys=None, layer=None
)

Build display labels for graph edges.

edge_style_from_weights

edge_style_from_weights(
    graph,
    *,
    layer=None,
    min_width=0.5,
    max_width=5.0,
    color_mode="greys"
)

Compute visual edge styles (pen width and color) from effective weights.

Parameters:

Name	Type	Description	Default
`graph`	`object`	AnnNet-like object exposing `ne`, `idx_to_edge`, and `get_effective_edge_weight(eid, layer)` methods.	required
`layer`	`str`	Layer name for retrieving edge weights. Defaults to `None`, which uses global weights.	`None`
`min_width`	`float`	Minimum line width for edges. Default is 0.5.	`0.5`
`max_width`	`float`	Maximum line width for edges. Default is 5.0.	`5.0`
`color_mode`	`('greys', 'signed')`	Edge coloring mode: - `'greys'` : map absolute weight to grayscale (darker = heavier) - `'signed'` : use red for positive, blue for negative, black for zero	`'greys'`

Returns:

Type	Description
`dict[int, dict[str, str]]`	A mapping from edge index to a style dict with keys: - `penwidth` : stroke width (stringified float) - `color` : color name or hex code

Notes

Invalid or missing weights default to 1.0.
Normalization is performed across all edges in the graph.

to_graphviz

to_graphviz(
    graph,
    *,
    layout="dot",
    graph_attr=None,
    node_attr=None,
    edge_attr=None,
    custom_edge_attr=None,
    custom_vertex_attr=None,
    edge_indexes=None,
    orphan_edges=True,
    suppress_warnings=True
)

Convert a graph to a Graphviz Digraph.

to_pydot

to_pydot(
    graph,
    *,
    layout="dot",
    graph_attr=None,
    node_attr=None,
    edge_attr=None,
    custom_edge_attr=None,
    custom_vertex_attr=None,
    edge_indexes=None,
    orphan_edges=True
)

Convert a graph to a pydot Dot graph.

to_matplotlib

to_matplotlib(
    graph,
    *,
    ax=None,
    edge_indexes=None,
    orphan_edges=True,
    show_vertex_labels=True,
    vertex_label_key=None,
    show_edge_labels=False,
    edge_label_keys=None,
    layer=None,
    node_size=900.0,
    node_color="#f5f5f5",
    edge_color="#333333",
    hyperedge_color="#777777"
)

Draw an AnnNet graph with matplotlib and return (figure, axes).

This minimal fallback renderer does not require Graphviz, pydot, or NetworkX. It places vertices on a circle, draws binary directed edges as arrows, undirected binary edges as plain segments, and hyperedges via a small center marker connected to incident vertices.

plot

plot(
    graph,
    *,
    backend=None,
    layout="dot",
    layer=None,
    show_edge_labels=False,
    edge_label_keys=None,
    show_vertex_labels=True,
    vertex_label_key=None,
    use_weight_style=True,
    orphan_edges=True,
    suppress_warnings=True,
    **kwargs
)

Build a fully styled graph object ready for rendering.

Parameters:

Name	Type	Description	Default
`graph`	`object`	AnnNet-like object with `vertices()`, `get_edge()`, `get_attr_edge()`, etc.	required
`backend`	`('auto', 'graphviz', 'pydot', 'matplotlib')`	Visualization backend to use. `None` uses AnnNet's configured plotting default. `'auto'` prefers Graphviz, then pydot, then matplotlib.	`'auto'`
`layout`	`str`	Layout engine (e.g. `'dot'`, `'neato'`). Default is `'dot'`.	`'dot'`
`layer`	`str`	Layer name for weight or label extraction. Default is `None`.	`None`
`show_edge_labels`	`bool`	Whether to include weight and attribute labels on edges. Default is `False`.	`False`
`edge_label_keys`	`list of str`	Extra edge attribute keys to display if `show_edge_labels=True`.	`None`
`show_vertex_labels`	`bool`	Whether to label vertices with IDs or attributes. Default is `True`.	`True`
`vertex_label_key`	`str`	Attribute key for vertex labels. If `None`, uses vertex IDs.	`None`
`use_weight_style`	`bool`	Whether to style edges based on weights. Default is `True`.	`True`
`orphan_edges`	`bool`	Whether to render edges with missing endpoints. Default is `True`.	`True`
`suppress_warnings`	`bool`	Suppress backend rendering warnings (stderr). Default is `True`.	`True`
`**kwargs`		Additional keyword arguments forwarded to `to_graphviz()` or `to_pydot()`.	`{}`

Returns:

Type	Description
`graphviz.Digraph, pydot.Dot, or tuple`	A styled, backend-specific graph object. Matplotlib returns `(figure, axes)`.

Raises:

Type	Description
`ValueError`	If an invalid `backend` name is provided.

Notes

Edge styling and labels are applied before backend construction.
If show_edge_labels=True, edges are regenerated with label overrides.

render

render(obj, path, format='svg')

Render a Graphviz, Pydot, or matplotlib graph object to disk.

Parameters:

Name	Type	Description	Default
`obj`	`graphviz.Digraph, pydot.Dot, matplotlib Figure/Axes, or (Figure, Axes)`	The graph object returned by `plot()`.	required
`path`	`str`	Destination file path (without extension if `format` is specified).	required
`format`	`('svg', 'png', 'raw')`	Output format. Default is `'svg'`. `'png'` and `'raw'` are supported for Pydot.	`'svg'`

Returns:

Type	Description
`str`	Full path to the written output file.

Raises:

Type	Description
`TypeError`	If `obj` is not a supported graph type.

Notes

Graphviz objects use the built-in .render() API.
Pydot objects write directly via .write_svg(), .write_png(), or .write_raw().
Matplotlib figures use .savefig().
The file extension is appended automatically if not present.