SWATGenXSWAT+ calibration QA
Matching USGS gages to SWAT+ channels
Calibrating SWAT+ against USGS streamflow only works when each gage sits on the channel that represents the same place in the model — here is how SWATGenX makes that match NHD-first, classifies every gage, and vets which ones are truly ready for hands-off calibration.
QA step 2 of 3 (delineation → this assignment → drainage-area audit). Peace River HUC-8 is the transparent full-inventory reference; the same screens run on the Myakka, Hillsborough, and Tampa Bay models below.
- 76-gage full inventory · nothing dropped
- 54 auto-cal eligible · 22 flagged for review
- NHD-first reach pick, SWAT-second mapping
- Obs coverage vetted: 16 hands-off cal-ready
This is the second step of the SWATGenX streamflow-QA pipeline: after the river network is delineated from NHDPlus HR (see the delineation comparison), each USGS gage has to be tied to the SWAT+ channel that represents the same hydrologic location. Get this wrong and a perfectly good model will appear to fail calibration for the wrong reason.
We use the Peace River HUC-8 (Florida) as a transparent, fully public reference: how the NHD-first assignment works, how every gage is classified (tributary, mainstem, lake outlet, canal), and how many gages clear the quality gates for hands-off calibration. Per-gage area fidelity — whether the assigned channel carries the right drainage area — is then checked on the drainage-area audit page.
Assignment is necessary but not sufficient. The same v3 screens now run across the neighboring Florida-fleet models (Myakka, Hillsborough, and the Tampa Bay catalog outlet), and applying them there taught us a lesson worth its own section below: observation coverage has to be vetted independently of assignment, because a station file can be 100% missing-data sentinel while looking perfectly assigned on every map.
Motivation
Why gage assignment comes first
A SWAT+ model can only be calibrated against a USGS gage if that gage is tied to the channel representing the same place in the model. SWATGenX makes that match on the Peace River HUC-8 (Florida) reference model and records it transparently — extraction, the assignment class of every gage, and which ones clear the gates for automatic calibration, reported over the full 76-gage inventory rather than a hand-picked subset.
- Aim: Show how we assign gages (NHD-first, SWAT-second) and how many pass each quality gate before calibration.
- What we conclude: 54 gages are auto-cal eligible by class; 22 are flagged for manual review (still mapped). Only 16 meet class + obs + SWAT/NHD checks for hands-off calibration.
- Next: Per-gage area diagnostics and outlier investigation on the drainage-area audit page.
Methods
Peace River HUC-8 — reference watershed
Tier L Florida benchmark (03100101): whole-HUC-8 SWAT+ with 76 USGS gages after v3 assignment to chandeg.con.
How we assign USGS gages to SWAT+ rivers
NHD-first: pick the NHDPlus HR reference reach using coordinates, USGS NWIS site drainage area (when available), GNIS/name context, stream order, LevelPath, FType, and lake/canal flags—without using SWAT+ AreaC or chandeg.con area. SWAT-second: map that reach to executable chandeg.con via crosswalk or controlled downstream replacement. Drainage-area comparison runs only after assignment, on calibration-ready stations.
- NHD-first reference reach (no SWAT area for reach choice)
- SWAT-second map to chandeg.con GIS channel
- Assignment class and calibration eligibility
- SWAT+ vs NHDPlus HR TotDASqKm ratio (drainage-area fidelity)
NHD-first reference reach (hydrography + NWIS site context, no SWAT area), then SWAT-second map to chandeg.con via NHD→GIS crosswalk or controlled downstream replacement. SWAT+ area is not used to pick the reach—only to audit fidelity afterward.
Results and discussion
Full accounting — all 76 Peace gages
Every gage receives an assignment class. Counts below are from the production Peace inventory and must sum to 76. We do not drop gages from this table—manual-review and area-bias flags are shown explicitly.
- 76 in-basin USGS gages with v3 channel assignment
- = 54 auto-cal assignment class + 22 manual-review class (13 lake outlet · 9 canal)
- Of auto-cal class: 52 with SWAT/NHD in 0.5–2.0× SWAT/NHD; 2 with SWAT/NHD outside band (2 also lack usable obs → process audit on drainage-area page)
- 20 have usable 2000–2024 obs (any class); 4 of those are manual-review only (usable obs but not auto-cal)
- 16 cal-ready for automatic calibration (auto-cal class + usable obs + 0.5–2.0× SWAT/NHD SWAT/NHD)
Counts by assignment class
Auto-cal columns apply only to the three calibration-ready classes. Review gages remain in the model but are excluded from automatic calibration until reviewed.
| Assignment class | Gages | Usable obs | SWAT/NHD OK | SWAT/NHD bias | Cal-ready | Meaning |
|---|---|---|---|---|---|---|
Clean tributary tributary_clean | 36 | 12 | 34 | 2 | 12 | Tributary reach; channel choice and SWAT/NHD look consistent |
Mainstem — known NHD offset mainstem_known_nhd_offset | 16 | 4 | 16 | 0 | 4 | Mainstem reach; ~10–17% SWAT+ vs NHD offset documented on Peace |
Clean mainstem mainstem_clean | 2 | 0 | 2 | 0 | 0 | Mainstem reach; SWAT/NHD within tight tolerance |
Lake outlet — review lake_outlet_review | 13 | 3 | — | — | 0 | Lake outlet or lake-linked routing — human review before auto-calibration |
Canal / artificial — review canal_or_artificial_review | 9 | 1 | — | — | 0 | Canal, ditch, or artificial path — human review before auto-calibration |
| Total | 76 | 20 | 72 | 2 | 16 | All Peace gages |
Drainage-area snapshot — all Peace gages
USGS NWIS site drainage, NHDPlus HR cumulative area on the assigned reach, and SWAT+ chandeg.con area for every Peace gage. Scatter plots use gages where both compared areas exist; the inventory table lists all 76 with flags for large gaps and cal-ready status.
Large NHD–USGS gaps on canals and lake outlets are expected and visible here—they are why those classes are marked for manual review, not hidden from the inventory.
- USGS site drainage — area published for the gage in the USGS station catalog (independent check).
- NHD reference area — cumulative drainage on the NHDPlus HR stream reach we assign to the gage (national hydrography).
- SWAT+ channel area — drainage area of the executable model channel after routing assignment (compare to both USGS and NHD below).
drain_area_va in NWIS (NHD–USGS scatter and gap bands use the remaining 57). SWAT+ vs NHD scatter uses 76 gages with both areas. NHD vs USGS (57 paired): 15 within 10%; 6 over 50% (0 over 100%). SWAT+ vs USGS: 33 within 10%; 12 over 50% (4 over 100%). On 38 of 57 paired gages, SWAT+ is closer to the USGS catalog than NHD was.NHD vs USGS — gap bands
SWAT+ vs USGS — gap bands
Large gaps vs who must be reviewed by hand
Drainage-area scatter plots
Chart A — NHD vs USGS (map vs catalog)
Chart B — SWAT+ vs NHD (model vs map)
Chart C — SWAT+ vs USGS (model vs catalog)
Full Peace inventory (76 gages)
Every in-basin USGS station after v3 assignment. Amber rows: |NHD−USGS| or |SWAT+−USGS| >50%. Cal-ready = auto-cal class + usable 2000–2024 obs + SWAT/NHD in 0.5–2.0×.
| USGS | Assignment | USGS (km²) | NHD (km²) | SWAT+ (km²) | NHD−USGS | SWAT+−USGS | SWAT/NHD | Obs | Cal-ready |
|---|---|---|---|---|---|---|---|---|---|
| 02293681 | lake_outlet_reviewreview | 53.09 | 78.53 | 126.94 | +47.91% | +139.09% | ×1.03 | no | — |
| 02293694 | canal_or_artificial_reviewreview | 150.22 | 78.53 | 9.8 | -47.72% | -93.48% | ×0.12 | no | — |
| 02293986 | canal_or_artificial_reviewreview | 414.4 | 0.14 | 0.14 | -99.97% | -99.97% | ×0.99 | no | — |
| 02293987 | canal_or_artificial_reviewreview | 419.58 | 386.91 | 404.85 | -7.79% | -3.51% | ×1.05 | yes | — |
| 02294068 | lake_outlet_reviewreview | 59.57 | 37.81 | 29.98 | -36.52% | -49.67% | ×0.79 | no | — |
| 02294161 | lake_outlet_reviewreview | 530.43 | 503.9 | 590.62 | -5% | +11.35% | ×1.17 | partial | — |
| 02294260 | lake_outlet_reviewreview | — | 50.04 | 61.04 | — | — | ×1.22 | partial | — |
| 02294261 | lake_outlet_reviewreview | — | 52.17 | 61.04 | — | — | ×1.17 | partial | — |
| 02294290 | lake_outlet_reviewreview | 157.99 | 135.27 | 335.26 | -14.38% | +112.2% | ×2.48 | partial | — |
| 02294330 | lake_outlet_reviewreview | 55.43 | 48.74 | 63.59 | -12.06% | +14.72% | ×1.3 | partial | — |
| 02294405 | canal_or_artificial_reviewreview | 48.69 | 32.96 | 48.53 | -32.31% | -0.33% | ×1.47 | partial | — |
| 02294655 | lake_outlet_reviewreview | 1,023.05 | 865.34 | 1,046.57 | -15.42% | +2.3% | ×1.21 | yes | — |
| 02294705 | lake_outlet_reviewreview | — | 865.34 | 1,046.57 | — | — | ×1.21 | no | — |
| 02294775 | lake_outlet_reviewreview | 1,025.64 | 865.34 | 1,046.57 | -15.63% | +2.04% | ×1.21 | yes | — |
| 02295163 | lake_outlet_reviewreview | 111.37 | 114.31 | 126.51 | +2.64% | +13.6% | ×1.11 | partial | — |
| 02296750 | lake_outlet_reviewreview | 3,540.51 | 3,036.01 | 3,415.87 | -14.25% | -3.52% | ×1.13 | yes | — |
| 02297105 | lake_outlet_reviewreview | 4,325.28 | 3,071.18 | 3,754.94 | -28.99% | -13.19% | ×1.22 | partial | — |
| 280242081531600 | canal_or_artificial_reviewreview | — | 7.88 | 7.88 | — | — | ×1 | no | — |
| 280441081520200 | canal_or_artificial_reviewreview | — | 8.94 | 13.74 | — | — | ×1.54 | no | — |
| 280531081520500 | canal_or_artificial_reviewreview | — | 4.62 | 5.56 | — | — | ×1.2 | no | — |
| 280531081520501 | canal_or_artificial_reviewreview | — | 4.62 | 5.56 | — | — | ×1.2 | no | — |
| 280557081512300 | canal_or_artificial_reviewreview | — | 2.04 | 2.04 | — | — | ×1 | no | — |
| 02294217 | tributary_cleanauto-cal | 137.27 | 106.14 | 120.73 | -22.67% | -12.05% | ×1.14 | yes | yes |
| 02294491 | tributary_cleanauto-cal | 349.65 | 281.84 | 335.26 | -19.39% | -4.12% | ×1.19 | partial | — |
| 02294650 | mainstem_known_nhd_offsetauto-cal | 1,010.1 | 842.37 | 987.62 | -16.61% | -2.22% | ×1.17 | yes | yes |
| 02294747 | tributary_cleanauto-cal | — | 891.56 | 1,046.57 | — | — | ×1.17 | yes | yes |
| 02294760 | tributary_cleanauto-cal | — | 4.06 | 4.87 | — | — | ×1.2 | yes | yes |
| 02294781 | mainstem_known_nhd_offsetauto-cal | 1,064.49 | 910.65 | 1,066.47 | -14.45% | +0.19% | ×1.17 | yes | yes |
| 02294898 | mainstem_known_nhd_offsetauto-cal | 1,243.19 | 995.39 | 1,162.67 | -19.93% | -6.48% | ×1.17 | yes | yes |
| 02295013 | tributary_cleanauto-cal | 122.25 | 133.14 | 123.18 | +8.91% | +0.77% | ×0.93 | yes | yes |
| 02295194 | mainstem_known_nhd_offsetauto-cal | 1,587.66 | 1,342.3 | 1,537.73 | -15.45% | -3.14% | ×1.15 | partial | — |
| 02295203 | mainstem_known_nhd_offsetauto-cal | 1,590.25 | 1,352.06 | 1,548.04 | -14.98% | -2.65% | ×1.14 | no | — |
| 02295420 | tributary_cleanauto-cal | 313.39 | 181.28 | 231.22 | -42.15% | -26.22% | ×1.28 | yes | yes |
| 02295435 | tributary_cleanauto-cal | 13.75 | 13.15 | 13.73 | -4.41% | -0.18% | ×1.04 | no | — |
| 02295440 | mainstem_known_nhd_offsetauto-cal | 1,952.85 | 1,572.44 | 1,818.91 | -19.48% | -6.86% | ×1.16 | no | — |
| 02295520 | tributary_cleanauto-cal | — | 49.28 | 57.28 | — | — | ×1.16 | partial | — |
| 02295521 | tributary_cleanauto-cal | — | 49.28 | 9.47 | — | — | ×1.01 | no | — |
| 02295580 | tributary_cleanauto-cal | — | 92.5 | 110.72 | — | — | ×1.2 | partial | — |
| 02295607 | mainstem_known_nhd_offsetauto-cal | 2,092.71 | 1,683.97 | 1,949.98 | -19.53% | -6.82% | ×1.16 | no | — |
| 02295637 | mainstem_known_nhd_offsetauto-cal | 2,139.33 | 1,731.62 | 2,001.16 | -19.06% | -6.46% | ×1.16 | yes | yes |
| 02295755 | tributary_cleanauto-cal | 9.71 | 7.63 | 7.62 | -21.47% | -21.52% | ×1 | no | — |
| 02295798 | mainstem_known_nhd_offsetauto-cal | — | 1,897.45 | 2,167.13 | — | — | ×1.14 | no | — |
| 02295850 | tributary_cleanauto-cal | 38.85 | 58.98 | 60.19 | +51.82% | +54.92% | ×1.02 | no | — |
| 02296057 | tributary_cleanauto-cal | 45.32 | 44.01 | 41.42 | -2.9% | -8.61% | ×0.94 | partial | — |
| 02296180 | tributary_cleanauto-cal | 54.91 | 37.94 | 46.28 | -30.91% | -15.7% | ×1.22 | no | — |
| 02296191 | mainstem_known_nhd_offsetauto-cal | 79.25 | 80.99 | 89.29 | +2.2% | +12.67% | ×1.1 | no | — |
| 02296207 | tributary_cleanauto-cal | 98.68 | 86.57 | 94.87 | -12.27% | -3.86% | ×1.1 | no | — |
| 02296222 | mainstem_known_nhd_offsetauto-cal | 108.52 | 95.58 | 103.86 | -11.93% | -4.29% | ×1.09 | partial | — |
| 02296223 | tributary_cleanauto-cal | 108.52 | 95.58 | 103.86 | -11.93% | -4.29% | ×1.09 | no | — |
| 02296260 | tributary_cleanauto-cal | 497.28 | 468.69 | 492.29 | -5.75% | -1% | ×1.05 | yes | yes |
| 02296389 | tributary_cleanauto-cal | 168.61 | 140.64 | 732.11 | -16.59% | +334.21% | ×5.21 | partial | — |
| 02296500 | tributary_cleanauto-cal | 854.7 | 805.46 | 870.02 | -5.76% | +1.79% | ×1.08 | yes | yes |
| 02296525 | mainstem_known_nhd_offsetauto-cal | — | 2,873.3 | 3,228.51 | — | — | ×1.12 | no | — |
| 02297000 | tributary_cleanauto-cal | — | 172.95 | 183.19 | — | — | ×1.06 | no | — |
| 02297100 | tributary_cleanauto-cal | 341.88 | 289.74 | 312.12 | -15.25% | -8.7% | ×1.08 | yes | yes |
| 02297153 | tributary_cleanauto-cal | 34.96 | 23.84 | 87.72 | -31.82% | +150.88% | ×1.48 | no | — |
| 02297155 | tributary_cleanauto-cal | 108.78 | 89.11 | 125.58 | -18.08% | +15.45% | ×1.41 | yes | yes |
| 02297220 | tributary_cleanauto-cal | 123.8 | 97.08 | 101.44 | -21.59% | -18.07% | ×1.04 | no | — |
| 02297251 | tributary_cleanauto-cal | 336.7 | 287.28 | 327.86 | -14.68% | -2.62% | ×1.14 | partial | — |
| 02297272 | tributary_cleanauto-cal | 39.11 | 37.63 | 41.39 | -3.77% | +5.82% | ×482.92 | no | — |
| 02297290 | tributary_cleanauto-cal | 74.33 | 72.53 | 74.07 | -2.43% | -0.36% | ×1.02 | no | — |
| 02297310 | tributary_cleanauto-cal | 564.62 | 516.24 | 23.72 | -8.57% | -95.8% | ×1.02 | yes | yes |
| 02297345 | mainstem_known_nhd_offsetauto-cal | — | 4,007.5 | 4,463.27 | — | — | ×1.11 | no | — |
| 02297350 | mainstem_known_nhd_offsetauto-cal | 4,610.18 | 4,013.3 | 4,468.19 | -12.95% | -3.08% | ×1.11 | no | — |
| 02297460 | mainstem_known_nhd_offsetauto-cal | 4,843.28 | 4,130.56 | 4,595.75 | -14.72% | -5.11% | ×1.11 | no | — |
| 02297600 | tributary_cleanauto-cal | — | 153.72 | 165.61 | — | — | ×1.08 | partial | — |
| 02297635 | tributary_cleanauto-cal | 233.36 | 202.59 | 221.57 | -13.19% | -5.05% | ×1.09 | partial | — |
| 02297733 | mainstem_cleanauto-cal | 17.2 | 0.31 | 0.3 | -98.19% | -98.25% | ×0.97 | no | — |
| 02297875 | mainstem_cleanauto-cal | 37.3 | 66.77 | 67.04 | +79.03% | +79.75% | ×1 | no | — |
| 02298110 | tributary_cleanauto-cal | — | 409.66 | 161.13 | — | — | ×1.06 | partial | — |
| 02298123 | tributary_cleanauto-cal | 603.47 | 5.8 | 206.18 | -99.04% | -65.83% | ×1.04 | yes | yes |
| 02298124 | tributary_cleanauto-cal | 631.96 | 626.39 | 651.37 | -0.88% | +3.07% | ×1.04 | no | — |
| 02298170 | tributary_cleanauto-cal | 673.4 | 692.46 | 720.84 | +2.83% | +7.05% | ×1.04 | partial | — |
| 02298202 | tributary_cleanauto-cal | 966.07 | 929.9 | 977.24 | -3.74% | +1.16% | ×1.05 | yes | yes |
| 02298300 | mainstem_known_nhd_offsetauto-cal | 5,956.97 | 5,229.5 | 5,755.82 | -12.21% | -3.38% | ×1.1 | no | — |
| 274319081452000 | tributary_cleanauto-cal | 0.31 | 0.1 | 0.1 | -69.24% | -68.83% | ×1.01 | no | — |
Observation coverage is vetted independently of assignment
A gage can be perfectly assigned and still have nothing to calibrate against. Daily-streamflow archives use a −99 sentinel for missing values, and a station file can be entirely sentinel: On the Myakka model, 20 of 34 station observation files were 100% −99 sentinel — no real observations at all — while looking perfectly assigned on every map and carrying a misleading 0% gap in the inventory metadata.
Assignment-only or drainage-area-only vetting cannot catch this, so observation coverage is its own gate in the v3 inventory: A gage counts as cal-ready only if ≥80% of calendar days in the observation window carry a real (non-sentinel) value; the check counts days that are non-NaN and ≠ −99. That is the usable obs column in the tables above — and on Peace it is the decisive cut: On Peace this gate, not assignment, is the big cut: 54 class-eligible gages → 16 hands-off cal-ready.
Implementation: SWATGenX/streamflow_obs_coverage.py (usableObsForCal), consumed by the v3 inventory exporter and the calibration roster builders.
The same screens across the Florida fleet
The v3 NHD-first assignment and its readiness screens are not a Peace-only demo. The same gates run on the neighboring west-central Florida models; counts below are computed from the on-disk assignment inventories (v3 basins) and the Tampa Bay catalog drainage-area screen.
| Basin / model | Screen | Stations | Pass | Flagged | Flag breakdown |
|---|---|---|---|---|---|
Peace River HUC-8 03100101 | v3 assignment class | 76 | 54 | 22 | 13 lake outlet · 9 canal/artificial |
Myakka River HUC-8 03100102 | v3 assignment class | 34 | 23 | 11 | 7 lake outlet · 3 canal/artificial · 1 review |
Hillsborough River HUC-8 03100205 | v3 assignment class | 50 | 29 | 21 | 12 lake outlet · 5 canal/artificial · 2 ambiguous · 2 excluded |
Tampa Bay catalog outlet 031002060700 | drainage-area ratio flag (500 m catalog assignment) | 58 | 40 | 18 | all 18 flags outside ~0.5–1.8 model/USGS drainage ratio (0.0013–0.47 and 2.0–12.3) |
Tampa Bay uses a different screen: every gauge there has daily observations, and the flag is a model-vs-USGS drainage-area ratio band on the 500 m catalog assignment (58 gauges: median ratio 0.85; 40 in-band, 18 flagged). It answers the same question — is this gauge on the channel that drains what USGS says it drains — on a catalog model rather than a v3 workspace.
Sources: publication/analysis/qa/peace-station-assignment-v3-inventory.csv · model workspace 0310/huc8/03100102 · streamflow_data/stations_assignment_v3.csv · model workspace 0310/huc8/03100205 · streamflow_data/stations_assignment_v3.csv · publication/peace-multiscale-calibration/research/tampa_catalog_streamflow_stats.csv
Conclusion
Next step — does the assigned channel carry the right area?
Assignment (this page, QA step 2) ties each gage to a channel. The drainage-area audit (step 3) then verifies that the assigned channel actually carries the correct drainage area in the executable TxtInOut model — investigating outliers, process-audit gages, and the systematic SWAT+-vs-NHD offset, before calibration begins.
FAQ
How does SWATGenX assign USGS gages to SWAT+ channels?
NHD-first, SWAT-second. The reference reach is picked on the NHDPlus HR hydrography using the gage coordinates and NWIS site context (drainage area where reported, stream name, lake/canal setting) — SWAT+ areas play no role in the pick. That reference reach is then crosswalked to the SWAT+ chandeg.con channel, every gage gets an assignment class (clean tributary, clean mainstem, mainstem with known NHD offset, lake outlet, canal/artificial), and only the three calibration-ready classes with vetted observation coverage and an in-band SWAT/NHD area ratio go to hands-off calibration. On the Peace River HUC-8 reference inventory that is 76 gages → 54 auto-cal eligible by class → 16 fully cal-ready.
Why is a correct channel assignment not enough for automatic calibration?
Because a gage can be perfectly placed and still have nothing to calibrate against. Streamflow archives use a −99 sentinel for missing days, and a station file can be 100% sentinel — on the neighboring Myakka HUC-8 model, 20 of 34 station observation files contained no real observations at all, so a roster vetted on assignment and drainage area alone would have dispatched calibrations against empty records. SWATGenX therefore vets observation coverage as its own gate: a gage only counts as cal-ready if at least 80% of the calendar days in the calibration window carry real (non-sentinel) values. On Peace, that gate — not assignment — is the big cut: 54 class-eligible gages reduce to 16 hands-off cal-ready.
Why not assign stations using nearest channel or SWAT drainage area alone?
Nearest-channel rules fail at tributary–mainstem confluences, lake outlets, and canals. Area-only matching can pick a mainstem reach with plausible TotDASqKm while the gage is on a tributary. SWATGenX therefore selects an NHDPlus HR reference reach first, then maps it to SWAT+ output.
Does SWAT+ drainage area choose the reference reach?
Not in the improved method. QSWAT AreaC and chandeg.con areas are used only after assignment to audit agreement and classify calibration readiness. That keeps assignment errors separate from true SWAT+ vs NHDPlus HR area differences.
What stations are used on the drainage-area audit page?
Drainage-area closure should be interpreted on stations classified as calibration-ready (mainstem_clean, tributary_clean, or mainstem_known_nhd_offset with documented offset). Lake, canal, ambiguous, and missing-output stations require review or exclusion first.
What is mainstem_known_nhd_offset?
The station is on the correct mainstem channel, but SWAT+ chandeg area is systematically higher than NHD TotDASqKm (about 10–17% on Peace mainstem gages). That is treated as a delineation-definition offset, not fixed by moving the gage to a smaller side channel.
Related guides
Explore related
Last updated 2026-07-13.