Atlas 14 Precipitation¶
NOAA Atlas 14 provides precipitation frequency estimates for design storm modeling in the United States. The ras-commander precipitation subpackage provides five single-location hyetograph methods, two explicitly named gridded storm methods, and spatial analysis tools for integrating Atlas 14 data into HEC-RAS workflows.
Overview¶
Atlas 14 is the authoritative source for precipitation frequency estimates, used for:
- Regulatory floodplain mapping (1% AEP / 100-year events)
- Infrastructure design (drainage, culverts, bridges)
- Dam breach inundation studies (PMF, 0.2% AEP)
- Sensitivity analysis across multiple AEP events
Important: The pattern-based hyetograph methods take total_depth_inches as an input parameter. You specify the depth from the NOAA PFDS website for your location and AEP; the methods generate the temporal distribution for that depth. They do not automatically query NOAA for depth values. FrequencyStormDdf instead takes a cumulative depth-duration vector and preserves its 24-hour total, optionally reduced by an explicit TP-40 area factor.
Verify Atlas 14 depths at: https://hdsc.nws.noaa.gov/pfds/pfds_map_cont.html
Quick Start¶
Choose the temporal method explicitly. The alternating-block example below
builds a synthetic pattern from multiple durations. For a single duration's
spatial depth grid multiplied by an official NOAA temporal curve, use
Atlas14HyetographGrid as described in Gridded design-storm methods.
These methods answer different design questions; an Atlas 14 depth does not
uniquely specify a hyetograph or establish the resulting flood's AEP.
Generate a 24-hour, 1% AEP (100-year) design storm using the Alternating Block Method:
from ras_commander.precip import StormGenerator
# Step 1: Download DDF data for the temporal pattern (returns DataFrame)
# This queries the NOAA DDF tables used for temporal shape only
ddf_data = StormGenerator.download_from_coordinates(29.76, -95.37) # Houston, TX
# Step 2: Generate hyetograph with your Atlas 14 depth from NOAA PFDS
# (e.g., 17.0 inches for Houston 100-yr 24-hr, from hdsc.nws.noaa.gov/pfds)
hyeto = StormGenerator.generate_hyetograph(
ddf_data=ddf_data,
total_depth_inches=17.0, # Your Atlas 14 depth from NOAA PFDS
duration_hours=24,
position_percent=50 # Peak at 50% of storm (centered)
)
# hyeto is a DataFrame with columns: hour, incremental_depth, cumulative_depth
print(f"Total: {hyeto['cumulative_depth'].iloc[-1]:.6f} inches") # Exact: 17.000000
For HMS-equivalent results, use Atlas14Storm from hms-commander:
from ras_commander.precip import Atlas14Storm, ATLAS14_AVAILABLE
if ATLAS14_AVAILABLE:
hyeto = Atlas14Storm.generate_hyetograph(
total_depth_inches=17.0, # Your Atlas 14 depth from NOAA PFDS
state="tx",
region=3,
aep_percent=1.0,
quartile="All Cases"
)
print(f"Total: {hyeto['cumulative_depth'].iloc[-1]:.6f} inches") # Exact: 17.000000
Method Selection Guide¶
Summary Table¶
| Method | HMS Equivalent | Depth Conservation | Durations | Best For |
|---|---|---|---|---|
| Atlas14Storm | YES (10^-6) | Exact | 6h, 12h, 24h, 96h | Modern Atlas 14, regulatory submittals |
| FrequencyStormDdf | Bounded record agreement | Point or reduced total | 24h / 5min | Depth-duration inputs, 50%/67% placement, optional TP-40 reduction |
| FrequencyStorm | YES (10^-6) | Exact | 6-48hr | Fixed TP-40 temporal pattern, variable duration, 48hr gap |
| ScsTypeStorm | YES (10^-6) | Exact | 24hr only | SCS Type I/IA/II/III distributions |
| StormGenerator | NO | Exact | Any | Flexible peak positioning (0-100%) |
Decision Tree¶
Need precipitation hyetograph for HEC-RAS?
|
+- Have cumulative depth-duration inputs (24h / 5min)?
| --> Use FrequencyStormDdf (50%/67%; optional TP-40 area reduction)
|
+- Need HMS-equivalent temporal patterns?
| |
| +- Modern Atlas 14 (6h, 12h, 24h, or 96h)?
| | --> Use Atlas14Storm
| |
| +- Fixed TP-40 pattern or variable duration (6-48hr, including 48hr)?
| | --> Use FrequencyStorm
| |
| +- SCS Type I/IA/II/III (24hr only)?
| --> Use ScsTypeStorm
|
+- Need flexible peak positioning (0-100%)?
--> Use StormGenerator
Known Duration Limitations¶
48-hour duration: Atlas14Storm does not support 48-hour (NOAA does not publish 48h temporal CSVs). Use FrequencyStorm for 48-hour HMS-equivalent storms.
Duration coverage: - 6h: Atlas14Storm or FrequencyStorm - 12h: Atlas14Storm or FrequencyStorm - 24h: Atlas14Storm, FrequencyStorm, FrequencyStormDdf, or ScsTypeStorm - 48h: FrequencyStorm only - 96h: Atlas14Storm only
Standard AEP Events¶
Common AEP events for design and regulatory analysis:
| AEP | Return Period | Typical Application |
|---|---|---|
| 50% | 2-year | Frequent flooding, erosion, minor drainage |
| 20% | 5-year | Storm sewer design, minor structures |
| 10% | 10-year | Regulatory (some jurisdictions), street flooding |
| 4% | 25-year | Floodplain management, local regulations |
| 2% | 50-year | Infrastructure design, bridge hydraulics |
| 1% | 100-year | FEMA regulatory, base flood elevation |
| 0.5% | 200-year | Critical infrastructure, freeboard calculations |
| 0.2% | 500-year | High-hazard dams, PMF approximation |
Method Details¶
StormGenerator (Alternating Block Method)¶
Native ras-commander method using the Alternating Block Method (Chow, Maidment, Mays 1988). DDF data controls the temporal shape only; actual depth comes from total_depth_inches.
Key characteristics: - Flexible peak positioning (0% to 100% of storm duration) - NOT HMS-equivalent (different temporal algorithm) - Exact depth conservation via scaling - Any duration supported
from ras_commander.precip import StormGenerator
# Download DDF data (used for temporal pattern shape)
ddf_data = StormGenerator.download_from_coordinates(
lat=29.76,
lon=-95.37
)
# Generate with peak at 50% (centered), a common engineering choice
hyeto_centered = StormGenerator.generate_hyetograph(
ddf_data=ddf_data,
total_depth_inches=17.0,
duration_hours=24,
position_percent=50 # Peak centered at hour 12
)
# Generate with peak at 25% (early peak, more conservative)
hyeto_early = StormGenerator.generate_hyetograph(
ddf_data=ddf_data,
total_depth_inches=17.0,
duration_hours=24,
position_percent=25 # Peak at hour 6
)
# Return value: DataFrame with columns hour, incremental_depth, cumulative_depth
print(hyeto_centered.columns.tolist())
# ['hour', 'incremental_depth', 'cumulative_depth']
Supporting methods:
- StormGenerator.load_csv(csv_file) - Load DDF data from CSV
- StormGenerator.validate_hyetograph(hyetograph, expected_total_depth) - Verify depth
- StormGenerator.generate_all(ddf_data, events, ...) - Batch generate multiple events
- StormGenerator.save_hyetograph(hyetograph, output_path, format) - Save to CSV or HEC-RAS format
Atlas14Storm (HMS-Equivalent)¶
Imported from hms-commander. Matches HEC-RAS/HMS "Specified Pattern" at 10^-6 precision using official NOAA Atlas 14 temporal distributions.
Requires: hms-commander>=0.1.0 (installed automatically with ras-commander).
from ras_commander.precip import Atlas14Storm, ATLAS14_AVAILABLE
if ATLAS14_AVAILABLE:
# Generate HMS-equivalent hyetograph
# total_depth_inches comes from NOAA PFDS for your location and AEP
hyeto = Atlas14Storm.generate_hyetograph(
total_depth_inches=17.0, # From NOAA PFDS
state="tx",
region=3,
aep_percent=1.0, # 1.0 = 100-year, 2.0 = 50-year, etc.
quartile="All Cases"
)
total = hyeto['cumulative_depth'].iloc[-1]
print(f"Total depth: {total:.6f} inches") # Exact: 17.000000
# Check availability without importing conditionally
from ras_commander.precip import ATLAS14_AVAILABLE
if not ATLAS14_AVAILABLE:
print("hms-commander not installed: pip install hms-commander")
Quartile options: "First Quartile", "Second Quartile", "Third Quartile", "Fourth Quartile", "All Cases"
Supported durations: 6h, 12h, 24h, 96h (no 48h - use FrequencyStorm instead)
FrequencyStorm (HMS-Equivalent, TP-40)¶
Imported from hms-commander. TP-40/Hydro-35 pattern, HMS-equivalent for variable durations from 6 to 48 hours. Fill the 48-hour gap left by Atlas14Storm.
from ras_commander.precip import FrequencyStorm, FREQUENCY_STORM_AVAILABLE
if FREQUENCY_STORM_AVAILABLE:
# 24-hour storm (TP-40 defaults: 5-min interval, 67% peak position)
hyeto_24hr = FrequencyStorm.generate_hyetograph(
total_depth=13.20 # From NOAA PFDS for your location
)
# 6-hour storm with explicit parameters
hyeto_6hr = FrequencyStorm.generate_hyetograph(
total_depth=9.10,
total_duration_min=360, # 6 hours
time_interval_min=5
)
# 48-hour storm (not available in Atlas14Storm)
hyeto_48hr = FrequencyStorm.generate_hyetograph(
total_depth=20.5,
total_duration_min=2880, # 48 hours
time_interval_min=60
)
total = hyeto_24hr['cumulative_depth'].iloc[-1]
print(f"Total: {total:.6f} inches") # Exact depth conservation
Use FrequencyStorm when: - Working with legacy TP-40 data (Houston area and similar) - Need 48-hour duration HMS-equivalent storms - Need variable duration between 6-48 hours
ScsTypeStorm (HMS-Equivalent, SCS Distributions)¶
Imported from hms-commander. Implements SCS Type I, IA, II, and III temporal distributions extracted from HEC-HMS 4.13 source code.
SCS type guide: - Type I: Pacific maritime climate (early peak ~42%) - Type IA: Coastal areas, Atlantic/Gulf (early peak ~33%) - Type II: Most of US, central and eastern states (peak ~50%) - Type III: Gulf Coast, Florida, tropical/subtropical (late peak ~50%)
from ras_commander.precip import ScsTypeStorm, SCS_TYPE_AVAILABLE
if SCS_TYPE_AVAILABLE:
# SCS Type II (most common for central/eastern US)
hyeto_ii = ScsTypeStorm.generate_hyetograph(
total_depth_inches=10.0,
scs_type='II',
time_interval_min=60
)
print(f"Total: {hyeto_ii['cumulative_depth'].iloc[-1]:.6f} inches") # Exact: 10.000000
# Gulf Coast application
hyeto_iii = ScsTypeStorm.generate_hyetograph(
total_depth_inches=10.0,
scs_type='III',
time_interval_min=60
)
# Generate all 4 types at once
all_types = ScsTypeStorm.generate_all_types(
total_depth_inches=10.0,
time_interval_min=60
)
for scs_type, hyeto in all_types.items():
peak = hyeto['incremental_depth'].max()
print(f"Type {scs_type}: peak = {peak:.4f} in/hr")
SCS type options: 'I', 'IA', 'II', 'III' (case-insensitive)
Constraint: 24-hour duration only (HMS constraint, matches TR-55 specification)
Gridded design-storm methods¶
| API | Spatial input | Temporal construction | What varies between cells? |
|---|---|---|---|
Atlas14HyetographGrid |
One duration-total depth raster | One explicitly selected NOAA cumulative percentage curve, differenced into interval fractions | Depth; normalized temporal fractions are shared |
AbmHyetographGrid |
Multiple duration-depth rasters | Log-log interpolation, differences, descending block sort and alternating placement | Depth and potentially normalized temporal fractions |
Shared NOAA temporal distribution¶
Install the optional dependencies with
pip install "ras-commander[precip]" "hms-commander>=0.3.1".
Atlas14HyetographGrid implements rainfall[t, y, x] = depth[y, x] * fraction[t].
It obtains the dimensionless curve from the existing Atlas14Storm API and
applies it uniformly in time to all valid cells. This is a spatially varying
depth field with a shared temporal distribution, not uniform rainfall depth
and not a per-cell alternating-block calculation.
The caller must select temporal state, region, quartile, and
probability_column. Region numbers are NOAA temporal-distribution regions,
not political districts. The 50% column is a temporal-curve exceedance
selection; it is neither a 50% peak-position request nor the storm AEP.
The selected temporal duration must match the depth raster duration.
Supported temporal durations are 6, 12, 24 and 96 hours; a 48-hour curve is
not silently substituted or stretched from another duration.
For an original NOAA ASCII raster, read its .xml metadata and .prj first:
from ras_commander.precip import Atlas14HyetographGrid
# The official Texas tx100yr24ha product is 100-year/24-hour PDS,
# NAD83 geographic coordinates, with integer values in thousandths of inches.
output = Atlas14HyetographGrid.generate_from_asc_file(
asc_path="tx100yr24ha.asc",
scale_factor=0.001,
source_crs="EPSG:4269",
bounds=(-94.8, 29.4, -94.3, 30.0),
ari_years=100,
storm_duration_hours=24,
timestep_minutes=30,
state="tx",
region=3,
quartile="All Cases",
probability_column="50%",
depth_frequency_basis="PDS",
output_netcdf="atlas14_shared_pattern.nc",
)
Obtain that source from NOAA's Texas raster archive. The corresponding official temporal CSV contains the five supported tables. The example's selections are explicit example values, not automatic geographic recommendations.
generate(bounds=..., ...) downloads one requested duration through
Atlas14Grid; generate_from_depth_grid(depth_grid=..., x=..., y=...,
source_crs=..., ...) accepts an already prepared raster in inches.
Neither entry point guesses a temporal region. The raw-grid route requires
the caller to identify the input depth duration/frequency correctly.
The NetCDF is a design-storm data product, with interval depth, cumulative
depth, total depth, temporal fractions, CRS and interval bounds. It preserves
source NoData and cell-center registration. Source raster cropping does not
reproject or resample the raster. Missing cells are never converted to dry
cells, and the API adds no artificial missing first interval. Consult the
interval bounds rather than interpreting a timestamp as an instantaneous rate.
CF time coordinates use the synthetic origin 1970-01-01 00:00:00 solely to
encode elapsed time. It is not an observed event date. Rebase those
intervals explicitly to the intended model start when preparing forcing;
xr.open_dataset(path, decode_times=False) exposes the numeric elapsed hours.
Writing this file does not by itself qualify a HEC-RAS or HEC-HMS import route.
Consumer conversion must explicitly handle projection, units, timestamps and
NoData; use the established NetCDF/DSS APIs and verify receiving-engine values.
The API applies no areal reduction and no AMS/PDS conversion. Recorded frequency-basis metadata describes the supplied depths; it does not convert them. This is not a recommendation to omit areal reduction in a study. If depths were adjusted upstream, retain that provenance and do not reduce them a second time. TP-40's bounded domain is not extended by the grid method.
Alternating-block and balanced frequency storms¶
Alternating-block construction from multiple duration depths is established, not a newly invented temporal method. The HEC-HMS Frequency Storm technical reference describes nested or balanced storms, log-log depth-duration interpolation, incremental blocks and alternating arrangement. Such storms target multiple durations at a common precipitation frequency; that does not imply that an observed storm has the same exceedance probability at every duration.
AbmHyetographGrid keeps its existing method and defaults. Its name already
selects alternating-block construction. It is not silently redirected to a
NOAA empirical temporal curve. Its implementation sorts interval blocks,
places them left-first around the specified peak, clamps negative increments,
and rescales to retain the total. Its automatic subhourly inputs are estimated
from centroid DDF ratios; they are not independent subhourly rasters for
every cell. These choices are disclosed approximations, and total conservation
does not prove all moving-window duration maxima or full HMS equivalence.
Use FrequencyStormDdf for its separately documented bounded scalar workflow.
HEC also documents the precipitation-frequency grid plus user-specified temporal pattern workflow and application of NOAA temporal patterns. Choose the shared-pattern API when that is the specified design method; choose ABM when a synthetic multi-duration construction is required. Neither is universally preferable, and neither establishes spatial storm coherence merely by applying point-frequency depths simultaneously across a domain. Select duration, temporal pattern, storm area and reduction assumptions for the evaluation location and governing study criteria.
Method provenance and compatibility¶
New shared-pattern output identifies its temporal/spatial method, curve
selection, units, CRS and input frequency basis. Its source metadata records
the ASCII filename, scale and crop or the remote grid URL and selected product.
Caller-supplied arrays can carry upstream provenance via source_metadata.
ABM output records its
interpolation, block placement, negative-increment treatment and absence of
automatic reduction/conversion. There is no common method selector with a
silent default. Existing ABM calls retain their numerical behavior; selecting
the new class is an explicit change of methodology.
Atlas 14 Grid and Spatial Variance¶
Atlas14Grid - Remote Grid Access¶
Downloads only data within your project extent using HTTP byte-range requests. Achieves ~99.9% data reduction compared to full state dataset downloads.
Data specifications: - Coverage: CONUS (24N-50N, 125W-66W) - Resolution: ~0.0083 degrees (~830m) - Durations: 1, 2, 3, 6, 12, 24, 48, 72, 96, 168 hours - Return periods: 2, 5, 10, 25, 50, 100, 200, 500, 1000 years - Performance: ~5-15 seconds for a typical project extent
from ras_commander.precip import Atlas14Grid
# Get PFE data for HEC-RAS project extent
pfe = Atlas14Grid.get_pfe_from_project(
geom_hdf="MyProject.g01.hdf",
extent_source="2d_flow_area", # or "project_extent"
durations=[6, 12, 24],
return_periods=[10, 50, 100]
)
# Access data
lat = pfe['lat']
lon = pfe['lon']
ari = pfe['ari'] # Return period array (e.g., [10, 50, 100])
# Use dynamic indexing to find the correct return period index
import numpy as np
target_rp = 100
ari_idx = np.argmin(np.abs(ari - target_rp))
print(f"Using {ari[ari_idx]}-year (index {ari_idx})")
# 100-year, 24-hour max precipitation over project
precip_100yr_24hr = pfe['pfe_24hr'][:, :, ari_idx]
print(f"Max: {np.nanmax(precip_100yr_24hr):.2f} inches")
print(f"Min: {np.nanmin(precip_100yr_24hr):.2f} inches")
Important: Always use dynamic indexing to find return period array indices. Never hardcode array indices (index 0 is the 2-year period, not the first period you requested).
Atlas14Variance - Spatial Variance Analysis¶
Assesses whether uniform rainfall assumptions are appropriate for rain-on-grid modeling. A range percentage greater than 10% suggests spatially variable rainfall should be considered.
from ras_commander.precip import Atlas14Variance
# Quick check for representative event (100-yr, 24-hr)
stats = Atlas14Variance.analyze_quick(
geom_hdf="MyProject.g01.hdf",
duration=24,
return_period=100
)
print(f"Precipitation range: {stats['range_pct']:.1f}%")
if stats['range_pct'] > 10:
print("High variance - consider spatially variable rainfall")
else:
print("Uniform rainfall likely appropriate")
Full multi-event analysis:
# Full analysis across durations and return periods
results = Atlas14Variance.analyze(
geom_hdf="MyProject.g01.hdf",
durations=[6, 12, 24, 48],
return_periods=[10, 25, 50, 100, 500],
extent_source="2d_flow_area",
variance_denominator='min' # range_pct = (max-min)/min * 100
)
# Review results DataFrame
print(results[['duration_hr', 'return_period_yr', 'min_inches', 'max_inches', 'range_pct']])
# Check decision support
ok, msg = Atlas14Variance.is_uniform_rainfall_appropriate(results, threshold_pct=10.0)
print(msg)
# Generate report with plots
report_dir = Atlas14Variance.generate_report(
results_df=results,
output_dir="Atlas14_Variance_Report",
project_name="My Project",
include_plots=True
)
HUC12 watershed option: Analyze within the full HUC12 watershed instead of the 2D flow area:
results = Atlas14Variance.analyze(
geom_hdf="MyProject.g01.hdf",
use_huc12_boundary=True # Finds HUC12 containing 2D flow area center
)
Integration with HEC-RAS¶
Writing Hyetographs to Unsteady Files¶
Use RasUnsteady.set_precipitation_hyetograph() to replace an existing inline precipitation boundary in a HEC-RAS unsteady file. Use a project copy when comparing storm patterns:
from ras_commander import init_ras_project, RasUnsteady, RasCmdr
from ras_commander.precip import Atlas14Storm, ATLAS14_AVAILABLE
# Initialize project
init_ras_project("C:/Projects/MyModel", "7.0")
if ATLAS14_AVAILABLE:
# Generate HMS-equivalent hyetograph
# Depth from NOAA PFDS: https://hdsc.nws.noaa.gov/pfds/
hyeto = Atlas14Storm.generate_hyetograph(
total_depth_inches=17.0,
state="tx",
region=3,
aep_percent=1.0,
quartile="All Cases"
)
# Write directly to unsteady file (one call)
# Detects time interval from hour spacing (1HOUR, 30MIN, 5MIN, etc.)
RasUnsteady.set_precipitation_hyetograph("01", hyeto)
# Execute plan
RasCmdr.compute_plan("01")
The writer validates the DataFrame before changing the file and preserves the boundary's existing start-time configuration. Specify boundary_name="Area Name" to select an exact, case-insensitive name in boundary-location field 5; this selector is verified for 2D Flow Areas. Storage Area layouts require separate verification. Omitting the name selects the first precipitation boundary.
| Input | Contract |
|---|---|
hour |
Regular interval-end hours measured from the boundary start. Begin at one interval, or include a zero-depth row at hour zero. Pad delayed storms with explicit dry intervals. |
incremental_depth |
Finite, nonnegative depth over the preceding interval. Use inches for a US-customary model or millimeters for an SI model; the writer does not convert units. |
cumulative_depth |
Cumulative sum of the incremental depths, in the same units. |
The writer inserts a zero-depth start ordinate when needed. It rounds cumulative depths to 0.01 depth units before differencing into the native 8.2f fields, keeping each interval-end cumulative depth within 0.005 units of the input (apart from floating-point tolerance). Individual increments can change by up to 0.01 units. Atlas 14 generators return inches: convert both depth columns before writing an SI model.
Cover the simulation window explicitly. Check the written boundary and the final HDF precipitation at matching times before interpreting hydraulic differences. Notebook 721 retains a bounded HEC-RAS 7.0 Davis comparison; it does not qualify other versions, SI models, or other boundary-start configurations.
Multi-AEP Batch Workflow¶
Generate and execute a suite of AEP design storms:
from ras_commander import init_ras_project, RasCmdr, RasPlan, RasUnsteady, ras
from ras_commander.precip import StormGenerator
init_ras_project("C:/Projects/FloodStudy", "7.0")
template_unsteady = ras.plan_df.loc[
ras.plan_df['plan_number'] == '01', 'unsteady_number'
].iloc[0]
# DDF data for temporal pattern (download once, reuse for all AEPs)
ddf_data = StormGenerator.download_from_coordinates(29.76, -95.37)
# Atlas 14 depths for Houston from NOAA PFDS (100-yr=17.0, 50-yr=14.5, etc.)
# Verify at: https://hdsc.nws.noaa.gov/pfds/pfds_map_cont.html?lat=29.76&lon=-95.37
aep_depths = {
10.0: 11.5, # 10% AEP (10-yr), 24-hr depth in inches
2.0: 15.0, # 2% AEP (50-yr)
1.0: 17.0, # 1% AEP (100-yr)
0.2: 22.0, # 0.2% AEP (500-yr)
}
for aep_pct, total_depth in aep_depths.items():
return_period = int(100 / aep_pct)
# Generate hyetograph with Atlas 14 depth
hyeto = StormGenerator.generate_hyetograph(
ddf_data=ddf_data,
total_depth_inches=total_depth,
duration_hours=24,
position_percent=50
)
# Give each plan its own forcing file; cloning a plan alone shares the template's.
unsteady_num = RasPlan.clone_unsteady(template_unsteady)
new_plan = RasPlan.clone_plan(
"01", new_plan_shortid=f"{return_period}yr", unsteady_flow=unsteady_num
)
RasPlan.update_plan_description(new_plan, f"{return_period}-Year Design Storm ({aep_pct}% AEP)")
# Resolve the number through the initialized project, independent of cwd.
# Pad with dry intervals if needed to cover this plan's simulation window.
RasUnsteady.set_precipitation_hyetograph(unsteady_num, hyeto)
# Execute
RasCmdr.compute_plan(new_plan, num_cores=4)
print(f"Completed {return_period}-yr ({total_depth} inches)")
Gridded Atlas 14 units and QC¶
AbmHyetographGrid.generate_from_asc_files() converts raw PFDS ASCII depth
values to inches using scale_factor=0.001 by default. For example, the
raw Texas grid value 16905 means 16.905 inches. NOAA documents these grids
in thousandths of inches in its
Texas grid metadata.
This corrects the previous 0.01 default, which produced ten times the intended
depth for these files. Regenerate affected ASCII-derived storms. An explicit
scale_factor=0.001 used with earlier versions was already correct.
The remotely accessed CONUS NetCDF uses different packing metadata, including
scale_factor=0.01; its decoding is unchanged. Check each source product's
metadata. For ASCII products intentionally stored in hundredths of inches or
already in inches, explicitly pass scale_factor=0.01 or 1.0, respectively.
The ASCII nodata_value override remains in post-scaling units.
Generated incremental and cumulative variables are in inches. Built-in QC
rejects empty, missing, nonfinite, negative, or incorrectly labelled rainfall
and compares every stored cumulative value with the cumulative sum of the
increments. Without an independent depth, a passing result is explicitly
internal_consistency_only: both variables originate from the same generated
series, so this cannot establish correct source units or product selection.
qc = AbmHyetographGrid.verify_pixel(
"houston.nc", lat=29.75, lon=-95.45,
expected_depth_inches=16.905, # Independently checked value at the selected cell
)
assert qc["passed"], qc["failure_reasons"]
Use an independently verified reference for the selected nearest cell, return
period, and storm duration; the number above is an example from a Houston crop.
Check lat_actual and lon_actual. This tests total depth and internal
consistency, not nested-duration frequency matching, areal reduction, the temporal
pattern, or HEC-RAS ingestion. Zero-depth references require zero computed depth;
NoData pixels fail QC and are never treated as dry pixels.
Duration-dependent frequency rainfall and TP-40 reduction¶
FrequencyStormDdf constructs a balanced storm from cumulative depth-duration
inputs. It supports 24-hour storms at five-minute intervals, standard eight
knots or ten explicit knots, and 50% or 67% peak placement. The existing
FrequencyStorm fixed pattern and generic per-cell AbmHyetographGrid remain
separate methods with unchanged behavior.
from ras_commander.precip import FrequencyStormDdf
hyeto = FrequencyStormDdf.generate_hyetograph(
depths_inches=[1.3, 2.58, 5.02, 7.17, 8.74, 11.4, 13.9, 16.4],
durations_minutes=[5, 15, 60, 120, 180, 360, 720, 1440],
peak_position_percent=50,
area_reduction_method="TP-40",
storm_area_sqmi=100.0, # Explicit evaluation-area choice, in square miles
simulation_duration_hours=120,
)
The output columns are hour, incremental_depth and cumulative_depth, with
depths in inches. Row zero is a zero-depth start marker, followed by interval-end
values. Do not export that marker as an extra rainfall interval to DSS. The 50%
placement interval ends at 12:05; 67% ends at 16:05. Dry intervals extend the
control window without stretching or rescaling the storm.
Hydro-35 supplies absent 10/30-minute knots. Explicit knots are retained. Area reduction acts on the augmented cumulative depths, before log-log interpolation and differencing. Increments are placed in duration order, alternating left first. This ordering matches the independently read reference records even at slope transitions. HEC's manual describes sorting; agreement with these records does not establish universal equivalence across all settings or software versions.
Tp40Reduction.factor(duration_minutes, storm_area_sqmi) exposes the bounded
HEC-HMS compatibility relation 1 - f_D * (1 - exp(-0.015 * A)). Area A is in
square miles. Coefficients at 30, 60, 180, 360 and 1440 minutes are respectively
0.48, 0.35, 0.22, 0.17 and 0.09, interpolated in log-log space. This interface
accepts 5–1440 minutes and 0–400 square miles and rejects values outside those
bounds; it neither extrapolates nor silently clamps excessive area.
Short-duration convention: the inspected HMS implementation uses the 30-minute coefficient for 5-, 10- and 15-minute depths. This convention matches the delivered reduction records, but differs from the technical manual's prose that durations below 30 minutes are unadjusted. This API deliberately implements that bounded HMS compatibility convention. It is not a general recommendation to apply those factors to every watershed.
Use area_reduction_method="none" for already reduced inputs. Supplying an area
with that option is rejected to avoid ambiguous configuration. The caller must
choose the documented evaluation storm area; it is not inferred from grid cells
or subbasin geometry. The reduced total is retained, not normalized back to the
point total. Attributes record the point/areal totals, area, factors, knot mode,
placement and actual peak indices. Annual/partial-duration conversion and TP-49
durations are outside this interface.
Validation includes seven publicly shipped event vectors and private comparisons against 436 additional no-reduction vectors and 174 area-reduced vectors, all with 288 wet-window intervals. Those additional source vectors are not distributed with this repository; the public regression subset includes six neutral fixtures. Maximum observed interval differences are below 2.5e-14 inches. Neutral regression fixtures retain independently read values or complete-vector digests; no reduction factor was fitted to a delivered total. These comparisons establish bounded numerical agreement, not hydraulic validation, universal correctness, or a novelty claim.
References: HEC frequency-storm technical reference and HEC-HMS technical reference manual.
Example Notebooks¶
Complete workflow demonstrations:
examples/720_precipitation_methods_comprehensive.ipynb- Side-by-side comparison of all four hyetograph methods (Atlas14Storm, FrequencyStorm, ScsTypeStorm, StormGenerator) with validation- 721: Precipitation hyetograph comparison - 30-pattern generation and readback, with two bounded Davis runs comparing intended, written and native precipitation
examples/722_gridded_precipitation_atlas14.ipynb- Gridded precipitation workflow; spatial variance analysis; mesh polygon visualizationexamples/725_atlas14_spatial_variance.ipynb- Spatial variance analysis for uniform vs. distributed rainfall assessment; HUC12 watershed option
See Also¶
- Gridded Historic Precipitation - AORC historical data
- Boundary Conditions - General boundary condition workflows
- DSS Operations - Working with HEC-DSS files
- Plan Execution - Batch scenario execution
ras_commander/precip/CLAUDE.md- Complete method comparison and validation details- NOAA PFDS: https://hdsc.nws.noaa.gov/pfds/pfds_map_cont.html
Existing-model shared-pattern notebook¶
Notebook 731 applies an original NOAA depth raster and one explicitly selected temporal curve to an existing model footprint. It checks interval depths and masks, serializes Float32 intervals before explicit bilinear SHG conversion, and optionally attaches the resulting DSS to a staged model copy without running a solver.