dataframe_to_treedataframe_to_tree_by_relationpolars_to_treepolars_to_tree_by_relationadd_dict_to_tree_by_nameadd_dataframe_to_tree_by_pathadd_dataframe_to_tree_by_nameadd_polars_to_tree_by_pathadd_polars_to_tree_by_namestr_to_tree(
- tree_string, tree_prefix_list=[], node_type=Node
-)
+add_polars_to_tree_by_path(
+ tree,
+ data,
+ path_col="",
+ attribute_cols=[],
+ sep="/",
+ duplicate_name_allowed=True,
+)
- Construct tree from tree string
+ Add nodes and attributes to tree in-place, return root of tree.
+Adds to existing tree from polars DataFrame.
+Only attributes in attribute_cols with non-null values will be added to the tree.
+path_col and attribute_cols specify columns for node path and attributes to add to existing tree.
+If columns are not specified, path_col takes first column and all other columns are attribute_cols
+Path in path column should contain Node name, separated by sep.
+
+- For example: Path string "a/b" refers to Node("b") with parent Node("a").
+- Path separator
sep is for the input path and can differ from existing tree.
+
+Path in path column can start from root node name, or start with sep.
+
+- For example: Path string can be "/a/b" or "a/b", if sep is "/".
+
+All paths should start from the same root node.
+
+- For example: Path strings should be "a/b", "a/c", "a/b/d" etc. and should not start with another root node.
+
Examples:
- >>> from bigtree import str_to_tree
->>> tree_str = 'a\n├── b\n│ ├── d\n│ └── e\n│ ├── g\n│ └── h\n└── c\n └── f'
->>> root = str_to_tree(tree_str, tree_prefix_list=["├──", "└──"])
->>> root.show()
-a
-├── b
-│ ├── d
-│ └── e
-│ ├── g
-│ └── h
-└── c
- └── f
+ >>> import polars as pl
+>>> from bigtree import add_polars_to_tree_by_path, Node
+>>> root = Node("a")
+>>> path_data = pl.DataFrame([
+... ["a", 90],
+... ["a/b", 65],
+... ["a/c", 60],
+... ["a/b/d", 40],
+... ["a/b/e", 35],
+... ["a/c/f", 38],
+... ["a/b/e/g", 10],
+... ["a/b/e/h", 6],
+... ],
+... schema=["PATH", "age"]
+... )
+>>> root = add_polars_to_tree_by_path(root, path_data)
+>>> root.show(attr_list=["age"])
+a [age=90]
+├── b [age=65]
+│ ├── d [age=40]
+│ └── e [age=35]
+│ ├── g [age=10]
+│ └── h [age=6]
+└── c [age=60]
+ └── f [age=38]
@@ -3508,13 +3599,13 @@
- tree_stringtree
- str
+ Node
- String to construct tree
+ existing tree
@@ -3522,14 +3613,43 @@
- tree_prefix_listdata
+ DataFrame
+
+
+
+ data containing node path and attribute information
+
+
+
+ required
+
+
+
+ path_col
+ str
+
+
+
+ column of data containing path_name information,
+if not set, it will take the first column of data
+
+
+
+ ''
+
+
+
+ attribute_cols
List[str]
- List of prefix to mark the end of tree branch/stem and start of node name, optional.
-If not specified, it will infer unicode characters and whitespace as prefix.
+ columns of data containing node attribute information,
+if not set, it will take all columns of data except path_col
@@ -3537,17 +3657,31 @@
- node_typesep
- Type[Node]
+ str
- node type of tree to be created, defaults to Node
+ path separator for input path_col
- Node
+ '/'
+
+
+
+ duplicate_name_allowed
+ bool
+
+
+
+ indicator if nodes with duplicate Node name is allowed, defaults to True
+
+
+
+ True
@@ -3586,50 +3720,43 @@
-
-
+
-list_to_tree(
- paths,
- sep="/",
- duplicate_name_allowed=True,
- node_type=Node,
-)
+
- Construct tree from list of path strings.
-Path should contain Node name, separated by sep.
-
-- For example: Path string "a/b" refers to Node("b") with parent Node("a").
-
-Path can start from root node name, or start with sep.
-
-- For example: Path string can be "/a/b" or "a/b", if sep is "/".
-
-All paths should start from the same root node.
-
-- For example: Path strings should be "a/b", "a/c", "a/b/d" etc. and should not start with another root node.
-
+ Add attributes to existing tree in-place.
+Adds to existing tree from polars DataFrame.
+Only attributes in attribute_cols with non-null values will be added to the tree.
+name_col and attribute_cols specify columns for node name and attributes to add to existing tree.
+If columns are not specified, the first column will be taken as name column and all other columns as attributes.
+Input data node names that are not existing node names will be ignored.
+Note that if multiple nodes have the same name, attributes will be added to all nodes sharing same name.
Examples:
- >>> from bigtree import list_to_tree
->>> path_list = ["a/b", "a/c", "a/b/d", "a/b/e", "a/c/f", "a/b/e/g", "a/b/e/h"]
->>> root = list_to_tree(path_list)
->>> root.show()
-a
-├── b
-│ ├── d
-│ └── e
-│ ├── g
-│ └── h
-└── c
- └── f
+ >>> import polars as pl
+>>> from bigtree import add_polars_to_tree_by_name, Node
+>>> root = Node("a")
+>>> b = Node("b", parent=root)
+>>> name_data = pl.DataFrame([
+... ["a", 90],
+... ["b", 65],
+... ],
+... schema=["NAME", "age"]
+... )
+>>> root = add_polars_to_tree_by_name(root, name_data)
+>>> root.show(attr_list=["age"])
+a [age=90]
+└── b [age=65]
@@ -3646,13 +3773,13 @@
- pathstree
- List[str]
+ Node
- list containing path strings
+ existing tree
@@ -3660,31 +3787,156 @@
- sepdata
+ DataFrame
+
+
+
+ data containing node name and attribute information
+
+
+
+ required
+
+
+
+ name_col
str
- path separator for input paths and created tree, defaults to /
+ column of data containing name information,
+if not set, it will take the first column of data
- '/'
+ ''
- duplicate_name_allowedattribute_cols
- bool
+ List[str]
- indicator if nodes with duplicate Node name is allowed, defaults to True
+ column(s) of data containing node attribute information,
+if not set, it will take all columns of data except path_col
- True
+ []
+
+
+
+
+
+
+
+
Returns:
+
+
+
+ Type
+ Description
+
+
+
+
+
+ Node
+
+
+
+ (Node)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Construct tree from tree string
+
+
+
+Examples:
+ >>> from bigtree import str_to_tree
+>>> tree_str = 'a\n├── b\n│ ├── d\n│ └── e\n│ ├── g\n│ └── h\n└── c\n └── f'
+>>> root = str_to_tree(tree_str, tree_prefix_list=["├──", "└──"])
+>>> root.show()
+a
+├── b
+│ ├── d
+│ └── e
+│ ├── g
+│ └── h
+└── c
+ └── f
+
+
+
+
+ Parameters:
+
+
+
+ Name
+ Type
+ Description
+ Default
+
+
+
+
+ tree_string
+ str
+
+
+
+ String to construct tree
+
+
+
+ required
+
+
+
+ tree_prefix_list
+ List[str]
+
+
+
+ List of prefix to mark the end of tree branch/stem and start of node name, optional.
+If not specified, it will infer unicode characters and whitespace as prefix.
+
+
+
+ []
@@ -3737,30 +3989,41 @@
-
-
+
-list_to_tree_by_relation(
- relations, allow_duplicates=False, node_type=Node
-)
+
- Construct tree from list of tuple containing parent-child names.
-Root node is inferred when parent is empty, or when name appears as parent but not as child.
-Since tree is created from parent-child names, only names of leaf nodes may be repeated.
-Error will be thrown if names of intermediate nodes are repeated as there will be confusion.
-This error can be ignored by setting allow_duplicates to be True.
+ Construct tree from list of path strings.
+Path should contain Node name, separated by sep.
+
+- For example: Path string "a/b" refers to Node("b") with parent Node("a").
+
+Path can start from root node name, or start with sep.
+
+- For example: Path string can be "/a/b" or "a/b", if sep is "/".
+
+All paths should start from the same root node.
+
+- For example: Path strings should be "a/b", "a/c", "a/b/d" etc. and should not start with another root node.
+
Examples:
- >>> from bigtree import list_to_tree_by_relation
->>> relations_list = [("a", "b"), ("a", "c"), ("b", "d"), ("b", "e"), ("c", "f"), ("e", "g"), ("e", "h")]
->>> root = list_to_tree_by_relation(relations_list)
+ >>> from bigtree import list_to_tree
+>>> path_list = ["a/b", "a/c", "a/b/d", "a/b/e", "a/c/f", "a/b/e/g", "a/b/e/h"]
+>>> root = list_to_tree(path_list)
>>> root.show()
a
├── b
@@ -3786,13 +4049,13 @@
- relationspaths
- List[Tuple[str, str]]
+ List[str]
- list containing tuple containing parent-child names
+ list containing path strings
@@ -3800,18 +4063,31 @@
- allow_duplicatessep
+ str
+
+
+
+ path separator for input paths and created tree, defaults to /
+
+
+
+ '/'
+
+
+
+ duplicate_name_allowed
bool
- allow duplicate intermediate nodes such that child node will
-be tagged to multiple parent nodes, defaults to False
+ indicator if nodes with duplicate Node name is allowed, defaults to True
- False
+ True
@@ -3864,61 +4140,514 @@
-
+
-dict_to_tree(
- path_attrs,
- sep="/",
- duplicate_name_allowed=True,
- node_type=Node,
-)
+
+
+
+
+ Construct tree from list of tuple containing parent-child names.
+Root node is inferred when parent is empty, or when name appears as parent but not as child.
+Since tree is created from parent-child names, only names of leaf nodes may be repeated.
+Error will be thrown if names of intermediate nodes are repeated as there will be confusion.
+This error can be ignored by setting allow_duplicates to be True.
+
+
+
+Examples:
+ >>> from bigtree import list_to_tree_by_relation
+>>> relations_list = [("a", "b"), ("a", "c"), ("b", "d"), ("b", "e"), ("c", "f"), ("e", "g"), ("e", "h")]
+>>> root = list_to_tree_by_relation(relations_list)
+>>> root.show()
+a
+├── b
+│ ├── d
+│ └── e
+│ ├── g
+│ └── h
+└── c
+ └── f
+
+
+
+
+ Parameters:
+
+
+
+ Name
+ Type
+ Description
+ Default
+
+
+
+
+ relations
+ List[Tuple[str, str]]
+
+
+
+ list containing tuple containing parent-child names
+
+
+
+ required
+
+
+
+ allow_duplicates
+ bool
+
+
+
+ allow duplicate intermediate nodes such that child node will
+be tagged to multiple parent nodes, defaults to False
+
+
+
+ False
+
+
+
+ node_type
+ Type[Node]
+
+
+
+ node type of tree to be created, defaults to Node
+
+
+
+ Node
+
+
+
+
+
+
+
+ Returns:
+
+
+
+ Type
+ Description
+
+
+
+
+
+ Node
+
+
+
+ (Node)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Construct tree from nested dictionary using path,
+key: path, value: dict of attribute name and attribute value.
+Path should contain Node name, separated by sep.
+
+- For example: Path string "a/b" refers to Node("b") with parent Node("a").
+
+Path can start from root node name, or start with sep.
+
+- For example: Path string can be "/a/b" or "a/b", if sep is "/".
+
+All paths should start from the same root node.
+
+- For example: Path strings should be "a/b", "a/c", "a/b/d" etc. and should not start with another root node.
+
+All attributes in path_attrs will be added to the tree, including attributes with null values.
+
+
+
+Examples:
+ >>> from bigtree import dict_to_tree
+>>> path_dict = {
+... "a": {"age": 90},
+... "a/b": {"age": 65},
+... "a/c": {"age": 60},
+... "a/b/d": {"age": 40},
+... "a/b/e": {"age": 35},
+... "a/c/f": {"age": 38},
+... "a/b/e/g": {"age": 10},
+... "a/b/e/h": {"age": 6},
+... }
+>>> root = dict_to_tree(path_dict)
+>>> root.show(attr_list=["age"])
+a [age=90]
+├── b [age=65]
+│ ├── d [age=40]
+│ └── e [age=35]
+│ ├── g [age=10]
+│ └── h [age=6]
+└── c [age=60]
+ └── f [age=38]
+
+
+
+
+ Parameters:
+
+
+
+ Name
+ Type
+ Description
+ Default
+
+
+
+
+ path_attrs
+ Dict[str, Any]
+
+
+
+ dictionary containing path and node attribute information,
+key: path, value: dict of tree attribute and attribute value
+
+
+
+ required
+
+
+
+ sep
+ str
+
+
+
+ path separator of input path_attrs and created tree, defaults to /
+
+
+
+ '/'
+
+
+
+ duplicate_name_allowed
+ bool
+
+
+
+ indicator if nodes with duplicate Node name is allowed, defaults to True
+
+
+
+ True
+
+
+
+ node_type
+ Type[Node]
+
+
+
+ node type of tree to be created, defaults to Node
+
+
+
+ Node
+
+
+
+
+
+
+
+ Returns:
+
+
+
+ Type
+ Description
+
+
+
+
+
+ Node
+
+
+
+ (Node)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+nested_dict_to_tree(
+ node_attrs,
+ name_key="name",
+ child_key="children",
+ node_type=Node,
+)
+
+
+
+
+ Construct tree from nested recursive dictionary.
+
+key: name_key, child_key, or any attributes key.value of name_key (str): node name.value of child_key (List[Dict[str, Any]]): list of dict containing name_key and child_key (recursive).
+
+
+
+Examples:
+ >>> from bigtree import nested_dict_to_tree
+>>> path_dict = {
+... "name": "a",
+... "age": 90,
+... "children": [
+... {"name": "b",
+... "age": 65,
+... "children": [
+... {"name": "d", "age": 40},
+... {"name": "e", "age": 35, "children": [
+... {"name": "g", "age": 10},
+... ]},
+... ]},
+... ],
+... }
+>>> root = nested_dict_to_tree(path_dict)
+>>> root.show(attr_list=["age"])
+a [age=90]
+└── b [age=65]
+ ├── d [age=40]
+ └── e [age=35]
+ └── g [age=10]
+
+
+
+
+ Parameters:
+
+
+
+ Name
+ Type
+ Description
+ Default
+
+
+
+
+ node_attrs
+ Dict[str, Any]
+
+
+
+ dictionary containing node, children, and node attribute information,
+key: name_key and child_key
+value of name_key (str): node name
+value of child_key (List[Dict[str, Any]]): list of dict containing name_key and child_key (recursive)
+
+
+
+ required
+
+
+
+ name_key
+ str
+
+
+
+ key of node name, value is type str
+
+
+
+ 'name'
+
+
+
+ child_key
+ str
+
+
+
+ key of child list, value is type list
+
+
+
+ 'children'
+
+
+
+ node_type
+ Type[Node]
+
+
+
+ node type of tree to be created, defaults to Node
+
+
+
+ Node
+
+
+
+
+
+
+
+ Returns:
+
+
+
+ Type
+ Description
+
+
+
+
+
+ Node
+
+
+
+ (Node)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+dataframe_to_tree(
+ data,
+ path_col="",
+ attribute_cols=[],
+ sep="/",
+ duplicate_name_allowed=True,
+ node_type=Node,
+)
- Construct tree from nested dictionary using path,
-key: path, value: dict of attribute name and attribute value.
-Path should contain Node name, separated by sep.
+ Construct tree from pandas DataFrame using path, return root of tree.
+path_col and attribute_cols specify columns for node path and attributes to construct tree.
+If columns are not specified, path_col takes first column and all other columns are attribute_cols.
+Only attributes in attribute_cols with non-null values will be added to the tree.
+Path in path column can start from root node name, or start with sep.
-- For example: Path string "a/b" refers to Node("b") with parent Node("a").
+- For example: Path string can be "/a/b" or "a/b", if sep is "/".
-Path can start from root node name, or start with sep.
+Path in path column should contain Node name, separated by sep.
-- For example: Path string can be "/a/b" or "a/b", if sep is "/".
+- For example: Path string "a/b" refers to Node("b") with parent Node("a").
All paths should start from the same root node.
- For example: Path strings should be "a/b", "a/c", "a/b/d" etc. and should not start with another root node.
-All attributes in path_attrs will be added to the tree, including attributes with null values.
Examples:
- >>> from bigtree import dict_to_tree
->>> path_dict = {
-... "a": {"age": 90},
-... "a/b": {"age": 65},
-... "a/c": {"age": 60},
-... "a/b/d": {"age": 40},
-... "a/b/e": {"age": 35},
-... "a/c/f": {"age": 38},
-... "a/b/e/g": {"age": 10},
-... "a/b/e/h": {"age": 6},
-... }
->>> root = dict_to_tree(path_dict)
->>> root.show(attr_list=["age"])
-a [age=90]
-├── b [age=65]
-│ ├── d [age=40]
-│ └── e [age=35]
-│ ├── g [age=10]
-│ └── h [age=6]
-└── c [age=60]
- └── f [age=38]
+ >>> import pandas as pd
+>>> from bigtree import dataframe_to_tree
+>>> path_data = pd.DataFrame([
+... ["a", 90],
+... ["a/b", 65],
+... ["a/c", 60],
+... ["a/b/d", 40],
+... ["a/b/e", 35],
+... ["a/c/f", 38],
+... ["a/b/e/g", 10],
+... ["a/b/e/h", 6],
+... ],
+... columns=["PATH", "age"]
+... )
+>>> root = dataframe_to_tree(path_data)
+>>> root.show(attr_list=["age"])
+a [age=90]
+├── b [age=65]
+│ ├── d [age=40]
+│ └── e [age=35]
+│ ├── g [age=10]
+│ └── h [age=6]
+└── c [age=60]
+ └── f [age=38]
@@ -3935,20 +4664,49 @@
- path_attrsdata
- Dict[str, Any]
+ DataFrame
- dictionary containing path and node attribute information,
-key: path, value: dict of tree attribute and attribute value
+ data containing path and node attribute information
required
+
+ path_col
+ str
+
+
+
+ column of data containing path_name information,
+if not set, it will take the first column of data
+
+
+
+ ''
+
+
+
+ attribute_cols
+ List[str]
+
+
+
+ columns of data containing node attribute information,
+if not set, it will take all columns of data except path_col
+
+
+
+ []
+
+
sep
@@ -3956,7 +4714,7 @@
- path separator of input path_attrs and created tree, defaults to /
+ path separator of input path_col and created tree, defaults to /
@@ -4027,53 +4785,61 @@
-
-
+
-nested_dict_to_tree(
- node_attrs,
- name_key="name",
- child_key="children",
- node_type=Node,
-)
+dataframe_to_tree_by_relation(
+ data,
+ child_col="",
+ parent_col="",
+ attribute_cols=[],
+ allow_duplicates=False,
+ node_type=Node,
+)
- Construct tree from nested recursive dictionary.
-
-key: name_key, child_key, or any attributes key.value of name_key (str): node name.value of child_key (List[Dict[str, Any]]): list of dict containing name_key and child_key (recursive).
+ Construct tree from pandas DataFrame using parent and child names, return root of tree.
+Root node is inferred when parent name is empty, or when name appears in parent column but not in child column.
+Since tree is created from parent-child names, only names of leaf nodes may be repeated.
+Error will be thrown if names of intermediate nodes are repeated as there will be confusion.
+This error can be ignored by setting allow_duplicates to be True.
+child_col and parent_col specify columns for child name and parent name to construct tree.
+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:
- >>> from bigtree import nested_dict_to_tree
->>> path_dict = {
-... "name": "a",
-... "age": 90,
-... "children": [
-... {"name": "b",
-... "age": 65,
-... "children": [
-... {"name": "d", "age": 40},
-... {"name": "e", "age": 35, "children": [
-... {"name": "g", "age": 10},
-... ]},
-... ]},
-... ],
-... }
->>> root = nested_dict_to_tree(path_dict)
->>> root.show(attr_list=["age"])
-a [age=90]
-└── b [age=65]
- ├── d [age=40]
- └── e [age=35]
- └── g [age=10]
+ >>> import pandas as pd
+>>> from bigtree import dataframe_to_tree_by_relation
+>>> relation_data = pd.DataFrame([
+... ["a", None, 90],
+... ["b", "a", 65],
+... ["c", "a", 60],
+... ["d", "b", 40],
+... ["e", "b", 35],
+... ["f", "c", 38],
+... ["g", "e", 10],
+... ["h", "e", 6],
+... ],
+... columns=["child", "parent", "age"]
+... )
+>>> root = dataframe_to_tree_by_relation(relation_data)
+>>> root.show(attr_list=["age"])
+a [age=90]
+├── b [age=65]
+│ ├── d [age=40]
+│ └── e [age=35]
+│ ├── g [age=10]
+│ └── h [age=6]
+└── c [age=60]
+ └── f [age=38]
@@ -4090,16 +4856,13 @@
- node_attrsdata
- Dict[str, Any]
+ DataFrame
- dictionary containing node, children, and node attribute information,
-key: name_key and child_key
-value of name_key (str): node name
-value of child_key (List[Dict[str, Any]]): list of dict containing name_key and child_key (recursive)
+ data containing path and node attribute information
@@ -4107,31 +4870,63 @@
- name_keychild_col
str
- key of node name, value is type str
+ column of data containing child name information, defaults to None
+if not set, it will take the first column of data
- 'name'
+ ''
- child_keyparent_col
str
- key of child list, value is type list
+ column of data containing parent name information, defaults to None
+if not set, it will take the second column of data
- 'children'
+ ''
+
+
+
+ attribute_cols
+ List[str]
+
+
+
+ columns of data containing node attribute information,
+if not set, it will take all columns of data except child_col and parent_col
+
+
+
+ []
+
+
+
+ allow_duplicates
+ bool
+
+
+
+ allow duplicate intermediate nodes such that child node will
+be tagged to multiple parent nodes, defaults to False
+
+
+
+ False
@@ -4184,12 +4979,12 @@
-
-
+
-dataframe_to_tree(
+polars_to_tree(
data,
path_col="",
attribute_cols=[],
@@ -4201,7 +4996,7 @@
- Construct tree from pandas DataFrame using path, return root of tree.
+ Construct tree from polars DataFrame using path, return root of tree.
path_col and attribute_cols specify columns for node path and attributes to construct tree.
If columns are not specified, path_col takes first column and all other columns are attribute_cols.
Only attributes in attribute_cols with non-null values will be added to the tree.
@@ -4221,9 +5016,9 @@
Examples:
- >>> import pandas as pd
->>> from bigtree import dataframe_to_tree
->>> path_data = pd.DataFrame([
+ >>> import polars as pl
+>>> from bigtree import polars_to_tree
+>>> path_data = pl.DataFrame([
... ["a", 90],
... ["a/b", 65],
... ["a/c", 60],
@@ -4233,9 +5028,9 @@
... ["a/b/e/g", 10],
... ["a/b/e/h", 6],
... ],
-... columns=["PATH", "age"]
+... schema=["PATH", "age"]
... )
->>> root = dataframe_to_tree(path_data)
+>>> root = polars_to_tree(path_data)
>>> root.show(attr_list=["age"])
a [age=90]
├── b [age=65]
@@ -4263,7 +5058,7 @@
data
- DataFrame
+ DataFrame
@@ -4382,12 +5177,12 @@
-
-
+
-dataframe_to_tree_by_relation(
+polars_to_tree_by_relation(
data,
child_col="",
parent_col="",
@@ -4399,7 +5194,7 @@
-
Construct tree from pandas DataFrame using parent and child names, return root of tree.
+ Construct tree from polars DataFrame using parent and child names, return root of tree.
Root node is inferred when parent name is empty, or when name appears in parent column but not in child column.
Since tree is created from parent-child names, only names of leaf nodes may be repeated.
Error will be thrown if names of intermediate nodes are repeated as there will be confusion.
@@ -4413,9 +5208,9 @@
>>> import pandas as pd
->>> from bigtree import dataframe_to_tree_by_relation
->>> relation_data = pd.DataFrame([
+ >>> import polars as pl
+>>> from bigtree import polars_to_tree_by_relation
+>>> relation_data = pl.DataFrame([
... ["a", None, 90],
... ["b", "a", 65],
... ["c", "a", 60],
@@ -4425,9 +5220,9 @@ ... ["g", "e", 10],
... ["h", "e", 6],
... ],
-... columns=["child", "parent", "age"]
+... schema=["child", "parent", "age"]
... )
->>> root = dataframe_to_tree_by_relation(relation_data)
+>>> root = polars_to_tree_by_relation(relation_data)
>>> root.show(attr_list=["age"])
a [age=90]
├── b [age=65]
@@ -4455,7 +5250,7 @@ DataFrame
+ DataFrame
diff --git a/bigtree/tree/export/index.html b/bigtree/tree/export/index.html
index 018eef7c..1b883f50 100644
--- a/bigtree/tree/export/index.html
+++ b/bigtree/tree/export/index.html
@@ -287,7 +287,7 @@
-
+
@@ -872,10 +872,6 @@
-
-
-
-
@@ -900,24 +896,16 @@
-
-
-
-
+
-
-
-
-
-
+
+
-
+
-
-
+
-
-
+
-
-
+
-
+
+
+
+
+
@@ -2445,36 +2426,36 @@
-
+
-
-
+
-
-
+
-
-
+
-
+
+
+
+
+
@@ -2554,8 +2544,8 @@ Tree Export Methods
tree_to_dict, tree_to_nested_dict
-DataFrame
-tree_to_dataframeDataFrame (pandas, polars)
+tree_to_dataframe, tree_to_polars
Dot (for .dot, .png, .svg, .jpeg, etc.)
@@ -2634,6 +2624,14 @@ Tree Export Customizations
Column name for path, node name, node parent
+tree_to_polarsYes with attr_dict or all_attrs
+Yes with max_depth
+Yes with skip_depth
+Yes with leaf_only
+Column name for path, node name, node parent
+
+
tree_to_dotNo
No
@@ -3600,64 +3598,52 @@
-
-
+
-tree_to_newick(
+tree_to_dataframe(
tree,
- intermediate_node_name=True,
- length_attr="",
- length_sep=NewickCharacter.SEP,
- attr_list=[],
- attr_prefix="&&NHX:",
- attr_sep=NewickCharacter.SEP,
-)
+ path_col="path",
+ name_col="name",
+ parent_col="",
+ attr_dict={},
+ all_attrs=False,
+ max_depth=0,
+ skip_depth=0,
+ leaf_only=False,
+)
- Export tree to Newick notation. Useful for describing phylogenetic tree.
-In the Newick Notation (or New Hampshire Notation),
- - Tree is represented in round brackets i.e., (child1,child2,child3)parent.
- - If there are nested tree, they will be in nested round brackets i.e., ((grandchild1)child1,(grandchild2,grandchild3)child2)parent.
- - If there is length attribute, they will be beside the name i.e., (child1:0.5,child2:0.1)parent.
- - If there are other attributes, attributes are represented in square brackets i.e., (child1:0.5[S:human],child2:0.1[S:human])parent[S:parent].
+ Export tree to pandas DataFrame.
+All descendants from tree will be exported, tree can be the root node or child node of tree.
-
- Customizations include
-
-- Omitting names of root and intermediate nodes, default all node names are shown.
-- Changing length separator to other symbol, default is
:.
-- Adding an attribute prefix, default is
&&NHX:.
-- Changing the attribute separator to other symbol, default is
:.
-
-
Examples:
- >>> from bigtree import Node, tree_to_newick
->>> root = Node("a", species="human")
->>> b = Node("b", age=65, species="human", parent=root)
->>> c = Node("c", age=60, species="human", parent=root)
->>> d = Node("d", age=40, species="human", parent=b)
->>> e = Node("e", age=35, species="human", parent=b)
->>> root.show()
-a
-├── b
-│ ├── d
-│ └── e
-└── c
-
-
- >>> tree_to_newick(root, length_attr="age")
-'((d:40,e:35)b:65,c:60)a'
+ >>> from bigtree import Node, tree_to_dataframe
+>>> root = Node("a", age=90)
+>>> b = Node("b", age=65, parent=root)
+>>> c = Node("c", age=60, parent=root)
+>>> d = Node("d", age=40, parent=b)
+>>> e = Node("e", age=35, parent=b)
+>>> tree_to_dataframe(root, name_col="name", parent_col="parent", path_col="path", attr_dict={"age": "person age"})
+ path name parent person age
+0 /a a None 90
+1 /a/b b a 65
+2 /a/b/d d b 40
+3 /a/b/e e b 35
+4 /a/c c a 60
- >>> tree_to_newick(root, length_attr="age", attr_list=["species"])
-'((d:40[&&NHX:species=human],e:35[&&NHX:species=human])b:65[&&NHX:species=human],c:60[&&NHX:species=human])a[&&NHX:species=human]'
+ For a subset of a tree.
+ >>> tree_to_dataframe(b, name_col="name", parent_col="parent", path_col="path", attr_dict={"age": "person age"})
+ path name parent person age
+0 /a/b b a 65
+1 /a/b/d d b 40
+2 /a/b/e e b 35
@@ -3688,87 +3674,116 @@
- intermediate_node_namepath_col
- bool
+ str
- indicator if intermediate nodes have node names, defaults to True
+ column name for node.path_name, defaults to 'path'
- True
+ 'path'
- length_attrname_col
str
- node length attribute to extract to beside name, optional
+ column name for node.node_name, defaults to 'name'
- ''
+ 'name'
- length_sepparent_col
str
- separator between node name and length, used if length_attr is non-empty, defaults to ":"
+ column name for node.parent.node_name, optional
- SEP
+ ''
- attr_listattr_dict
- Iterable[str]
+ Dict[str, str]
- list of node attributes to extract into square bracket, optional
+ dictionary mapping node attributes to column name,
+key: node attributes, value: corresponding column in dataframe, optional
- []
+ {}
- attr_prefixall_attrs
- str
+ bool
- prefix before all attributes, within square bracket, used if attr_list is non-empty, defaults to "&&NHX:"
+ indicator whether to retrieve all Node attributes, overrides attr_dict, defaults to False
- '&&NHX:'
+ False
- attr_sepmax_depth
- str
+ int
- separator between attributes, within square brackets, used if attr_list is non-empty, defaults to ":"
+ maximum depth to export tree, optional
- SEP
+ 0
+
+
+
+ skip_depth
+ int
+
+
+
+ number of initial depths to skip, optional
+
+
+
+ 0
+
+
+
+ leaf_only
+ bool
+
+
+
+ indicator to retrieve only information from leaf nodes
+
+
+
+ False
@@ -3787,11 +3802,11 @@
- str
+ DataFrame
- (str)
+ (pd.DataFrame)
@@ -3807,44 +3822,64 @@
-
-
+
-tree_to_dict(
+tree_to_polars(
tree,
- name_key="name",
- parent_key="",
- attr_dict={},
- all_attrs=False,
- max_depth=0,
- skip_depth=0,
- leaf_only=False,
-)
+ path_col="path",
+ name_col="name",
+ parent_col="",
+ attr_dict={},
+ all_attrs=False,
+ max_depth=0,
+ skip_depth=0,
+ leaf_only=False,
+)
- Export tree to dictionary.
+ Export tree to polars DataFrame.
All descendants from tree will be exported, tree can be the root node or child node of tree.
-Exported dictionary will have key as node path, and node attributes as a nested dictionary.
Examples:
- >>> from bigtree import Node, tree_to_dict
+ >>> from bigtree import Node, tree_to_polars
>>> root = Node("a", age=90)
>>> b = Node("b", age=65, parent=root)
>>> c = Node("c", age=60, parent=root)
>>> d = Node("d", age=40, parent=b)
>>> e = Node("e", age=35, parent=b)
->>> tree_to_dict(root, name_key="name", parent_key="parent", attr_dict={"age": "person age"})
-{'/a': {'name': 'a', 'parent': None, 'person age': 90}, '/a/b': {'name': 'b', 'parent': 'a', 'person age': 65}, '/a/b/d': {'name': 'd', 'parent': 'b', 'person age': 40}, '/a/b/e': {'name': 'e', 'parent': 'b', 'person age': 35}, '/a/c': {'name': 'c', 'parent': 'a', 'person age': 60}}
+>>> tree_to_polars(root, name_col="name", parent_col="parent", path_col="path", attr_dict={"age": "person age"})
+shape: (5, 4)
+┌────────┬──────┬────────┬────────────┐
+│ path ┆ name ┆ parent ┆ person age │
+│ --- ┆ --- ┆ --- ┆ --- │
+│ str ┆ str ┆ str ┆ i64 │
+╞════════╪══════╪════════╪════════════╡
+│ /a ┆ a ┆ null ┆ 90 │
+│ /a/b ┆ b ┆ a ┆ 65 │
+│ /a/b/d ┆ d ┆ b ┆ 40 │
+│ /a/b/e ┆ e ┆ b ┆ 35 │
+│ /a/c ┆ c ┆ a ┆ 60 │
+└────────┴──────┴────────┴────────────┘
- For a subset of a tree
- >>> tree_to_dict(c, name_key="name", parent_key="parent", attr_dict={"age": "person age"})
-{'/a/c': {'name': 'c', 'parent': 'a', 'person age': 60}}
+ For a subset of a tree.
+ >>> tree_to_polars(b, name_col="name", parent_col="parent", path_col="path", attr_dict={"age": "person age"})
+shape: (3, 4)
+┌────────┬──────┬────────┬────────────┐
+│ path ┆ name ┆ parent ┆ person age │
+│ --- ┆ --- ┆ --- ┆ --- │
+│ str ┆ str ┆ str ┆ i64 │
+╞════════╪══════╪════════╪════════════╡
+│ /a/b ┆ b ┆ a ┆ 65 │
+│ /a/b/d ┆ d ┆ b ┆ 40 │
+│ /a/b/e ┆ e ┆ b ┆ 35 │
+└────────┴──────┴────────┴────────────┘
@@ -3875,13 +3910,27 @@
- name_keypath_col
str
- dictionary key for node.node_name, defaults to 'name'
+ column name for node.path_name, defaults to 'path'
+
+
+
+ 'path'
+
+
+
+ name_col
+ str
+
+
+
+ column name for node.node_name, defaults to 'name'
@@ -3889,13 +3938,13 @@
- parent_keyparent_col
str
- dictionary key for node.parent.node_name, optional
+ column name for node.parent.node_name, optional
@@ -3909,8 +3958,8 @@
- dictionary mapping node attributes to dictionary key,
-key: node attributes, value: corresponding dictionary key, optional
+ dictionary mapping node attributes to column name,
+key: node attributes, value: corresponding column in dataframe, optional
@@ -3989,11 +4038,11 @@
- Dict[str, Any]
+ DataFrame
- (Dict[str, Any])
+ (pl.DataFrame)
@@ -4009,38 +4058,44 @@
-
-
+
-tree_to_nested_dict(
+tree_to_dict(
tree,
name_key="name",
- child_key="children",
+ parent_key="",
attr_dict={},
all_attrs=False,
max_depth=0,
-)
+ skip_depth=0,
+ leaf_only=False,
+)
- Export tree to nested dictionary.
+ Export tree to dictionary.
All descendants from tree will be exported, tree can be the root node or child node of tree.
-Exported dictionary will have key as node attribute names, and children as a nested recursive dictionary.
+Exported dictionary will have key as node path, and node attributes as a nested dictionary.
Examples:
- >>> from bigtree import Node, tree_to_nested_dict
+ >>> from bigtree import Node, tree_to_dict
>>> root = Node("a", age=90)
>>> b = Node("b", age=65, parent=root)
>>> c = Node("c", age=60, parent=root)
>>> d = Node("d", age=40, parent=b)
>>> e = Node("e", age=35, parent=b)
->>> tree_to_nested_dict(root, all_attrs=True)
-{'name': 'a', 'age': 90, 'children': [{'name': 'b', 'age': 65, 'children': [{'name': 'd', 'age': 40}, {'name': 'e', 'age': 35}]}, {'name': 'c', 'age': 60}]}
+>>> tree_to_dict(root, name_key="name", parent_key="parent", attr_dict={"age": "person age"})
+{'/a': {'name': 'a', 'parent': None, 'person age': 90}, '/a/b': {'name': 'b', 'parent': 'a', 'person age': 65}, '/a/b/d': {'name': 'd', 'parent': 'b', 'person age': 40}, '/a/b/e': {'name': 'e', 'parent': 'b', 'person age': 35}, '/a/c': {'name': 'c', 'parent': 'a', 'person age': 60}}
+
+ For a subset of a tree
+ >>> tree_to_dict(c, name_key="name", parent_key="parent", attr_dict={"age": "person age"})
+{'/a/c': {'name': 'c', 'parent': 'a', 'person age': 60}}
@@ -4085,17 +4140,17 @@
- child_keyparent_key
str
- dictionary key for list of children, optional
+ dictionary key for node.parent.node_name, optional
- 'children'
+ ''
@@ -4141,6 +4196,34 @@
0
+
+ skip_depth
+ int
+
+
+
+ number of initial depths to skip, optional
+
+
+
+ 0
+
+
+
+ leaf_only
+ bool
+
+
+
+ indicator to retrieve only information from leaf nodes
+
+
+
+ False
+
+
@@ -4177,52 +4260,38 @@
-
-
+
-tree_to_dataframe(
+tree_to_nested_dict(
tree,
- path_col="path",
- name_col="name",
- parent_col="",
- attr_dict={},
- all_attrs=False,
- max_depth=0,
- skip_depth=0,
- leaf_only=False,
-)
+ name_key="name",
+ child_key="children",
+ attr_dict={},
+ all_attrs=False,
+ max_depth=0,
+)
- Export tree to pandas DataFrame.
+ Export tree to nested dictionary.
All descendants from tree will be exported, tree can be the root node or child node of tree.
+Exported dictionary will have key as node attribute names, and children as a nested recursive dictionary.
Examples:
- >>> from bigtree import Node, tree_to_dataframe
+ >>> from bigtree import Node, tree_to_nested_dict
>>> root = Node("a", age=90)
>>> b = Node("b", age=65, parent=root)
>>> c = Node("c", age=60, parent=root)
>>> d = Node("d", age=40, parent=b)
>>> e = Node("e", age=35, parent=b)
->>> tree_to_dataframe(root, name_col="name", parent_col="parent", path_col="path", attr_dict={"age": "person age"})
- path name parent person age
-0 /a a None 90
-1 /a/b b a 65
-2 /a/b/d d b 40
-3 /a/b/e e b 35
-4 /a/c c a 60
-
- For a subset of a tree.
- >>> tree_to_dataframe(b, name_col="name", parent_col="parent", path_col="path", attr_dict={"age": "person age"})
- path name parent person age
-0 /a/b b a 65
-1 /a/b/d d b 40
-2 /a/b/e e b 35
+>>> tree_to_nested_dict(root, all_attrs=True)
+{'name': 'a', 'age': 90, 'children': [{'name': 'b', 'age': 65, 'children': [{'name': 'd', 'age': 40}, {'name': 'e', 'age': 35}]}, {'name': 'c', 'age': 60}]}
@@ -4253,27 +4322,13 @@
- path_col
- str
-
-
-
- column name for node.path_name, defaults to 'path'
-
-
-
- 'path'
-
-
-
- name_colname_key
str
- column name for node.node_name, defaults to 'name'
+ dictionary key for node.node_name, defaults to 'name'
@@ -4281,17 +4336,17 @@
- parent_colchild_key
str
- column name for node.parent.node_name, optional
+ dictionary key for list of children, optional
- ''
+ 'children'
@@ -4301,8 +4356,8 @@
- dictionary mapping node attributes to column name,
-key: node attributes, value: corresponding column in dataframe, optional
+ dictionary mapping node attributes to dictionary key,
+key: node attributes, value: corresponding dictionary key, optional
@@ -4337,34 +4392,6 @@
0
-
- skip_depth
- int
-
-
-
- number of initial depths to skip, optional
-
-
-
- 0
-
-
-
- leaf_only
- bool
-
-
-
- indicator to retrieve only information from leaf nodes
-
-
-
- False
-
-
@@ -4381,11 +4408,11 @@
- DataFrame
+ Dict[str, Any]
- (pd.DataFrame)
+ (Dict[str, Any])
@@ -5268,6 +5295,213 @@
+
+
+
+
+
+
+tree_to_newick(
+ tree,
+ intermediate_node_name=True,
+ length_attr="",
+ length_sep=NewickCharacter.SEP,
+ attr_list=[],
+ attr_prefix="&&NHX:",
+ attr_sep=NewickCharacter.SEP,
+)
+
+
+
+
+ Export tree to Newick notation. Useful for describing phylogenetic tree.
+In the Newick Notation (or New Hampshire Notation),
+ - Tree is represented in round brackets i.e., (child1,child2,child3)parent.
+ - If there are nested tree, they will be in nested round brackets i.e., ((grandchild1)child1,(grandchild2,grandchild3)child2)parent.
+ - If there is length attribute, they will be beside the name i.e., (child1:0.5,child2:0.1)parent.
+ - If there are other attributes, attributes are represented in square brackets i.e., (child1:0.5[S:human],child2:0.1[S:human])parent[S:parent].
+
+
+ Customizations include
+
+- Omitting names of root and intermediate nodes, default all node names are shown.
+- Changing length separator to other symbol, default is
:.
+- Adding an attribute prefix, default is
&&NHX:.
+- Changing the attribute separator to other symbol, default is
:.
+
+
+
+
+Examples:
+ >>> from bigtree import Node, tree_to_newick
+>>> root = Node("a", species="human")
+>>> b = Node("b", age=65, species="human", parent=root)
+>>> c = Node("c", age=60, species="human", parent=root)
+>>> d = Node("d", age=40, species="human", parent=b)
+>>> e = Node("e", age=35, species="human", parent=b)
+>>> root.show()
+a
+├── b
+│ ├── d
+│ └── e
+└── c
+
+
+
+ >>> tree_to_newick(root, length_attr="age", attr_list=["species"])
+'((d:40[&&NHX:species=human],e:35[&&NHX:species=human])b:65[&&NHX:species=human],c:60[&&NHX:species=human])a[&&NHX:species=human]'
+
+
+
+
+ Parameters:
+
+
+
+ Name
+ Type
+ Description
+ Default
+
+
+
+
+ tree
+ Node
+
+
+
+ tree to be exported
+
+
+
+ required
+
+
+
+ intermediate_node_name
+ bool
+
+
+
+ indicator if intermediate nodes have node names, defaults to True
+
+
+
+ True
+
+
+
+ length_attr
+ str
+
+
+
+ node length attribute to extract to beside name, optional
+
+
+
+ ''
+
+
+
+ length_sep
+ str
+
+
+
+ separator between node name and length, used if length_attr is non-empty, defaults to ":"
+
+
+
+ SEP
+
+
+
+ attr_list
+ Iterable[str]
+
+
+
+ list of node attributes to extract into square bracket, optional
+
+
+
+ []
+
+
+
+ attr_prefix
+ str
+
+
+
+ prefix before all attributes, within square bracket, used if attr_list is non-empty, defaults to "&&NHX:"
+
+
+
+ '&&NHX:'
+
+
+
+ attr_sep
+ str
+
+
+
+ separator between attributes, within square brackets, used if attr_list is non-empty, defaults to ":"
+
+
+
+ SEP
+
+
+
+
+
+
+
+ Returns:
+
+
+
+ Type
+ Description
+
+
+
+
+
+ str
+
+
+
+ (str)
+
+
+
+
+
+
+
+
+
+
+
diff --git a/bigtree/tree/helper/index.html b/bigtree/tree/helper/index.html
index 2ddbedfa..21f80575 100644
--- a/bigtree/tree/helper/index.html
+++ b/bigtree/tree/helper/index.html
@@ -287,7 +287,7 @@
-
+
@@ -872,10 +872,6 @@
-
-
-
-
@@ -900,24 +896,16 @@
-
-
-
-
+
-
-
-
-
-
+
+