← Back to usersum index

Disturbed Lands Module

Translates wildfire burn-severity maps into WEPP-ready soil and vegetation inputs so erosion models reflect post-fire conditions.

See also: ENDUSER.md for the user-facing workflow guide. AGENTS.md for coding conventions. Disturbed Land Soil Lookup for the end-user parameter reference. SBS Map Utilities for raster classification details. Soil File Specification for WEPP soil format reference.

What This Module Does

After a wildfire, hillslope soils and vegetation change dramatically. Burned soils become water-repellent (hydrophobic), ground cover disappears, and erosion rates can increase by orders of magnitude. The Disturbed module automates the translation of a Soil Burn Severity (SBS) map into the specific soil and management parameters that the WEPP erosion model needs.

The core logic is:

1. Read the burn severity map — a GeoTIFF classifying each pixel as unburned, low, moderate, or high severity
2. For each hillslope, determine its dominant burn severity and existing vegetation type (forest, shrub, or grass)
3. Look up replacement parameters from a table keyed by (vegetation type + severity, soil texture) — this produces new erodibility values, hydraulic conductivity, cover fractions, and plant parameters
4. Write new WEPP input files (.sol and .man) that reflect the post-fire state

The result is a complete set of WEPP inputs that model how a burned watershed will respond to rainfall — more runoff, more erosion, faster peak flows — compared to the undisturbed baseline.

Who Uses This

• BAER specialists building rapid post-fire erosion assessments
• Incident hydrologists evaluating debris-flow and flooding risk
• Researchers comparing treatment scenarios (mulch, seeding, prescribed fire) against burned baselines
• WEPPcloud operators running standard disturbed-land projects

Key Inputs

Soil Burn Severity (SBS) Map

The primary input. Users either:

• Upload a raster (.tif or .img) — typically from BARC or RAVG products
• Generate a uniform severity — applies one severity level across the entire watershed (useful for scenario analysis)

The module reprojects the raster to match the watershed DEM, classifies pixels into four severity classes (unburned=130, low=131, moderate=132, high=133), and computes per-hillslope dominant severity.

Disturbed Land Soil Lookup Table

A CSV (disturbed/disturbed_land_soil_lookup.csv) that maps every combination of disturbed land-use class and soil texture to WEPP parameters. Each project gets its own copy that can be edited through the PowerUser panel.

Key parameters in the lookup:

Configuration Options

How It Works

Step 1: Landuse Remapping

When a hillslope has forest vegetation and the SBS map shows high severity fire at that location, the module replaces the management file:

• UnDisturbed/Old_Forest.man → UnDisturbed/High_Severity_Fire.man

This changes canopy cover from 90% to 40%, interrill cover from 100% to 30%, and maximum LAI from 14.0 to 2.0 — reflecting a severely burned forest floor.

The same logic applies to shrub and grass classes when burn_shrubs / burn_grass are enabled:

• UnDisturbed/Shrub.man → UnDisturbed/Shrub_High_Severity_Fire.man
• UnDisturbed/Tall_Grass.man → UnDisturbed/Grass_High_Severity_Fire.man

Step 2: Soil Regeneration

For each hillslope, the module:

1. Determines the simplified soil texture (clay loam, loam, sand loam, or silt loam) from clay/sand percentages
2. Looks up replacement erodibility and conductivity parameters from the lookup table
3. Writes a new .sol file with the disturbed parameters, using WeppSoilUtil for version-aware serialization

For soil versions 9003+, the lkeff parameter enforces a lower bound on hydraulic conductivity to simulate persistent water repellency. High severity burns typically use lkeff=0.1 mm/h (strong hydrophobicity), while low severity uses lkeff=10 mm/h (minimal effect).

Step 3: PMET Parameters

Writes pmetpara.txt with basal crop coefficient (pmet_kcb) and readily-available water (pmet_rawp) values from the lookup table, used for ET calculations.

Vegetation Parameters by Burn Severity

Forest

Initial conditions (cover and roughness)

Plant parameters

Shrub

Initial conditions

Plant parameters

Grass

Initial conditions

Plant parameters

Soil Lookup Example (Loam Texture)

These rows from disturbed_land_soil_lookup.csv show how soil parameters change with severity for loam soils. Other textures (clay loam, sand loam, silt loam) follow similar patterns with texture-appropriate values.

Note: lkeff=-9999 means no hydrophobicity adjustment is applied (grass fires typically do not produce significant water repellency).

How Parameters Affect WEPP Simulations

The disturbed parameterization feeds directly into the WEPP-forest Fortran kernels:

• Cover fractions (cancov, inrcov, rilcov) reduce rainfall interception and hydraulic friction. Lower cover → more water reaches the soil surface → more runoff and erosion.

• Erodibility (ki, kr) and critical shear (shcrit) control how easily soil detaches. Burned soils are more erodible because organic binding agents are destroyed and soil structure collapses.

• Hydraulic conductivity (avke, lkeff) controls infiltration capacity. The lkeff lower bound simulates hydrophobic layers — waxy residues from burned organic matter that repel water. When ksatadj=1, WEPP dynamically adjusts conductivity based on soil saturation, allowing recovery as cumulative precipitation breaks down the hydrophobic layer.

• Plant parameters (rdmax, xmxlai, hmax) control vegetation recovery. Burned hillslopes start with reduced root depth, leaf area, and canopy height, which limits transpiration and interception.

The parameterization is directionally correct at the regime level: burned conditions produce more runoff and sediment than undisturbed across seasonal and annual totals. Individual storm events may occasionally show the opposite due to antecedent moisture state — a dry burned soil can still infiltrate more than a saturated undisturbed soil. This is expected WEPP hydrology behavior; compare distributions and totals rather than individual events.

Static Management Overrides

To keep undisturbed vs. disturbed comparisons strictly "static to static," the lookup table sets plant.data.decfct and plant.data.dropfc to 1 for all landuses except agriculture crops. This prevents management files from decaying or dropping plant material during the comparison window, avoiding unintended differences in residue/root mass between templates.

Quick Start

import shutil
from os.path import join as _join

from wepppy.nodb.mods import Disturbed

wd = "/wc1/runs/ab/abcdef12345"
disturbed = Disturbed.getInstance(wd)

src = "/path/to/sbs.tif"
dst = _join(disturbed.disturbed_dir, "sbs.tif")
shutil.copyfile(src, dst)

disturbed.validate("sbs.tif")
disturbed.remap_landuse()
disturbed.modify_soils()

Developer Notes

• remap_landuse() and remap_mofe_landuse() map SBS classes 131/132/133 to low/mod/high severity management keys using wepppy/wepp/management/data/disturbed.json.
• If a management entry defines SoilFile/sol_path, the controller copies that soil directly instead of regenerating from the lookup table.
• For treatment suffixes (-mulch_15, -thinning, etc.), lookup_disturbed_class() strips the suffix so soils are keyed by burn severity, not treatment type.
• For MOFE runs, each OFE gets its own disturbed soil file, reassembled into a .mofe.sol via SoilMultipleOfeSynth.
• build_extended_land_soil_lookup() exports a merged lookup (management + soil parameters); it is not part of the default run workflow.
• All mutations must occur inside with disturbed.locked(): blocks to respect Redis-backed locking.

Validation Results (48-Simulation Matrix)

A 48-simulation matrix test (4 soil textures × 3 vegetation types × 4 burn severities, 100-year climate) validates the parameterization. Key findings:

1. Runoff increases with burn severity: Forest burned conditions show more runoff events than unburned in 86% of matched events (low severity) through 76% (high severity).

2. Sediment delivery increases dramatically at high severity: Forest high severity produces 174× more total sediment than unburned (5,338 vs 30.6 kg/m). Shrub high severity shows 23×. At high severity, 100% of matched events show burned > unburned for forest.

3. Texture matters: Clay loam shows the highest sediment response; sand loam shows minimal differences due to high infiltration capacity even when burned.

4. Grass response is muted at low severity: Tall grass shows high "equal" event counts at low severity (66% of events), indicating minimal hydrologic impact from low-severity grass fires.

Full results: tests/disturbed/analysis_results.md Test suite: tests/disturbed/test_disturbed_matrix.py

Further Reading

• Disturbed Land Soil Lookup — end-user parameter reference
• SBS Map Utilities — raster classification and color-table contracts
• SBS Controls Behavior — UI upload/uniform mode documentation
• WEPP Soil Files — soil file format versions and parameter definitions
• Management File Conventions — management file structure
• Soil Migration Utilities — WeppSoilUtil API