HmsArf¶
Areal reduction factor helpers for design-storm workflows.
hms_commander.HmsArf
¶
HmsArf - Areal Reduction Factor (ARF) Operations
This module provides static methods for applying Areal Reduction Factors to HEC-HMS meteorologic model files. ARFs adjust precipitation depths to account for the spatial variability of rainfall over large drainage areas.
All methods are static and designed to be used without instantiation.
HmsArf
¶
Areal Reduction Factor (ARF) application for HEC-HMS met files.
Applies ARF scalars to precipitation depths in .met files, scaling point precipitation to areal averages based on subbasin-specific reduction factors.
Supports two workflows:
- Compute: Per-junction ARF values from DAR curves and CDA
(compute_kcda_cdas, lookup_arf_from_dar, build_kcda_arf_table)
- Apply: ARF scalar to global depths in a met file (apply_arf)
All methods are static - no instantiation required.
Example
from hms_commander import HmsArf dar_curve = [(10, 1.0), (100, 0.97), (1000, 0.92), (10000, 0.85)] table = HmsArf.build_kcda_arf_table( ... "watershed.basin", ["J-Outlet"], dar_curve ... ) result = HmsArf.apply_arf("model.met", arf=table.loc[0, 'arf']) print(f"Updated {result['depths_modified']} depths")
Source code in hms_commander/HmsArf.py
25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 | |
validate_arf_table(met_path, arf_table, hms_object=None)
staticmethod
¶
Verify all subbasins in met file have ARF values in the table.
Parameters¶
met_path : str or Path Path to the .met file arf_table : dict or pd.DataFrame If dict: {subbasin_name: arf_scalar}. If DataFrame: must have columns 'subbasin' and 'arf'. hms_object : optional Optional HmsPrj instance
Returns¶
dict Validation result with keys: - valid: bool — True if all subbasins have ARF values - met_subbasins: list — subbasins found in met file - arf_subbasins: list — subbasins in ARF table - missing: list — subbasins in met file but not in ARF table - extra: list — subbasins in ARF table but not in met file
Example¶
result = HmsArf.validate_arf_table("model.met", arf_table) if not result['valid']: ... print(f"Missing ARFs for: {result['missing']}")
Source code in hms_commander/HmsArf.py
apply_arf(met_path, arf_table=None, arf=None, preserve_original=True, hms_object=None)
staticmethod
¶
Apply Areal Reduction Factors to precipitation depths in a met file.
Two usage modes:
Mode 1 – Direct scalar (A03 workflow, "Frequency Based Hypothetical"):
Pass arf as a float. All Depth: lines inside the
Precip Method Parameters: block are multiplied by the scalar.
This correctly handles met files where subbasin blocks are empty
and depths live only in the global parameters block.
Mode 2 – Per-subbasin table (met files with per-subbasin depth lines):
Pass arf_table as a dict or DataFrame. Each subbasin block that
contains Depth: lines is updated with its own ARF scalar. Falls
back to mean-ARF global modification when no subbasin blocks have depths.
Parameters¶
met_path : str or Path
Path to the .met file
arf_table : dict or pd.DataFrame, optional
If dict: {subbasin_name: arf_scalar}.
If DataFrame: must have columns 'subbasin' and 'arf'.
Ignored when arf is provided.
arf : float, optional
Single scalar ARF applied to ALL Depth: lines in the
Precip Method Parameters: block. Takes precedence over
arf_table when provided.
preserve_original : bool, default True
If True, creates a backup copy (.met.bak) before modifying.
hms_object : optional
Optional HmsPrj instance
Returns¶
dict Summary with keys: - subbasins_updated: int - subbasins_skipped: int - depths_modified: int — number of Depth: lines changed - changes: list of dict — per-subbasin/global change details - backup_path: str or None
Example¶
A03: Apply 0.92 ARF to all global depths¶
result = HmsArf.apply_arf("model.met", arf=0.92) print(f"Modified {result['depths_modified']} depth values")
Per-subbasin ARF table¶
arf_table = {'Subbasin-1': 0.92, 'Subbasin-2': 0.88} result = HmsArf.apply_arf("model.met", arf_table=arf_table)
Notes¶
ARF scalars are typically between 0.0 and 1.0, where 1.0 means no reduction. Values > 1.0 are allowed but will produce a warning.
Source code in hms_commander/HmsArf.py
119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 | |
compute_kcda_cdas(basin_path, kcda_junctions, hms_object=None)
staticmethod
¶
Compute Contributing Drainage Area (CDA) at each KCDA junction.
Traverses the basin network upstream from each KCDA junction and sums the subbasin areas to obtain the Contributing Drainage Area.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
basin_path
|
Union[str, Path]
|
Path to the .basin file |
required |
kcda_junctions
|
List[str]
|
List of KCDA junction names (analysis points) |
required |
hms_object
|
Optional HmsPrj instance |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
DataFrame with columns: |
DataFrame
|
|
DataFrame
|
|
DataFrame
|
|
DataFrame
|
|
Example
cdas = HmsArf.compute_kcda_cdas( ... "watershed.basin", ["J-Outlet", "J-Fork-A"] ... ) print(cdas[['junction', 'cda_acres', 'subbasin_count']])
Source code in hms_commander/HmsArf.py
lookup_arf_from_dar(cda, dar_curve, duration_hours=24.0)
staticmethod
¶
Interpolate ARF from a DAR (Depth-Area Reduction) curve at a given CDA.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cda
|
float
|
Contributing drainage area (same units as dar_curve 'area' column or first element of each tuple) |
required |
dar_curve
|
Union[DataFrame, List[Tuple[float, float]], Dict]
|
One of: - DataFrame with columns ['area', 'arf'] - List of (area, arf) tuples, sorted or unsorted - Dict keyed by duration_hours → list of (area, arf) tuples, e.g. {6.0: [(10, 1.0), ...], 24.0: [(10, 1.0), ...]} |
required |
duration_hours
|
float
|
Used only when dar_curve is a duration-keyed dict. Selects the nearest available duration key. |
24.0
|
Returns:
| Name | Type | Description |
|---|---|---|
float |
float
|
ARF value in [min_curve_arf, 1.0]. |
float
|
Returns 1.0 if CDA is at or below the minimum curve area |
|
float
|
(no reduction for very small areas). Extrapolation beyond the |
|
float
|
maximum curve area returns the last (smallest) ARF value. |
Example
dar = [(10, 1.0), (100, 0.97), (1000, 0.92), (10000, 0.85)] HmsArf.lookup_arf_from_dar(500, dar) # between 100 and 1000 0.945 # approx
Source code in hms_commander/HmsArf.py
build_kcda_arf_table(basin_path, kcda_junctions, dar_curve, duration_hours=24.0, hms_object=None)
staticmethod
¶
Compute ARF for each KCDA junction from DAR curves and drainage area.
Combines compute_kcda_cdas() and lookup_arf_from_dar() into a
single call. Specify outlet junctions → traverse upstream → sum subbasin
areas → CDA → look up ARF from DAR curve.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
basin_path
|
Union[str, Path]
|
Path to the .basin file |
required |
kcda_junctions
|
List[str]
|
KCDA junction names (analysis points) |
required |
dar_curve
|
Union[DataFrame, List[Tuple[float, float]], Dict]
|
DAR curve (see |
required |
duration_hours
|
float
|
Storm duration for DAR curve lookup (default: 24) |
24.0
|
hms_object
|
Optional HmsPrj instance |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
DataFrame sorted ascending by CDA with columns: |
DataFrame
|
|
DataFrame
|
|
DataFrame
|
|
DataFrame
|
|
DataFrame
|
|
DataFrame
|
|
Example
dar_curve = [(10, 1.0), (100, 0.97), (1000, 0.92), (10000, 0.85)] table = HmsArf.build_kcda_arf_table( ... "watershed.basin", ... ["J-Outlet", "J-Mid", "J-Headwater"], ... dar_curve, ... duration_hours=24, ... ) print(table[['junction', 'cda_acres', 'arf']])
Source code in hms_commander/HmsArf.py
Texas 1-day ARF (Asquith 1999)¶
HmsArfTexas implements the circular-watershed and cell-based areal-reduction
factors of USGS WRIR 99-4267 (Table 7, Table 8) for Austin, Dallas and Houston.
It does not edit met files.
Scope. 24-hour (1-day) design storm, recurrence interval of 2 years or
greater, circular-equivalent radius 0-50 mi, and the three study areas.
extrapolate=True relaxes only the radius/area domain (beyond 50 mi, with a
logged warning). A duration other than 24 hr and a recurrence interval below
2 years always raise ValueError, regardless of extrapolate; WRIR 99-4267
(p. 25) limits the method to the one-day duration. Non-finite or negative
circular radii/areas and scaling depths raise ValueError; cell areas must
also be positive. Invalid numeric inputs (including bools, strings, and values
outside the float64 range) raise ValueError. A computed ARF or S2 outside
(0, 1] also raises ValueError from circular_arf, noncircular_arf,
depth_distance and therefore
scale_depth and scale_hyetograph; this can occur only with
extrapolate=True. The TxDOT HDM
cautions that applicability diminishes with distance from Austin, Dallas and
Houston and as the design-storm duration departs from 1 day; the module does
not check the watershed location.
Dallas 24-27 mi row. By default the module reproduces Table 7 as printed,
including an ARF intercept of 0.6800 for Dallas, 24 <= r <= 27 mi. The S2
intercept in that row is 0.6880, and in the other 29 rows the ARF intercept
equals the S2 intercept; 0.6880 makes the ARF approximately continuous at
r = 24 mi (a residual of about 0.0003 remains, like the other joins). Joins
select the higher-radius segment, so the corrected or printed row applies over
24 <= r < 27 mi.
Pass dallas_intercept_correction=True to circular_arf, scale_depth or
scale_hyetograph to use 0.6880 (ARF about 0.008 higher for Dallas areas of
roughly 1,810-2,290 mi2). No erratum has been located; the correction is an
inference from the report's own equations.
HDM Table 4-12 typos. The HDM table differs from WRIR Table 7 in two Houston entries: the 7-11 mi ARF intercept (HDM 0.8708, WRIR 0.8078) and the 15-20 mi ARF slope (HDM 0.00053, WRIR 0.0053). The module follows the WRIR.
from hms_commander import HmsArfTexas
arf = HmsArfTexas.circular_arf("dallas", area_mi2=50.3, recurrence_interval_yr=100) # 0.85
depth = HmsArfTexas.scale_depth(9.55, "dallas", area_mi2=50.3, recurrence_interval_yr=100)
hms_commander.HmsArfTexas
¶
HmsArfTexas - Texas 1-day areal-reduction factor (Asquith, 1999)
Implements the areal-reduction factor (ARF) equations published in Table 7 of
Asquith, W.H., 1999, Areal-Reduction Factors for the Precipitation of the
1-Day Design Storm in Texas: U.S. Geological Survey Water-Resources
Investigations Report 99-4267, 81 p.
The same equations are reproduced as Table 4-12 of the TxDOT Hydraulic Design Manual (Ch. 4, Sec. 13, 09/2019).
Scope. Duration and recurrence interval are hard limits that extrapolate
never relaxes; only the radius/area domain can be extrapolated:
- 1-day (24 hr) design storm only (the method rests on daily precipitation
data; WRIR 99-4267 p. 25 limits it to the one-day duration). Any other
duration raises
ValueError, even withextrapolate=True. - Three study areas only: Austin, Dallas, Houston.
- Circular-watershed radius 0 to 50 mi (area 0 to ~7,850 mi2); non-circular
watersheds use the report's cell method (distance of each cell to the
watershed centroid, 0 to 50 mi). Beyond 50 mi raises
ValueErrorunlessextrapolate=True(warning logged; last published segment continued). - Recurrence interval of 2 years or greater (smaller values raise
ValueError, even withextrapolate=True). The published relation is the "2-year or greater" depth-distance relation and is not a function of the recurrence interval within that range; the report notes that the true ARF does vary with recurrence interval, which this relation does not capture.
HDM caution (Sec. 13, p. 4-64): "the applicability of this method diminishes the farther away from the Austin, Dallas, or Houston areas the study area is and as the duration of the design storm increasingly differs from that of 1 day." The report (p. 25) says the same. Use for a watershed far from these cities, for other durations, or for rainfall events shorter than a day is an engineering judgement that this module does not validate.
All methods are static - no instantiation required.
HmsArfTexas
¶
Texas 1-day areal-reduction factors per Asquith (1999), USGS WRIR 99-4267.
ARF = (mean depth over the watershed) / (point depth of the design storm). The factor depends on watershed size and shape and on the city whose precipitation network defined the depth-distance relation. Multiply a 1-day, 2-year-or-greater point depth (e.g. NOAA Atlas 14) by the factor.
Caution: derived from Austin, Dallas and Houston daily data only. The HDM
states the method's applicability diminishes with distance from those
cities and as the storm duration departs from 1 day. Duration other
than 24 hr and recurrence interval below 2 yr always raise ValueError
(WRIR 99-4267 p. 25). Only the radius/area domain (0-50 mi) can be
extrapolated, with extrapolate=True (a warning is logged).
Example
from hms_commander import HmsArfTexas arf = HmsArfTexas.circular_arf("dallas", area_mi2=50.3, ... recurrence_interval_yr=100) round(arf, 2) 0.85 HmsArfTexas.scale_depth(9.55, "dallas", area_mi2=50.3, ... recurrence_interval_yr=100) # doctest: +SKIP
radius_from_area(area_mi2)
staticmethod
¶
Radius (mi) of the circle with the given area (mi2).
depth_distance(city, r_mi, *, extrapolate=False)
staticmethod
¶
Estimated 2-year-or-greater depth-distance relation S2(r), Table 7.
S2(r) is the expected ratio of concurrent depth at distance r from the point of the design storm to the point depth (dimensionless).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
city
|
str
|
'austin', 'dallas' or 'houston'. |
required |
r_mi
|
float
|
Distance in miles, 0 to 50. |
required |
extrapolate
|
bool
|
Allow r > 50 mi (last published segment, warning). |
False
|
Returns:
| Type | Description |
|---|---|
float
|
S2(r), dimensionless, 0 < S2 <= 1. |
Raises:
| Type | Description |
|---|---|
ValueError
|
bad city or distance, distance > 50 mi with
|
circular_arf(city, area_mi2=None, *, radius_mi=None, recurrence_interval_yr, duration_hr=DURATION_HR, extrapolate=False, dallas_intercept_correction=False)
staticmethod
¶
ARF for a circular watershed, Table 7 column "ARF2(r)".
Give either area_mi2 (the circle of equal area is used) or
radius_mi.
Valid for: 1-day duration, recurrence interval >= 2 yr, radius 0-50 mi (area up to ~7,854 mi2), and the three study areas. See the module docstring for the HDM caution about use away from Austin, Dallas and Houston.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
city
|
str
|
'austin', 'dallas' or 'houston'. |
required |
area_mi2
|
float
|
Watershed area, square miles. |
None
|
radius_mi
|
float
|
Radius of the circular watershed, miles. |
None
|
recurrence_interval_yr
|
float
|
Design-storm recurrence interval, years (required; must be >= 2). |
required |
duration_hr
|
float
|
Design-storm duration, hours. Must be 24 (the one-day limitation, WRIR 99-4267 p. 25); never relaxed. |
DURATION_HR
|
extrapolate
|
bool
|
Permit radius > 50 mi only; logs a warning and continues the last published segment. Does not relax the 24-hr duration or the 2-yr recurrence-interval limits. |
False
|
dallas_intercept_correction
|
bool
|
The default reproduces Table 7 exactly, including the printed Dallas 24-27 mi ARF intercept 0.6800. If True, use 0.6880, the value implied by the S2 intercept in the same row (ARF intercept = S2 intercept in the other 29 rows) and by continuity at r = 24 mi. |
False
|
Returns:
| Type | Description |
|---|---|
float
|
Areal-reduction factor, dimensionless, 0 < ARF <= 1. |
Raises:
| Type | Description |
|---|---|
ValueError
|
unknown city, bad/ambiguous size input, duration
!= 24 hr or recurrence interval < 2 yr (always, regardless
of |
noncircular_arf(city, distances_mi, areas_mi2, *, recurrence_interval_yr, duration_hr=DURATION_HR, extrapolate=False)
staticmethod
¶
ARF for a non-circular watershed by the report's cell method (Table 8).
The watershed is divided into cells; each cell's distance to the centroid is substituted into S2(r) and the area-weighted mean of S2 is the ARF (Asquith 1999, p. 32; HDM Sec. 13 steps 1-8).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
city
|
str
|
'austin', 'dallas' or 'houston'. |
required |
distances_mi
|
Sequence[float]
|
Distance from each cell to the watershed centroid. |
required |
areas_mi2
|
Sequence[float]
|
Area of each cell, square miles. |
required |
recurrence_interval_yr, duration_hr, extrapolate
|
as in
:meth: |
required |
Returns:
| Type | Description |
|---|---|
float
|
Areal-reduction factor, dimensionless, 0 < ARF <= 1. |
Raises:
| Type | Description |
|---|---|
ValueError
|
invalid inputs, scope violations as in
:meth: |
scale_depth(depth, city, area_mi2=None, *, radius_mi=None, recurrence_interval_yr, duration_hr=DURATION_HR, extrapolate=False, dallas_intercept_correction=False)
staticmethod
¶
Multiply a finite, nonnegative 1-day point depth (any depth unit) by the circular ARF.
Accepts a scalar, list, numpy array or pandas object; returns the same
kind (lists are returned as numpy arrays).
Parameters other than depth are as in :meth:circular_arf.
Raises:
| Type | Description |
|---|---|
ValueError
|
any non-finite or negative depth, or a validation
failure from :meth: |
scale_hyetograph(incremental_depths, city, area_mi2=None, *, radius_mi=None, recurrence_interval_yr, duration_hr=DURATION_HR, extrapolate=False, dallas_intercept_correction=False)
staticmethod
¶
Scale every ordinate of a 24-hour incremental hyetograph by the ARF.
The published factor is a single value for the whole 1-day storm, so the temporal pattern is preserved and the total depth is scaled by the ARF. Depths must be finite and nonnegative. Accepts a list, numpy array or pandas Series/DataFrame.
Raises:
| Type | Description |
|---|---|
ValueError
|
any non-finite or negative depth, or a validation
failure from :meth: |