ragraph.analysis._utils#

Utility functions for managing the graph object during analysis.

Module Contents#

Functions#

create_parent(→ ragraph.node.Node)

Add a parent node for given children to a given graph.

get_available_name(→ str)

Get an available node name starting with prefix, appended the first integer

inherit_edges(→ None)

Let a cluster root nodes inherit all edges from their direct children

set_children(→ None)

Safely set children of parent node.

unset_parent(→ None)

Clearing the parent of a node. Moves sole siblings upwards, replacing the parent.

clear_local_hierarchy(→ None)

Strip a local hierarchy between a given root node and leaf nodes, removing all
ragraph.analysis._utils.create_parent(graph: ragraph.graph.Graph, children: Union[List[ragraph.node.Node], List[str]], prefix: str = 'node', lower: int = 0, **node_kwargs) → ragraph.node.Node#

Add a parent node for given children to a given graph.

Parameters:

  • graph – Graph to create parent in.

  • children – Children to add a parent node for.

  • prefix – Parent name prefix, will be appended by first available integer.

  • lower – Lower bound for integer to append to parent name prefix.

  • kwargs –

Returns:

Created parent node.

ragraph.analysis._utils.get_available_name(graph: ragraph.graph.Graph, prefix: str, lower: int) → str#

Get an available node name starting with prefix, appended the first integer that is free starting at lower.

Parameters:

  • graph – Graph to check availability in.

  • prefix – Node name prefix, will be appended by first available integer.

  • lower – Lower bound for integer to append to name prefix.

Returns:

First available node name not in graph.node_dict.

ragraph.analysis._utils.inherit_edges(graph: ragraph.graph.Graph, new_parents: Iterable[Union[str, ragraph.node.Node]], parent_siblings: Iterable[Union[str, ragraph.node.Node]]) → None#

Let a cluster root nodes inherit all edges from their direct children (not descendants).

Parameters:

  • graph – Graph to work in.

  • new_parents – New parent nodes to recreate edges for.

  • parent_siblings – Already existing parent siblings.

Note

Sometimes a clustering iteration does not introduce a new parent for every node, hence the distinction in parent nodes. New parent nodes look for edges from/to their children where old parent nodes already have edges (as this method has probably been called before). In general, it’s better to wait with edge recreation until the graph’s hierarchy is complete. Inserting and moving nodes half-way a tree would have way too many implications for the edges.

ragraph.analysis._utils.set_children(graph: ragraph.graph.Graph, parent: ragraph.node.Node, children: List[ragraph.node.Node]) → None#

Safely set children of parent node.

Parameters:

  • graph – Graph to work in.

  • parent – Parent node.

  • children – Children to set.

Note

If the children are attempted to be set to the parent itself, return. If children has length 1, the grandchildren are used and child is deleted. If children has length 1 and it is a leaf node, a ValueError is raised.

ragraph.analysis._utils.unset_parent(graph: ragraph.graph.Graph, node: ragraph.node.Node, roots: Optional[List[ragraph.node.Node]] = None) → None#

Clearing the parent of a node. Moves sole siblings upwards, replacing the parent.

Parameters:

  • graph – Graph to work in.

  • node – The node of which the parent must be cleared.

  • roots – Roots are protected nodes that are never deleted.

Note

The node is has its parent unset and is therefore removed from the parent’s children. The parent may have just a single other child left, in which case that child node should replace the parent altogether. When it has more children, it is kept intact.

Example

Unsetting the parent of “a” in the following tree:

       g
   ____|____
  |         |
  e         f
 _|_     ___|___
|   |   |   |   |
a   b   c   d   e

leaves the following forest:

a        g
     ____|____
    |         |
    b         f
           ___|___
          |   |   |
          c   d   e

in which “a” has become a root and “b” has become a child of “g” since “e” has been removed.

ragraph.analysis._utils.clear_local_hierarchy(graph: ragraph.graph.Graph, leafs: List[ragraph.node.Node], roots: Optional[List[ragraph.node.Node]] = None) → None#

Strip a local hierarchy between a given root node and leaf nodes, removing all non-leaf nodes and setting the root as parent.

Parameters:

  • graph – Graph to strip nodes in.

  • leafs – Lower bound leaf nodes to start from.

  • root – Optional root nodes that are kept intact.