ras-commander 0.48.0__py3-none-any.whl → 0.49.0__py3-none-any.whl

ras_commander/HdfResultsPlan.py

@@ -1,11 +1,22 @@
 """
-Class: HdfResultsPlan
+HdfResultsPlan: A module for extracting and analyzing HEC-RAS plan HDF file results.
 
-Attribution: A substantial amount of code in this file is sourced or derived 
-from the https://github.com/fema-ffrd/rashdf library, 
-released under MIT license and Copyright (c) 2024 fema-ffrd
+Attribution:
+    Substantial code sourced/derived from https://github.com/fema-ffrd/rashdf
+    Copyright (c) 2024 fema-ffrd, MIT license
 
-The file has been forked and modified for use in RAS Commander.
+Description:
+    Provides static methods for extracting unsteady flow results, volume accounting,
+    and reference data from HEC-RAS plan HDF files.
+
+Available Functions:
+    - get_unsteady_info: Extract unsteady attributes
+    - get_unsteady_summary: Extract unsteady summary data
+    - get_volume_accounting: Extract volume accounting data
+    - get_runtime_data: Extract runtime and compute time data
+
+Note:
+    All methods are static and designed to be used without class instantiation.
 """
 
 from typing import Dict, List, Union, Optional
@@ -14,7 +25,7 @@ import h5py
 import pandas as pd
 import xarray as xr
 from .Decorators import standardize_input, log_call
-from .HdfBase import HdfBase
+from .HdfUtils import HdfUtils
 from .HdfResultsXsec import HdfResultsXsec
 from .LoggingConfig import get_logger
 import numpy as np
@@ -25,26 +36,27 @@ logger = get_logger(__name__)
 
 class HdfResultsPlan:
     """
-    A class for handling HEC-RAS plan HDF file results related to unsteady flow and reference line/point outputs.
-
-    This class provides methods for extracting and analyzing data from HEC-RAS plan HDF files,
-    focusing on unsteady flow results, volume accounting, and reference line/point time series outputs.
+    Handles extraction of results data from HEC-RAS plan HDF files.
 
-    Methods in this class use the @standardize_input decorator to handle different input types
-    (e.g., plan number, file path) and the @log_call decorator for logging method calls.
+    This class provides static methods for accessing and analyzing:
+        - Unsteady flow results
+        - Volume accounting data
+        - Runtime statistics
+        - Reference line/point time series outputs
 
-    Attributes:
-        None
+    All methods use:
+        - @standardize_input decorator for consistent file path handling
+        - @log_call decorator for operation logging
+        - HdfUtils class for common HDF operations
 
     Note:
-        This class is designed to work with HEC-RAS plan HDF files and requires the HdfBase class
-        for some of its operations.
+        No instantiation required - all methods are static.
     """
 
     @staticmethod
     @log_call
     @standardize_input(file_type='plan_hdf')
-    def get_results_unsteady_attrs(hdf_path: Path) -> Dict:
+    def get_unsteady_info(hdf_path: Path) -> pd.DataFrame:
         """
         Get unsteady attributes from a HEC-RAS HDF plan file.
 
@@ -52,7 +64,7 @@ class HdfResultsPlan:
             hdf_path (Path): Path to the HEC-RAS plan HDF file.
 
         Returns:
-            Dict: A dictionary containing the unsteady attributes.
+            pd.DataFrame: A DataFrame containing the unsteady attributes.
 
         Raises:
             FileNotFoundError: If the specified HDF file is not found.
@@ -62,16 +74,22 @@ class HdfResultsPlan:
             with h5py.File(hdf_path, 'r') as hdf_file:
                 if "Results/Unsteady" not in hdf_file:
                     raise KeyError("Results/Unsteady group not found in the HDF file.")
-                return dict(hdf_file["Results/Unsteady"].attrs)
+                
+                # Create dictionary from attributes
+                attrs_dict = dict(hdf_file["Results/Unsteady"].attrs)
+                
+                # Create DataFrame with a single row index
+                return pd.DataFrame(attrs_dict, index=[0])
+                
         except FileNotFoundError:
             raise FileNotFoundError(f"HDF file not found: {hdf_path}")
         except Exception as e:
             raise RuntimeError(f"Error reading unsteady attributes: {str(e)}")
-
+        
     @staticmethod
     @log_call
     @standardize_input(file_type='plan_hdf')
-    def get_results_unsteady_summary_attrs(hdf_path: Path) -> Dict:
+    def get_unsteady_summary(hdf_path: Path) -> pd.DataFrame:
         """
         Get results unsteady summary attributes from a HEC-RAS HDF plan file.
 
@@ -79,7 +97,7 @@ class HdfResultsPlan:
             hdf_path (Path): Path to the HEC-RAS plan HDF file.
 
         Returns:
-            Dict: A dictionary containing the results unsteady summary attributes.
+            pd.DataFrame: A DataFrame containing the results unsteady summary attributes.
 
         Raises:
             FileNotFoundError: If the specified HDF file is not found.
@@ -89,16 +107,22 @@ class HdfResultsPlan:
             with h5py.File(hdf_path, 'r') as hdf_file:
                 if "Results/Unsteady/Summary" not in hdf_file:
                     raise KeyError("Results/Unsteady/Summary group not found in the HDF file.")
-                return dict(hdf_file["Results/Unsteady/Summary"].attrs)
+                
+                # Create dictionary from attributes
+                attrs_dict = dict(hdf_file["Results/Unsteady/Summary"].attrs)
+                
+                # Create DataFrame with a single row index
+                return pd.DataFrame(attrs_dict, index=[0])
+                
         except FileNotFoundError:
             raise FileNotFoundError(f"HDF file not found: {hdf_path}")
         except Exception as e:
             raise RuntimeError(f"Error reading unsteady summary attributes: {str(e)}")
-
+        
     @staticmethod
     @log_call
     @standardize_input(file_type='plan_hdf')
-    def get_results_volume_accounting_attrs(hdf_path: Path) -> Dict:
+    def get_volume_accounting(hdf_path: Path) -> pd.DataFrame:
         """
         Get volume accounting attributes from a HEC-RAS HDF plan file.
 
@@ -106,7 +130,7 @@ class HdfResultsPlan:
             hdf_path (Path): Path to the HEC-RAS plan HDF file.
 
         Returns:
-            Dict: A dictionary containing the volume accounting attributes.
+            pd.DataFrame: A DataFrame containing the volume accounting attributes.
 
         Raises:
             FileNotFoundError: If the specified HDF file is not found.
@@ -116,7 +140,13 @@ class HdfResultsPlan:
             with h5py.File(hdf_path, 'r') as hdf_file:
                 if "Results/Unsteady/Summary/Volume Accounting" not in hdf_file:
                     raise KeyError("Results/Unsteady/Summary/Volume Accounting group not found in the HDF file.")
-                return dict(hdf_file["Results/Unsteady/Summary/Volume Accounting"].attrs)
+                
+                # Get attributes and create dictionary
+                attrs_dict = dict(hdf_file["Results/Unsteady/Summary/Volume Accounting"].attrs)
+                
+                # Create DataFrame with a single row index
+                return pd.DataFrame(attrs_dict, index=[0])
+                
         except FileNotFoundError:
             raise FileNotFoundError(f"HDF file not found: {hdf_path}")
         except Exception as e:
@@ -126,13 +156,29 @@ class HdfResultsPlan:
     @standardize_input(file_type='plan_hdf')
     def get_runtime_data(hdf_path: Path) -> Optional[pd.DataFrame]:
         """
-        Extract runtime and compute time data from a single HDF file.
+        Extract detailed runtime and computational performance metrics from HDF file.
 
         Args:
-            hdf_path (Path): The full path to the HDF file.
+            hdf_path (Path): Path to HEC-RAS plan HDF file
 
         Returns:
-            Optional[pd.DataFrame]: DataFrame containing runtime and compute time data, or None if data extraction fails.
+            Optional[pd.DataFrame]: DataFrame containing:
+                - Plan identification (name, file)
+                - Simulation timing (start, end, duration)
+                - Process-specific compute times
+                - Performance metrics (simulation speeds)
+                Returns None if required data cannot be extracted
+
+        Notes:
+            - Times are reported in multiple units (ms, s, hours)
+            - Compute speeds are calculated as simulation-time/compute-time ratios
+            - Process times include: geometry, preprocessing, event conditions, 
+            and unsteady flow computations
+
+        Example:
+            >>> runtime_stats = HdfResultsPlan.get_runtime_data('path/to/plan.hdf')
+            >>> if runtime_stats is not None:
+            >>>     print(f"Total compute time: {runtime_stats['Complete Process (hr)'][0]:.2f} hours")
         """
         if hdf_path is None:
             logger.error(f"Could not find HDF file for input")
@@ -206,196 +252,6 @@ class HdfResultsPlan:
 
             return compute_summary_df
 
-
-
-    @staticmethod
-    @log_call
-    @standardize_input(file_type='plan_hdf')
-    def reference_timeseries_output(hdf_path: Path, reftype: str = "lines") -> xr.Dataset:
-        """
-        Get timeseries output for reference lines or points.
-
-        Args:
-            hdf_path (Path): Path to the HDF file.
-            reftype (str): Type of reference, either "lines" or "points" (default "lines").
-
-        Returns:
-            xr.Dataset: Dataset containing the timeseries output for reference lines or points.
-
-        Raises:
-            FileNotFoundError: If the specified HDF file is not found.
-            ValueError: If an invalid reftype is provided.
-        """
-        try:
-            with h5py.File(hdf_path, 'r') as hdf_file:
-                return HdfResultsPlan._reference_timeseries_output(hdf_file, reftype)
-        except FileNotFoundError:
-            raise FileNotFoundError(f"HDF file not found: {hdf_path}")
-        except ValueError as ve:
-            raise ValueError(f"Invalid reftype: {str(ve)}")
-        except Exception as e:
-            raise RuntimeError(f"Error getting reference timeseries output: {str(e)}")
-
-
-    @staticmethod
-    def _reference_timeseries_output(hdf_file: h5py.File, reftype: str = "lines") -> xr.Dataset:
-        """
-        Private method to return timeseries output data for reference lines or points from a HEC-RAS HDF plan file.
-
-        Parameters
-        ----------
-        hdf_file : h5py.File
-            Open HDF file object.
-        reftype : str, optional
-            The type of reference data to retrieve. Must be either "lines" or "points".
-            (default: "lines")
-
-        Returns
-        -------
-        xr.Dataset
-            An xarray Dataset with reference line or point timeseries data.
-            Returns an empty Dataset if the reference output data is not found.
-
-        Raises
-        ------
-        ValueError
-            If reftype is not "lines" or "points".
-        """
-        if reftype == "lines":
-            output_path = "Results/Unsteady/Output/Output Blocks/Base Output/Unsteady Time Series/Reference Lines"
-            abbrev = "refln"
-        elif reftype == "points":
-            output_path = "Results/Unsteady/Output/Output Blocks/Base Output/Unsteady Time Series/Reference Points"
-            abbrev = "refpt"
-        else:
-            raise ValueError('reftype must be either "lines" or "points".')
-
-        try:
-            reference_group = hdf_file[output_path]
-        except KeyError:
-            logger.error(f"Could not find HDF group at path '{output_path}'. "
-                         f"The Plan HDF file may not contain reference {reftype[:-1]} output data.")
-            return xr.Dataset()
-
-        reference_names = reference_group["Name"][:]
-        names = []
-        mesh_areas = []
-        for s in reference_names:
-            name, mesh_area = s.decode("utf-8").split("|")
-            names.append(name)
-            mesh_areas.append(mesh_area)
-
-        times = HdfBase._get_unsteady_datetimes(hdf_file)
-
-        das = {}
-        for var in ["Flow", "Velocity", "Water Surface"]:
-            group = reference_group.get(var)
-            if group is None:
-                continue
-            values = group[:]
-            units = group.attrs["Units"].decode("utf-8")
-            da = xr.DataArray(
-                values,
-                name=var,
-                dims=["time", f"{abbrev}_id"],
-                coords={
-                    "time": times,
-                    f"{abbrev}_id": range(values.shape[1]),
-                    f"{abbrev}_name": (f"{abbrev}_id", names),
-                    "mesh_name": (f"{abbrev}_id", mesh_areas),
-                },
-                attrs={"units": units, "hdf_path": f"{output_path}/{var}"},
-            )
-            das[var] = da
-        return xr.Dataset(das)
-
         
 
 
-    @staticmethod
-    @log_call
-    @standardize_input(file_type='plan_hdf')
-    def reference_lines_timeseries_output(hdf_path: Path) -> xr.Dataset:
-        """
-        Get timeseries output for reference lines.
-
-        Args:
-            hdf_path (Path): Path to the HDF file.
-
-        Returns:
-            xr.Dataset: Dataset containing the timeseries output for reference lines.
-
-        Raises:
-            FileNotFoundError: If the specified HDF file is not found.
-        """
-        return HdfResultsPlan.reference_timeseries_output(hdf_path, reftype="lines")
-
-    @staticmethod
-    @log_call
-    @standardize_input(file_type='plan_hdf')
-    def reference_points_timeseries_output(hdf_path: Path) -> xr.Dataset:
-        """
-        Get timeseries output for reference points.
-
-        Args:
-            hdf_path (Path): Path to the HDF file.
-
-        Returns:
-            xr.Dataset: Dataset containing the timeseries output for reference points.
-
-        Raises:
-            FileNotFoundError: If the specified HDF file is not found.
-        """
-        return HdfResultsPlan.reference_timeseries_output(hdf_path, reftype="points")
-    
-    @staticmethod
-    @log_call
-    @standardize_input(file_type='plan_hdf')
-    def reference_summary_output(hdf_path: Path, reftype: str = "lines") -> pd.DataFrame:
-        """
-        Get summary output for reference lines or points.
-
-        Args:
-            hdf_path (Path): Path to the HDF file.
-            reftype (str): Type of reference, either "lines" or "points" (default "lines").
-
-        Returns:
-            pd.DataFrame: DataFrame containing the summary output for reference lines or points.
-
-        Raises:
-            ValueError: If an invalid reftype is provided.
-        """
-        if not hdf_path.exists():
-            logger.error(f"HDF file not found: {hdf_path}")
-            return pd.DataFrame()  # Return an empty DataFrame if the path doesn't exist
-
-        try:
-            # Get the timeseries output
-            ds = HdfResultsPlan.reference_timeseries_output(hdf_path, reftype)
-            
-            if 'station' not in ds.dims:
-                logger.error("No 'station' dimension found in the dataset.")
-                return pd.DataFrame()  # Return an empty DataFrame if 'station' dimension is missing
-            
-            # Calculate summary statistics
-            summary = ds.groupby('station').agg({
-                'WSE': ['min', 'max', 'mean'],
-                'Q': ['min', 'max', 'mean']
-            })
-            
-            # Flatten column names
-            summary.columns = ['_'.join(col).strip() for col in summary.columns.values]
-            
-            # Reset index to make 'station' a column
-            summary = summary.reset_index()
-            
-            return summary
-        except ValueError as ve:
-            logger.error(f"Invalid reftype: {str(ve)}")
-            return pd.DataFrame()  # Return an empty DataFrame on ValueError
-        except Exception as e:
-            logger.error(f"Error in reference_summary_output: {str(e)}")
-            return pd.DataFrame()  # Return an empty DataFrame on general error
-
-
-

ras_commander/HdfResultsPlot.py

@@ -0,0 +1,182 @@
+"""
+Class: HdfResultsPlot
+
+A collection of static methods for visualizing HEC-RAS results data from HDF files using matplotlib.
+
+Public Functions:
+    plot_results_mesh_variable(variable_df, variable_name, colormap='viridis', point_size=10):
+        Generic plotting function for any mesh variable with customizable styling.
+        
+    plot_results_max_wsel(max_ws_df):
+        Visualizes the maximum water surface elevation distribution across mesh cells.
+        
+    plot_results_max_wsel_time(max_ws_df):
+        Displays the timing of maximum water surface elevation for each cell,
+        including statistics about the temporal distribution.
+
+Requirements:
+    - matplotlib
+    - pandas
+    - geopandas (for geometry handling)
+
+Input DataFrames must contain:
+    - 'geometry' column with Point objects containing x,y coordinates
+    - Variable data columns as specified in individual function docstrings
+"""
+
+import matplotlib.pyplot as plt
+import pandas as pd
+from typing import Dict
+from .Decorators import log_call
+from .HdfMesh import HdfMesh
+
+class HdfResultsPlot:
+    """
+    A class containing static methods for plotting HEC-RAS results data.
+    
+    This class provides visualization methods for various types of HEC-RAS results,
+    including maximum water surface elevations and timing information.
+    """
+
+    @staticmethod
+    @log_call
+    def plot_results_max_wsel(max_ws_df: pd.DataFrame) -> None:
+        """
+        Plots the maximum water surface elevation per cell.
+
+        Args:
+            max_ws_df (pd.DataFrame): DataFrame containing merged data with coordinates 
+                                    and max water surface elevations.
+        """
+        # Extract x and y coordinates from the geometry column
+        max_ws_df['x'] = max_ws_df['geometry'].apply(lambda geom: geom.x if geom is not None else None)
+        max_ws_df['y'] = max_ws_df['geometry'].apply(lambda geom: geom.y if geom is not None else None)
+
+        if 'x' not in max_ws_df.columns or 'y' not in max_ws_df.columns:
+            print("Error: 'x' or 'y' columns not found in the merged dataframe.")
+            print("Available columns:", max_ws_df.columns.tolist())
+            return
+
+        fig, ax = plt.subplots(figsize=(12, 8))
+        scatter = ax.scatter(max_ws_df['x'], max_ws_df['y'], 
+                           c=max_ws_df['maximum_water_surface'], 
+                           cmap='viridis', s=10)
+
+        ax.set_title('Max Water Surface per Cell')
+        ax.set_xlabel('X Coordinate')
+        ax.set_ylabel('Y Coordinate')
+        plt.colorbar(scatter, label='Max Water Surface (ft)')
+
+        ax.grid(True, linestyle='--', alpha=0.7)
+        plt.rcParams.update({'font.size': 12})
+        plt.tight_layout()
+        plt.show()
+
+    @staticmethod
+    @log_call
+    def plot_results_max_wsel_time(max_ws_df: pd.DataFrame) -> None:
+        """
+        Plots the time of the maximum water surface elevation (WSEL) per cell.
+
+        Args:
+            max_ws_df (pd.DataFrame): DataFrame containing merged data with coordinates 
+                                    and max water surface timing information.
+        """
+        # Convert datetime strings using the renamed utility function
+        max_ws_df['max_wsel_time'] = pd.to_datetime(max_ws_df['maximum_water_surface_time'])
+        
+        # Extract coordinates
+        max_ws_df['x'] = max_ws_df['geometry'].apply(lambda geom: geom.x if geom is not None else None)
+        max_ws_df['y'] = max_ws_df['geometry'].apply(lambda geom: geom.y if geom is not None else None)
+
+        if 'x' not in max_ws_df.columns or 'y' not in max_ws_df.columns:
+            raise ValueError("x and y coordinates are missing from the DataFrame. Make sure the 'geometry' column exists and contains valid coordinate data.")
+
+        fig, ax = plt.subplots(figsize=(12, 8))
+
+        min_time = max_ws_df['max_wsel_time'].min()
+        color_values = (max_ws_df['max_wsel_time'] - min_time).dt.total_seconds() / 3600
+
+        scatter = ax.scatter(max_ws_df['x'], max_ws_df['y'], 
+                           c=color_values, cmap='viridis', s=10)
+
+        ax.set_title('Time of Maximum Water Surface Elevation per Cell')
+        ax.set_xlabel('X Coordinate')
+        ax.set_ylabel('Y Coordinate')
+
+        cbar = plt.colorbar(scatter)
+        cbar.set_label('Hours since simulation start')
+        cbar.set_ticks(range(0, int(color_values.max()) + 1, 6))
+        cbar.set_ticklabels([f'{h}h' for h in range(0, int(color_values.max()) + 1, 6)])
+
+        ax.grid(True, linestyle='--', alpha=0.7)
+        plt.rcParams.update({'font.size': 12})
+        plt.tight_layout()
+        plt.show()
+
+        # Print timing information
+        print(f"\nSimulation Start Time: {min_time}")
+        print(f"Time Range: {color_values.max():.1f} hours")
+        print("\nTiming Statistics (hours since start):")
+        print(color_values.describe()) 
+
+    @staticmethod
+    @log_call
+    def plot_results_mesh_variable(variable_df: pd.DataFrame, variable_name: str, colormap: str = 'viridis', point_size: int = 10) -> None:
+        """
+        Plot any mesh variable with consistent styling.
+        
+        Args:
+            variable_df (pd.DataFrame): DataFrame containing the variable data
+            variable_name (str): Name of the variable (for labels)
+            colormap (str): Matplotlib colormap to use. Default: 'viridis'
+            point_size (int): Size of the scatter points. Default: 10
+
+        Returns:
+            None
+
+        Raises:
+            ImportError: If matplotlib is not installed
+            ValueError: If required columns are missing from variable_df
+        """
+        try:
+            import matplotlib.pyplot as plt
+        except ImportError:
+            logger.error("matplotlib is required for plotting. Please install it with 'pip install matplotlib'")
+            raise ImportError("matplotlib is required for plotting")
+
+        # Get cell coordinates if not in variable_df
+        if 'geometry' not in variable_df.columns:
+            cell_coords = HdfMesh.mesh_cell_points(plan_hdf_path)
+            merged_df = pd.merge(variable_df, cell_coords, on=['mesh_name', 'cell_id'])
+        else:
+            merged_df = variable_df
+            
+        # Extract coordinates, handling None values
+        merged_df = merged_df.dropna(subset=['geometry'])
+        merged_df['x'] = merged_df['geometry'].apply(lambda geom: geom.x if geom is not None else None)
+        merged_df['y'] = merged_df['geometry'].apply(lambda geom: geom.y if geom is not None else None)
+        
+        # Drop any rows with None coordinates
+        merged_df = merged_df.dropna(subset=['x', 'y'])
+        
+        if len(merged_df) == 0:
+            logger.error("No valid coordinates found for plotting")
+            raise ValueError("No valid coordinates found for plotting")
+            
+        # Create plot
+        fig, ax = plt.subplots(figsize=(12, 8))
+        scatter = ax.scatter(merged_df['x'], merged_df['y'], 
+                           c=merged_df[variable_name], 
+                           cmap=colormap, 
+                           s=point_size)
+        
+        # Customize plot
+        ax.set_title(f'{variable_name} per Cell')
+        ax.set_xlabel('X Coordinate')
+        ax.set_ylabel('Y Coordinate')
+        plt.colorbar(scatter, label=variable_name)
+        ax.grid(True, linestyle='--', alpha=0.7)
+        plt.rcParams.update({'font.size': 12})
+        plt.tight_layout()
+        plt.show()