dss-read-boundary-data

name	dss_read_boundary-data
shared_corpus	true
harness_scope	shared
source_owner	gpt-cmdr
security_review	internal
description	Reads HEC-DSS files (V6 and V7) for boundary condition extraction using RasDss class. Handles JVM configuration, HEC Monolith download, catalog reading, and time series extraction. Use when working with DSS files, extracting boundary data, reading HEC-HMS output, integrating DSS workflows with HEC-RAS, cataloging DSS file contents, or converting DSS data to pandas DataFrames. Triggers: DSS, HEC-DSS, boundary condition, time series, JVM, Java, catalog, pathname, HEC-HMS, Monolith, pyjnius, read DSS, extract DSS, DSS boundary, DSS catalog, DSS DataFrame, DSS V6, DSS V7.

Reading DSS Boundary Data

Primary Source Navigator -- Use this skill as a concise entry point to DSS file operations. Read authoritative sources for complete documentation.

Quick Reference

from ras_commander import init_ras_project, RasDss

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

# Read DSS catalog
catalog = RasDss.get_catalog("file.dss")

# Extract single time series
df = RasDss.read_timeseries("file.dss", pathname)

# Extract ALL boundary DSS data (recommended)
enhanced = RasDss.extract_boundary_timeseries(
    ras.boundaries_df,
    ras_object=ras
)

Primary Sources (Read These First)

1. Module Architecture & Developer Guidance

Location: ras_commander/dss/AGENTS.md

Read this for:

• Lazy loading architecture (no overhead until first use)
• Three-level lazy loading (package → subpackage → method)
• Public API reference table
• DataFrame metadata structure (df.attrs)
• Dependencies (pyjnius, Java, HEC Monolith)
• Adding new DSS methods
• Testing DSS operations
• Common issues and troubleshooting

Why authoritative: Written by maintainers, updated with code changes, read by developers working on the module.

2. Complete Workflow Example

Location: examples/310_dss_boundary_extraction.ipynb

Read this for:

• Step-by-step extraction workflow
• Real project (BaldEagleCrkMulti2D)
• Catalog reading examples
• Single time series extraction
• Batch extraction with extract_boundary_timeseries()
• Plotting DSS boundary data
• Exporting results to CSV
• Accessing extracted DataFrames

Why this is authoritative: Tested with real HEC-RAS projects, serves as functional test, maintained alongside library.

3. Source Code & Docstrings

Location: ras_commander/dss/RasDss.py

Read this for:

• Complete method signatures
• Parameter types and defaults
• Return value structures
• Error handling patterns
• Implementation details

Why this is authoritative: Source code is always correct, docstrings updated with each release.

Technology Overview

HEC-DSS Format

• DSS = Data Storage System (binary format)
• Used by HEC-HMS, HEC-ResSim, HEC-FIA
• Versions: V6 (older) and V7 (current)
• Data identified by pathname (7-part string)

DSS Pathname Format

/A/B/C/D/E/F/

• A: Project or basin name
• B: Location (e.g., gauge, river station)
• C: Parameter (FLOW, STAGE, PRECIP, etc.)
• D: Start date (e.g., 01JAN2000)
• E: Time interval (15MIN, 1HOUR, 1DAY, etc.)
• F: Version or scenario (RUN:SCENARIO, GAGE, OBS, etc.)

Example:

//BALD EAGLE 40/FLOW/01JAN1999/15MIN/RUN:PMF-EVENT/

Lazy Loading Architecture

No Overhead Until First Use

See ras_commander/dss/AGENTS.md for complete details.

Three-level lazy loading:

1. Package Import: Lightweight, no Java loaded

   from ras_commander import RasDss  # Fast, no JVM
   

2. First Method Call: Configures JVM, downloads Monolith (~20 MB, one-time)

   catalog = RasDss.get_catalog("file.dss")  # Triggers setup
   

3. Subsequent Calls: Uses cached JVM and libraries

   df = RasDss.read_timeseries(...)  # Fast, reuses JVM
   

Dependencies

Required (must install manually):

pip install pyjnius

Required (system):

• Java JRE or JDK 8+ (set JAVA_HOME)

Auto-downloaded:

• HEC Monolith libraries (~20 MB) to ~/.ras-commander/dss/

Core Methods

See ras_commander/dss/AGENTS.md for complete API reference table.

Essential Methods

1. get_catalog(dss_file) - List all paths in DSS file

   • Returns: List[str] of DSS pathnames
   • Use: Explore DSS file contents

2. read_timeseries(dss_file, pathname) - Extract single time series

   • Returns: DataFrame with DatetimeIndex and 'value' column
   • Metadata in df.attrs (pathname, units, type, interval, dss_file)
   • Use: Extract specific boundary data

3. extract_boundary_timeseries(boundaries_df, ras_object) - Extract ALL DSS boundaries

   • Returns: Enhanced DataFrame with 'dss_timeseries' column
   • Automatically processes all DSS-defined boundaries
   • Use: Recommended for complete boundary extraction

4. get_info(dss_file) - Quick file summary

   • Returns: Dict with filename, size, total_paths, sample_paths
   • Use: Validate DSS file before full extraction

5. read_multiple_timeseries(dss_file, pathnames) - Batch extract

   • Returns: Dict[str, DataFrame] mapping pathname to data
   • Use: Extract specific set of paths efficiently

Common Workflows

Workflow 1: Read Catalog and Extract Single Path

# List available data
catalog = RasDss.get_catalog("file.dss")
flow_paths = [p for p in catalog if '/FLOW/' in p]

# Extract specific path
df = RasDss.read_timeseries("file.dss", flow_paths[0])
print(f"Units: {df.attrs['units']}")
print(f"Points: {len(df)}")

Workflow 2: Extract ALL Boundary Data (Recommended)

from ras_commander import init_ras_project, RasDss

# Initialize project
ras = init_ras_project("project_path", "7.0")

# Extract all DSS boundary data
enhanced = RasDss.extract_boundary_timeseries(
    ras.boundaries_df,
    ras_object=ras
)

# Access extracted data
for idx, row in enhanced.iterrows():
    if row['Use DSS'] and row['dss_timeseries'] is not None:
        df = row['dss_timeseries']
        print(f"{row['bc_type']}: {len(df)} points")

Workflow 3: Plot DSS Boundary

import matplotlib.pyplot as plt

# Get DSS boundary
dss_boundaries = enhanced[enhanced['Use DSS'] == True]
first_dss = dss_boundaries.iloc[0]

# Plot
df = first_dss['dss_timeseries']
df['value'].plot(figsize=(12, 4))
plt.title(f"{first_dss['bc_type']} - {first_dss['river_reach_name']}")
plt.ylabel(f"Flow ({df.attrs['units']})")
plt.grid(True)
plt.show()

Error Handling

See ras_commander/dss/AGENTS.md for complete troubleshooting guide.

Common Errors

1. pyjnius Not Installed

ImportError: pyjnius is required for DSS file operations.

Fix: pip install pyjnius

2. Java Not Found

RuntimeError: JAVA_HOME not set and Java not found automatically.

Fix: Install Java JRE/JDK 8+ and set JAVA_HOME

3. JVM Already Started

RuntimeError: JVM configuration already done.

Fix: Restart Python process or notebook kernel

4. DSS File Not Found

FileNotFoundError: DSS file not found: ...

Fix: Use absolute paths or resolve relative to project directory

Robust Pattern

from pathlib import Path

try:
    dss_file = Path("file.dss").resolve()
    if not dss_file.exists():
        raise FileNotFoundError(f"DSS file not found: {dss_file}")

    catalog = RasDss.get_catalog(dss_file)
    print(f"Success: {len(catalog)} paths")

except ImportError as e:
    print(f"Missing dependency: {e}")
    print("Install: pip install pyjnius")

except RuntimeError as e:
    print(f"Java/JVM error: {e}")
    print("Check JAVA_HOME and Java installation")

Complete Documentation

DO NOT read the reference/ or examples/ folders in this skill directory - they contain outdated duplicated content.

Always prefer primary sources:

1. Module architecture: ras_commander/dss/AGENTS.md
2. Complete workflow: examples/310_dss_boundary_extraction.ipynb
3. API details: ras_commander/dss/RasDss.py docstrings

Key Takeaways

1. Lazy Loading: No overhead until first DSS method call
2. Auto-Download: HEC Monolith installed automatically (~20 MB, one-time)
3. Unified API: DSS and manual boundaries in same DataFrame
4. One-Call Extraction: extract_boundary_timeseries() handles all DSS data
5. Metadata Preserved: Units, pathname, interval in df.attrs
6. V6 and V7: Both DSS versions supported
7. Primary Sources: Always read AGENTS.md and notebook 310 for authoritative guidance

Cross-References

Rules (follow these):

• .claude/rules/hec-ras/dss-files.md -- DSS domain overview, pathname format, lazy loading
• .claude/rules/validation/validation-patterns.md -- Validation patterns for DSS pathnames

Skills (related workflows):

• usgs_integrate_gauges -- Use when USGS gauge data feeds DSS boundaries
• hecras_compute_plans -- Use downstream after validating boundary conditions
• precip_analyze_aorc -- Use when working with precipitation DSS data

Primary sources:

• ras_commander/dss/AGENTS.md -- Complete DSS documentation
• examples/310_dss_boundary_extraction.ipynb -- DSS extraction workflow