← Back to usersum index

Treatments Module

Apply post-fire rehabilitation and forest management treatments to WEPPcloud watersheds.

Overview

The Treatments module enables land managers and hydrologists to model how rehabilitation treatments affect erosion and runoff in fire-affected or forested landscapes. Treatments modify the landuse management and soil properties of selected hillslopes before WEPP model execution.

Who uses this:

• BAER Teams: Evaluate mulch application effectiveness after wildfires
• Forest Service Planners: Compare thinning strategies and prescribed fire options
• Hydrologists: Model erosion changes under different treatment scenarios

What you can do:

• Apply mulch at different application rates to reduce post-fire erosion
• Simulate prescribed fire as a pre-emptive forest treatment
• Evaluate forest thinning with various harvest methods
• Upload custom treatment maps to apply treatments spatially

Getting Started (Web Interface)

Enabling the Treatments Module

Treatments is an optional module that must be added to your project:

1. Open your WEPPcloud project
2. Click the Mods dropdown menu in the control panel
3. Select Treatments from the list
4. The Treatments panel will appear in your project controls

Choosing an Application Mode

The Treatments panel offers two ways to apply treatments:

Mode 1: Specify Hillslopes

1. Select Specify Hillslopes in the Treatments panel
2. On the map, click hillslopes you want to treat (they will highlight)
3. Choose a treatment from the dropdown menu
4. Click Build Treatments

This mode is useful for quick analyses or when you want to treat a small number of specific hillslopes.

Mode 4: Upload Treatment Map

1. Select Upload Treatment Map in the Treatments panel
2. Click the file upload button and select your treatment raster (.tif or .img)
3. Click Build Treatments

The system will:

• Reproject your raster to align with the watershed
• Assign treatments to hillslopes based on the most common pixel value within each hillslope
• Apply the appropriate management and soil changes

See Preparing Treatment Maps for detailed instructions on creating treatment rasters.

Understanding Treatment Types

Mulch Treatments

Mulch application increases ground cover to reduce erosion on burned hillslopes. Three application rates are available:

How ground cover changes:

Mulch increases ground cover following a saturating response—initial applications produce large gains, but returns diminish as cover approaches 100%.

Example: A high-severity burn area with 10% residual ground cover treated with mulch_30 (1.0 tons/acre) would increase to approximately 49% ground cover.

Important: Mulch treatments only apply to hillslopes classified as fire-disturbed (high, moderate, or low severity). Non-fire hillslopes are skipped even if selected or included in your treatment map.

Thinning Treatments

Thinning removes trees to reduce fuel loads and improve forest health. Treatments are named thinning_{canopy}_{ground_cover}:

• First number: Target canopy cover after thinning (40% = aggressive, 65% = moderate)
• Second number: Ground cover retention based on harvest method

Higher ground cover retention means less soil disturbance from equipment. Choose based on your terrain and available equipment.

Important: Thinning treatments only apply to hillslopes classified as forest. Other vegetation types are skipped.

Prescribed Fire

Prescribed fire applies low-intensity burns appropriate for the vegetation type:

The system automatically selects the correct fire intensity based on whether the hillslope is forest, shrub, or grass.

Preparing Treatment Maps for Upload

This section guides GIS users through creating treatment rasters for Mode 4.

Raster Requirements

Treatment Pixel Values

Encode your raster with these integer values where treatments should apply:

Mulch:

Prescribed Fire:

Thinning:

Creating a Treatment Map in QGIS

(These instructions are provided as guidance; your workflow may vary)

1. Create a polygon layer for treatment areas

   Layer → Create Layer → New Shapefile Layer
   - Geometry type: Polygon
   - Add field: "treatment" (Integer)
   

2. Draw treatment areas and assign pixel values

   • Digitize polygons around areas you want to treat
   • Set the treatment attribute to the pixel value from the table above (e.g., 140 for mulch_30)

3. Convert to raster

   Raster → Conversion → Rasterize (Vector to Raster)
   - Input layer: your treatment polygons
   - Field to use for burn-in: treatment
   - Output raster size: ~10m resolution (or match your DEM)
   - NoData value: 0
   - Output format: GeoTIFF
   

4. Verify the output

   • Check that pixel values match your intended treatments
   • Confirm the raster has a valid coordinate system (Layer Properties → Information)

Creating a Treatment Map in ArcGIS Pro

(These instructions are provided as guidance; your workflow may vary)

1. Create polygon feature class with treatment field

   Analysis → Tools → Create Feature Class
   - Add field "TreatmentCode" (Short Integer)
   

2. Draw polygons and assign treatment codes

   • Edit the attribute table to enter pixel values from the treatment table

3. Convert to raster

   Analysis → Tools → Polygon to Raster
   - Value field: TreatmentCode
   - Cell size: ~10m (or match watershed resolution)
   

4. Export as GeoTIFF

   Right-click layer → Data → Export Raster
   - Format: TIFF
   

How Treatment Maps Are Processed

When you upload a treatment map:

1. Reprojection: Your raster is automatically reprojected and resampled to align with the watershed
2. Hillslope assignment: For each hillslope, the most common (modal) treatment pixel value becomes that hillslope's treatment
3. Filtering: Pixel values that don't match valid treatment codes are ignored
4. Application: Treatments are applied based on vegetation type (mulch requires fire disturbance, thinning requires forest)

Tip: If a hillslope contains multiple treatment types, only the dominant one applies. For precise treatment boundaries, consider refining your watershed delineation.

Troubleshooting

Where Treatment Data Is Stored

Treatment files are stored in the treatments/ directory within your project:

your_project/
└── treatments/
    ├── [uploaded raster]     # Your original treatment map
    └── treatments.tif        # Aligned treatment map (after processing)

Treatment assignments are saved in the project and will persist when you reopen it.

Developer Notes

The following sections contain technical details for developers working with the Treatments module programmatically.

Key Attributes

Python API Usage

Basic treatment application:

from wepppy.nodb.mods.treatments import Treatments, TreatmentsMode

# Get the singleton instance for a working directory
treatments = Treatments.getInstance(wd)

# Set application mode
treatments.mode = TreatmentsMode.UserDefinedSelection

# Define hillslope-treatment assignments
# Keys are topaz hillslope IDs, values are treatment keys from disturbed.json
treatments.treatments_domlc_d = {
    '11': '140',   # mulch_30
    '21': '141',   # mulch_60
    '31': '142'    # prescribed_fire
}

# Apply treatments to landuse and soils
treatments.build_treatments()

Using treatment maps (Mode 4):

treatments = Treatments.getInstance(wd)
treatments.mode = TreatmentsMode.UserDefinedMap

# Validate and process uploaded treatment raster
treatments.validate('my_treatment_map.tif')

# Build treatments using the extracted hillslope-treatment mapping
treatments.build_treatments()

Querying valid treatments:

treatments = Treatments.getInstance(wd)

# Get list of treatment keys marked IsTreatment=True in disturbed.json
valid_keys = treatments.get_valid_treatment_keys()
# e.g., ['115', '116', '117', '124', '125', '126', '127', '128',
#        '139', '140', '141', '142']

# Get lookup dictionary for UI display (DisturbedClass -> Key)
lookup = treatments.treatments_lookup
# e.g., {'mulch_15': '139', 'mulch_30': '140', ...}

Mulch Ground Cover Model

Mulch treatments modify ground cover using a calibrated Hill-type saturation model:

G(m) = L - (L - G0) / (1 + (a*m)^b)

Where:

• G0 = initial ground cover (%)
• m = mulch application (tons/acre)
• L = 100% (saturation limit)
• a = 0.847, b = 1.737 (calibrated parameters)

Implementation: mulch_application.py

Integration Points

Dependencies:

• wepppy.nodb.core.landuse.Landuse - Landuse mapping and management registry
• wepppy.nodb.core.soils.Soils - Soil files and hillslope-soil assignments
• wepppy.nodb.mods.disturbed.Disturbed - Disturbed class lookups and soil rules
• wepppy.nodb.core.watershed.Watershed - Raster alignment for treatment maps

API Endpoints:

• Flask: /runs/<runid>/<config>/tasks/set_treatments_mode/
• FastAPI: /api/runs/{runid}/{config}/build-treatments
• UI Template: templates/controls/treatments_pure.htm

Persistence

Code Organization

wepppy/nodb/mods/treatments/
├── __init__.py           # Public API exports
├── treatments.py         # Main Treatments class
├── mulch_application.py  # Ground cover response model
└── README.md             # This file

Key Patterns

• Singleton per working directory: Treatments.getInstance(wd) returns cached instance
• @nodb_setter decorator: Wraps property setters with automatic locking, logging, and persistence
• Context manager locking: Use with treatments.locked(): for manual transaction control
• Strategy dispatch: _apply_treatment() routes to _apply_mulch(), _apply_prescribed_fire(), or _apply_thinning()

Testing

Tests: tests/weppcloud/routes/test_treatments_bp.py

Known Limitations

• Mulch treatments only apply to fire-disturbed hillslopes
• Treatment map mode requires the watershed subwta raster for alignment
• The module is marked "Experimental" in the UI

Further Reading

• NoDb README - Core NoDb controller architecture
• AGENTS.md - Locking and cache refresh semantics
• Disturbed Module - Fire severity and disturbed class handling
• disturbed.json - Treatment key definitions
• Ground Cover Model - Derivation of mulch response parameters