← Back to usersum index

Agricultural Fields (AgFields)

AgFields models agricultural fields inside a WEPPcloud project by converting uploaded field boundaries into hydrologic sub-fields and then running WEPP for each sub-field. Use it when watershed totals alone are too coarse and you need field-by-field or within-field comparisons tied to crop rotations.

What This Is For

AgFields is for questions such as:

• Which fields contribute the most runoff or sediment?
• Which parts of one mapped field behave differently because they drain through different hillslopes?
• How do crop rotations change modeled response from year to year?

This is a field-management workflow layered onto a WEPPcloud watershed project. It is not a replacement for the watershed model, and it does not assume each mapped field behaves as one uniform hydrologic unit.

The User-Facing Setup Flow

AgFields currently behaves more like a staged setup-and-prep workflow than a single one-click model control. The user-facing decisions are centered on uploaded files, file columns, and required support tables.

The core setup sequence is:

1. provide a field-boundary GeoJSON,
2. confirm the field ID column,
3. define the crop-year column pattern,
4. rasterize fields onto the project DEM grid,
5. abstract hydrologic sub-fields,
6. polygonize sub-fields,
7. provide the crop-to-management lookup,
8. run WEPP per sub-field.

If you automate or troubleshoot this workflow, those stages map directly to controller actions:

• validate_field_boundary_geojson(...)
• set_field_id_key(...)
• set_rotation_accessor(...)
• rasterize_field_boundaries_geojson()
• peridot_abstract_sub_fields(...)
• polygonize_sub_fields()
• validate_rotation_lookup()
• run_wepp_ag_fields(...)

Those prep stages matter because later steps assume the earlier ones already succeeded. If the field IDs, crop columns, rasterized boundaries, or sub-field abstractions are wrong, the WEPP runs are still likely to finish but the answers will be attached to the wrong field logic.

What You Need To Supply

The current AgFields workflow expects these user-provided inputs:

Important current rules:

• the boundary GeoJSON must contain a field_id column during validation,
• the crop-year pattern must work for every observed climate year,
• crop names in the schedule must match rotation_lookup.tsv,
• the field geometry must overlap the project DEM extent after CRS handling.

Key Choices You Actually Make

Field boundary upload

The boundary upload is not just geometry input. During validation, AgFields normalizes the file into ag_fields/fields.WGS.geojson and extracts the non-geometry attributes into ag_fields/rotation_schedule.parquet.

That means one uploaded GeoJSON is carrying two jobs at once:

• field geometry,
• the rotation schedule table.

If the uploaded file has the right polygons but the wrong or incomplete attribute table, the geometry may look fine while the crop schedule still fails later.

Field ID column

The field ID is the backbone of the workflow. The system uses it to:

• burn fields into field_boundaries.tif,
• join rotation rows back to the right field,
• connect sub-fields to their parent field,
• organize field and sub-field outputs.

Duplicate IDs are not fatal at validation time, but they are a warning sign. If one ID refers to multiple distinct field records, later summaries become much harder to interpret.

Crop-year column pattern

AgFields uses a user-defined pattern such as Crop{} to find the per-year crop columns. This choice is checked against the run's observed climate years.

That means the crop schedule is not free-form. If the climate is observed from 2008 through 2015, the chosen accessor must resolve to valid columns for every year in that range.

If one year is missing, the later WEPP run step fails when it tries to build the crop rotation schedule for that field.

Crop-to-management lookup

rotation_lookup.tsv tells the system how to turn crop names into WEPP management files.

The database column can currently point to:

• weppcloud
• plant_file_db

Use weppcloud when the crop should map to a WEPPcloud management ID. Use plant_file_db when the crop should map to a .man file stored under ag_fields/plant_files/.

This lookup is where many "the model ran but the management is wrong" problems actually begin. If the crop spelling in the uploaded schedule does not match the lookup spelling, the crop cannot be mapped cleanly.

Why API-Backed Prep Matters

AgFields has several preprocessing steps that materially change what gets modeled. They are not bookkeeping.

For end users, the practical lesson is simple: if the prep products do not look reasonable, the final WEPP results will not become more trustworthy by rerunning them.

Field And Sub-Field Assumptions

AgFields does not assume one polygon equals one hydrologically uniform field.

Instead, it assumes:

• a user-defined field may cross multiple hydrologic units,
• those intersections can be represented as separate sub-fields,
• each sub-field can be modeled with a representative hillslope profile,
• each sub-field inherits climate, soils, and routing context from the watershed structure it intersects.

This is why one mapped field may become several modeled sub-fields.

That behavior is intentional. A large field that crosses more than one drainage setting can have materially different slope length, contributing area, and erosion response in different parts of the same mapped parcel.

Current simplifications to keep in mind:

• sub-fields are treated as hydrologically disconnected modeled units in this workflow,
• very small sub-fields can be filtered with sub_field_min_area_threshold_m2,
• representative slope files simplify local variation within each sub-field,
• operations such as terraces, turn rows, irrigation features, and temporary traffic patterns are not automatically inferred from the field polygon.

How To Work Through An AgFields Run

1. Prepare the base WEPPcloud project first. AgFields depends on the normal project DEM, watershed, soils, landuse context, and observed climate range.

2. Upload a field-boundary GeoJSON that includes field_id and crop-year columns. Expect the workflow to extract the attribute table into rotation_schedule.parquet.

3. Confirm the ID field and crop-year pattern. The ID must be stable across the workflow, and the crop-year pattern must match every observed climate year in the run.

4. Rasterize the field boundaries. This is where CRS mistakes and extent mismatches usually become obvious. If the fields do not overlap the DEM grid, stop and fix that before continuing.

5. Run sub-field abstraction. Expect fields that span more than one hydrologic setting to split into multiple sub-fields. That is normal and often the point of using AgFields.

6. Review the sub-field products before running WEPP. Check whether the resulting sub-fields match your understanding of field drainage structure.

7. Build or review rotation_lookup.tsv, and upload plant files if needed. This is the management-translation step. A clean crop lookup is more important than squeezing in every possible crop label variation.

8. Run WEPP per sub-field. Expect one WEPP hillslope-style simulation per sub-field rather than one simulation per original field polygon.

What Outputs To Look At

The most useful AgFields outputs are usually:

• ag_fields/sub_fields/sub_fields.geojson or sub_fields.WGS.geojson for inspecting the modeled sub-field layout,
• ag_fields/sub_fields/fields.parquet for the sub-field metadata table,
• wepp/ag_fields/output/ for the actual WEPP result files,
• AgFields Spatial and AgFields Metrics in export-oriented tooling when available.

Interpret results at the right scale:

• compare one field to another when the management question is field prioritization,
• compare sub-fields inside one field when the question is internal variability,
• compare years when the question is crop-rotation effect.

A large difference between two sub-fields in the same mapped field usually means the field spans different hydrologic settings, not that the model is unstable.

Assumptions And Limits

• AgFields requires observed climate years because the crop schedule is checked against explicit year columns.
• The uploaded GeoJSON must carry both usable geometry and a usable rotation table.
• field_id is required and should be stable and effectively unique for interpretation to remain clear.
• Crop names must match rotation_lookup.tsv; near-matches are still mismatches.
• Sub-fields are representative hydrologic units, not full operational replicas of every within-field feature.
• Results inherit the strengths and weaknesses of the underlying watershed, soils, climate, and management data.

Related Docs

• WEPP
• Ag Field Mod
• Getting Started