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