How to add a decision tree (beta)

A how-to guide for adding a decision tree.

Introduction

Would you like to populate control values and properties based on the previous inputs in the control panel? Then add a decision tree to your solution by following these steps.

A decision tree has a branch structure based on decisions and their consequences. It keeps branching out, step by step, until you reach a final decision or outcome.

Prerequisites

You configured the frames and routes for your solution.

1. Add an entity data store

Add an entity datastore with kind: EntityDataStore.
Define the properties as usual.

  my-entity-data-store:
    kind: EntityDataStore
    properties:
      space:
        type: String
      finish:
        type: String
      product-code:
        type: String
      price:
        type: Number
      quantity-min:
        type: Number
      quantity-max:
        type: Number

2. Define your decision tree

To define the decision tree, define entities in your entity datastore. The entities can be added in two ways:

Either from static records:
You can define the list of entities with key-value pairs in the solution.yaml file.

Each entity defines a final decision.
Each property can define a decision point or a dynamic value as a consequence of the previous decisions.

💡The keys in the entities should match the EntityDataStore properties.

For example the EntityDataStore below has different paint types as entities with varying prices.

  my-entity-data-store:
    kind: EntityDataStore
    entities:
      - space: Indoor
        finish: Matte
        product-code: "I-M-0000"
        price: 5
        quantity-min: 5
        quantity-max: 15
      - space: Indoor
        finish: Glossy
        product-code: "I-G-0000"
        price: 10
        quantity-min: 10
        quantity-max: 20
      ...
    properties:
      ...

Or from a CSV file: You can define and manage entities in a CSV file for convenience instead.
- To define your decision tree, compile your CSV file.
  - Each column can define a decision point or a dynamic value as a consequence of the previous decisions.
  - Each row defines a final decision, and represents an entity in the EntityDataStore.
💡The columns in the CSV file should match the entity datastore properties.

For example the table below has different paint types in each row with varying prices.

space finish product-code price quantity-min quantity-max

Indoor Matte I-M-0000 5 5 15

Indoor Glossy I-G-0000 10 10 20

Outdoor Glossy O-G-0000 10 10 20

Outdoor Matte O-M-0000 10 10 25

💡You can export a CSV file from your preferred spreadsheet editor.
- Save your .csv file to the solution folder.
- Define entities with the fromCsvFile tag and refer to your CSV file.
  
  The configuration should look similar to the example below:
```
my-entity-data-store:
  kind: EntityDataStore
  fromCsvFile: my-csv-file-1.csv
  properties:
    ...
```
❗To save a new version of the CSV file with updated content, you need to rename your file (e.g. “my-csv-file-2.csv”).

space	finish	product-code	price	quantity-min	quantity-max
Indoor	Matte	I-M-0000	5	5	15
Indoor	Glossy	I-G-0000	10	10	20
Outdoor	Glossy	O-G-0000	10	10	20
Outdoor	Matte	O-M-0000	10	10	25

3. Add a control panel

Add a control panel with kind: ControlPanel to your solution.
Define the controlsas usual. The controls, which are linked to the decision tree, needs to have the same names as the properties defined in the entity datastore.

The configuration should look similar to the example below:

my-control-panel:
  kind: ControlPanel
  controls:
    space:
      kind: Dropdown
      label: Space
      choices: []
    finish:
      kind: Dropdown
      label: Finish
      choices: []
    product-code:
      kind: Dropdown
      label: Product code
      choices: []
    quantity:
      kind: NumberInput
      label: Quantity

Based on the decisions made in the user interface, the entities can be filtered. To filter the decision tree with inputs, subscribe yourEntityDataStore to your ControlPanel .

Under your EntityDataStore define a subscription with kind: ControlPanel .
Define the source and frame .

To populate the control panel inputs with the decision tree, subscribe your ControlPanel to your EntityDataStore.

Under your ControlPanel define a subscription with kind: EntityDataStore.
Define the source and frame .
Use the setControls tag to set properties of your controls based on the decision tree.
- Define the control’s name that you’d like to link to the decision tree.
- You can set different types of properties of the controls with the control setter. See the controlsetter configuration docs.
- Optionally define which decisions have consequences on a control’s properties by filtering the entities.

my-control-panel:
  kind: ControlPanel
  controls:
    space:
      kind: Dropdown
      label: Space
      choices: []
    finish:
      kind: Dropdown
      label: Finish
      choices: []
    product-code:
      kind: Dropdown
      label: Product family
      choices: []
    quantity:
      kind: NumberInput
      label: Quantity
  subscribe:
    - kind: EntityDataStore # subscribe control panel to entity datastore to set choices
      frame: my-home-frame
      source: my-entity-data-store
      setControls:
        space:
          type: setDropDownChoices
        finish:
          type: setDropDownChoices
          filterChoices: [space]
        product-code:
          type: setDropDownChoices
          filterChoices: [space,finish]
        quantity:
          type: setMinMax
          minProperty: quantity-min
          maxProperty: quantity-max
        filterBy: [product-code]

To run your Grasshopper model with the values from the decision tree:

Subscribe your Model to the EntityDataStore .
Define the source and frame .
Define the name of the input to receive the filtered entities with the setInput tag.
Define which inputs to use as filters with the filterEntities tag.

my-model:
  kind: Model
  modelFile: my-gh-model.gh
  subscribe:
    - kind: EntityDataStore # subscribe model to entity data store to get filter set
      frame: my-home-frame
      source: my-entity-data-store
      setInput: my-gh-input
      filterEntities: [space, finish, product-code]

See the image below as an example.

Configuration

See the EntityDataStore configuration docs and ControlPanel configuration docs for more information.