Analyzing AORC Precipitation

examples/900_aorc_precipitation.ipynb

Live working example showing:

• AORC data retrieval from cloud storage
• Spatial averaging over watersheds
• Temporal aggregation to HEC-RAS intervals
• Export to DSS and CSV formats
• Integration with HEC-RAS unsteady flow files

3. Atlas 14 Single-Project Workflow

examples/720_atlas14_aep_events.ipynb

Complete design storm workflow:

• Query Atlas 14 precipitation frequency values
• Generate SCS Type II temporal distributions
• Apply areal reduction factors
• Create HEC-RAS plans for multiple AEP events
• Batch execution and results processing

4. Atlas 14 Multi-Project Batch Processing

examples/722_atlas14_multi_project.ipynb

Advanced batch processing:

• Process multiple HEC-RAS projects simultaneously
• Standardized AEP suite (10%, 2%, 1%, 0.2%)
• Automated plan creation across projects
• Parallel execution with result consolidation

Quick Start

AORC Historical Data (30 seconds)

from ras_commander.precip import PrecipAorc

# Retrieve hourly AORC data for watershed
aorc_data = PrecipAorc.retrieve_aorc_data(
    watershed="02070010",  # HUC-8 code or shapefile path
    start_date="2015-05-01",
    end_date="2015-05-15"
)

# Spatial average over watershed
avg_precip = PrecipAorc.spatial_average(aorc_data, watershed)

# Aggregate to HEC-RAS interval
hourly = PrecipAorc.aggregate_to_interval(avg_precip, interval="1HR")

# Export to DSS for HEC-RAS
PrecipAorc.export_to_dss(
    hourly,
    dss_file="precipitation.dss",
    pathname="/PROJECT/PRECIP/AORC//1HOUR/OBS/"
)

Atlas 14 Design Storm (30 seconds)

from ras_commander.precip import StormGenerator

# Get 24-hr, 1% AEP (100-year) precipitation
precip = StormGenerator.get_precipitation_frequency(
    location=(38.9, -77.0),  # lat, lon
    duration_hours=24,
    aep_percent=1.0
)

# Generate SCS Type II distribution
hyetograph = StormGenerator.generate_design_storm(
    total_precip=precip,
    duration_hours=24,
    distribution="SCS_Type_II",
    interval_minutes=15
)

# Export to HEC-RAS DSS
StormGenerator.export_to_dss(
    hyetograph,
    dss_file="design_storm.dss",
    pathname="/PROJECT/PRECIP/DESIGN//15MIN/SYN/"
)

When to Use This Skill

Use when you need to:

1. Retrieve historical precipitation - AORC data for calibration and validation
2. Generate design storms - Atlas 14 AEP events (10%, 2%, 1%, 0.2%, etc.)
3. Process precipitation spatially - Watershed averaging, areal reduction factors
4. Aggregate precipitation temporally - Match HEC-RAS/HMS timesteps
5. Export to HEC-RAS/HMS - DSS files, CSV time series, or direct HDF integration
6. Identify storm events - Extract individual storms from AORC record
7. Apply temporal distributions - SCS Type II, IA, III for design storms

Core Concepts (Brief)

AORC Dataset

• Coverage: CONUS (1979-present), ~800m hourly resolution
• Format: Cloud-optimized Zarr on AWS S3 (anonymous access)
• Provider: NOAA Office of Water Prediction
• Use Case: Historical calibration, storm event analysis

NOAA Atlas 14

• Coverage: CONUS, Hawaii, Puerto Rico
• Data: Precipitation frequency estimates (depth-duration-frequency)
• Access: NOAA HDSC PFDS API (JSON)
• Use Case: Design storm generation for AEP events

Temporal Distributions

• SCS Type II: Standard for most of US (peak at 12hr of 24hr storm)
• SCS Type IA: Pacific maritime climate (peak at 8hr)
• SCS Type III: Gulf Coast and Florida (peak at 13hr)

Areal Reduction Factors (ARF)

• < 10 sq mi: ARF ≈ 1.0 (use point values)
• 10-100 sq mi: ARF = 0.95-0.98
• > 100 sq mi: ARF < 0.95 (significant reduction)

Common Workflows (High-Level)

Calibration with AORC

1. Retrieve AORC for historical storm event
2. Apply spatial average over watershed
3. Aggregate to model timestep
4. Run HEC-RAS/HMS model
5. Compare modeled vs observed flow/stage

Details: See ras_commander/precip/CLAUDE.md "AORC Workflow" section

Design Storm Analysis

1. Query Atlas 14 for design AEP
2. Generate temporal distribution (SCS Type II)
3. Apply areal reduction (if needed)
4. Export to HEC-RAS/HMS
5. Run model for design event

Details: See ras_commander/precip/CLAUDE.md "Atlas 14 Workflow" section

Multi-Event Suite

1. Define AEP range (50% to 0.2%)
2. Loop through events and generate design storms
3. Batch run HEC-RAS models
4. Generate flood frequency curves

Details: See examples/104_Atlas14_AEP_Multi_Project.ipynb

API Quick Reference (Navigate to CLAUDE.md for Details)

PrecipAorc Methods

Data Retrieval:

• retrieve_aorc_data() - Download AORC time series for watershed
• get_available_years() - Query available data years (1979-present)
• check_data_coverage() - Verify spatial and temporal coverage

Spatial Processing:

• spatial_average() - Calculate areal average over watershed
• extract_by_watershed() - Extract data for HUC or custom polygon
• resample_grid() - Aggregate AORC grid cells to coarser resolution

Temporal Processing:

• aggregate_to_interval() - Aggregate to HEC-RAS/HMS intervals (1HR, 6HR, 1DAY)
• extract_storm_events() - Identify and extract individual storm events
• calculate_rolling_totals() - Compute N-hour rolling precipitation totals

Output Formats:

• export_to_dss() - DSS format for HEC-RAS/HMS
• to_csv() - CSV time series for HEC-HMS
• to_netcdf() - NetCDF for further analysis

StormGenerator Methods

Design Storm Creation:

• generate_design_storm() - Create Atlas 14 design storm hyetograph
• get_precipitation_frequency() - Query Atlas 14 point precipitation values
• apply_temporal_distribution() - Apply standard temporal patterns (SCS Type II, etc.)

Spatial Processing:

• apply_areal_reduction() - Apply ARF for large watersheds
• interpolate_point_values() - Interpolate Atlas 14 values to grid
• generate_multi_point_storms() - Spatially distributed design storms

Output Formats:

• export_to_dss() - HEC-RAS DSS precipitation
• export_to_hms_gage() - HEC-HMS precipitation gage file
• to_csv() - Tabular hyetograph (CSV)

Full method signatures and parameters: See ras_commander/precip/CLAUDE.md

Example Patterns

AORC Storm Catalog Generation

from ras_commander.precip import PrecipAorc
from ras_commander import init_ras_project
from ras_commander.hdf import HdfProject

# Initialize project
ras = init_ras_project("path/to/project", "6.6")

# Get project bounds from geometry HDF
geom_hdf = ras.project_folder / f"{ras.project_name}.g09.hdf"
bounds = HdfProject.get_project_bounds_latlon(
    geom_hdf,
    buffer_percent=50.0  # 50% buffer ensures full coverage
)

# Generate storm catalog
catalog = PrecipAorc.get_storm_catalog(
    bounds=bounds,
    year=2020,
    inter_event_hours=8.0,     # USGS standard for storm separation
    min_depth_inches=0.75,     # Minimum significant precipitation
    buffer_hours=48            # Simulation warmup buffer
)

# Returns DataFrame with:
# storm_id, start_time, end_time, sim_start, sim_end,
# total_depth_in, peak_intensity_in_hr, duration_hours, rank

Complete workflow: See examples/900_aorc_precipitation.ipynb

Atlas 14 Multi-Event Suite

from ras_commander.precip import StormGenerator

# Define AEP suite
aep_events = [10, 4, 2, 1, 0.5, 0.2]  # 10%, 4%, 2%, 1%, 0.5%, 0.2%

for aep in aep_events:
    # Query Atlas 14
    precip = StormGenerator.get_precipitation_frequency(
        location=(38.9, -77.0),
        duration_hours=24,
        aep_percent=aep
    )

    # Generate design storm
    hyetograph = StormGenerator.generate_design_storm(
        total_precip=precip,
        duration_hours=24,
        distribution="SCS_Type_II"
    )

    # Export to DSS
    dss_file = f"design_storm_{aep}pct.dss"
    StormGenerator.export_to_dss(hyetograph, dss_file)

Complete multi-project workflow: See examples/722_atlas14_multi_project.ipynb

Dependencies

Required:

• pandas (time series handling)
• numpy (numerical operations)
• xarray (for AORC NetCDF data)
• requests (Atlas 14 API access)

Optional:

• geopandas (spatial operations on watersheds)
• rasterio (AORC grid processing)

Installation:

pip install ras-commander[precip]  # Includes all precipitation dependencies
# OR
pip install xarray rasterio geopandas

Navigation Map

When you need...

API Documentation

→ Read ras_commander/precip/CLAUDE.md (329 lines, complete API reference)

AORC Workflow Example

→ Open examples/900_aorc_precipitation.ipynb (live working code)

Atlas 14 Single Project

→ Open examples/720_atlas14_aep_events.ipynb

Atlas 14 Multi-Project Batch

→ Open examples/722_atlas14_multi_project.ipynb

Method Signatures and Parameters

→ Read ras_commander/precip/CLAUDE.md "Module Organization" section

Use Cases and Performance

→ Read ras_commander/precip/CLAUDE.md "Common Use Cases" and "Performance" sections

Data Source Details

→ Read ras_commander/precip/CLAUDE.md "Data Sources" section

Key Design Principles

1. Primary Sources First: Always refer to ras_commander/precip/CLAUDE.md for authoritative API details
2. Example Notebooks as References: Use notebooks to understand workflows in practice
3. No Duplication: This skill does NOT duplicate workflows - it NAVIGATES to them
4. Multi-Level Verifiability: All outputs reviewable in HEC-RAS/HMS GUI
5. Lazy Loading: Optional dependencies only loaded when needed

Performance Notes (Brief)

AORC Data Retrieval:

• Speed: ~1-5 minutes per year of hourly data
• Storage: ~10-50 MB per year (hourly, single watershed)
• Caching: Local cache recommended for repeated analyses

Atlas 14 Queries:

• Speed: < 5 seconds per query (API access)
• Rate Limiting: NOAA PFDS has request limits (respect usage guidelines)
• Caching: Automatic caching of API responses

Details: See ras_commander/precip/CLAUDE.md "Performance" section

See Also

Within Repository:

• ras_commander/precip/CLAUDE.md - Complete precipitation API reference (PRIMARY SOURCE)
• ras_commander/CLAUDE.md - Parent library context
• ras_commander/dss/AGENTS.md - DSS file operations
• examples/900_aorc_precipitation.ipynb - AORC demonstration
• examples/720_atlas14_aep_events.ipynb - Atlas 14 single project
• examples/722_atlas14_multi_project.ipynb - Atlas 14 multi-project

Related Components:

• ras_commander.RasUnsteady - Unsteady flow file management
• ras_commander.dss.RasDss - DSS file operations
• .claude/rules/python/path-handling.md - Spatial data handling patterns

Usage Pattern

1. Understand the workflow: Read ras_commander/precip/CLAUDE.md for complete details
2. See it in action: Open relevant example notebook (examples/24_*.ipynb, examples/103_*.ipynb, etc.)
3. Implement: Copy patterns from notebook, adapt to your project
4. Verify: Check outputs in HEC-RAS/HMS GUI

This skill is a lightweight index - detailed content lives in primary sources.