Skip to content

Commit a2d79e7

Browse files
committed
docs: update shifting with guideline
1 parent 6078bef commit a2d79e7

File tree

1 file changed

+35
-0
lines changed

1 file changed

+35
-0
lines changed

docs/bigtree/tree/modify.md

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,41 @@ All other methods calls these 2 methods directly.
8787
| merge_leaves + overriding/merge_attribute | "a/b/c" | "a/d/c" | **If path not present**: Behaves like merge_leaves<br>**If path present**: Behaves like overriding/merge_attribute, but original node `c` remains |
8888
| delete_children | "a/b" | "a/d/b" | Shift/copy node `b` only without any node `b` children |
8989

90+
## Guideline
91+
92+
If you're still feeling lost over the parameters, here are some guiding questions to ask yourself.
93+
94+
- Do I want to retain the original node where they are?
95+
- Yes: Set `copy=True`
96+
- Default performs a shift instead of copy
97+
- Am I unsure of what nodes I am going to shift, they may or may not exist and this is perfectly fine?
98+
- Yes: Set `skippable=True`
99+
- Default throws error if origin node is not found
100+
- The origin node (and its descendants) may clash with the destination node(s), how do I want to handle it?
101+
- Set `overriding=True` to overwrite origin node
102+
- Set `merge_attribute=True` to combine both nodes' attributes
103+
- Default throws error about the clash in node name
104+
- I want to shift everything under the node, but not the node itself
105+
- Set `merge_children=True` or `merge_leaves=True` to shift the children and leaf nodes respectively
106+
- Default shifts the node itself, and everything under it
107+
- I want to shift the node and only the node, and not everything under it
108+
- Yes: Set `delete_children=True`
109+
- Default shifts the node itself, and everything under it
110+
- I want to shift things from one tree to another tree
111+
- Specify `to_tree`
112+
- Default shifts nodes within the same tree
113+
114+
What about the permutations between the parameters?
115+
116+
- These parameters are standalone and does not produce any interaction effect
117+
- `copy`, `skippable`, `delete_children`
118+
- These parameters have some interaction:
119+
- `overriding` and `merge_attribute` with `merge_children` and `merge_leaves`
120+
- `overriding` + `merge_children`: Behaves like `merge_children` when there is no clash in node name, otherwise behaves like `overriding`. Note that clashes will preserve destination nodes' children only.
121+
- `overriding` + `merge_leaves`: Behaves like `merge_leaves` when there is no clash in node name, otherwise behaves like `overriding`. Note that clashes will preserve destination nodes' leaves only.
122+
- `merge_attribute` + `merge_children`: Behaves like `merge_children` when there is no clash in node name, otherwise behaves like `merge_attribute`. Note that attributes will be merged for node and all descendants, and will preserve origin and destination nodes' children.
123+
- `merge_attribute` + `merge_leaves`: Behaves like `merge_leaves` when there is no clash in node name, otherwise behaves like `merge_attribute`. Note that attributes will be merged for node and all descendants, and will preserve origin nodes' children and destination nodes' leaves.
124+
90125
-----
91126

92127
::: bigtree.tree.modify

0 commit comments

Comments
 (0)