aiida.tools.visualization package#

Provides tools for visualization of the provenance graph.

Submodules#

provides functionality to create graphs of the AiiDa data providence, via graphviz.

class aiida.tools.visualization.graph.Graph(engine: str | None = None, graph_attr: dict | None = None, global_node_style: dict | None = None, global_edge_style: dict | None = None, include_sublabels: bool = True, link_style_fn: LinkStyleFunc | None = None, node_style_fn: Callable[[orm.Node], dict] | None = None, node_sublabel_fn: Callable[[orm.Node], str] | None = None, node_id_type: Literal['pk', 'uuid', 'label'] = 'pk', backend: StorageBackend | None = None)[source]#

Bases: object

A class to create graphviz graphs of the AiiDA node provenance.

__dict__ = mappingproxy({'__module__': 'aiida.tools.visualization.graph', '__doc__': 'A class to create graphviz graphs of the AiiDA node provenance.', '__init__': <function Graph.__init__>, 'backend': <property object>, 'graphviz': <property object>, 'nodes': <property object>, 'edges': <property object>, '_load_node': <function Graph._load_node>, 'add_node': <function Graph.add_node>, 'add_edge': <function Graph.add_edge>, '_convert_link_types': <staticmethod(<function Graph._convert_link_types>)>, 'add_incoming': <function Graph.add_incoming>, 'add_outgoing': <function Graph.add_outgoing>, 'recurse_descendants': <function Graph.recurse_descendants>, 'recurse_ancestors': <function Graph.recurse_ancestors>, 'add_origin_to_targets': <function Graph.add_origin_to_targets>, 'add_origins_to_targets': <function Graph.add_origins_to_targets>, '__dict__': <attribute '__dict__' of 'Graph' objects>, '__weakref__': <attribute '__weakref__' of 'Graph' objects>, '__annotations__': {'_nodes': 'set[int]', '_edges': 'set[tuple[int, int, None | LinkPair]]'}})#

__init__(engine: str | None = None, graph_attr: dict | None = None, global_node_style: dict | None = None, global_edge_style: dict | None = None, include_sublabels: bool = True, link_style_fn: LinkStyleFunc | None = None, node_style_fn: Callable[[orm.Node], dict] | None = None, node_sublabel_fn: Callable[[orm.Node], str] | None = None, node_id_type: Literal['pk', 'uuid', 'label'] = 'pk', backend: StorageBackend | None = None)[source]#

A class to create graphviz graphs of the AiiDA node provenance

Nodes and edges, are cached, so that they are only created once

Parameters:

engine – the graphviz engine, e.g. dot, circo
graph_attr – attributes for the graphviz graph
global_node_style – styles which will be added to all nodes. Note this will override any builtin attributes
global_edge_style – styles which will be added to all edges. Note this will override any builtin attributes
include_sublabels – if True, the note text will include node dependant sub-labels
link_style_fn – callable mapping LinkType to graphviz style dict; link_style_fn(link_type, add_label, add_type) -> dict
node_sublabel_fn – callable mapping nodes to a graphviz style dict; node_sublabel_fn(node) -> dict
node_sublabel_fn – callable mapping data node to a sublabel (e.g. specifying some attribute values) node_sublabel_fn(node) -> str
node_id_type – the type of identifier to within the node text

__module__ = 'aiida.tools.visualization.graph'#

__weakref__#: list of weak references to the object (if defined)

static _convert_link_types(link_types: None | str | LinkType | Sequence[str] | Sequence[LinkType]) → tuple[LinkType, ...][source]#: Convert link types, which may be strings, to a member of LinkType

_load_node(node: int | str | Node) → Node[source]#

Load a node (if not already loaded)

Parameters:: node – node or node pk/uuid

Add single node to the graph

Parameters:

in_node – node or node pk/uuid
out_node – node or node pk/uuid
link_pair – defining the relationship between the nodes
style – graphviz style parameters
overwrite – whether to overwrite existing edge

Add nodes and edges for incoming links to a node

Parameters:

node – node or node pk/uuid
link_types – filter by link types
annotate_links – label edges with the link ‘label’, ‘type’ or ‘both’
return_pks – whether to return a list of nodes, or list of node pks

Returns:

list of nodes or node pks

add_node(node: int | str | Node, style_override: dict | None = None, overwrite: bool = False) → Node[source]#

Add single node to the graph

Parameters:

node – node or node pk/uuid
style_override – graphviz style parameters that will override default values
overwrite – whether to overwrite an existing node

add_origin_to_targets(origin: int | str | Node, target_cls: type[Node], target_filters: dict | None = None, include_target_inputs: bool = False, include_target_outputs: bool = False, origin_style: Mapping[str, Any] | None = None, annotate_links: Literal[None, 'label', 'type', 'both'] | None = None) → None[source]#

Add nodes and edges from an origin node to all nodes of a target node class.

Parameters:

origin – node or node pk/uuid
target_cls – target node class
target_filters – filters for query of target nodes
include_target_inputs – Include incoming links for all target nodes
include_target_outputs – Include outgoing links for all target nodes
origin_style – node style map for origin node
annotate_links – label edges with the link ‘label’, ‘type’ or ‘both’

add_origins_to_targets(origin_cls: type[Node], target_cls: type[Node], origin_filters: dict | None = None, target_filters: dict | None = None, include_target_inputs: bool = False, include_target_outputs: bool = False, origin_style: Mapping[str, Any] | None = None, annotate_links: Literal[None, 'label', 'type', 'both'] | None = None) → None[source]#

Add nodes and edges from all nodes of an origin class to all node of a target node class.

Parameters:

origin_cls – origin node class
target_cls – target node class
origin_filters – filters for origin nodes
target_filters – filters for target nodes
include_target_inputs – Include incoming links for all target nodes
include_target_outputs – Include outgoing links for all target nodes
origin_style – node style map for origin node
annotate_links – label edges with the link ‘label’, ‘type’ or ‘both’

Add nodes and edges for outgoing links to a node

Parameters:

node – node or node pk
link_types – filter by link types
annotate_links – label edges with the link ‘label’, ‘type’ or ‘both’
return_pks – whether to return a list of nodes, or list of node pks

Returns:

list of nodes or node pks

property backend: StorageBackend#: The backend used to create the graph

property edges: set[tuple[int, int, None | LinkPair]]#: Return a copy of the edges

property graphviz: Digraph#: Return a copy of the graphviz.Digraph

property nodes: set[int]#: Return a copy of the nodes

Add nodes and edges from an origin recursively, following incoming links

Parameters:

origin – node or node pk/uuid
depth – if not None, stop after travelling a certain depth into the graph
link_types – filter by subset of link types
annotate_links – label edges with the link ‘label’, ‘type’ or ‘both’
origin_style – node style map for origin node
include_process_outputs – include outgoing links for all processes
highlight_classes – class label (as displayed in the graph, e.g. ‘StructureData’, ‘FolderData’, etc.) to be highlight and other nodes are decolorized

Add nodes and edges from an origin recursively, following outgoing links

Parameters:

origin – node or node pk/uuid
depth – if not None, stop after travelling a certain depth into the graph
link_types – filter by subset of link types
annotate_links – label edges with the link ‘label’, ‘type’ or ‘both’
origin_style – node style map for origin node
include_calculation_inputs – include incoming links for all processes
highlight_classes – target class in exported graph expected to be highlight and other nodes are decolorized

class aiida.tools.visualization.graph.LinkStyleFunc(*args, **kwargs)[source]#

Bases: Protocol

Protocol for a link style function

__abstractmethods__ = frozenset({})#

__call__(link_pair: LinkPair, add_label: bool, add_type: bool) → dict[source]#: Call self as a function.

__dict__ = mappingproxy({'__module__': 'aiida.tools.visualization.graph', '__doc__': 'Protocol for a link style function', '__call__': <function LinkStyleFunc.__call__>, '__dict__': <attribute '__dict__' of 'LinkStyleFunc' objects>, '__weakref__': <attribute '__weakref__' of 'LinkStyleFunc' objects>, '__parameters__': (), '_is_protocol': True, '__subclasshook__': <function Protocol.__init_subclass__.<locals>._proto_hook>, '__init__': <function _no_init_or_replace_init>, '__abstractmethods__': frozenset(), '_abc_impl': <_abc._abc_data object>, '__annotations__': {}})#

__init__(*args, **kwargs)#

__module__ = 'aiida.tools.visualization.graph'#

__parameters__ = ()#

__subclasshook__()#

Abstract classes can override this to customize issubclass().

This is invoked early on by abc.ABCMeta.__subclasscheck__(). It should return True, False or NotImplemented. If it returns NotImplemented, the normal algorithm is used. Otherwise, it overrides the normal algorithm (and the outcome is cached).

__weakref__#: list of weak references to the object (if defined)

_abc_impl = <_abc._abc_data object>#

_is_protocol = True#

aiida.tools.visualization.graph._add_graphviz_edge(graph: Digraph, in_node: Node, out_node: Node, style: dict | None = None) → dict[source]#

Add graphviz edge between two nodes

Parameters:

graph – the graphviz.DiGraph to add the edge to
in_node – the head node
out_node – the tail node
style – the graphviz style

aiida.tools.visualization.graph._add_graphviz_node(graph: Digraph, node: Node, node_style_func, node_sublabel_func, style_override: dict | None = None, include_sublabels: bool = True, id_type: Literal['pk', 'uuid', 'label'] = 'pk')[source]#

Create a node in the graph

The first line of the node text is always ‘<node.name> (<node.pk>)’. Then, if include_sublabels=True, subsequent lines are added, which are node type dependant.

Parameters:

graph – the graphviz.Digraph to add the node to
node – the node to add
node_style_func – callable mapping a node instance to a dictionary defining the graphviz node style
node_sublabel_func – callable mapping a node instance to a sub-label for the node text
style_override – style dictionary, whose keys will override the final computed style
include_sublabels – whether to include the sublabels for nodes
id_type – the type of identifier to use for node labels

Nodes are styled based on the node type

For subclasses of Data, the class_node_type attribute is used for mapping to type specific styles

For subclasses of ProcessNode, we choose styles to distinguish between types, and also color the nodes for successful/failed processes

aiida.tools.visualization.graph._default_ignore_node_styles() → dict[source]#: Return the default style for ignored nodes.

aiida.tools.visualization.graph._default_origin_node_styles() → dict[source]#: Return the default style for origin nodes.

aiida.tools.visualization.graph._get_node_label(node: Node, id_type: Literal['pk', 'uuid', 'label'] = 'pk') → str[source]#: Return a label text of node and the return format is ‘<NodeType> (<id>)’.

aiida.tools.visualization.graph.default_link_styles(link_pair: LinkPair, add_label: bool, add_type: bool) → dict[source]#

Map link_pair to a graphviz edge style

Parameters:

link_type – a LinkPair attribute
add_label – include link label
add_type – include link type

aiida.tools.visualization.graph.default_node_styles(node: Node) → dict[source]#

Map a node to a graphviz node style

Parameters:: node – the node to map

aiida.tools.visualization.graph.default_node_sublabels(node: Node) → str[source]#

Function mapping nodes to a sub-label (e.g. specifying some attribute values)

Parameters:: node – the node to map

aiida.tools.visualization.graph.get_node_id_label(node: Node, id_type: Literal['pk', 'uuid', 'label']) → str[source]#: Return an identifier str for the node

aiida.tools.visualization.graph.pstate_node_styles(node: Node) → dict[source]#

Map a process node to a graphviz node style

Parameters:: node – the node to map