extracting-dss-results

gpt-cmdr's avatarfrom gpt-cmdr

Extracts and analyzes HEC-HMS simulation results from DSS files using HmsDss andHmsResults classes. Handles peak flows, hydrographs, volume summaries, and time seriesdata. Leverages ras-commander's RasDss for DSS V6/V7 support. Use when processingHMS results, extracting peak flows, analyzing hydrographs, computing volumes, orexporting time series. Integrates with HEC-RAS for boundary condition workflows.Trigger keywords: DSS file, results, peak flow, hydrograph, time series, volume,extract results, HMS output, analyze results.

⭐1stars🔀0forks📁View on GitHub🕐Updated Dec 31, 2025
[Document Data Extraction]

When & Why to Use This Skill

This Claude skill automates the extraction and analysis of HEC-HMS simulation results from DSS files. It streamlines hydrological workflows by programmatically retrieving peak flows, hydrographs, and volume summaries, ensuring high-performance data processing and seamless integration with HEC-RAS for boundary condition modeling.

Use Cases

  • Automated Post-Simulation Analysis: Rapidly extract peak flows, timing, and outflow hydrographs from DSS files immediately after HEC-HMS model execution.
  • Hydrological Reporting and Export: Convert complex simulation data into structured pandas DataFrames or CSV files for project documentation and external visualization.
  • Multi-Scenario Comparison: Efficiently compare results across multiple simulation runs to analyze the impact of different basin parameters or rainfall events.
  • Integrated Water Resource Modeling: Facilitate the handoff of HMS results to HEC-RAS by extracting precise time-series data for hydraulic boundary conditions.
nameextracting-dss-results
description|
Trigger keywordsDSS file, results, peak flow, hydrograph, time series, volume,

Extracting DSS Results

Quick Start

from hms_commander import HmsResults, HmsDss

# Extract peak flows
peaks = HmsResults.get_peak_flows("results.dss")

# Extract hydrograph
flows = HmsResults.get_outflow_timeseries("results.dss", "Outlet")

# Get precipitation time series
precip = HmsResults.get_precipitation_timeseries("results.dss", "Subbasin1")

Primary Sources

Code:

  • hms_commander/HmsDss.py - DSS operations (wraps RasDss)
  • hms_commander/HmsResults.py - Results extraction and analysis

Integration: Uses ras_commander.RasDss for DSS V6/V7 support

Rules: .claude/rules/hec-hms/dss-operations.md - DSS patterns

When to Use This Skill

  • Extracting simulation results after HmsCmdr.compute_run()
  • Analyzing peak flows and timing
  • Processing hydrographs for plotting or export
  • Computing volume summaries (acre-feet)
  • Linking HMS results to HEC-RAS (boundary conditions)
  • Comparing multiple runs

Core Capabilities

1. Peak Flow Extraction

Returns DataFrame with peak flows for all elements:

peaks = HmsResults.get_peak_flows("results.dss")
# Columns: Element, Peak Flow (cfs), Time to Peak

2. Time Series Extraction

Get complete hydrographs:

flows = HmsResults.get_outflow_timeseries("results.dss", "Outlet")
# Returns: pandas DataFrame with datetime index

3. Volume Analysis

volumes = HmsResults.get_volume_summary("results.dss")
# Returns: DataFrame with volumes in acre-feet

4. Multi-Run Comparison

comparison = HmsResults.compare_runs(
    ["baseline.dss", "alternative.dss"],
    element="Outlet"
)

DSS Pathname Format

HMS uses standard DSS pathname: /A/B/C/D/E/F/

  • A: Basin name
  • B: Element name (subbasin/junction/reach)
  • C: Parameter type (FLOW, PRECIP, etc.)
  • D: Time interval (15MIN, 1HOUR, etc.)
  • E: Run name
  • F: Version (usually blank)

Example: /BASIN/OUTLET/FLOW/15MIN/RUN1/

See: .claude/rules/hec-hms/dss-operations.md for complete pathname details

RasDss Integration

HmsDss wraps ras-commander's RasDss:

Why?

  • No code duplication
  • Consistent DSS operations across HMS and RAS
  • Automatic V6/V7 support
  • Shared Java bridge maintenance

Check availability:

if HmsDss.is_available():
    catalog = HmsDss.get_catalog("results.dss")
else:
    print("RasDss not available - install ras-commander")

Common Workflows

Workflow 1: Post-Simulation Analysis

from hms_commander import init_hms_project, hms, HmsCmdr, HmsResults

# Run simulation
init_hms_project("project")
HmsCmdr.compute_run("Run 1")

# Extract results
dss_file = hms.run_df.loc["Run 1", "dss_file"]
peaks = HmsResults.get_peak_flows(dss_file)
print(peaks)

Workflow 2: Export for External Analysis

# Export all results to CSV
HmsResults.export_results_to_csv("results.dss", "output_folder")

Workflow 3: HMS to RAS Linking

from hms_commander import HmsResults, HmsGeo

# Extract HMS hydrograph
hms_flows = HmsResults.get_outflow_timeseries("hms_results.dss", "Outlet")

# Get peak for validation
peaks = HmsResults.get_peak_flows("hms_results.dss")
hms_peak = peaks.loc["Outlet", "Peak Flow (cfs)"]

# Document spatial reference for RAS matching
lat, lon = HmsGeo.get_project_centroid_latlon("project.geo")

# Handoff to RAS:
# - DSS file: hms_results.dss
# - Pathname: /BASIN/OUTLET/FLOW/15MIN/RUN/
# - Outlet location: (lat, lon)
# - Peak: hms_peak cfs

# See: linking-hms-to-hecras skill for complete workflow

Reference Files

  • reference/hmsdss_api.md - Complete HmsDss API
  • reference/hmsresults_api.md - Complete HmsResults API
  • reference/dss_pathnames.md - Pathname structure details
  • examples/peak_flows.md - Peak flow analysis
  • examples/hydrographs.md - Time series plotting
  • executing-hms-runs - Generate results to extract
  • linking-hms-to-hecras - Use HMS results in RAS (complete workflow)