Basic Data Tree Actions

Introduction

LEVEL: INTERMEDIATE
Expected Time: 45 min

Most data tree component can be found under Sets > Tree

For an effective use of multiple data trees it is necessary to make sure that the data is at the same branch level at the different trees. If this is not the case you will have to edit the tree structure. There is a wide range of options for editing the data tree. This already indicates that there is a wide range of problems you can encounter with the data structures. Understanding how to edit them is crucial for effective use of Grasshopper.

Essential Data Tree Components

Flatten Tree

Flatten with node

The flatten tree option is one which is often used to restructure the data tree structure by deleting the branch information and put all the data together in the root of data tree. It a drastic option and often forms the basis for restructuring the Data Tree from scratch.

Flattening a tree deletes all the information of where the data comes from. Therefore you should only use flattening techniques, when the origin of data is not relevant for later steps in a script.

Flattening can be done using methods:

Flatten data with the flatten tree node

Flatten with RMB

Right-click on the output of a node and click on flatten.

Graft Tree

Graft

Grafting a tree adds complexity to a list of data. Each data item is added to a new branch. This can help you to repeat a certain procedure on each item, or let specific items in a list interact with specific items of another list.

Grafting can be done using two methods:

Use the graft node;
Right-click on the output of a node and click on graft.

Simplify Tree

Simplify

Simplifying reduces the complexity of a tree, but keeps the branch structure. For example a branch with the structure {0;0;0;1} will be reduced to {1}.

Similar to flattening, try to avoid simplifying data trees. Although the zeros in the previously mentioned example may seem irrelevant, they tell us something about the origin of data. Only simplify when it is absolutely necessary for the interaction with other data trees.

Similarly to grafting and flattening, simplifying can also be done by right-clicking on an input or output.

Recommended Data Tree Components

Trim Tree

The trim tree component merges the smallest lists in the data tree. For example: {0;1;2} and {0;1;4) is combined to {0;1}. Simply said, trimming a tree works similar to flattening, however, it only flattens the smallest branches.

Besides the Tree input, the component also has a Depth input. This Depth input indicates how deep the data tree should be flattened. For example: {0;1;2} and {0;1;4} with depth 2, will result in a data tree with {0} as only branch.

Shift Paths

The Shift Path option looks a bit like a controlled Flatten option. It gives you the possibility to move the data one or more branches lower or to collapse the data into a single branch similar like the Flatten option, however, now placed on a single branch.

Shift Paths with offset 2

The offset value can be positive or negative. Negative numbers give results similar to the Trim Tree component. Positive numbers approach the Data Tree differently. The component re-orders the data tree based on the smallest branch in a tree. For example: {0;0;0) and {0;3;0) (both structures end with a 0) with Offset 2 are combined into {0}.

Tree Branch

The tree branch component is useful when you need a specific branch of a tree. In most scripts, a data tree is first simplified, and then a specific branch is selected.

Explode Tree

When you need more than one branch, the explode tree component can be useful. By clicking on the + and - icon, you can add more or less branches.

The explode tree component has some limitations:

The component does not change parametrically if the data tree structure changes during execution;
Branches are only available in a specific order.

Tree Statistics

Sometimes, data trees can have complex structures of which it is not easy to extract a specific branch. To get some information about the branches (paths), depth and length, you can use the Tree Statistics component.

Entwine

When you want to combine two lists into on data tree, but you want to have the lists in different branches, you can use the entwine component.

By right-clicking on the entwine icon, you can specify if you want the data to be flattened or grafted.

Prune Tree

If you need to cull branches that have less, or more, than a certain amount of items, you can use the Prune Tree component.

For example: if the minimum is 2, all branches with less than 2 items will be removed.

Clean Tree

When you want to remove Null data, invalid data or empty branches, you can use the clean tree component. Which data should be removed, is based on a boolean input for each category.

Advanced Data Tree Components

Match Tree

When two trees have the same amount of branches, but the structure of the branches is different, you can match the trees. For example: a tree with branches {0;0;0} and {0;0;7} that should match {0;0;0} and {0;0;1} will result in {0;0;0} and {0;0;1).

Flip Matrix

If we compare a data tree to a matrix, the branches can be considered columns, and the items in the branches rows. Using the flip matrix node, you can flip the columns and the rows of a data structure.

Unflatten Tree

Based on a guide tree, you can unflatten a tree. This is useful if you need to change certain values based on a pattern that should continue no matter the branch an item is on.

(de)Construct Path

Using the construct path function, you can construct a path out of a series of numbers. With the deconstruct path function, you will achieve the opposite result.

Path Compare

Using the path compare you can check if a path follows certain rules. You can use operators to like *, <, > etc. to specify the rules.

Replace Paths

Using this node, you can merge or replace certain branches in a data tree. It is possible to use operators like *, <, > etc. in the mask to specify which paths to search for. In this example, we have merged branch {0;0} and {0;1} because we replaced all branches that follow the {0;<2} rule for {0;0}.

Relative Item(s)

Relative Item

The relative item node is all about relations between items in a data structure. The function is able to split a tree in two parts where output A has a repeating relation with output B. For example: if we have one item in branch {1;0} and one item in branch {2;1}, the offset (difference) between these items is {1;1}. The relative item function is able to retrieve all these relations for each item in the data structure.

Sometimes, a relation is not available. For example: if we have an item in branch {5;5} and we are asking for offset {2;2}, but the branch {7;7} does not exist, this relation will not be included in the output. You can change this by setting the Wrap Items or Wrap Paths to true.

Furthermore, it is possible to create an offset within a branch. This can be done by adding (item) behind the path. For example: the offset {0;0}(1) will find the relation by retrieving the next item in each branch.

Split Tree

Based on a mask you can split a data tree. For example, you can split a tree where the indices 0-5 go to a first list, and all other indices go to another list.

Suirify

Sometimes you need to simplify a data tree. This will work most of the time, except for the situation when a data tree only has one branch. The suirify node can be used as an extreme version of simplification. However, this node is only used in very specific situations.

The suirify node is only available in Rhino 7. It can be found under Params » Util » Suirify

Path Mapper

The path mapper is a logistical operator that can do almost all the above mentioned procedures. Double-click on the icon of the node to set the parameters. The basic options can be divided into the following categories:

Flattening the data: remove all small branches that are not relevant anymore;

Path Mapper with path_index

If you only need to change the names of the branches, use the path_index indicator;

Path Mapper with item_count

Similarly, you can use the path_count and item_count to restructure based on the amount of paths or branches.

Operator syntax

Operator Syntax

To specify certain rules related to paths/branches, in most cases you can use all the following operators:

The * sign: any number or integer in a path
The ? sign: any single integer
The ! sign: anything except this item
The (x, y, z) structure: one of the items between the brackets
The (x To y) structure: any number in this range
The [x To y] structure: all numbers in this range
The “or” operator: choose between two structures
The “and” operator: include both structures
The <, <=, > and >= signs: any number that follows this rule

Other utilities

Stream Filter

The stream filter is a simple method of switching between two or more lists by simply selecting the wanted list by its input number. This input number can be defined within the network and thereby can change depending on a variety of settings influencing which list is passed through the filter.

Stream Gate

The stream gate works similar to the stream filter option. The difference however is that we have only one input list. An index number defines to which output channel the list is gated. The selection if therefore focussed on which channel the list is gated.