ras-commander 0.44.0__py3-none-any.whl → 0.46.0__py3-none-any.whl

ras_commander/HdfPlan.py

@@ -198,3 +198,8 @@ class HdfPlan:
             return HdfUtils.get_attrs(hdf_path, "Geometry")
         except Exception as e:
             raise ValueError(f"Failed to get geometry attributes: {str(e)}")
+
+
+
+
+

ras_commander/HdfPump.py

@@ -0,0 +1,269 @@
+import h5py
+import numpy as np
+import pandas as pd
+import geopandas as gpd
+import xarray as xr
+from pathlib import Path
+from shapely.geometry import Point
+from typing import List, Dict, Any, Optional, Union
+from .HdfUtils import HdfUtils
+from .HdfBase import HdfBase
+from .Decorators import standardize_input, log_call
+from .LoggingConfig import get_logger
+
+logger = get_logger(__name__)
+
+class HdfPump:
+    """
+    A class for handling pump station related data from HEC-RAS HDF files.
+    """
+
+    @staticmethod
+    @log_call
+    @standardize_input(file_type='plan_hdf')
+    def get_pump_stations(hdf_path: Path) -> gpd.GeoDataFrame:
+        """
+        Extract pump station data from the HDF file.
+
+        Args:
+            hdf_path (Path): Path to the HDF file.
+
+        Returns:
+            gpd.GeoDataFrame: GeoDataFrame containing pump station data.
+
+        Raises:
+            KeyError: If the required datasets are not found in the HDF file.
+        """
+        try:
+            with h5py.File(hdf_path, 'r') as hdf:
+                # Extract pump station data
+                attributes = hdf['/Geometry/Pump Stations/Attributes'][()]
+                points = hdf['/Geometry/Pump Stations/Points'][()]
+
+                # Create geometries
+                geometries = [Point(x, y) for x, y in points]
+
+                # Create GeoDataFrame
+                gdf = gpd.GeoDataFrame(geometry=geometries)
+                gdf['station_id'] = range(len(gdf))
+
+                # Add attributes and decode byte strings
+                attr_df = pd.DataFrame(attributes)
+                string_columns = attr_df.select_dtypes([object]).columns
+                for col in string_columns:
+                    attr_df[col] = attr_df[col].apply(lambda x: x.decode('utf-8') if isinstance(x, bytes) else x)
+                
+                for col in attr_df.columns:
+                    gdf[col] = attr_df[col]
+
+                # Set CRS if available
+                crs = HdfUtils.projection(hdf_path)
+                if crs:
+                    gdf.set_crs(crs, inplace=True)
+
+                return gdf
+
+        except KeyError as e:
+            logger.error(f"Required dataset not found in HDF file: {e}")
+            raise
+        except Exception as e:
+            logger.error(f"Error extracting pump station data: {e}")
+            raise
+
+    @staticmethod
+    @log_call
+    @standardize_input(file_type='plan_hdf')
+    def get_pump_groups(hdf_path: Path) -> pd.DataFrame:
+        """
+        Extract pump group data from the HDF file.
+
+        Args:
+            hdf_path (Path): Path to the HDF file.
+
+        Returns:
+            pd.DataFrame: DataFrame containing pump group data.
+
+        Raises:
+            KeyError: If the required datasets are not found in the HDF file.
+        """
+        try:
+            with h5py.File(hdf_path, 'r') as hdf:
+                # Extract pump group data
+                attributes = hdf['/Geometry/Pump Stations/Pump Groups/Attributes'][()]
+                efficiency_curves_info = hdf['/Geometry/Pump Stations/Pump Groups/Efficiency Curves Info'][()]
+                efficiency_curves_values = hdf['/Geometry/Pump Stations/Pump Groups/Efficiency Curves Values'][()]
+
+                # Create DataFrame and decode byte strings
+                df = pd.DataFrame(attributes)
+                string_columns = df.select_dtypes([object]).columns
+                for col in string_columns:
+                    df[col] = df[col].apply(lambda x: x.decode('utf-8') if isinstance(x, bytes) else x)
+
+                # Add efficiency curve data
+                df['efficiency_curve_start'] = efficiency_curves_info[:, 0]
+                df['efficiency_curve_count'] = efficiency_curves_info[:, 1]
+
+                # Process efficiency curves
+                def get_efficiency_curve(start, count):
+                    return efficiency_curves_values[start:start+count].tolist()
+
+                df['efficiency_curve'] = df.apply(lambda row: get_efficiency_curve(row['efficiency_curve_start'], row['efficiency_curve_count']), axis=1)
+
+                return df
+
+        except KeyError as e:
+            logger.error(f"Required dataset not found in HDF file: {e}")
+            raise
+        except Exception as e:
+            logger.error(f"Error extracting pump group data: {e}")
+            raise
+
+    @staticmethod
+    @log_call
+    @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.
+
+        Args:
+            hdf_path (Path): Path to the HDF file.
+            pump_station (str): Name of the pump station.
+
+        Returns:
+            xr.DataArray: DataArray containing the timeseries data.
+
+        Raises:
+            KeyError: If the required datasets are not found in the HDF file.
+            ValueError: If the specified pump station is not found.
+        """
+        try:
+            with h5py.File(hdf_path, 'r') as hdf:
+                # Check if the pump station exists
+                pumping_stations_path = "/Results/Unsteady/Output/Output Blocks/DSS Hydrograph Output/Unsteady Time Series/Pumping Stations"
+                if pump_station not in hdf[pumping_stations_path]:
+                    raise ValueError(f"Pump station '{pump_station}' not found in HDF file")
+
+                # Extract timeseries data
+                data_path = f"{pumping_stations_path}/{pump_station}/Structure Variables"
+                data = hdf[data_path][()]
+
+                # Extract time information
+                time = HdfBase._get_unsteady_datetimes(hdf)
+
+                # Create DataArray
+                da = xr.DataArray(
+                    data=data,
+                    dims=['time', 'variable'],
+                    coords={'time': time, 'variable': ['Flow', 'Stage HW', 'Stage TW', 'Pump Station', 'Pumps on']},
+                    name=pump_station
+                )
+
+                # Add attributes and decode byte strings
+                units = hdf[data_path].attrs.get('Variable_Unit', b'')
+                da.attrs['units'] = units.decode('utf-8') if isinstance(units, bytes) else units
+                da.attrs['pump_station'] = pump_station
+
+                return da
+
+        except KeyError as e:
+            logger.error(f"Required dataset not found in HDF file: {e}")
+            raise
+        except ValueError as e:
+            logger.error(str(e))
+            raise
+        except Exception as e:
+            logger.error(f"Error extracting pump station timeseries data: {e}")
+            raise
+
+    @staticmethod
+    @log_call
+    @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.
+
+        Args:
+            hdf_path (Path): Path to the HDF file.
+
+        Returns:
+            pd.DataFrame: DataFrame containing pump station summary data.
+
+        Raises:
+            KeyError: If the required datasets are not found in the HDF file.
+        """
+        try:
+            with h5py.File(hdf_path, 'r') as hdf:
+                # Extract summary data
+                summary_path = "/Results/Unsteady/Summary/Pump Station"
+                if summary_path not in hdf:
+                    logger.warning("Pump Station summary data not found in HDF file")
+                    return pd.DataFrame()
+
+                summary_data = hdf[summary_path][()]
+                
+                # Create DataFrame and decode byte strings
+                df = pd.DataFrame(summary_data)
+                string_columns = df.select_dtypes([object]).columns
+                for col in string_columns:
+                    df[col] = df[col].apply(lambda x: x.decode('utf-8') if isinstance(x, bytes) else x)
+
+                return df
+
+        except KeyError as e:
+            logger.error(f"Required dataset not found in HDF file: {e}")
+            raise
+        except Exception as e:
+            logger.error(f"Error extracting pump station summary data: {e}")
+            raise
+
+    @staticmethod
+    @log_call
+    @standardize_input(file_type='plan_hdf')
+    def get_pump_operation_data(hdf_path: Path, pump_station: str) -> pd.DataFrame:
+        """
+        Extract pump operation data for a specific pump station.
+
+        Args:
+            hdf_path (Path): Path to the HDF file.
+            pump_station (str): Name of the pump station.
+
+        Returns:
+            pd.DataFrame: DataFrame containing pump operation data.
+
+        Raises:
+            KeyError: If the required datasets are not found in the HDF file.
+            ValueError: If the specified pump station is not found.
+        """
+        try:
+            with h5py.File(hdf_path, 'r') as hdf:
+                # Check if the pump station exists
+                pump_stations_path = "/Results/Unsteady/Output/Output Blocks/DSS Profile Output/Unsteady Time Series/Pumping Stations"
+                if pump_station not in hdf[pump_stations_path]:
+                    raise ValueError(f"Pump station '{pump_station}' not found in HDF file")
+
+                # Extract pump operation data
+                data_path = f"{pump_stations_path}/{pump_station}/Structure Variables"
+                data = hdf[data_path][()]
+
+                # Extract time information
+                time = HdfBase._get_unsteady_datetimes(hdf)
+
+                # Create DataFrame and decode byte strings
+                df = pd.DataFrame(data, columns=['Flow', 'Stage HW', 'Stage TW', 'Pump Station', 'Pumps on'])
+                string_columns = df.select_dtypes([object]).columns
+                for col in string_columns:
+                    df[col] = df[col].apply(lambda x: x.decode('utf-8') if isinstance(x, bytes) else x)
+                    
+                df['Time'] = time
+
+                return df
+
+        except KeyError as e:
+            logger.error(f"Required dataset not found in HDF file: {e}")
+            raise
+        except ValueError as e:
+            logger.error(str(e))
+            raise
+        except Exception as e:
+            logger.error(f"Error extracting pump operation data: {e}")
+            raise

ras_commander/HdfResultsMesh.py

@@ -14,7 +14,7 @@ import xarray as xr
 from pathlib import Path
 import h5py
 from typing import Union, List, Optional, Dict, Any, Tuple
-
+from .HdfMesh import HdfMesh
 from .HdfBase import HdfBase
 from .HdfUtils import HdfUtils
 from .Decorators import log_call, standardize_input
@@ -233,7 +233,7 @@ class HdfResultsMesh:
     @standardize_input(file_type='plan_hdf')
     def mesh_max_face_v(hdf_path: Path, round_to: str = "100ms") -> pd.DataFrame:
         """
-        Get maximum face velocity for each mesh cell.
+        Get maximum face velocity for each mesh face.
 
         Args:
             hdf_path (Path): Path to the HDF file.
@@ -363,27 +363,22 @@ class HdfResultsMesh:
         Raises:
             ValueError: If there's an error processing the timeseries output data.
         """
-        TIME_SERIES_OUTPUT_VARS_CELLS = [
-            "Water Surface",
-            "Depth",
-            "Velocity",
-            "Velocity X",
-            "Velocity Y",
-            "Froude Number",
-            "Courant Number",
-            "Shear Stress",
-            "Bed Elevation",
-            "Precipitation Rate",
-            "Infiltration Rate",
-            "Evaporation Rate",
-            "Percolation Rate",
-            "Groundwater Elevation",
-            "Groundwater Depth",
-            "Groundwater Flow",
-            "Groundwater Velocity",
-            "Groundwater Velocity X",
-            "Groundwater Velocity Y",
-        ]
+        TIME_SERIES_OUTPUT_VARS = {
+            "cell": [
+                "Water Surface", "Depth", "Velocity", "Velocity X", "Velocity Y",
+                "Froude Number", "Courant Number", "Shear Stress", "Bed Elevation",
+                "Precipitation Rate", "Infiltration Rate", "Evaporation Rate",
+                "Percolation Rate", "Groundwater Elevation", "Groundwater Depth",
+                "Groundwater Flow", "Groundwater Velocity", "Groundwater Velocity X",
+                "Groundwater Velocity Y"
+            ],
+            "face": [
+                "Face Velocity", "Face Flow", "Face Water Surface", "Face Courant",
+                "Face Cumulative Volume", "Face Eddy Viscosity", "Face Flow Period Average",
+                "Face Friction Term", "Face Pressure Gradient Term", "Face Shear Stress",
+                "Face Tangential Velocity"
+            ]
+        }
 
         try:
             start_time = HdfBase._get_simulation_start_time(hdf_file)
@@ -397,7 +392,7 @@ class HdfResultsMesh:
             if var:
                 variables = [var]
             else:
-                variables = TIME_SERIES_OUTPUT_VARS_CELLS
+                variables = TIME_SERIES_OUTPUT_VARS["cell"] + TIME_SERIES_OUTPUT_VARS["face"]
 
             datasets = {}
             for mesh_name in mesh_names:
@@ -417,13 +412,16 @@ class HdfResultsMesh:
                             truncated_time_stamps = time_stamps
 
                         if values.shape[0] != len(truncated_time_stamps):
-                            logger.warning(f"Mismatch between number of time steps ({len(truncated_time_stamps)}) and data shape ({values.shape}) for variable {variable}")
+                            logger.warning(f"Mismatch between time steps ({len(truncated_time_stamps)}) and data shape ({values.shape}) for variable {variable}")
                             continue
 
+                        # Determine if this is a face-based or cell-based variable
+                        id_dim = "face_id" if any(face_var in variable for face_var in TIME_SERIES_OUTPUT_VARS["face"]) else "cell_id"
+
                         data_vars[variable] = xr.DataArray(
                             data=values,
-                            dims=['time', 'cell_id'],
-                            coords={'time': truncated_time_stamps, 'cell_id': np.arange(values.shape[1])},
+                            dims=['time', id_dim],
+                            coords={'time': truncated_time_stamps, id_dim: np.arange(values.shape[1])},
                             attrs={'units': units}
                         )
                     except KeyError:
@@ -454,16 +452,7 @@ class HdfResultsMesh:
         Args:
             hdf_file (h5py.File): Open HDF file object.
             mesh_name (str): Name of the mesh.
-            var (str): Variable name to retrieve. Valid options include:
-                "Water Surface", "Face Velocity", "Cell Velocity X", "Cell Velocity Y",
-                "Face Flow", "Face Water Surface", "Cell Volume", "Cell Volume Error",
-                "Cell Water Surface Error", "Cell Courant", "Face Courant",
-                "Cell Hydraulic Depth", "Cell Invert Depth",
-                "Cell Cumulative Precipitation Depth", "Cell Divergence Term",
-                "Cell Eddy Viscosity X", "Cell Eddy Viscosity Y", "Cell Flow Balance",
-                "Cell Storage Term", "Cell Water Source Term", "Face Cumulative Volume",
-                "Face Eddy Viscosity", "Face Flow Period Average", "Face Friction Term",
-                "Face Pressure Gradient Term", "Face Shear Stress", "Face Tangential Velocity"
+            var (str): Variable name to retrieve.
             truncate (bool): Whether to truncate the output to remove trailing zeros (default True).
 
         Returns:
@@ -478,7 +467,6 @@ class HdfResultsMesh:
             if path not in hdf_file:
                 raise ValueError(f"Path {path} not found in HDF file")
 
-            # Use h5py to get the dataset
             dataset = hdf_file[path]
             values = dataset[:]
             units = dataset.attrs.get("Units", "").decode("utf-8")
@@ -491,11 +479,12 @@ class HdfResultsMesh:
                     values = values[start:end]
                     times = times[start:end]
 
-            # Create xarray DataArray
-            dims = ["time", "cell"] if values.ndim == 2 else ["time"]
+            # Determine if this is a face-based or cell-based variable
+            id_dim = "face_id" if "Face" in var else "cell_id"
+            dims = ["time", id_dim] if values.ndim == 2 else ["time"]
             coords = {"time": times}
             if values.ndim == 2:
-                coords["cell"] = np.arange(values.shape[1])
+                coords[id_dim] = np.arange(values.shape[1])
 
             return xr.DataArray(
                 values,
@@ -548,26 +537,30 @@ class HdfResultsMesh:
                 if isinstance(hdf_file[f"{base_path}/{name}"], h5py.Group):
                     mesh_names.append(name)
         return mesh_names
-
+    
     @staticmethod
     def _get_mesh_summary_output(hdf_file: h5py.File, var: str, round_to: str = "100ms") -> pd.DataFrame:
         """
         Get the summary output data for a given variable from the HDF file.
 
-        This method retrieves summary output data for all 2D flow areas (meshes) in the HDF file
-        for a specified variable. It handles both 1D and 2D datasets.
-        Group attributes are added as metadata to the DataFrame.
-
-        Args:
-            hdf_file (h5py.File): Open HDF file object.
-            var (str): The summary output variable to retrieve.
-            round_to (str): The time unit to round the datetimes to. Default is "100ms".
-
-        Returns:
-            pd.DataFrame: A DataFrame containing the summary output data with attributes as metadata.
-
-        Raises:
-            ValueError: If the HDF file cannot be opened or read, or if the requested data is not found.
+        Parameters
+        ----------
+        hdf_file : h5py.File
+            Open HDF file object.
+        var : str
+            The summary output variable to retrieve.
+        round_to : str, optional
+            The time unit to round the datetimes to. Default is "100ms".
+
+        Returns
+        -------
+        pd.DataFrame
+            A DataFrame containing the summary output data with attributes as metadata.
+
+        Raises
+        ------
+        ValueError
+            If the HDF file cannot be opened or read, or if the requested data is not found.
         """
         try:
             dfs = []
@@ -584,28 +577,44 @@ class HdfResultsMesh:
                 logger.debug(f"Attributes: {dict(group.attrs)}")
                 
                 if data.ndim == 2 and data.shape[0] == 2:
-                    # This is the case for "Maximum Water Surface"
+                    # Handle 2D datasets (e.g. Maximum Water Surface)
                     row_variables = group.attrs.get('Row Variables', [b'Value', b'Time'])
                     row_variables = [v.decode('utf-8').strip() for v in row_variables]
                     
                     df = pd.DataFrame({
                         "mesh_name": [mesh_name] * data.shape[1],
-                        "cell_id": range(data.shape[1]),
+                        "cell_id" if "Face" not in var else "face_id": range(data.shape[1]),
                         f"{var.lower().replace(' ', '_')}": data[0, :],
                         f"{var.lower().replace(' ', '_')}_time": HdfUtils._ras_timesteps_to_datetimes(
                             data[1, :], start_time, time_unit="days", round_to=round_to
                         )
                     })
+                    
                 elif data.ndim == 1:
-                    # Handle 1D datasets (like Cell Last Iteration)
+                    # Handle 1D datasets (e.g. Cell Last Iteration)
                     df = pd.DataFrame({
                         "mesh_name": [mesh_name] * len(data),
-                        "cell_id": range(len(data)),
+                        "cell_id" if "Face" not in var else "face_id": range(len(data)),
                         var.lower().replace(' ', '_'): data
                     })
+                    
                 else:
                     raise ValueError(f"Unexpected data shape for {var} in {mesh_name}. "
-                                     f"Got shape {data.shape}")
+                                  f"Got shape {data.shape}")
+                
+                # Add geometry based on variable type
+                if "Face" in var:
+                    face_df = HdfMesh.mesh_cell_faces(hdf_file)
+                    if not face_df.empty:
+                        df = df.merge(face_df[['mesh_name', 'face_id', 'geometry']], 
+                                    on=['mesh_name', 'face_id'], 
+                                    how='left')
+                else:
+                    cell_df = HdfMesh.mesh_cell_points(hdf_file)
+                    if not cell_df.empty:
+                        df = df.merge(cell_df[['mesh_name', 'cell_id', 'geometry']], 
+                                    on=['mesh_name', 'cell_id'], 
+                                    how='left')
                 
                 # Add group attributes as metadata
                 df.attrs['mesh_name'] = mesh_name
@@ -618,6 +627,9 @@ class HdfResultsMesh:
                 
                 dfs.append(df)
             
+            if not dfs:
+                return pd.DataFrame()
+                
             result = pd.concat(dfs, ignore_index=True)
             
             # Combine attributes from all meshes
@@ -634,7 +646,7 @@ class HdfResultsMesh:
             logger.info(f"Processed {len(result)} rows of summary output data")
             return result
         
-        except (KeyError, ValueError, AttributeError) as e:
+        except Exception as e:
             logger.error(f"Error processing summary output data: {e}")
             raise ValueError(f"Error processing summary output data: {e}")
         
@@ -660,3 +672,64 @@ class HdfResultsMesh:
         if output_item is None:
             raise ValueError(f"Could not find HDF group or dataset at path '{output_path}'")
         return output_item
+
+    @staticmethod
+    def plot_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()
+

ras_commander/HdfResultsPlan.py

@@ -396,3 +396,6 @@ class HdfResultsPlan:
         except Exception as e:
             logger.error(f"Error in reference_summary_output: {str(e)}")
             return pd.DataFrame()  # Return an empty DataFrame on general error
+
+
+