From 08ddd976361aecc47d7a1e311d29336871a1c608 Mon Sep 17 00:00:00 2001 From: Anthony Marcozzi Date: Thu, 30 Oct 2025 11:41:40 -0600 Subject: [PATCH] Update documentation to support attribute-based modifications and removals in tree inventory --- docs/guides/inventories.md | 38 +++++++++++++++++-- fastfuels_sdk/inventories.py | 72 +++++++++++++++++++++++++++--------- 2 files changed, 89 insertions(+), 21 deletions(-) diff --git a/docs/guides/inventories.md b/docs/guides/inventories.md index 805a6b5..a1bfff3 100644 --- a/docs/guides/inventories.md +++ b/docs/guides/inventories.md @@ -70,8 +70,8 @@ To adjust tree measurements based on conditions: # Reduce height of all trees over 20m by 10% tree_inventory = inventories.create_tree_inventory_from_treemap( modifications={ - "conditions": [{"field": "HT", "operator": "gt", "value": 20}], - "actions": [{"field": "HT", "modifier": "multiply", "value": 0.9}] + "conditions": [{"attribute": "HT", "operator": "gt", "value": 20}], + "actions": [{"attribute": "HT", "modifier": "multiply", "value": 0.9}] } ) ``` @@ -84,6 +84,36 @@ tree_inventory = inventories.create_tree_inventory_from_treemap( ) ``` +To remove trees based on attribute conditions: + +```python +# Remove all trees with diameter less than 10cm +tree_inventory = inventories.create_tree_inventory_from_treemap( + modifications={ + "conditions": [{"attribute": "DIA", "operator": "lt", "value": 10}], + "actions": [{"attribute": "all", "modifier": "remove"}] + } +) +``` + +You can also combine multiple modifications, including removal: + +```python +# Reduce height of tall trees AND remove small trees +tree_inventory = inventories.create_tree_inventory_from_treemap( + modifications=[ + { + "conditions": [{"attribute": "HT", "operator": "gt", "value": 20}], + "actions": [{"attribute": "HT", "modifier": "multiply", "value": 0.9}] + }, + { + "conditions": [{"attribute": "DIA", "operator": "lt", "value": 10}], + "actions": [{"attribute": "all", "modifier": "remove"}] + } + ] +) +``` + ## How to Apply Forest Management Treatments To thin to a target basal area: @@ -157,8 +187,8 @@ If you need to create an inventory with multiple modifications: tree_inventory = inventories.create_tree_inventory_from_treemap( seed=42, modifications={ - "conditions": [{"field": "HT", "operator": "gt", "value": 20}], - "actions": [{"field": "HT", "modifier": "multiply", "value": 0.9}] + "conditions": [{"attribute": "HT", "operator": "gt", "value": 20}], + "actions": [{"attribute": "HT", "modifier": "multiply", "value": 0.9}] }, treatments={ "method": "proportionalThinning", diff --git a/fastfuels_sdk/inventories.py b/fastfuels_sdk/inventories.py index a6aae29..913dd55 100644 --- a/fastfuels_sdk/inventories.py +++ b/fastfuels_sdk/inventories.py @@ -148,18 +148,29 @@ def create_tree_inventory( - seed: Integer for reproducible generation (optional) modifications : dict or list[dict], optional - List of modifications to apply. Each modification has: - - conditions: List of conditions that must be met - - actions: List of actions to apply when conditions are met + Rules for modifying or removing tree attributes. Each modification has: + - conditions: List of conditions that trees must meet + - actions: List of actions to apply to matching trees - Example: + Example - Modify attribute: ```python { - "conditions": [{"field": "HT", "operator": "gt", "value": 20}], - "actions": [{"field": "HT", "modifier": "multiply", "value": 0.9}] + "conditions": [{"attribute": "HT", "operator": "gt", "value": 20}], + "actions": [{"attribute": "HT", "modifier": "multiply", "value": 0.9}] } ``` + Example - Remove trees: + ```python + { + "conditions": [{"attribute": "DIA", "operator": "lt", "value": 10}], + "actions": [{"attribute": "all", "modifier": "remove"}] + } + ``` + + Available attributes: HT (height), DIA (diameter), CR (crown ratio), SPCD (species code) + Available modifiers: multiply, divide, add, subtract, replace, remove + treatments : dict or list[dict], optional List of silvicultural treatments to apply. Supports: @@ -220,8 +231,17 @@ def create_tree_inventory( >>> inventory = inventories.create_tree_inventory( ... sources="TreeMap", ... modifications={ - ... "conditions": [{"field": "HT", "operator": "gt", "value": 20}], - ... "actions": [{"field": "HT", "modifier": "multiply", "value": 0.9}] + ... "conditions": [{"attribute": "HT", "operator": "gt", "value": 20}], + ... "actions": [{"attribute": "HT", "modifier": "multiply", "value": 0.9}] + ... } + ... ) + + Remove small trees: + >>> inventory = inventories.create_tree_inventory( + ... sources="TreeMap", + ... modifications={ + ... "conditions": [{"attribute": "DIA", "operator": "lt", "value": 10}], + ... "actions": [{"attribute": "all", "modifier": "remove"}] ... } ... ) @@ -314,24 +334,34 @@ def create_tree_inventory_from_treemap( - "Meta2024": Meta's 2024 global canopy height map at 1-meter resolution modifications : dict or list[dict], optional - Rules for modifying tree attributes. Each modification includes: + Rules for modifying or removing tree attributes. Each modification includes: - conditions: List of criteria that trees must meet - actions: Changes to apply to matching trees - Example - Reduce height of tall trees: + Example - Modify attribute: ```python { - "conditions": [{"field": "HT", "operator": "gt", "value": 20}], - "actions": [{"field": "HT", "modifier": "multiply", "value": 0.9}] + "conditions": [{"attribute": "HT", "operator": "gt", "value": 20}], + "actions": [{"attribute": "HT", "modifier": "multiply", "value": 0.9}] } ``` - Available fields: + Example - Remove trees: + ```python + { + "conditions": [{"attribute": "DIA", "operator": "lt", "value": 10}], + "actions": [{"attribute": "all", "modifier": "remove"}] + } + ``` + + Available attributes: - HT: Height (meters) - DIA: Diameter at breast height (centimeters) - CR: Crown ratio (0-1) - SPCD: Species code (integer) + Available modifiers: multiply, divide, add, subtract, replace, remove + treatments : dict or list[dict], optional Silvicultural treatments to apply. Supports: @@ -395,8 +425,16 @@ def create_tree_inventory_from_treemap( Reduce height of tall trees: >>> tree_inventory = inventories.create_tree_inventory_from_treemap( ... modifications={ - ... "conditions": [{"field": "HT", "operator": "gt", "value": 20}], - ... "actions": [{"field": "HT", "modifier": "multiply", "value": 0.9}] + ... "conditions": [{"attribute": "HT", "operator": "gt", "value": 20}], + ... "actions": [{"attribute": "HT", "modifier": "multiply", "value": 0.9}] + ... } + ... ) + + Remove small trees: + >>> tree_inventory = inventories.create_tree_inventory_from_treemap( + ... modifications={ + ... "conditions": [{"attribute": "DIA", "operator": "lt", "value": 10}], + ... "actions": [{"attribute": "all", "modifier": "remove"}] ... } ... ) @@ -418,8 +456,8 @@ def create_tree_inventory_from_treemap( >>> tree_inventory = inventories.create_tree_inventory_from_treemap( ... seed=42, ... modifications={ - ... "conditions": [{"field": "HT", "operator": "gt", "value": 20}], - ... "actions": [{"field": "HT", "modifier": "multiply", "value": 0.9}] + ... "conditions": [{"attribute": "HT", "operator": "gt", "value": 20}], + ... "actions": [{"attribute": "HT", "modifier": "multiply", "value": 0.9}] ... }, ... treatments={ ... "method": "proportionalThinning",