Plotting

Draw a graph with Graphviz, pydot or Matplotlib. plot builds the drawing, and a notebook shows it. save writes it to a file.

from annnet.utils import plot, save

drawing = plot(anet, layout='dot')
save(drawing, 'network', format='svg')  # writes network.svg

plot(..., backend='auto') uses the first installed backend in this order: Graphviz, pydot, Matplotlib. The Matplotlib backend needs no other library. To change the default backend, call annnet.set_default_plot_backend.

show_cytoscape shows the graph as an interactive Cytoscape.js network: in the notebook with inline=True, otherwise in the browser.

from annnet.utils import show_cytoscape

show_cytoscape(anet, inline=True)

annnet.utils.plotting.plot

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

Build a styled graph object to display or to write with :func:save.

Parameters:

Name	Type	Description	Default
`graph`	`AnnNet or GraphView`	The graph or view to draw.	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_node_labels`	`bool`	Whether to label nodes with IDs or attributes. Default is `True`.	`True`
`node_label_key`	`str`	Attribute key for node labels. If `None`, uses node 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.

annnet.utils.plotting.save

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

Write a Graphviz, pydot or matplotlib graph object to a file.

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.

annnet.utils.plotting.show_cytoscape

show_cytoscape(
    graph,
    *,
    export_name="annnet export",
    layer=None,
    include_inter=False,
    include_coupling=False,
    hyperedges="skip",
    port=None,
    auto_open=True,
    inline=False,
    height="520px"
)

Show the graph as an interactive Cytoscape.js network.

The graph goes through :func:annnet.io.to_cx2 first, so the layer and hyperedge options are those of the CX2 export. In a Jupyter notebook, inline=True shows the network in the cell output. Otherwise the function starts a local web server and opens the view in the browser.

Parameters:

Name	Type	Description	Default
`graph`	`AnnNet`	The graph to show.	required
`export_name`	`str`	Name of the network display.	`"annnet export"`
`layer`	`tuple of str`	Elementary layer tuple specifying which layer to visualize. If None, shows the entire graph (may include coupling edges as self-loops). Example: layer=("social", "2020") for a 2-aspect multilayer network.	`None`
`include_inter`	`bool`	When layer is specified, whether to include interlayer edges (edges between nodes in different layers but same aspect). Only relevant if layer is not None.	`False`
`include_coupling`	`bool`	When layer is specified, whether to include coupling edges (edges connecting the same node across layers). Only relevant if layer is not None. Warning: Including coupling creates self-loops in the visualization.	`False`
`hyperedges`	`('skip', 'expand', 'reify')`	How to handle hyperedges: - "skip": Omit hyperedges entirely - "expand": Convert to cartesian product of pairwise edges - "reify": Create explicit hyperedge nodes with membership edges	`"skip"`
`port`	`int`	Port for local web server. If None, finds available port automatically.	`None`
`auto_open`	`bool`	If True, automatically open browser.	`True`
`inline`	`bool`	If True, return the view as notebook output instead of starting a web server.	`False`
`height`	`str`	Height of the inline view.	`"520px"`

Returns:

Type	Description
`str or HTML`	The local URL of the view, or the inline view if `inline=True`.

Notes

For multilayer graphs: - Without layer parameter: shows entire flattened graph with coupling edges appearing as self-loops (messy but shows full structure) - With layer parameter: shows clean single-layer view without coupling edges (recommended for visualization)

Press Ctrl+C in terminal to stop the web server.

Examples:

>>> show_cytoscape(anet, inline=True)  # in a notebook
>>> show_cytoscape(anet)  # all layers flattened, in the browser
>>> show_cytoscape(anet, layer=('social', '2020'))  # one layer

annnet.utils.plotting.to_graphviz

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

Convert a graph to a Graphviz Digraph.

annnet.utils.plotting.to_pydot

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

Convert a graph to a pydot Dot graph.

annnet.utils.plotting.to_matplotlib

to_matplotlib(
    graph,
    *,
    ax=None,
    edge_indexes=None,
    orphan_edges=True,
    show_node_labels=True,
    node_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 nodes 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 nodes.