✨ Construct

Construct Directed Acyclic Graph (DAG) from list, dictionary, and pandas DataFrame.

DAG Construct Methods

Construct DAG from	Using parent-child relation	Add node attributes
List	`list_to_dag`	No
Dictionary	`dict_to_dag`	Yes
DataFrame	`dataframe_to_dag`	Yes

These functions are not standalone functions. Under the hood, they have the following dependency,

bigtree.dag.construct

list_to_dag

list_to_dag(relations, node_type=DAGNode)

Construct DAG from list of tuples containing parent-child names. Note that node names must be unique.

Examples:

>>> from bigtree import list_to_dag, dag_iterator
>>> relations_list = [("a", "c"), ("a", "d"), ("b", "c"), ("c", "d"), ("d", "e")]
>>> dag = list_to_dag(relations_list)
>>> [(parent.node_name, child.node_name) for parent, child in dag_iterator(dag)]
[('a', 'd'), ('c', 'd'), ('d', 'e'), ('a', 'c'), ('b', 'c')]

Parameters:

Name	Type	Description	Default
`relations`	`List[Tuple[str, str]]`	list containing tuple of parent-child names	required
`node_type`	`Type[DAGNode]`	node type of DAG to be created, defaults to `DAGNode`	`DAGNode`

Returns:

Type	Description
`DAGNode`	(DAGNode)

dict_to_dag

dict_to_dag(
    relation_attrs, parent_key="parents", node_type=DAGNode
)

Construct DAG from nested dictionary, key: child name, value: dictionary of parent names, attribute name, and attribute value. Note that node names must be unique.

Examples:

>>> from bigtree import dict_to_dag, dag_iterator
>>> relation_dict = {
...     "a": {"step": 1},
...     "b": {"step": 1},
...     "c": {"parents": ["a", "b"], "step": 2},
...     "d": {"parents": ["a", "c"], "step": 2},
...     "e": {"parents": ["d"], "step": 3},
... }
>>> dag = dict_to_dag(relation_dict, parent_key="parents")
>>> [(parent.node_name, child.node_name) for parent, child in dag_iterator(dag)]
[('a', 'd'), ('c', 'd'), ('d', 'e'), ('a', 'c'), ('b', 'c')]

Parameters:

Name	Type	Description	Default
`relation_attrs`	`Dict[str, Any]`	dictionary containing node, node parents, and node attribute information, key: child name, value: dictionary of parent names, node attribute, and attribute value	required
`parent_key`	`str`	key of dictionary to retrieve list of parents name, defaults to 'parent'	`'parents'`
`node_type`	`Type[DAGNode]`	node type of DAG to be created, defaults to `DAGNode`	`DAGNode`

Returns:

Type	Description
`DAGNode`	(DAGNode)

dataframe_to_dag

dataframe_to_dag(
    data,
    child_col="",
    parent_col="",
    attribute_cols=[],
    node_type=DAGNode,
)

Construct DAG from pandas DataFrame. Note that node names must be unique.

child_col and parent_col specify columns for child name and parent name to construct DAG.
attribute_cols specify columns for node attribute for child name.
If columns are not specified, child_col takes first column, parent_col takes second column, and all other columns are attribute_cols.

Only attributes in attribute_cols with non-null values will be added to the tree.

Examples:

>>> import pandas as pd
>>> from bigtree import dataframe_to_dag, dag_iterator
>>> relation_data = pd.DataFrame([
...     ["a", None, 1],
...     ["b", None, 1],
...     ["c", "a", 2],
...     ["c", "b", 2],
...     ["d", "a", 2],
...     ["d", "c", 2],
...     ["e", "d", 3],
... ],
...     columns=["child", "parent", "step"]
... )
>>> dag = dataframe_to_dag(relation_data)
>>> [(parent.node_name, child.node_name) for parent, child in dag_iterator(dag)]
[('a', 'd'), ('c', 'd'), ('d', 'e'), ('a', 'c'), ('b', 'c')]

Parameters:

Name	Type	Description	Default
`data`	`DataFrame`	data containing path and node attribute information	required
`child_col`	`str`	column of data containing child name information, defaults to '' if not set, it will take the first column of data	`''`
`parent_col`	`str`	column of data containing parent name information, defaults to '' if not set, it will take the second column of data	`''`
`attribute_cols`	`List[str]`	columns of data containing child node attribute information, if not set, it will take all columns of data except `child_col` and `parent_col`	`[]`
`node_type`	`Type[DAGNode]`	node type of DAG to be created, defaults to `DAGNode`	`DAGNode`

Returns:

Type	Description
`DAGNode`	(DAGNode)