Plotting

Plotting helpers from annnet.utils.plotting.

annnet.utils.plotting

Functions

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 number_of_edges(), 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.

plot(graph, *, backend='graphviz', 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 with Graphviz or Pydot.

Parameters:

Name	Type	Description	Default
graph	object	AnnNet-like object with vertices(), get_edge(), get_attr_edge(), etc.	required
backend	('graphviz', 'pydot')	Visualization backend to use. Default is 'graphviz'.	'graphviz'
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
Digraph or Dot	A styled, backend-specific graph object suitable for rendering or exporting.

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(obj, path, format='svg')

Render a Graphviz or Pydot graph object to disk and return the output path.

Parameters:

Name	Type	Description	Default
obj	Digraph or Dot	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().
• The file extension is appended automatically if not present.