Skip to content

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:

Python
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:

Python
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

Text Only
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

Python
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).

Python
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.

Python
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%)

Python
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:

Python
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

Python
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.

Python
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:

Python
# 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:

Python
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:

Python
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:

Python
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.

Python
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.

Python
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 visualization
  • examples/725_atlas14_spatial_variance.ipynb - Spatial variance analysis for uniform vs. distributed rainfall assessment; HUC12 watershed option

See Also

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.