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

ras_commander/HdfPlan.py

@@ -6,6 +6,43 @@ from the https://github.com/fema-ffrd/rashdf library,
 released under MIT license and Copyright (c) 2024 fema-ffrd
 
 The file has been forked and modified for use in RAS Commander.
+
+-----
+
+All of the methods in this class are static and are designed to be used without instantiation.
+
+List of Functions in HdfPlan:
+- get_simulation_start_time()
+- get_simulation_end_time()
+- get_unsteady_datetimes()
+- get_plan_info_attrs()
+- get_plan_parameters()
+- get_meteorology_precip_attrs()
+- get_geom_attrs()
+
+
+REVISIONS NEEDED: 
+
+Use get_ prefix for functions that return data.  
+Since we are extracting plan data, we should use get_plan_...
+BUT, we will never set results data, so we should use results_
+
+We need to shorten names where possible.
+
+List of Revised Functions in HdfPlan:
+- get_plan_start_time()
+- get_plan_end_time()
+- get_plan_timestamps_list()     
+- get_plan_information()
+- get_plan_parameters()
+- get_plan_met_precip()
+- get_geometry_information()
+
+
+
+
+
+
 """
 
 import h5py
@@ -24,64 +61,53 @@ logger = get_logger(__name__)
 
 class HdfPlan:
     """
-    A class for handling operations on HEC-RAS plan HDF files.
-
-    This class provides methods for extracting and analyzing data from HEC-RAS plan HDF files,
-    including simulation times, plan information, and geometry attributes.
+    A class for handling 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.
+    Provides static methods for extracting data from HEC-RAS plan HDF files including 
+    simulation times, plan information, and geometry attributes. All methods use 
+    @standardize_input for handling different input types and @log_call for logging.
 
-    Attributes:
-        None
-
-    Methods:
-        get_simulation_start_time: Get the simulation start time.
-        get_simulation_end_time: Get the simulation end time.
-        get_unsteady_datetimes: Get a list of unsteady datetimes.
-        get_plan_info_attrs: Get plan information attributes.
-        get_plan_param_attrs: Get plan parameter attributes.
-        get_meteorology_precip_attrs: Get precipitation attributes.
-        get_geom_attrs: Get geometry attributes.
+    Note: This code is partially derived from the rashdf library (https://github.com/fema-ffrd/rashdf)
+    under MIT license.
     """
 
     @staticmethod
     @log_call
     @standardize_input(file_type='plan_hdf')
-    def get_simulation_start_time(hdf_path: Path) -> datetime:
+    def get_plan_start_time(hdf_path: Path) -> datetime:
         """
-        Get the simulation start time from the plan file.
+        Get the plan start time from the plan file.
 
         Args:
             hdf_path (Path): Path to the HEC-RAS plan HDF file.
 
         Returns:
-            datetime: The simulation start time.
+            datetime: The plan start time in UTC format.
 
         Raises:
-            ValueError: If there's an error reading the simulation start time.
+            ValueError: If there's an error reading the plan start time.
         """
         try:
             with h5py.File(hdf_path, 'r') as hdf_file:
-                return HdfBase._get_simulation_start_time(hdf_file)
+                return HdfBase.get_simulation_start_time(hdf_file)
         except Exception as e:
-            raise ValueError(f"Failed to get simulation start time: {str(e)}")
+            raise ValueError(f"Failed to get plan start time: {str(e)}")
 
     @staticmethod
     @log_call
     @standardize_input(file_type='plan_hdf')
-    def get_simulation_end_time(hdf_path: Path) -> datetime:
+    def get_plan_end_time(hdf_path: Path) -> datetime:
         """
-        Get the simulation end time from the plan file.
+        Get the plan end time from the plan file.
 
         Args:
             hdf_path (Path): Path to the HEC-RAS plan HDF file.
 
         Returns:
-            datetime: The simulation end time.
+            datetime: The plan end time.
 
         Raises:
-            ValueError: If there's an error reading the simulation end time.
+            ValueError: If there's an error reading the plan end time.
         """
         try:
             with h5py.File(hdf_path, 'r') as hdf_file:
@@ -89,57 +115,70 @@ class HdfPlan:
                 if plan_info is None:
                     raise ValueError("Plan Information not found in HDF file")
                 time_str = plan_info.attrs.get('Simulation End Time')
-                return datetime.strptime(time_str.decode('utf-8'), "%d%b%Y %H:%M:%S")
+                return HdfUtils.parse_ras_datetime(time_str.decode('utf-8'))
         except Exception as e:
-            raise ValueError(f"Failed to get simulation end time: {str(e)}")
+            raise ValueError(f"Failed to get plan end time: {str(e)}")
 
     @staticmethod
     @log_call
     @standardize_input(file_type='plan_hdf')
-    def get_unsteady_datetimes(hdf_path: Path) -> List[datetime]:
+    def get_plan_timestamps_list(hdf_path: Path) -> List[datetime]:
         """
-        Get the list of unsteady datetimes from the HDF file.
+        Get the list of output timestamps from the plan simulation.
 
         Args:
             hdf_path (Path): Path to the HEC-RAS plan HDF file.
 
         Returns:
-            List[datetime]: A list of datetime objects representing the unsteady timestamps.
+            List[datetime]: Chronological list of simulation output timestamps in UTC.
 
         Raises:
-            ValueError: If there's an error retrieving the unsteady datetimes.
+            ValueError: If there's an error retrieving the plan timestamps.
         """
         try:
             with h5py.File(hdf_path, 'r') as hdf_file:
-                return HdfBase._get_unsteady_datetimes(hdf_file)
+                return HdfBase.get_unsteady_timestamps(hdf_file)
         except Exception as e:
-            raise ValueError(f"Failed to get unsteady datetimes: {str(e)}")
+            raise ValueError(f"Failed to get plan timestamps: {str(e)}")
 
     @staticmethod
     @log_call
     @standardize_input(file_type='plan_hdf')
-    def get_plan_info_attrs(hdf_path: Path) -> Dict:
+    def get_plan_information(hdf_path: Path) -> Dict:
         """
-        Get plan information attributes from a HEC-RAS HDF plan file.
+        Get plan information from a HEC-RAS HDF plan file.
 
         Args:
             hdf_path (Path): Path to the HEC-RAS plan HDF file.
 
         Returns:
-            Dict: A dictionary containing the plan information attributes.
+            Dict: Plan information including simulation times, flow regime, 
+                computation settings, etc.
 
         Raises:
-            ValueError: If there's an error retrieving the plan information attributes.
+            ValueError: If there's an error retrieving the plan information.
         """
         try:
-            return HdfUtils.get_attrs(hdf_path, "Plan Data/Plan Information")
+            with h5py.File(hdf_path, 'r') as hdf_file:
+                plan_info_path = "Plan Data/Plan Information"
+                if plan_info_path not in hdf_file:
+                    raise ValueError(f"Plan Information not found in {hdf_path}")
+                
+                attrs = {}
+                for key in hdf_file[plan_info_path].attrs.keys():
+                    value = hdf_file[plan_info_path].attrs[key]
+                    if isinstance(value, bytes):
+                        value = HdfUtils.convert_ras_string(value)
+                    attrs[key] = value
+                
+                return attrs
         except Exception as e:
             raise ValueError(f"Failed to get plan information attributes: {str(e)}")
 
     @staticmethod
     @log_call
     @standardize_input(file_type='plan_hdf')
-    def get_plan_param_attrs(hdf_path: Path) -> Dict:
+    def get_plan_parameters(hdf_path: Path) -> Dict:
         """
         Get plan parameter attributes from a HEC-RAS HDF plan file.
 
@@ -153,14 +192,26 @@ class HdfPlan:
             ValueError: If there's an error retrieving the plan parameter attributes.
         """
         try:
-            return HdfUtils.get_attrs(hdf_path, "Plan Data/Plan Parameters")
+            with h5py.File(hdf_path, 'r') as hdf_file:
+                plan_params_path = "Plan Data/Plan Parameters"
+                if plan_params_path not in hdf_file:
+                    raise ValueError(f"Plan Parameters not found in {hdf_path}")
+                
+                attrs = {}
+                for key in hdf_file[plan_params_path].attrs.keys():
+                    value = hdf_file[plan_params_path].attrs[key]
+                    if isinstance(value, bytes):
+                        value = HdfUtils.convert_ras_string(value)
+                    attrs[key] = value
+                
+                return attrs
         except Exception as e:
             raise ValueError(f"Failed to get plan parameter attributes: {str(e)}")
 
     @staticmethod
     @log_call
     @standardize_input(file_type='plan_hdf')
-    def get_meteorology_precip_attrs(hdf_path: Path) -> Dict:
+    def get_plan_met_precip(hdf_path: Path) -> Dict:
         """
         Get precipitation attributes from a HEC-RAS HDF plan file.
 
@@ -168,38 +219,73 @@ class HdfPlan:
             hdf_path (Path): Path to the HEC-RAS plan HDF file.
 
         Returns:
-            Dict: A dictionary containing the precipitation attributes.
-
-        Raises:
-            ValueError: If there's an error retrieving the precipitation attributes.
+            Dict: Precipitation attributes including method, time series data,
+                and spatial distribution if available. Returns empty dict if
+                no precipitation data exists.
         """
         try:
-            return HdfUtils.get_attrs(hdf_path, "Event Conditions/Meteorology/Precipitation")
+            with h5py.File(hdf_path, 'r') as hdf_file:
+                precip_path = "Event Conditions/Meteorology/Precipitation"
+                if precip_path not in hdf_file:
+                    logger.error(f"Precipitation data not found in {hdf_path}")
+                    return {}
+                
+                attrs = {}
+                for key in hdf_file[precip_path].attrs.keys():
+                    value = hdf_file[precip_path].attrs[key]
+                    if isinstance(value, bytes):
+                        value = HdfUtils.convert_ras_string(value)
+                    attrs[key] = value
+                
+                return attrs
         except Exception as e:
-            raise ValueError(f"Failed to get precipitation attributes: {str(e)}")
-
+            logger.error(f"Failed to get precipitation attributes: {str(e)}")
+            return {}
+        
     @staticmethod
     @log_call
     @standardize_input(file_type='plan_hdf')
-    def get_geom_attrs(hdf_path: Path) -> Dict:
+    def get_geometry_information(hdf_path: Path) -> pd.DataFrame:
         """
-        Get geometry attributes from a HEC-RAS HDF plan file.
+        Get root level geometry attributes from the HDF plan file.
 
         Args:
             hdf_path (Path): Path to the HEC-RAS plan HDF file.
 
         Returns:
-            Dict: A dictionary containing the geometry attributes.
+            pd.DataFrame: DataFrame with geometry attributes including Creation Date/Time,
+                        Version, Units, and Projection information.
 
         Raises:
-            ValueError: If there's an error retrieving the geometry attributes.
+            ValueError: If Geometry group is missing or there's an error reading attributes.
         """
+        print(f"Getting geometry attributes from {hdf_path}")
         try:
-            return HdfUtils.get_attrs(hdf_path, "Geometry")
+            with h5py.File(hdf_path, 'r') as hdf_file:
+                geom_attrs_path = "Geometry"
+                print(f"Checking for Geometry group in {hdf_path}")
+                if geom_attrs_path not in hdf_file:
+                    raise ValueError(f"Geometry group not found in {hdf_path}")
+
+                attrs = {}
+                geom_group = hdf_file[geom_attrs_path]
+                print("Getting root level geometry attributes")
+                # Get root level geometry attributes only
+                for key, value in geom_group.attrs.items():
+                    if isinstance(value, bytes):
+                        try:
+                            value = HdfUtils.convert_ras_string(value)
+                        except UnicodeDecodeError:
+                            logger.warning(f"Failed to decode byte string for root attribute {key}")
+                            continue
+                    attrs[key] = value
+
+                print("Successfully extracted root level geometry attributes")
+                return pd.DataFrame.from_dict(attrs, orient='index', columns=['Value'])
+
+        except (OSError, RuntimeError) as e:
+            raise ValueError(f"Failed to read HDF file {hdf_path}: {str(e)}")
         except Exception as e:
             raise ValueError(f"Failed to get geometry attributes: {str(e)}")
 
 
-
-
-

ras_commander/HdfPlot.py

@@ -0,0 +1,104 @@
+"""
+Class: HdfPlot
+
+A collection of static methods for plotting general HDF data from HEC-RAS models.
+"""
+
+import matplotlib.pyplot as plt
+import pandas as pd
+import geopandas as gpd
+from typing import Optional, Union, Tuple
+from .Decorators import log_call, standardize_input
+from .HdfUtils import HdfUtils
+
+class HdfPlot:
+    """
+    A class containing static methods for plotting general HDF data from HEC-RAS models.
+    
+    This class provides plotting functionality for HDF data, focusing on
+    geometric elements like cell polygons and time series data.
+    """
+
+    @staticmethod
+    @log_call
+    def plot_mesh_cells(
+        cell_polygons_df: pd.DataFrame, ## THIS IS A GEODATAFRAME - NEED TO EDIT BOTH ARGUMENT AND USAGE
+        projection: str,
+        title: str = '2D Flow Area Mesh Cells',
+        figsize: Tuple[int, int] = (12, 8)
+    ) -> Optional[gpd.GeoDataFrame]:
+        """
+        Plots the mesh cells from the provided DataFrame and returns the GeoDataFrame.
+
+        Args:
+            cell_polygons_df (pd.DataFrame): DataFrame containing cell polygons.
+            projection (str): The coordinate reference system to assign to the GeoDataFrame.
+            title (str, optional): Plot title. Defaults to '2D Flow Area Mesh Cells'.
+            figsize (Tuple[int, int], optional): Figure size. Defaults to (12, 8).
+
+        Returns:
+            Optional[gpd.GeoDataFrame]: GeoDataFrame containing the mesh cells, or None if no cells found.
+        """
+        if cell_polygons_df.empty:
+            print("No Cell Polygons found.")
+            return None
+
+        # Convert any datetime columns to strings using HdfUtils
+        cell_polygons_df = HdfUtils.convert_df_datetimes_to_str(cell_polygons_df)
+        
+        cell_polygons_gdf = gpd.GeoDataFrame(cell_polygons_df, crs=projection)
+
+        print("Cell Polygons CRS:", cell_polygons_gdf.crs)
+        display(cell_polygons_gdf.head())
+
+        fig, ax = plt.subplots(figsize=figsize)
+        cell_polygons_gdf.plot(ax=ax, edgecolor='blue', facecolor='none')
+        ax.set_xlabel('X Coordinate')
+        ax.set_ylabel('Y Coordinate')
+        ax.set_title(title)
+        ax.grid(True)
+        plt.tight_layout()
+        plt.show()
+
+        return cell_polygons_gdf
+
+    @staticmethod
+    @log_call
+    def plot_time_series(
+        df: pd.DataFrame,
+        x_col: str,
+        y_col: str,
+        title: str = None,
+        figsize: Tuple[int, int] = (12, 6)
+    ) -> None:
+        """
+        Plots time series data from HDF results.
+
+        Args:
+            df (pd.DataFrame): DataFrame containing the time series data
+            x_col (str): Name of the column containing x-axis data (usually time)
+            y_col (str): Name of the column containing y-axis data
+            title (str, optional): Plot title. Defaults to None.
+            figsize (Tuple[int, int], optional): Figure size. Defaults to (12, 6).
+        """
+        # Convert any datetime columns to strings
+        df = HdfUtils.convert_df_datetimes_to_str(df)
+        
+        fig, ax = plt.subplots(figsize=figsize)
+        df.plot(x=x_col, y=y_col, ax=ax)
+        
+        if title:
+            ax.set_title(title)
+        ax.grid(True)
+        plt.tight_layout()
+        plt.show()
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    

ras_commander/HdfPump.py

@@ -1,3 +1,19 @@
+"""
+Class: HdfPump
+
+All of the methods in this class are static and are designed to be used without instantiation.
+
+List of Functions in HdfPump:
+- get_pump_stations()
+- get_pump_groups()
+- get_pump_station_timeseries()
+- get_pump_station_summary()
+- get_pump_operation_timeseries()
+
+
+"""
+
+
 import h5py
 import numpy as np
 import pandas as pd
@@ -16,6 +32,14 @@ logger = get_logger(__name__)
 class HdfPump:
     """
     A class for handling pump station related data from HEC-RAS HDF files.
+
+    This class provides static methods to extract and process pump station data, including:
+    - Pump station locations and attributes
+    - Pump group configurations and efficiency curves
+    - Time series results for pump operations
+    - Summary statistics for pump stations
+
+    All methods are static and designed to work with HEC-RAS HDF files containing pump data.
     """
 
     @staticmethod
@@ -26,13 +50,17 @@ class HdfPump:
         Extract pump station data from the HDF file.
 
         Args:
-            hdf_path (Path): Path to the HDF file.
+            hdf_path (Path): Path to the HEC-RAS HDF file.
 
         Returns:
-            gpd.GeoDataFrame: GeoDataFrame containing pump station data.
+            gpd.GeoDataFrame: GeoDataFrame containing pump station data with columns:
+                - geometry: Point geometry of pump station location
+                - station_id: Unique identifier for each pump station
+                - Additional attributes from the HDF file
 
         Raises:
-            KeyError: If the required datasets are not found in the HDF file.
+            KeyError: If pump station datasets are not found in the HDF file.
+            Exception: If there are errors processing the pump station data.
         """
         try:
             with h5py.File(hdf_path, 'r') as hdf:
@@ -57,7 +85,7 @@ class HdfPump:
                     gdf[col] = attr_df[col]
 
                 # Set CRS if available
-                crs = HdfUtils.projection(hdf_path)
+                crs = HdfBase.get_projection(hdf_path)
                 if crs:
                     gdf.set_crs(crs, inplace=True)
 
@@ -78,13 +106,18 @@ class HdfPump:
         Extract pump group data from the HDF file.
 
         Args:
-            hdf_path (Path): Path to the HDF file.
+            hdf_path (Path): Path to the HEC-RAS HDF file.
 
         Returns:
-            pd.DataFrame: DataFrame containing pump group data.
+            pd.DataFrame: DataFrame containing pump group data with columns:
+                - efficiency_curve_start: Starting index of efficiency curve data
+                - efficiency_curve_count: Number of points in efficiency curve
+                - efficiency_curve: List of efficiency curve values
+                - Additional attributes from the HDF file
 
         Raises:
-            KeyError: If the required datasets are not found in the HDF file.
+            KeyError: If pump group datasets are not found in the HDF file.
+            Exception: If there are errors processing the pump group data.
         """
         try:
             with h5py.File(hdf_path, 'r') as hdf:
@@ -123,18 +156,23 @@ class HdfPump:
     @standardize_input(file_type='plan_hdf')
     def get_pump_station_timeseries(hdf_path: Path, pump_station: str) -> xr.DataArray:
         """
-        Extract timeseries data for a specific pump station.
+        Extract timeseries results data for a specific pump station.
 
         Args:
-            hdf_path (Path): Path to the HDF file.
-            pump_station (str): Name of the pump station.
+            hdf_path (Path): Path to the HEC-RAS HDF file.
+            pump_station (str): Name or identifier of the pump station.
 
         Returns:
-            xr.DataArray: DataArray containing the timeseries data.
+            xr.DataArray: DataArray containing the timeseries data with dimensions:
+                - time: Timestamps of simulation
+                - variable: Variables including ['Flow', 'Stage HW', 'Stage TW', 
+                           'Pump Station', 'Pumps on']
+            Attributes include units and pump station name.
 
         Raises:
-            KeyError: If the required datasets are not found in the HDF file.
-            ValueError: If the specified pump station is not found.
+            KeyError: If required datasets are not found in the HDF file.
+            ValueError: If the specified pump station name is not found.
+            Exception: If there are errors processing the timeseries data.
         """
         try:
             with h5py.File(hdf_path, 'r') as hdf:
@@ -147,8 +185,8 @@ class HdfPump:
                 data_path = f"{pumping_stations_path}/{pump_station}/Structure Variables"
                 data = hdf[data_path][()]
 
-                # Extract time information
-                time = HdfBase._get_unsteady_datetimes(hdf)
+                # Extract time information - Updated to use new method name
+                time = HdfBase.get_unsteady_timestamps(hdf)
 
                 # Create DataArray
                 da = xr.DataArray(
@@ -180,16 +218,19 @@ class HdfPump:
     @standardize_input(file_type='plan_hdf')
     def get_pump_station_summary(hdf_path: Path) -> pd.DataFrame:
         """
-        Extract summary data for pump stations from the HDF file.
+        Extract summary statistics and performance data for all pump stations.
 
         Args:
-            hdf_path (Path): Path to the HDF file.
+            hdf_path (Path): Path to the HEC-RAS HDF file.
 
         Returns:
-            pd.DataFrame: DataFrame containing pump station summary data.
+            pd.DataFrame: DataFrame containing pump station summary data including
+                operational statistics and performance metrics. Returns empty DataFrame
+                if no summary data is found.
 
         Raises:
-            KeyError: If the required datasets are not found in the HDF file.
+            KeyError: If the summary dataset is not found in the HDF file.
+            Exception: If there are errors processing the summary data.
         """
         try:
             with h5py.File(hdf_path, 'r') as hdf:
@@ -219,20 +260,27 @@ class HdfPump:
     @staticmethod
     @log_call
     @standardize_input(file_type='plan_hdf')
-    def get_pump_operation_data(hdf_path: Path, pump_station: str) -> pd.DataFrame:
+    def get_pump_operation_timeseries(hdf_path: Path, pump_station: str) -> pd.DataFrame:
         """
-        Extract pump operation data for a specific pump station.
+        Extract detailed pump operation results data for a specific pump station.
 
         Args:
-            hdf_path (Path): Path to the HDF file.
-            pump_station (str): Name of the pump station.
+            hdf_path (Path): Path to the HEC-RAS HDF file.
+            pump_station (str): Name or identifier of the pump station.
 
         Returns:
-            pd.DataFrame: DataFrame containing pump operation data.
+            pd.DataFrame: DataFrame containing pump operation data with columns:
+                - Time: Simulation timestamps
+                - Flow: Pump flow rate
+                - Stage HW: Headwater stage
+                - Stage TW: Tailwater stage
+                - Pump Station: Station identifier
+                - Pumps on: Number of active pumps
 
         Raises:
-            KeyError: If the required datasets are not found in the HDF file.
-            ValueError: If the specified pump station is not found.
+            KeyError: If required datasets are not found in the HDF file.
+            ValueError: If the specified pump station name is not found.
+            Exception: If there are errors processing the operation data.
         """
         try:
             with h5py.File(hdf_path, 'r') as hdf:
@@ -245,8 +293,8 @@ class HdfPump:
                 data_path = f"{pump_stations_path}/{pump_station}/Structure Variables"
                 data = hdf[data_path][()]
 
-                # Extract time information
-                time = HdfBase._get_unsteady_datetimes(hdf)
+                # Extract time information - Updated to use new method name
+                time = HdfBase.get_unsteady_timestamps(hdf)
 
                 # Create DataFrame and decode byte strings
                 df = pd.DataFrame(data, columns=['Flow', 'Stage HW', 'Stage TW', 'Pump Station', 'Pumps on'])