graphit.graph_axis package

graphit.graph_axis.graph_axis_class module

Graph axis methods

Class for traversing and querying (sub)graph hierarchy with respect to a root node.

TODO: Add dict/list like methods for adding new nodes to the graph at a given

level automatically creating the edges to link the new node. Perhaps add some more method to mimick dict/list like behaviour.

class graphit.graph_axis.graph_axis_class.GraphAxis(edges=None, directed=False, nodes=None, data=None, root=None, orm=None, storagedriver=<function init_dictstorage_driver>, **kwargs)

Bases: graphit.graph.GraphBase

Hierarchical graph query and traversal with respect to a root node.

The GraphAxis class extends the Graph base class with methods that enable query and traversal of graphs that have a hierachy with respect to a certain root node. A root node is chosen by node ID (nid) and is the one with the lowest ID (number) by default or any other one chosen at a later time. Hierarchy is queried with respect to the root node by means of axis that include: children, descendants, leaves, neighours, siblings, parents and ancestors.

These methods return selections, or sub-graphs, that represent the respective axis. By default these selections maintain full connectivity to the full graphs and thus represent a selective ‘view’ on the full graph. This behaviour can be changed by enabling a ‘mask’ on the selection or by copying the selection into a new independent graph. The behaviour of both options are the same, connectivity is maintained with the selection but outside of it. The benefit of a mask, enabled by settings ‘masked’ to True, is that it is non-destructive to the data and can be easily lifted again.

The behaviour of axis methods is furthermore affected by the directivety of the graph. The default non-directive graphs can be fully traversed forwards and backwards. Directed graphs or mixed graphs block traversal to parts of the graph by lack of an edge to traverse over.

All of the axis methods are wrappers around their respective function in graphit.graph_axis.graph_axis_methods. These functions return node ID’s that are used by the wrapper method to return the respective sub-graph or node ID’s with ‘return_nids’ equals True.

adjacency

all_parents(node=None, include_self=False, return_nids=False)

Get all parent nodes to the source node relative to the graph root

Directed graphs and/or masked behaviour: masked nodes or directed nodes not having an edge from source to node will not be returned.

Parameters

• node (:py:int, :py:str) – node to define parents of

• include_self (:py:bool) – include source nid in results

• return_nids (:py:bool) – return parent nid instead of a new graph object representing the selection

Returns

all parents of the node

Return type

:graphit:graph, :py:list

ancestors(node=None, include_self=False, return_nids=False)

Return the ancestors of the source node

Traversal path is determined as the shortest path between the root node and the target node (Dijkstra shortest path).

Directed graphs and/or masked behaviour: if the target node is not reachable using the Dijkstra shortest path method, the selection will remain empty.

Parameters

• node (:py:int, :py:str) – source node to start search from

• include_self (:py:bool) – include source nid in results

• return_nids (:py:bool) – return a list of node ID’s (nid) instead of a new graph object representing the selection

Returns

node ancestors

Return type

:graphit:graph, :py:list

children(node=None, include_self=False, parent=None, return_nids=False)

Return the children of the source node.

Traversal path is determined from the parent node with respect to the root via the source node to the children.

Directed graphs and/or masked behaviour: masked child nodes or child nodes with directed connections from child to parent but not vice-versa will not be returned.

Parameters

• node (:py:int, :py:str) – source node to start search from

• include_self (:py:bool) – include source nid in results

• parent (:py:int, :py:str) – parent nid if known

• return_nids (:py:bool) – return a list of node ID’s (nid) instead of a new graph object representing the selection

Returns

node children

Return type

:graphit:graph, :py:list

data

descendants(node=None, include_self=False, return_nids=False)

Return all descendants nodes to the source node

Traversal path is determined from the parent with respect to the root node to the source node and then all descendants of the source.

Directed graphs and/or masked behaviour: masked descendant linage’s or linage’s unreachable by directed edges are not returned.

Parameters

• node (:py:int, :py:str) – source node to start search from

• include_self (:py:bool) – include source nid in results

• return_nids (:py:bool) – return a list of node ID’s (nid) instead of a new graph object representing the selection

Returns

node descendants

Return type

:graphit:graph, :py:list

directed

edge_tools

edges

get_root()

Convenience method for returning the root node of a graph

items(keystring=None, valuestring=None, desc=True)

Python dict-like function to return node items in the (sub)graph.

Keystring defines the value lookup key in the node data dict. This defaults to the graph key_tag. Valuestring defines the value lookup key in the node data dict.

Parameters

• keystring (:py:str) – Data key to use for dictionary keys.

• valuestring (:py:str) – Data key to use for dictionary values.

• desc (:py:bool) – return nested values as new GraphAxis objects

Returns

List of keys, value pairs

Return type

:py:list

keys(keystring=None, desc=False)

Python dict-like function to return node keys in the (sub)graph.

Keystring defines the key lookup in the node data dict.

Parameters

• keystring (:py:str) – Data key to use for dictionary keys.

• desc (:py:bool) – return nested values as new GraphAxis objects

Returns

List of keys

Return type

:py:list

leaves(return_nids=False, include_root=False, include_isolated=False)

Return all leaf nodes in the (sub)graph

Directed graphs and/or masked behaviour: leaf nodes are identified as those nodes having one edge only. This equals one adjacency node in an undirectional graph and no adjacency nodes in a directed graph.

Graph root nodes do not affect the character of a node being a leave, neither will unidirectional versus directional edges.

Parameters

• include_root (:py:bool) – include the root node if it is a leaf

• return_nids (:py:bool) – return a list of node ID’s (nid) instead of a new graph object representing the selection

• include_isolated (:py:bool) – Include isolated nodes in the result

Returns

leaf nodes

Return type

:graphit:graph, :py:list

masked

neighbors(node=None, include_self=False, return_nids=False)

Return de neighbor nodes of the source node.

This method is not hierarchical and thus the root node has no effect.

Directed graphs and/or masked behaviour: masked nodes or directed nodes not having an edge from source to node will not be returned.

Parameters

• node (:py:int, :py:str) – node to return neighbors for

• include_self (:py:bool) – include source nid in results

• return_nids (:py:bool) – return a list of node ID’s (nid) instead of a new graph object representing the selection

Returns

node neighbors

Return type

:graphit:graph, :py:list

node_tools

nodes

origin

orm

parent(node=None, include_self=False, return_nids=False)

Get the parent node of the source node relative to the graph root when following the shortest path (Dijkstra shortest path).

Parameters

• node (:py:int, :py:str) – node to define parent of

• include_self (:py:bool) – include source nid in results

• return_nids (:py:bool) – return parent nid instead of a new graph object representing the selection

Returns

parent node

Return type

:graphit:graph, :py:list

root

siblings(node=None, include_self=False, parent=None, return_nids=False)

Get the siblings of the source node

Directed graphs and/or masked behaviour: masked nodes or directed nodes not having an edge from source to node will not be returned.

Parameters

• node (:py:int, :py:str) – source node to start search from

• include_self (:py:bool) – include source nid in results

• parent (:py:int, :py:str) – parent nid if known

• return_nids (:py:bool) – return a list of node ID’s (nid) instead of a new graph object representing the selection

Returns

node siblings

Return type

:graphit:graph, :py:list

storagedriver

update(data)

Python dict-like update method for recursive update graph nodes from dictionary or other graph.

Parameters

data – dictionary or graph to update from

values(valuestring=None, desc=True)

Python dict-like function to return node values in the (sub)graph.

Valuestring defines the value lookup key in the node data dict.

Parameters

• valuestring (:py:str) – Data key to use for dictionary values.

• desc (:py:bool) – return nested values as new GraphAxis objects

Returns

List of values

Return type

:py:list

xpath(expression, sep='/')

Evaluate XPath expression against graph

Parameters

• expression (:py:str) – XPath axpression

• sep (:py:str) – XPath path location seperator

Return type

:graphit:GraphAxis

graphit.graph_axis.graph_axis_methods module

Graph axis methods

Functions for traversing and querying (sub)graph hierarchy with respect to a root node. These functions are similar to the axis methods commonly found in XML libraries.

All these functions accept a (sub)graph, a node id (nid) to query axis based hierarchy for and a root nid relative to which the hierarchy should be defined.

graphit.graph_axis.graph_axis_methods.closest_to(graph, source, target)

Determine which of the target nodes are closest to the source node.

This method is not hierarchical and thus the root node has no effect.

Parameters

• graph (Graph class instance) – Graph to perform calculation for

• source (:py:int, :py:str) – source node id

• target (:py:list) – target node id’s

Return type

:py:list

graphit.graph_axis.graph_axis_methods.node_neighbors(graph, nid)

Return de neighbor nodes of the node.

This method is not hierarchical and thus the root node has no effect.

Directed graphs and/or masked behaviour: masked nodes or directed nodes not having an edge from source to node will not be returned.

Parameters

• graph (Graph class instance) – Graph to query

• nid (:py:int) – node ID to return neighbors for

graphit.graph_axis.graph_axis_methods.node_all_parents(graph, nid, root)

Get all parent nodes to the source node relative to the graph root

Directed graphs and/or masked behaviour: masked nodes or directed nodes not having an edge from source to node will not be returned.

Parameters

• graph (Graph class instance) – Graph to perform calculation for

• nid (:py:int, :py:str) – source node to start search from

• root (:py:int, :py:str) – root node for the search

Returns

parent node ID’s

Return type

:py:list

graphit.graph_axis.graph_axis_methods.node_ancestors(graph, nid, root, include_self=False)

Return the ancestors of the source node

Traversal path is determined as the shortest path between the root node and the target node (Dijkstra shortest path).

This function always uses the full graph to return the ancestors. For masked graphs, check afterwards if the ancestors are in the graph node view or use the GraphAxis ‘ancestors’ method that performs that check.

Parameters

• graph (Graph class instance) – Graph to perform calculation for

• nid (:py:int, :py:str) – source node to start search from

• root (:py:int, :py:str) – root node for the search

• include_self (:py:bool) – include source nid in results

Returns

ancestor node ID’s

Return type

:py:list

graphit.graph_axis.graph_axis_methods.node_children(graph, nid, root, include_self=False, parent=None)

Return the children of the source node.

Traversal path is determined from the parent node with respect to the root via the source node to the children. A speedup can be achieved by proving the known parent nid using the parent argument no longer requiring a call to node_parent.

Directed graphs and/or masked behaviour: masked child nodes or child nodes with directed connections from child to parent but not vice-versa will not be returned.

Parameters

• graph (Graph class instance) – Graph to perform calculation for

• nid (:py:int, :py:str) – source node to start search from

• root (:py:int, :py:str) – root node for the search

• include_self (:py:bool) – include source nid in results

• parent (:py:int, :py:str) – parent nid if known

Returns

children node ID’s

Return type

:py:list

graphit.graph_axis.graph_axis_methods.node_descendants(graph, nid, root, include_self=False)

Return all descendants nodes to the source node

Traversal path is determined from the parent with respect to the root node to the source node and then all descendants of the source.

Directed graphs and/or masked behaviour: masked descendant linage’s or linage’s unreachable by directed edges are not returned.

Parameters

• graph (Graph class instance) – Graph to perform calculation for

• nid (:py:int, :py:str) – source node to start search from

• root (:py:int, :py:str) – root node for the search

• include_self (:py:bool) – include source nid in results

Returns

descendants node ID’s

Return type

:py:list

graphit.graph_axis.graph_axis_methods.node_leaves(graph, include_isolated=False)

Return all leaf nodes in the graph

Selects all nodes in the graph that are connected to one other node using a directed or undirected edge. The first selection may also include isolated nodes being nodes without any edge to other nodes. These are subsequently removed because they are no ‘leaves’ of a parent node. However, is ‘include_isolated’ is True, they are returned

Graph root nodes do not affect the character of a node being a leaf, directed graphs will if the edge goes from leaf to parent only as this effectively isolates the node from the parents.

Parameters

• graph (Graph class instance) – Graph to perform calculation for

• include_isolated (:py:bool) – Include isolated nodes in the result

Returns

leaf node ID’s

Return type

:py:list

graphit.graph_axis.graph_axis_methods.node_parent(graph, nid, root)

Get the parent node of the source node relative to the graph root when following the shortest path (Dijkstra shortest path).

This function always uses the full graph to return the parent. For masked graphs, check afterwards if the parent is in the graph node view or use the GraphAxis ‘parent’ method that performs that check.

Parameters

• graph (Graph class instance) – Graph to perform calculation for

• nid (:py:int, :py:str) – source node to start search from

• root (:py:int, :py:str) – root node for the search

Returns

parent node ID

Return type

Graph object

graphit.graph_axis.graph_axis_methods.node_siblings(graph, nid, root, parent=None)

Get the siblings of the source node

Directed graphs and/or masked behaviour: masked nodes or directed nodes not having an edge from source to node will not be returned. A speedup can be achieved by proving the known parent nid using the parent argument no longer requiring a call to node_parent.

Parameters

• graph (Graph class instance) – Graph to perform calculation for

• nid (:py:int, :py:str) – source node to start search from

• root (:py:int, :py:str) – root node for the search

• parent (:py:int, :py:str) – parent nid if known

Returns

sibling node ID’s

Return type

:py:list

graphit.graph_axis.graph_axis_mixin module

file: graph_mixin.py

NodeTools and EdgeTools classes for axis based graphs (GraphAxis class)

class graphit.graph_axis.graph_axis_mixin.NodeAxisTools

Bases: graphit.graph_mixin.NodeTools

path(key=None, sep='.')

Build a breadcrumb (path) trail from the root node to the current node.

Parameters

• key (:py:str) – parameter key to build breadcrumb path from

• sep (:py:str) – breadcrumb path seperator character

Returns

breadcrumb path

Return type

:py:str

Module contents