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

ras_commander/HdfResultsXsec.py

@@ -1,11 +1,30 @@
 """
 Class: HdfResultsXsec
 
-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
+Contains methods for extracting 1D results data from HDF files. 
+This includes cross section timeseries, structures and reference line/point timeseries as these are all 1D elements.
 
-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 HdfResultsXsec:
+- get_xsec_timeseries(): Extract cross-section timeseries data including water surface, velocity, and flow
+- get_ref_lines_timeseries(): Get timeseries output for reference lines
+- get_ref_points_timeseries(): Get timeseries output for reference points
+
+TO BE IMPLEMENTED: 
+DSS Hydrograph Extraction for 1D and 2D Structures. 
+
+Planned functions:
+- get_bridge_timeseries(): Extract timeseries data for bridge structures
+- get_inline_structures_timeseries(): Extract timeseries data for inline structures
+
+Notes:
+- All functions use the get_ prefix to indicate they return data
+- Results data functions use results_ prefix to indicate they handle results data
+- All functions include proper error handling and logging
+- Functions return xarray Datasets for efficient handling of multi-dimensional data
 """
 
 from pathlib import Path
@@ -25,152 +44,23 @@ logger = get_logger(__name__)
 
 class HdfResultsXsec:
     """
-    A class for handling cross-section results from HEC-RAS HDF files.
-
-    This class provides methods to extract and process steady flow simulation results
-    for cross-sections, including water surface elevations, flow rates, energy grades,
-    and additional parameters such as encroachment stations and velocities.
+    A static class for extracting and processing 1D results data from HEC-RAS HDF files.
 
-    The class relies on the HdfBase and HdfUtils classes for core HDF file operations
-    and utility functions.
+    This class provides methods to extract and process unsteady flow simulation results
+    for cross-sections, reference lines, and reference points. All methods are static
+    and designed to be used without class instantiation.
 
-    Attributes:
-        None
+    The class handles:
+    - Cross-section timeseries (water surface, velocity, flow)
+    - Reference line timeseries
+    - Reference point timeseries
 
-    
+    Dependencies:
+        - HdfBase: Core HDF file operations
+        - HdfUtils: Utility functions for HDF processing
     """
 
 
-
-
-
-
-
-
-
-
-
-
-    @staticmethod
-    @log_call
-    @standardize_input(file_type='plan_hdf')
-    def get_pump_station_profile_output(hdf_path: Path) -> pd.DataFrame:
-        """
-        Extract pump station profile output data from the HDF file.
-
-        Args:
-            hdf_path (Path): Path to the HDF file.
-
-        Returns:
-            pd.DataFrame: DataFrame containing pump station profile output data.
-
-        Raises:
-            KeyError: If the required datasets are not found in the HDF file.
-        """
-        try:
-            with h5py.File(hdf_path, 'r') as hdf:
-                # Extract profile output data
-                profile_path = "/Results/Unsteady/Output/Output Blocks/DSS Profile Output/Unsteady Time Series/Pumping Stations"
-                if profile_path not in hdf:
-                    logger.warning("Pump Station profile output data not found in HDF file")
-                    return pd.DataFrame()
-
-                # Initialize an empty list to store data from all pump stations
-                all_data = []
-
-                # Iterate through all pump stations
-                for station in hdf[profile_path].keys():
-                    station_path = f"{profile_path}/{station}/Structure Variables"
-                    
-                    data = hdf[station_path][()]
-                    
-                    # Create a DataFrame for this pump station
-                    df = pd.DataFrame(data, columns=['Flow', 'Stage HW', 'Stage TW', 'Pump Station', 'Pumps on'])
-                    df['Station'] = station
-                    
-                    all_data.append(df)
-
-                # Concatenate all DataFrames
-                result_df = pd.concat(all_data, ignore_index=True)
-
-                # Add time information
-                time = HdfBase._get_unsteady_datetimes(hdf)
-                result_df['Time'] = [time[i] for i in result_df.index]
-
-                return result_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 profile output 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
-                df = pd.DataFrame(summary_data)
-
-                # Convert column names
-                df.columns = [col.decode('utf-8') if isinstance(col, bytes) else col for col in df.columns]
-
-                # Convert byte string values to regular strings
-                for col in df.columns:
-                    if df[col].dtype == object:
-                        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
-
-
-
-
 # Tested functions from AWS webinar where the code was developed
 # Need to add examples
 
@@ -178,7 +68,7 @@ class HdfResultsXsec:
     @staticmethod
     @log_call
     @standardize_input(file_type='plan_hdf')
-    def extract_cross_section_results(hdf_path: Path) -> xr.Dataset:
+    def get_xsec_timeseries(hdf_path: Path) -> xr.Dataset:
         """
         Extract Water Surface, Velocity Total, Velocity Channel, Flow Lateral, and Flow data from HEC-RAS HDF file.
         Includes Cross Section Only and Cross Section Attributes as coordinates in the xarray.Dataset.
@@ -270,3 +160,153 @@ class HdfResultsXsec:
             logger.error(f"Error extracting cross section results: {e}")
             raise
 
+
+
+    @staticmethod
+    @log_call
+    @standardize_input(file_type='plan_hdf')
+    def get_ref_lines_timeseries(hdf_path: Path) -> xr.Dataset:
+        """
+        Extract timeseries output data for reference lines from HEC-RAS HDF file.
+
+        Parameters:
+        -----------
+        hdf_path : Path
+            Path to the HEC-RAS results HDF file
+
+        Returns:
+        --------
+        xr.Dataset
+            Dataset containing flow, velocity, and water surface data for reference lines.
+            Returns empty dataset if reference line data not found.
+
+        Raises:
+        -------
+        FileNotFoundError
+            If the specified HDF file is not found
+        KeyError
+            If required datasets are missing from the HDF file
+        """
+        return HdfResultsXsec._reference_timeseries_output(hdf_path, reftype="lines")
+
+    @staticmethod
+    @log_call
+    @standardize_input(file_type='plan_hdf')
+    def get_ref_points_timeseries(hdf_path: Path) -> xr.Dataset:
+        """
+        Extract timeseries output data for reference points from HEC-RAS HDF file.
+
+        This method extracts flow, velocity, and water surface elevation data for all
+        reference points defined in the model. Reference points are user-defined locations
+        where detailed output is desired.
+
+        Parameters:
+        -----------
+        hdf_path : Path
+            Path to the HEC-RAS results HDF file
+
+        Returns:
+        --------
+        xr.Dataset
+            Dataset containing the following variables for each reference point:
+            - Flow [cfs or m³/s]
+            - Velocity [ft/s or m/s]
+            - Water Surface [ft or m]
+            
+            The dataset includes coordinates:
+            - time: Simulation timesteps
+            - refpt_id: Unique identifier for each reference point
+            - refpt_name: Name of each reference point
+            - mesh_name: Associated 2D mesh area name
+            
+            Returns empty dataset if reference point data not found.
+
+        Raises:
+        -------
+        FileNotFoundError
+            If the specified HDF file is not found
+        KeyError
+            If required datasets are missing from the HDF file
+
+        Examples:
+        --------
+        >>> ds = HdfResultsXsec.get_ref_points_timeseries("path/to/plan.hdf")
+        >>> # Get water surface timeseries for first reference point
+        >>> ws = ds['Water Surface'].isel(refpt_id=0)
+        >>> # Get all data for a specific reference point by name
+        >>> point_data = ds.sel(refpt_name='Point1')
+        """
+        return HdfResultsXsec._reference_timeseries_output(hdf_path, reftype="points")
+    
+
+    @staticmethod
+    def _reference_timeseries_output(hdf_file: h5py.File, reftype: str = "lines") -> xr.Dataset:
+        """
+        Internal 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_timestamps(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)

ras_commander/HdfStruc.py

@@ -6,6 +6,14 @@ 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 HdfStruc:
+- get_structures()
+- get_geom_structures_attrs()
 """
 from typing import Dict, Any, List, Union
 from pathlib import Path
@@ -24,68 +32,83 @@ logger = get_logger(__name__)
 
 class HdfStruc:
     """
-    HEC-RAS HDF Structures class for handling operations related to structures in HDF files.
-
-    This class provides methods for extracting and analyzing data about structures
-    from HEC-RAS HDF files. It includes functionality to retrieve structure geometries
-    and attributes.
-
-    Methods in this class use the @standardize_input decorator to handle different
-    input types (file path, etc.) and the @log_call decorator for logging method calls.
-
-    Attributes:
-        GEOM_STRUCTURES_PATH (str): Constant for the HDF path to structures data.
-
-    Note: This class contains static methods and does not require instantiation.
+    Handles 2D structure geometry data extraction from HEC-RAS HDF files.
+
+    This class provides static methods for extracting and analyzing structure geometries
+    and their attributes from HEC-RAS geometry HDF files. All methods are designed to work
+    without class instantiation.
+
+    Notes
+    -----
+    - 1D Structure data should be accessed via the HdfResultsXsec class
+    - All methods use @standardize_input for consistent file handling
+    - All methods use @log_call for operation logging
+    - Returns GeoDataFrames with both geometric and attribute data
     """
     
     @staticmethod
     @log_call
     @standardize_input(file_type='geom_hdf')
-    def structures(hdf_path: Path, datetime_to_str: bool = False) -> GeoDataFrame:
+    def get_structures(hdf_path: Path, datetime_to_str: bool = False) -> GeoDataFrame:
         """
-        Extracts structure data from a HEC-RAS geometry HDF5 file and returns it as a GeoDataFrame.
-
-        This function excludes Property Tables, Pier and Abutment Data/Attributes, and Gate Groups.
-        It includes Table Info, Centerlines as LineStrings, Structures Attributes, Bridge Coefficient Attributes,
-        and Profile Data (as a list of station and elevation values for each structure).
+        Extracts structure data from a HEC-RAS geometry HDF5 file.
 
         Parameters
         ----------
         hdf_path : Path
-            Path to the HEC-RAS geometry HDF5 file.
+            Path to the HEC-RAS geometry HDF5 file
         datetime_to_str : bool, optional
-            Convert datetime objects to strings, by default False.
+            If True, converts datetime objects to ISO format strings, by default False
 
         Returns
         -------
         GeoDataFrame
-            A GeoDataFrame containing all relevant structure data with geometries and attributes.
+            Structure data with columns:
+            - Structure ID: unique identifier
+            - Geometry: LineString of structure centerline
+            - Various attribute columns from the HDF file
+            - Profile_Data: list of station/elevation dictionaries
+            - Bridge coefficient attributes (if present)
+            - Table info attributes (if present)
+
+        Notes
+        -----
+        - Group-level attributes are stored in GeoDataFrame.attrs['group_attributes']
+        - Invalid geometries are dropped with warning
+        - All byte strings are decoded to UTF-8
+        - CRS is preserved from the source file
         """
         try:
             with h5py.File(hdf_path, 'r') as hdf:
                 if "Geometry/Structures" not in hdf:
                     logger.info(f"No structures found in: {hdf_path}")
                     return GeoDataFrame()
-
+                
                 def get_dataset_df(path: str) -> pd.DataFrame:
                     """
-                    Helper function to convert an HDF5 dataset to a pandas DataFrame.
+                    Converts an HDF5 dataset to a pandas DataFrame.
 
                     Parameters
                     ----------
                     path : str
-                        The path to the dataset within the HDF5 file.
+                        Dataset path within the HDF5 file
 
                     Returns
                     -------
                     pd.DataFrame
-                        DataFrame representation of the dataset.
+                        DataFrame containing the dataset values.
+                        - For compound datasets, column names match field names
+                        - For simple datasets, generic column names (Value_0, Value_1, etc.)
+                        - Empty DataFrame if dataset not found
+
+                    Notes
+                    -----
+                    Automatically decodes byte strings to UTF-8 with error handling.
                     """
                     if path not in hdf:
                         logger.warning(f"Dataset not found: {path}")
                         return pd.DataFrame()
-
+                    
                     data = hdf[path][()]
                     
                     if data.dtype.names:
@@ -100,6 +123,7 @@ class HdfStruc:
                         return pd.DataFrame(data, columns=[f'Value_{i}' for i in range(data.shape[1])])
 
                 # Extract relevant datasets
+                group_attrs = HdfBase.get_attrs(hdf, "Geometry/Structures")
                 struct_attrs = get_dataset_df("Geometry/Structures/Attributes")
                 bridge_coef = get_dataset_df("Geometry/Structures/Bridge Coefficient Attributes")
                 table_info = get_dataset_df("Geometry/Structures/Table Info")
@@ -135,7 +159,7 @@ class HdfStruc:
                 struct_gdf = GeoDataFrame(
                     struct_attrs,
                     geometry=geoms,
-                    crs=HdfUtils.projection(hdf_path)
+                    crs=HdfBase.get_projection(hdf_path)
                 )
 
                 # Drop entries with invalid geometries
@@ -205,6 +229,12 @@ class HdfStruc:
 
                 # Final GeoDataFrame
                 logger.info("Successfully extracted structures GeoDataFrame.")
+                
+                # Add group attributes to the GeoDataFrame's attrs['group_attributes']
+                struct_gdf.attrs['group_attributes'] = group_attrs
+                
+                logger.info("Successfully extracted structures GeoDataFrame with attributes.")
+                
                 return struct_gdf
 
         except Exception as e:
@@ -216,30 +246,30 @@ class HdfStruc:
     @standardize_input(file_type='geom_hdf')
     def get_geom_structures_attrs(hdf_path: Path) -> Dict[str, Any]:
         """
-        Return geometry structures attributes from a HEC-RAS HDF file.
-
-        This method extracts attributes related to geometry structures from the HDF file.
+        Extracts structure attributes from a HEC-RAS geometry HDF file.
 
         Parameters
         ----------
         hdf_path : Path
-            Path to the HEC-RAS geometry HDF file.
+            Path to the HEC-RAS geometry HDF file
 
         Returns
         -------
         Dict[str, Any]
-            A dictionary containing the geometry structures attributes.
+            Dictionary of structure attributes from the Geometry/Structures group.
+            Returns empty dict if no structures are found.
 
         Notes
         -----
-        If no structures are found in the geometry file, an empty dictionary is returned.
+        Attributes are extracted from the HDF5 group 'Geometry/Structures'.
+        All byte strings in attributes are automatically decoded to UTF-8.
         """
         try:
             with h5py.File(hdf_path, 'r') as hdf_file:
                 if "Geometry/Structures" not in hdf_file:
                     logger.info(f"No structures found in the geometry file: {hdf_path}")
                     return {}
-                return HdfUtils.get_attrs(hdf_file, "Geometry/Structures")
+                return HdfUtils.hdf5_attrs_to_dict(hdf_file["Geometry/Structures"].attrs)
         except Exception as e:
             logger.error(f"Error reading geometry structures attributes: {str(e)}")
             return {}