ras-commander 0.41.0__py3-none-any.whl → 0.42.0__py3-none-any.whl

ras_commander/RasHdf.py

@@ -1,9 +1,9 @@
 """
 RasHdf Module
 
-This module provides utilities for working with RESULTS (Plan) HDF files in HEC-RAS projects.
+This module provides utilities for working with HDF files in HEC-RAS projects.
 It contains the RasHdf class, which offers various static methods for extracting,
-analyzing, and manipulating data from HEC-RAS RESULTS HDF files.
+analyzing, and manipulating data from HEC-RAS HDF files.
 
 Note:
     This method is decorated with @hdf_operation, which handles the opening and closing of the HDF file.
@@ -642,3 +642,978 @@ class RasHdf:
             percent_impervious = cls._extract_dataset(hdf_file, f'{base_path}/Percent Impervious', ['Percent Impervious'])
 
             return cell_classifications, face_classifications, percent_impervious
+
+    @classmethod
+    @log_call
+    def get_perimeter_data(
+        cls,
+        hdf_input: Union[str, Path],
+        area_name: Optional[str] = None,
+        ras_object=None
+    ) -> Optional[pd.DataFrame]:
+        """
+        Extract Perimeter Data from the HDF file.
+
+        Args:
+            hdf_input (Union[str, Path]): The plan number or full path to the HDF file.
+            area_name (Optional[str]): Name of the 2D Flow Area to extract data from.
+                If None, uses the first 2D Area Name found.
+            ras_object (RasPrj, optional): The RAS project object. If None, uses the global ras instance.
+
+        Returns:
+            Optional[pd.DataFrame]: DataFrame containing Perimeter Data
+
+        Example:
+            >>> perimeter_df = RasHdf.get_perimeter_data("path/to/file.hdf")
+            >>> if perimeter_df is not None:
+            ...     print(perimeter_df.head())
+            ... else:
+            ...     print("Perimeter data not found")
+        """
+        with h5py.File(cls._get_hdf_filename(hdf_input, ras_object), 'r') as hdf_file:
+            area_name = cls._get_area_name(hdf_file, area_name, hdf_file.filename)
+
+            perimeter_path = f'Geometry/2D Flow Areas/{area_name}/Perimeter'
+            perimeter_df = cls._extract_dataset(hdf_file, perimeter_path, ['X', 'Y'])
+
+            return perimeter_df
+
+    @classmethod
+    @log_call
+    def _get_area_name(cls, hdf_input: Union[str, Path], area_name: Optional[str] = None, ras_object=None) -> str:
+        """
+        Get the 2D Flow Area name from the HDF file.
+
+        Args:
+            hdf_input (Union[str, Path]): The plan number or full path to the HDF file.
+            area_name (Optional[str]): The provided area name, if any.
+            ras_object (RasPrj, optional): The RAS project object. If None, uses the global ras instance.
+
+        Returns:
+            str: The 2D Flow Area name.
+
+        Raises:
+            ValueError: If no 2D Flow Areas are found in the HDF file or if the specified area name is not found.
+        """
+        with h5py.File(cls._get_hdf_filename(hdf_input, ras_object), 'r') as hdf_file:
+            if area_name is None:
+                area_names = [name for name in hdf_file['Geometry/2D Flow Areas'].keys() if isinstance(hdf_file['Geometry/2D Flow Areas'][name], h5py.Group)]
+                if not area_names:
+                    raise ValueError("No 2D Flow Areas found in the HDF file")
+                area_name = area_names[0]
+            else:
+                if area_name not in hdf_file['Geometry/2D Flow Areas']:
+                    raise ValueError(f"2D Flow Area '{area_name}' not found in the HDF file")
+        return area_name
+
+    @classmethod
+    @log_call
+    def _extract_dataset(cls, hdf_input: Union[str, Path], dataset_path: str, column_names: List[str], ras_object=None) -> Optional[pd.DataFrame]:
+        """
+        Extract a dataset from the HDF file and convert it to a DataFrame.
+
+        Args:
+            hdf_input (Union[str, Path]): The plan number or full path to the HDF file.
+            dataset_path (str): The path to the dataset within the HDF file.
+            column_names (List[str]): The names to assign to the DataFrame columns.
+            ras_object (RasPrj, optional): The RAS project object. If None, uses the global ras instance.
+
+        Returns:
+            Optional[pd.DataFrame]: The extracted data as a DataFrame, or None if the dataset is not found.
+        """
+        with h5py.File(cls._get_hdf_filename(hdf_input, ras_object), 'r') as hdf_file:
+            try:
+                dataset = hdf_file[dataset_path][()]
+                df = pd.DataFrame(dataset, columns=column_names)
+                return df
+            except KeyError:
+                return None
+
+    @classmethod
+    @log_call
+    def read_hdf_to_dataframe(cls, hdf_input: Union[str, Path], dataset_path: str, fill_value: Union[int, float, str] = -9999, ras_object=None) -> pd.DataFrame:
+        """
+        Reads an HDF5 dataset and converts it into a pandas DataFrame, handling byte strings and missing values.
+
+        Args:
+            hdf_input (Union[str, Path]): Path to the HDF file or plan number.
+            dataset_path (str): Path to the dataset within the HDF file.
+            fill_value (Union[int, float, str], optional): The value to use for filling missing data. Defaults to -9999.
+            ras_object (RasPrj, optional): The RAS project object. If None, uses the global ras instance.
+
+        Returns:
+            pd.DataFrame: The resulting DataFrame with byte strings decoded and missing values replaced.
+
+        Raises:
+            KeyError: If the dataset is not found in the HDF file.
+        """
+        with h5py.File(cls._get_hdf_filename(hdf_input, ras_object), 'r') as hdf_file:
+            try:
+                hdf_dataset = hdf_file[dataset_path]
+                hdf_dataframe = cls.convert_to_dataframe_array(hdf_dataset)
+                byte_columns = [col for col in hdf_dataframe.columns if isinstance(hdf_dataframe[col].iloc[0], (bytes, bytearray))]
+                
+                hdf_dataframe[byte_columns] = hdf_dataframe[byte_columns].applymap(lambda x: x.decode('utf-8') if isinstance(x, (bytes, bytearray)) else x)
+                hdf_dataframe = hdf_dataframe.replace({fill_value: np.NaN})
+                
+                return hdf_dataframe
+            except KeyError:
+                raise
+        
+    @classmethod
+    @log_call
+    def get_group_attributes_as_df(cls, hdf_input: Union[str, Path], group_path: str, ras_object=None) -> pd.DataFrame:
+        """
+        Convert attributes inside a given HDF group to a DataFrame.
+
+        Args:
+            hdf_input (Union[str, Path]): Path to the HDF file or plan number.
+            group_path (str): Path of the group in the HDF file.
+            ras_object (RasPrj, optional): The RAS project object. If None, uses the global ras instance.
+
+        Returns:
+            pd.DataFrame: DataFrame of all attributes in the specified group with their properties.
+
+        Raises:
+            KeyError: If the specified group_path is not found in the file.
+
+        Example:
+            >>> attributes_df = RasHdf.get_group_attributes_as_df("path/to/file.hdf", "/Results/Unsteady/Output")
+            >>> print(attributes_df.head())
+        """
+        hdf_filename = cls._get_hdf_filename(hdf_input, ras_object)
+        
+        with h5py.File(hdf_filename, 'r') as hdf_file:
+            try:
+                group = hdf_file[group_path]
+                attributes = []
+                for attr in group.attrs:
+                    value = group.attrs[attr]
+                    attr_info = {
+                        'Attribute': attr,
+                        'Value': value,
+                        'Type': type(value).__name__,
+                        'Shape': value.shape if isinstance(value, np.ndarray) else None,
+                        'Size': value.size if isinstance(value, np.ndarray) else None,
+                        'Dtype': value.dtype if isinstance(value, np.ndarray) else None
+                    }
+                    if isinstance(value, bytes):
+                        attr_info['Value'] = value.decode('utf-8')
+                    elif isinstance(value, np.ndarray):
+                        if value.dtype.kind == 'S':
+                            attr_info['Value'] = [v.decode('utf-8') for v in value]
+                        elif value.dtype.kind in ['i', 'f', 'u']:
+                            attr_info['Value'] = value.tolist()
+                    attributes.append(attr_info)
+                
+                return pd.DataFrame(attributes)
+            except KeyError:
+                logger.critical(f"Group path '{group_path}' not found in HDF file '{hdf_filename}'")
+
+    # Last functions from PyHMT2D:
+
+    from ras_commander.logging_config import log_call
+
+    @classmethod
+    @log_call
+    def get_2d_area_solution_times(cls, hdf_input: Union[str, Path], area_name: Optional[str] = None, ras_object=None) -> Optional[np.ndarray]:
+        """
+        Retrieve solution times for a specified 2D Flow Area.
+        
+        Args:
+            hdf_input (Union[str, Path]): The plan number or full path to the HDF file.
+            area_name (Optional[str]): Name of the 2D Flow Area. If None, uses the first area found.
+            ras_object (RasPrj, optional): The RAS project object. If None, uses the global ras instance.
+        
+        Returns:
+            Optional[np.ndarray]: Array of solution times, or None if not found.
+        
+        Example:
+            >>> solution_times = RasHdf.get_2d_area_solution_times("03", area_name="Area1")
+            >>> print(solution_times)
+            [0.0, 0.5, 1.0, ...]
+        """
+        with h5py.File(cls._get_hdf_filename(hdf_input, ras_object), 'r') as hdf_file:
+            try:
+                solution_times = np.array(
+                    hdf_file['Results']['Unsteady']['Output']['Output Blocks']
+                    ['Base Output']['Unsteady Time Series']['Time']
+                )
+                return solution_times
+            except KeyError:
+                return None
+
+    @classmethod
+    @log_call
+    def get_2d_area_solution_time_dates(cls, hdf_input: Union[str, Path], area_name: Optional[str] = None, ras_object=None) -> Optional[np.ndarray]:
+        """
+        Retrieve solution time dates for a specified 2D Flow Area.
+        
+        Args:
+            hdf_input (Union[str, Path]): The plan number or full path to the HDF file.
+            area_name (Optional[str]): Name of the 2D Flow Area. If None, uses the first area found.
+            ras_object (RasPrj, optional): The RAS project object. If None, uses the global ras instance.
+        
+        Returns:
+            Optional[np.ndarray]: Array of solution time dates, or None if not found.
+        
+        Example:
+            >>> solution_time_dates = RasHdf.get_2d_area_solution_time_dates("03", area_name="Area1")
+            >>> print(solution_time_dates)
+            ['2024-01-01T00:00:00', '2024-01-01T00:30:00', ...]
+        """
+        with h5py.File(cls._get_hdf_filename(hdf_input, ras_object), 'r') as hdf_file:
+            try:
+                solution_time_dates = np.array(
+                    hdf_file['Results']['Unsteady']['Output']['Output Blocks']
+                    ['Base Output']['Unsteady Time Series']['Time Date Stamp']
+                )
+                return solution_time_dates
+            except KeyError:
+                return None
+
+    @classmethod
+    @log_call
+    def load_2d_area_solutions(
+        cls,
+        hdf_file: h5py.File,
+        ras_object=None
+    ) -> Optional[Dict[str, pd.DataFrame]]:
+        """
+        Load 2D Area Solutions (Water Surface Elevation and Face Normal Velocity) from the HDF file
+        and provide them as pandas DataFrames.
+
+        **Note:** 
+            - This function has only been tested with HEC-RAS version 6.5.
+            - Ensure that the HDF file structure matches the expected paths.
+
+        Args:
+            hdf_file (h5py.File): An open HDF5 file object.
+            ras_object (RasPrj, optional): The RAS project object. If None, uses the global ras instance.
+
+        Returns:
+            Optional[Dict[str, pd.DataFrame]]: A dictionary containing:
+                - 'solution_times': DataFrame of solution times.
+                - For each 2D Flow Area:
+                    - '{Area_Name}_WSE': Water Surface Elevation DataFrame.
+                    - '{Area_Name}_Face_Velocity': Face Normal Velocity DataFrame.
+        """
+        try:
+            solution_times_path = '/Results/Unsteady/Output/Output Blocks/Base Output/Unsteady Time Series/Time'
+            if solution_times_path not in hdf_file:
+                return None
+
+            solution_times = hdf_file[solution_times_path][()]
+            solution_times_df = pd.DataFrame({
+                'Time_Step': solution_times
+            })
+
+            solutions_dict = {
+                'solution_times': solution_times_df
+            }
+
+            two_d_area_names = cls.get_2d_flow_area_names(hdf_file, ras_object=ras_object)
+            if not two_d_area_names:
+                return solutions_dict
+
+            for area in two_d_area_names:
+                wse_path = f'/Results/Unsteady/Output/Output Blocks/Base Output/Unsteady Time Series/2D Flow Areas/{area}/Water Surface'
+                face_velocity_path = f'/Results/Unsteady/Output/Output Blocks/Base Output/Unsteady Time Series/2D Flow Areas/{area}/Face Velocity'
+
+                if wse_path not in hdf_file:
+                    continue
+
+                wse_data = hdf_file[wse_path][()]
+                cell_center_coords_path = f'/Geometry/2D Flow Areas/{area}/Cell Center Coordinate'
+                if cell_center_coords_path not in hdf_file:
+                    continue
+
+                cell_center_coords = hdf_file[cell_center_coords_path][()]
+                if cell_center_coords.shape[0] != wse_data.shape[1]:
+                    continue
+
+                wse_df = pd.DataFrame({
+                    'Time_Step': np.repeat(solution_times, wse_data.shape[1]),
+                    'Cell_ID': np.tile(np.arange(wse_data.shape[1]), wse_data.shape[0]),
+                    'X': cell_center_coords[:, 0].repeat(wse_data.shape[0]),
+                    'Y': cell_center_coords[:, 1].repeat(wse_data.shape[0]),
+                    'WSE': wse_data.flatten()
+                })
+                solutions_dict[f'{area}_WSE'] = wse_df
+
+                if face_velocity_path not in hdf_file:
+                    continue
+
+                face_velocity_data = hdf_file[face_velocity_path][()]
+                face_center_coords_path = f'/Geometry/2D Flow Areas/{area}/Face Points Coordinates'
+                if face_center_coords_path not in hdf_file:
+                    continue
+
+                face_center_coords = hdf_file[face_center_coords_path][()]
+                if face_center_coords.shape[0] != face_velocity_data.shape[1]:
+                    continue
+
+                face_velocity_df = pd.DataFrame({
+                    'Time_Step': np.repeat(solution_times, face_velocity_data.shape[1]),
+                    'Face_ID': np.tile(np.arange(face_velocity_data.shape[1]), face_velocity_data.shape[0]),
+                    'X': face_center_coords[:, 0].repeat(face_velocity_data.shape[0]),
+                    'Y': face_center_coords[:, 1].repeat(face_velocity_data.shape[0]),
+                    'Normal_Velocity_ft_s': face_velocity_data.flatten()
+                })
+                solutions_dict[f'{area}_Face_Velocity'] = face_velocity_df
+
+            return solutions_dict
+
+        except Exception as e:
+            return None
+
+    @classmethod
+    @log_call
+    def get_hdf_paths_with_properties(cls, hdf_input: Union[str, Path], ras_object=None) -> pd.DataFrame:
+        """
+        List all paths in the HDF file with their properties.
+
+        Args:
+            hdf_input (Union[str, Path]): The plan number or full path to the HDF file.
+            ras_object (RasPrj, optional): The RAS project object. If None, uses the global ras instance.
+
+        Returns:
+            pd.DataFrame: DataFrame of all paths and their properties in the HDF file.
+
+        Example:
+            >>> paths_df = RasHdf.get_hdf_paths_with_properties("path/to/file.hdf")
+            >>> print(paths_df.head())
+        """
+        with h5py.File(cls._get_hdf_filename(hdf_input, ras_object), 'r') as hdf_file:
+            paths = []
+            def visitor_func(name: str, node: h5py.Group) -> None:
+                path_info = {
+                    "HDF_Path": name,
+                    "Type": type(node).__name__,
+                    "Shape": getattr(node, "shape", None),
+                    "Size": getattr(node, "size", None),
+                    "Dtype": getattr(node, "dtype", None)
+                }
+                paths.append(path_info)
+            hdf_file.visititems(visitor_func)
+            return pd.DataFrame(paths)
+        
+    @classmethod
+    @log_call
+    def build_2d_area_face_hydraulic_information(cls, hdf_input: Union[str, Path, h5py.File], area_name: Optional[str] = None, ras_object=None) -> Optional[List[List[np.ndarray]]]:
+        """
+        Build face hydraulic information tables (elevation, area, wetted perimeter, Manning's n) for each face in 2D Flow Areas.
+        
+        Args:
+            hdf_input (Union[str, Path, h5py.File]): The HDF5 file path or open HDF5 file object.
+            area_name (Optional[str]): Name of the 2D Flow Area. If None, builds for all areas.
+            ras_object (RasPrj, optional): The RAS project object. If None, uses the global ras instance.
+        
+        Returns:
+            Optional[List[List[np.ndarray]]]: Nested lists containing hydraulic information for each face in each 2D Flow Area.
+        
+        Example:
+            >>> hydraulic_info = RasHdf.build_2d_area_face_hydraulic_information("03")
+            >>> print(hydraulic_info[0][0])  # First face of first area
+            [[Elevation1, Area1, WettedPerim1, ManningN1],
+             [Elevation2, Area2, WettedPerim2, ManningN2],
+             ...]
+        """
+        try:
+            ras_obj = ras_object if ras_object is not None else ras
+            with h5py.File(cls._get_hdf_filename(hdf_input, ras_obj), 'r') as hdf_file:
+                two_d_area_names = cls.get_2d_flow_area_names(hdf_file, ras_object=ras_object)
+                hydraulic_info_table = []
+
+                for area in two_d_area_names:
+                    face_elev_info = np.array(hdf_file[f'Geometry/2D Flow Areas/{area}/Faces Area Elevation Info'])
+                    face_elev_values = np.array(hdf_file[f'Geometry/2D Flow Areas/{area}/Faces Area Elevation Values'])
+                    
+                    area_hydraulic_info = []
+                    for face in face_elev_info:
+                        start_row, count = face
+                        face_data = face_elev_values[start_row:start_row + count].copy()
+                        area_hydraulic_info.append(face_data)
+                    
+                    hydraulic_info_table.append(area_hydraulic_info)
+
+                return hydraulic_info_table
+
+        except KeyError:
+            return None
+
+    @classmethod
+    @log_call
+    def build_2d_area_face_point_coordinates_list(cls, hdf_input: Union[str, Path, h5py.File], area_name: Optional[str] = None, ras_object=None) -> Optional[List[np.ndarray]]:
+        """
+        Build a list of face point coordinates for each 2D Flow Area.
+        
+        Args:
+            hdf_input (Union[str, Path, h5py.File]): The HDF5 file path or open HDF5 file object.
+            area_name (Optional[str]): Name of the 2D Flow Area. If None, builds for all areas.
+            ras_object (RasPrj, optional): The RAS project object. If None, uses the global ras instance.
+        
+        Returns:
+            Optional[List[np.ndarray]]: List containing arrays of face point coordinates for each 2D Flow Area.
+        
+        Example:
+            >>> face_coords_list = RasHdf.build_2d_area_face_point_coordinates_list("03")
+            >>> print(face_coords_list[0])  # Coordinates for first area
+            [[X1, Y1], [X2, Y2], ...]
+        """
+        try:
+            with h5py.File(cls._get_hdf_filename(hdf_input, ras_object), 'r') as hdf_file:
+                two_d_area_names = cls.get_2d_flow_area_names(hdf_file, ras_object=ras_object)
+                face_point_coords_list = []
+
+                for area in two_d_area_names:
+                    face_points = np.array(hdf_file[f'Geometry/2D Flow Areas/{area}/Face Points Coordinates'])
+                    face_point_coords_list.append(face_points)
+
+                return face_point_coords_list
+
+        except KeyError:
+            return None
+
+    @classmethod
+    @log_call
+    def build_2d_area_face_profile(cls, hdf_input: Union[str, Path, h5py.File], area_name: Optional[str] = None, ras_object=None, n_face_profile_points: int = 10) -> Optional[List[np.ndarray]]:
+        """
+        Build face profiles representing sub-grid terrain for each face in 2D Flow Areas.
+        
+        Args:
+            hdf_input (Union[str, Path, h5py.File]): The HDF5 file path or open HDF5 file object.
+            area_name (Optional[str]): Name of the 2D Flow Area. If None, builds for all areas.
+            ras_object (RasPrj, optional): The RAS project object. If None, uses the global ras instance.
+            n_face_profile_points (int): Number of points to interpolate along each face profile.
+        
+        Returns:
+            Optional[List[np.ndarray]]: List containing arrays of profile points for each face in each 2D Flow Area.
+        
+        Example:
+            >>> face_profiles = RasHdf.build_2d_area_face_profile("03", n_face_profile_points=20)
+            >>> print(face_profiles[0][0])  # Profile points for first face of first area
+            [[X1, Y1, Z1], [X2, Y2, Z2], ...]
+        """
+        try:
+            with h5py.File(cls._get_hdf_filename(hdf_input, ras_object), 'r') as hdf_file:
+                two_d_area_names = cls.get_2d_flow_area_names(hdf_file, ras_object=ras_object)
+                face_profiles = []
+
+                for area in two_d_area_names:
+                    face_faces = np.array(hdf_file[f'Geometry/2D Flow Areas/{area}/Faces FacePoint Indexes'])
+                    face_point_coords = np.array(hdf_file[f'Geometry/2D Flow Areas/{area}/Face Points Coordinates'])
+                    profile_points_all_faces = []
+
+                    for face in face_faces:
+                        face_start, face_end = face
+                        start_coords = face_point_coords[face_start]
+                        end_coords = face_point_coords[face_end]
+                        
+                        length = cls.horizontal_distance(start_coords, end_coords)
+                        stations = np.linspace(0, length, n_face_profile_points, endpoint=True)
+                        
+                        interpolated_points = np.array([
+                            start_coords + (end_coords - start_coords) * i / (n_face_profile_points - 1)
+                            for i in range(n_face_profile_points)
+                        ])
+                        
+                        interpolated_points = cls.interpolate_z_coords(interpolated_points)
+                        
+                        profile_points_all_faces.append(interpolated_points)
+
+                    face_profiles.append(profile_points_all_faces)
+
+                return face_profiles
+
+        except KeyError as e:
+            logging.error(f"Error building face profiles: {e}")
+            return None
+
+    @classmethod
+    @log_call
+    def build_face_facepoints(cls, hdf_input: Union[str, Path], area_name: Optional[str] = None, ras_object=None) -> Optional[List[np.ndarray]]:
+        """
+        Build face's facepoint list for each 2D Flow Area.
+        
+        Args:
+            hdf_input (Union[str, Path]): The plan number or full path to the HDF file.
+            area_name (Optional[str]): Name of the 2D Flow Area. If None, builds for all areas.
+            ras_object (RasPrj, optional): The RAS project object. If None, uses the global ras instance.
+        
+        Returns:
+            Optional[List[np.ndarray]]: List containing arrays of face point indexes for each face in each 2D Flow Area.
+        
+        Example:
+            >>> face_facepoints = RasHdf.build_face_facepoints("03")
+            >>> print(face_facepoints[0][0])  # FacePoint indexes for first face of first area
+            [start_idx, end_idx]
+        """
+        try:
+            with h5py.File(cls._get_hdf_filename(hdf_input, ras_object), 'r') as hdf_file:
+                two_d_area_names = cls.get_2d_flow_area_names(hdf_file, ras_object=ras_object)
+                face_facepoints_list = []
+
+                for area in two_d_area_names:
+                    face_facepoints = np.array(hdf_file[f'Geometry/2D Flow Areas/{area}/Faces FacePoint Indexes'])
+                    face_facepoints_list.append(face_facepoints)
+
+                return face_facepoints_list
+
+        except KeyError as e:
+            logger = logging.getLogger(__name__)
+            logger.error(f"Error building face facepoints list: {e}")
+            return None
+
+    @classmethod
+    @log_call
+    def build_2d_area_boundaries(cls, hdf_input: Union[str, Path], area_name: Optional[str] = None, ras_object=None) -> Optional[Tuple[int, np.ndarray, List[str], List[str], List[str], np.ndarray, np.ndarray]]:
+        """
+        Build boundaries with their point lists for each 2D Flow Area.
+        
+        Args:
+            hdf_input (Union[str, Path]): The plan number or full path to the HDF file.
+            area_name (Optional[str]): Name of the 2D Flow Area. If None, builds for all areas.
+            ras_object (RasPrj, optional): The RAS project object. If None, uses the global ras instance.
+        
+        Returns:
+            Optional[Tuple[int, np.ndarray, List[str], List[str], List[str], np.ndarray, np.ndarray]]:
+                Tuple containing total boundaries, boundary IDs, boundary names, associated 2D Flow Area names, boundary types,
+                total points per boundary, and boundary point lists.
+        
+        Example:
+            >>> total_boundaries, boundary_ids, boundary_names, flow_area_names, boundary_types, total_points, boundary_points = RasHdf.build_2d_area_boundaries("03")
+            >>> print(total_boundaries)
+            5
+        """
+        try:
+            with h5py.File(cls._get_hdf_filename(hdf_input, ras_object), 'r') as hdf_file:
+                two_d_area_names = cls.get_2d_flow_area_names(hdf_file, ras_object=ras_object)
+                total_boundaries = 0
+                boundary_ids = []
+                boundary_names = []
+                flow_area_names = []
+                boundary_types = []
+                total_points_per_boundary = []
+                boundary_points_list = []
+
+                for area in two_d_area_names:
+                    boundary_points = np.array(hdf_file[f'Geometry/2D Flow Areas/{area}/Boundary Points'])
+                    if boundary_points.size == 0:
+                        logger = logging.getLogger(__name__)
+                        logger.warning(f"No boundary points found for 2D Flow Area: {area}")
+                        continue
+
+                    current_boundary_id = boundary_points[0][0]
+                    current_boundary_points = [boundary_points[0][2], boundary_points[0][3]]
+                    boundary_id = current_boundary_id
+
+                    for point in boundary_points[1:]:
+                        if point[0] == current_boundary_id:
+                            current_boundary_points.append(point[3])
+                        else:
+                            # Save the completed boundary
+                            boundary_ids.append(current_boundary_id)
+                            boundary_names.append(point[0])  # Assuming boundary name is stored here
+                            flow_area_names.append(area)
+                            boundary_types.append(point[2])  # Assuming boundary type is stored here
+                            total_points_per_boundary.append(len(current_boundary_points))
+                            boundary_points_list.append(np.array(current_boundary_points))
+                            total_boundaries += 1
+
+                            # Start a new boundary
+                            current_boundary_id = point[0]
+                            current_boundary_points = [point[2], point[3]]
+
+                    # Save the last boundary
+                    boundary_ids.append(current_boundary_id)
+                    boundary_names.append(boundary_points[-1][0])  # Assuming boundary name is stored here
+                    flow_area_names.append(area)
+                    boundary_types.append(boundary_points[-1][2])  # Assuming boundary type is stored here
+                    total_points_per_boundary.append(len(current_boundary_points))
+                    boundary_points_list.append(np.array(current_boundary_points))
+                    total_boundaries += 1
+
+                return (total_boundaries, np.array(boundary_ids), boundary_names, flow_area_names, boundary_types, np.array(total_points_per_boundary), np.array(boundary_points_list))
+
+        except KeyError as e:
+            logger = logging.getLogger(__name__)
+            logger.error(f"Error building boundaries: {e}")
+            return None
+
+    # Helper Methods for New Functionalities
+
+    @classmethod
+    @log_call
+    def horizontal_distance(cls, coord1: np.ndarray, coord2: np.ndarray) -> float:
+        """
+        Calculate the horizontal distance between two coordinate points.
+        
+        Args:
+            coord1 (np.ndarray): First coordinate point [X, Y].
+            coord2 (np.ndarray): Second coordinate point [X, Y].
+        
+        Returns:
+            float: Horizontal distance.
+        
+        Example:
+            >>> distance = RasHdf.horizontal_distance([0, 0], [3, 4])
+            >>> print(distance)
+            5.0
+        """
+        return np.linalg.norm(coord2 - coord1)
+
+    @classmethod
+    @log_call
+    def interpolate_z_coords(cls, points: np.ndarray) -> np.ndarray:
+        """
+        Interpolate Z coordinates for a set of points.
+        
+        Args:
+            points (np.ndarray): Array of points with [X, Y].
+        
+        Returns:
+            np.ndarray: Array of points with [X, Y, Z].
+        
+        Example:
+            >>> interpolated = RasHdf.interpolate_z_coords(np.array([[0,0], [1,1]]))
+            >>> print(interpolated)
+            [[0, 0, Z0],
+             [1, 1, Z1]]
+        """
+        # Placeholder for actual interpolation logic
+        # This should be replaced with the appropriate interpolation method
+        z_coords = np.zeros((points.shape[0], 1))  # Assuming Z=0 for simplicity
+        return np.hstack((points, z_coords))
+
+    @classmethod
+    @log_call
+    def extract_string_from_hdf(
+        cls,
+        hdf_input: Union[str, Path],
+        hdf_path: str,
+        ras_object: Optional["RasPrj"] = None
+    ) -> str:
+        """
+        Extract string from HDF object at a given path.
+
+        Args:
+            hdf_input (Union[str, Path]): Either the plan number or the full path to the HDF file.
+            hdf_path (str): Path of the object in the HDF file.
+            ras_object (Optional["RasPrj"]): Specific RAS object to use. If None, uses the global ras instance.
+
+        Returns:
+            str: Extracted string from the specified HDF object.
+
+        Raises:
+            ValueError: If no HDF file is found for the given plan number.
+            FileNotFoundError: If the specified HDF file does not exist.
+            KeyError: If the specified hdf_path is not found in the file.
+
+        Example:
+            >>> result = RasHdf.extract_string_from_hdf("path/to/file.hdf", "/Results/Summary/Compute Messages (text)")
+            >>> print(result)
+        """
+        with h5py.File(cls._get_hdf_filename(hdf_input, ras_object), 'r') as hdf_file:
+            try:
+                hdf_object = hdf_file[hdf_path]
+                if isinstance(hdf_object, h5py.Group):
+                    return f"Group: {hdf_path}\nContents: {list(hdf_object.keys())}"
+                elif isinstance(hdf_object, h5py.Dataset):
+                    data = hdf_object[()]
+                    if isinstance(data, bytes):
+                        return data.decode('utf-8')
+                    elif isinstance(data, np.ndarray) and data.dtype.kind == 'S':
+                        return [v.decode('utf-8') for v in data]
+                    else:
+                        return str(data)
+                else:
+                    return f"Unsupported object type: {type(hdf_object)}"
+            except KeyError:
+                logger = logging.getLogger(__name__)
+                logger.error(f"Path not found: {hdf_path}")
+                raise KeyError(f"Path not found: {hdf_path}")
+
+    @classmethod
+    @log_call
+    def decode_byte_strings(dataframe: pd.DataFrame) -> pd.DataFrame:
+        """
+        Decodes byte strings in a DataFrame to regular string objects.
+
+        This function converts columns with byte-encoded strings (e.g., b'string') into UTF-8 decoded strings.
+
+        Args:
+            dataframe (pd.DataFrame): The DataFrame containing byte-encoded string columns.
+
+        Returns:
+            pd.DataFrame: The DataFrame with byte strings decoded to regular strings.
+
+        Example:
+            >>> df = pd.DataFrame({'A': [b'hello', b'world'], 'B': [1, 2]})
+            >>> decoded_df = RasHdf.decode_byte_strings(df)
+            >>> print(decoded_df)
+                A  B
+            0  hello  1
+            1  world  2
+        """
+        str_df = dataframe.select_dtypes(['object'])
+        str_df = str_df.stack().str.decode('utf-8').unstack()
+        for col in str_df:
+            dataframe[col] = str_df[col]
+        return dataframe
+
+    @classmethod
+    @log_call
+    def perform_kdtree_query(
+        reference_points: np.ndarray,
+        query_points: np.ndarray,
+        max_distance: float = 2.0
+    ) -> np.ndarray:
+        """
+        Performs a KDTree query between two datasets and returns indices with distances exceeding max_distance set to -1.
+
+        Args:
+            reference_points (np.ndarray): The reference dataset for KDTree.
+            query_points (np.ndarray): The query dataset to search against KDTree of reference_points.
+            max_distance (float, optional): The maximum distance threshold. Indices with distances greater than this are set to -1. Defaults to 2.0.
+
+        Returns:
+            np.ndarray: Array of indices from reference_points that are nearest to each point in query_points. 
+                        Indices with distances > max_distance are set to -1.
+
+        Example:
+            >>> ref_points = np.array([[0, 0], [1, 1], [2, 2]])
+            >>> query_points = np.array([[0.5, 0.5], [3, 3]])
+            >>> result = RasHdf.perform_kdtree_query(ref_points, query_points)
+            >>> print(result)
+            array([ 0, -1])
+        """
+        dist, snap = KDTree(reference_points).query(query_points, distance_upper_bound=max_distance)
+        snap[dist > max_distance] = -1
+        return snap
+
+    @classmethod
+    @log_call
+    def find_nearest_neighbors(points: np.ndarray, max_distance: float = 2.0) -> np.ndarray:
+        """
+        Creates a self KDTree for dataset points and finds nearest neighbors excluding self, 
+        with distances above max_distance set to -1.
+
+        Args:
+            points (np.ndarray): The dataset to build the KDTree from and query against itself.
+            max_distance (float, optional): The maximum distance threshold. Indices with distances 
+                                            greater than max_distance are set to -1. Defaults to 2.0.
+
+        Returns:
+            np.ndarray: Array of indices representing the nearest neighbor in points for each point in points. 
+                        Indices with distances > max_distance or self-matches are set to -1.
+
+        Example:
+            >>> points = np.array([[0, 0], [1, 1], [2, 2], [10, 10]])
+            >>> result = RasHdf.find_nearest_neighbors(points)
+            >>> print(result)
+            array([1, 0, 1, -1])
+        """
+        dist, snap = KDTree(points).query(points, k=2, distance_upper_bound=max_distance)
+        snap[dist > max_distance] = -1
+        
+        snp = pd.DataFrame(snap, index=np.arange(len(snap)))
+        snp = snp.replace(-1, np.nan)
+        snp.loc[snp[0] == snp.index, 0] = np.nan
+        snp.loc[snp[1] == snp.index, 1] = np.nan
+        filled = snp[0].fillna(snp[1])
+        snapped = filled.fillna(-1).astype(np.int64).to_numpy()
+        return snapped
+
+    @classmethod
+    @log_call
+    def consolidate_dataframe(
+        dataframe: pd.DataFrame,
+        group_by: Optional[Union[str, List[str]]] = None,
+        pivot_columns: Optional[Union[str, List[str]]] = None,
+        level: Optional[int] = None,
+        n_dimensional: bool = False,
+        aggregation_method: Union[str, Callable] = 'list'
+    ) -> pd.DataFrame:
+        """
+        Consolidate rows in a DataFrame by merging duplicate values into lists or using a specified aggregation function.
+
+        Args:
+            dataframe (pd.DataFrame): The DataFrame to consolidate.
+            group_by (Optional[Union[str, List[str]]]): Columns or indices to group by.
+            pivot_columns (Optional[Union[str, List[str]]]): Columns to pivot.
+            level (Optional[int]): Level of multi-index to group by.
+            n_dimensional (bool): If True, use a pivot table for N-Dimensional consolidation.
+            aggregation_method (Union[str, Callable]): Aggregation method, e.g., 'list' to aggregate into lists.
+
+        Returns:
+            pd.DataFrame: The consolidated DataFrame.
+
+        Example:
+            >>> df = pd.DataFrame({'A': [1, 1, 2], 'B': [4, 5, 6], 'C': [7, 8, 9]})
+            >>> result = RasHdf.consolidate_dataframe(df, group_by='A')
+            >>> print(result)
+            B         C
+            A            
+            1  [4, 5]  [7, 8]
+            2  [6]     [9]
+        """
+        if aggregation_method == 'list':
+            agg_func = lambda x: tuple(x)
+        else:
+            agg_func = aggregation_method
+
+        if n_dimensional:
+            result = dataframe.pivot_table(group_by, pivot_columns, aggfunc=agg_func)
+        else:
+            result = dataframe.groupby(group_by, level=level).agg(agg_func).applymap(list)
+
+        return result
+    
+    @classmethod
+    @log_call
+    def find_nearest_value(array: Union[list, np.ndarray], target_value: Union[int, float]) -> Union[int, float]:
+        """
+        Finds the nearest value in a NumPy array to the specified target value.
+
+        Args:
+            array (Union[list, np.ndarray]): The array to search within.
+            target_value (Union[int, float]): The value to find the nearest neighbor to.
+
+        Returns:
+            Union[int, float]: The nearest value in the array to the specified target value.
+
+        Example:
+            >>> arr = np.array([1, 3, 5, 7, 9])
+            >>> result = RasHdf.find_nearest_value(arr, 6)
+            >>> print(result)
+            5
+        """
+        array = np.asarray(array)
+        idx = (np.abs(array - target_value)).argmin()
+        return array[idx]
+    
+    @staticmethod
+    @log_call
+    def _get_hdf_filename(hdf_input: Union[str, Path, h5py.File], ras_object=None) -> Optional[Path]:
+        """
+        Get the HDF filename from the input.
+
+        Args:
+            hdf_input (Union[str, Path, h5py.File]): The plan number, full path to the HDF file as a string, a Path object, or an h5py.File object.
+            ras_object (RasPrj, optional): The RAS project object. If None, uses the global ras instance.
+
+        Returns:
+            Optional[Path]: The full path to the HDF file as a Path object, or None if an error occurs.
+
+        Note:
+            This method logs critical errors instead of raising exceptions.
+        """
+
+        # If hdf_input is already an h5py.File object, return its filename
+        if isinstance(hdf_input, h5py.File):
+            return Path(hdf_input.filename)
+
+        # Convert to Path object if it's a string
+        if isinstance(hdf_input, str):
+            hdf_input = Path(hdf_input)
+
+        # If hdf_input is a file path, return it directly
+        if isinstance(hdf_input, Path) and hdf_input.is_file():
+            return hdf_input
+
+        # If hdf_input is not a file path, assume it's a plan number and require ras_object
+        ras_obj = ras_object or ras
+        if not ras_obj.initialized:
+            logger.critical("ras_object is not initialized. ras_object is required when hdf_input is not a direct file path.")
+            return None
+
+        plan_info = ras_obj.plan_df[ras_obj.plan_df['plan_number'] == str(hdf_input)]
+        if plan_info.empty:
+            logger.critical(f"No HDF file found for plan number {hdf_input}")
+            return None
+
+        hdf_filename = plan_info.iloc[0]['HDF_Results_Path']
+        if hdf_filename is None:
+            logger.critical(f"HDF_Results_Path is None for plan number {hdf_input}")
+            return None
+
+        hdf_path = Path(hdf_filename)
+        if not hdf_path.is_file():
+            logger.critical(f"HDF file not found: {hdf_path}")
+            return None
+
+        return hdf_path
+
+
+
+@log_call
+def save_dataframe_to_hdf(
+    dataframe: pd.DataFrame,
+    hdf_parent_group: h5py.Group,
+    dataset_name: str,
+    attributes: Optional[Dict[str, Union[int, float, str]]] = None,
+    fill_value: Union[int, float, str] = -9999,
+    **kwargs: Any
+) -> h5py.Dataset:
+    """
+    Save a pandas DataFrame to an HDF5 dataset within a specified parent group.
+
+    This function addresses limitations of `pd.to_hdf()` by using h5py to create and save datasets.
+
+    Args:
+        dataframe (pd.DataFrame): The DataFrame to save.
+        hdf_parent_group (h5py.Group): The parent HDF5 group where the dataset will be created.
+        dataset_name (str): The name of the new dataset to add in the HDF5 parent group.
+        attributes (Optional[Dict[str, Union[int, float, str]]]): A dictionary of attributes to add to the dataset.
+        fill_value (Union[int, float, str]): The value to use for filling missing data.
+        **kwargs: Additional keyword arguments passed to `hdf_parent_group.create_dataset()`.
+
+    Returns:
+        h5py.Dataset: The created HDF5 dataset within the parent group.
+
+    Raises:
+        ValueError: If the DataFrame columns are not consistent.
+
+    Example:
+        >>> df = pd.DataFrame({'A': [1, 2, 3], 'B': ['a', 'b', 'c']})
+        >>> with h5py.File('data.h5', 'w') as f:
+        ...     group = f.create_group('my_group')
+        ...     dataset = save_dataframe_to_hdf(df, group, 'my_dataset')
+        >>> print(dataset)
+    """
+    df = dataframe.copy()
+
+    # Replace '/' in column names with '-' to avoid issues in HDF5
+    if df.columns.dtype == 'O':
+        df.columns = df.columns.str.replace('/', '-', regex=False)
+    
+    # Fill missing values with the specified fill_value
+    df = df.fillna(fill_value)
+    
+    # Identify string columns and ensure consistency
+    string_cols = df.select_dtypes(include=['object']).columns
+    if not string_cols.equals(df.select_dtypes(include=['object']).columns):
+        logger.error("Inconsistent string columns detected")
+        raise ValueError("Inconsistent string columns detected")
+    
+    # Encode string columns to bytes
+    df[string_cols] = df[string_cols].applymap(lambda x: x.encode('utf-8')).astype('bytes')
+
+    # Prepare data for HDF5 dataset creation
+    arr = df.to_records(index=False) if not isinstance(df.columns, pd.RangeIndex) else df.values
+    
+    # Remove existing dataset if it exists
+    if dataset_name in hdf_parent_group:
+        logger.warning(f"Existing dataset {dataset_name} will be overwritten")
+        del hdf_parent_group[dataset_name]
+    
+    # Create the dataset in the HDF5 file
+    dataset = hdf_parent_group.create_dataset(dataset_name, data=arr, **kwargs)
+    
+    # Update dataset attributes if provided
+    if attributes:
+        dataset.attrs.update(attributes)
+    
+    logger.info(f"Successfully saved DataFrame to dataset: {dataset_name}")
+    return dataset

{ras_commander-0.41.0.dist-info → ras_commander-0.42.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ras-commander
-Version: 0.41.0
+Version: 0.42.0
 Summary: A Python library for automating HEC-RAS operations
 Home-page: https://github.com/billk-FM/ras-commander
 Author: William M. Katzenmeyer

{ras_commander-0.41.0.dist-info → ras_commander-0.42.0.dist-info}/RECORD

@@ -2,15 +2,15 @@ ras_commander/RasCmdr.py,sha256=_opzPdFuja2wXmFu2iayP6igJqGeILAavPC1XsCC6ks,2501
 ras_commander/RasExamples.py,sha256=XKnbqQTc5t43iFkjJLF3lgqZW4YaGh-79sGYDAmtqiU,19245
 ras_commander/RasGeo.py,sha256=GiRtgRg0JsuCDkpYS6SkJoaLksPUskHGDRpJLYVUMz8,5411
 ras_commander/RasGpt.py,sha256=-524sU_PBPxCmjDKJbDXg6Q3k1-Uhk2tYj6HeW8QFJ8,4201
-ras_commander/RasHdf.py,sha256=Und1QcOpuHD2dCZvxPiwNXCoEQs_XG9WFGBlNwMDDrE,32689
+ras_commander/RasHdf.py,sha256=K5apgOaHRqiOrrzZvAEMUbLmw7LWmW18bDk3JCy2z6c,77160
 ras_commander/RasPlan.py,sha256=GT8-2X_Or6ufrfpQPv6G3WMLuTNsOO0OCYh1jrbsqZ0,40303
 ras_commander/RasPrj.py,sha256=-iEltmz7B-wXrs4R3iuj6tXX9i-6u_yEl7ZcLmasoWs,33980
 ras_commander/RasUnsteady.py,sha256=37GKaYNJZ39y-khhy01LbHwZnf7HT0V2XKQ-UUaJHlY,4639
 ras_commander/RasUtils.py,sha256=vA3DzvNMeKH3A4cMQLK2a3dihftXBGypYvoi-ckMlSs,29480
 ras_commander/__init__.py,sha256=h4xld8gpvjTTpOOJcPKXwsRMUVGtg8tRqf64AHwZB3k,1051
 ras_commander/logging_config.py,sha256=5bYd_5KMlf81bXsiu2mABBlw0USMhcu5uRv8DIYJSFE,2317
-ras_commander-0.41.0.dist-info/LICENSE,sha256=_pbd6qHnlsz1iQ-ozDW_49r86BZT6CRwO2iBtw0iN6M,457
-ras_commander-0.41.0.dist-info/METADATA,sha256=wYlsP7QFa-lYa5CUKg8Mbi6VFwojfJm_l1GK_TVgCew,15671
-ras_commander-0.41.0.dist-info/WHEEL,sha256=GV9aMThwP_4oNCtvEC2ec3qUYutgWeAzklro_0m4WJQ,91
-ras_commander-0.41.0.dist-info/top_level.txt,sha256=i76S7eKLFC8doKcXDl3aiOr9RwT06G8adI6YuKbQDaA,14
-ras_commander-0.41.0.dist-info/RECORD,,
+ras_commander-0.42.0.dist-info/LICENSE,sha256=_pbd6qHnlsz1iQ-ozDW_49r86BZT6CRwO2iBtw0iN6M,457
+ras_commander-0.42.0.dist-info/METADATA,sha256=9opk4wxJ_Qmaeiky2Ui1AP8zyCtfiy-l8Hzav_WnGPQ,15671
+ras_commander-0.42.0.dist-info/WHEEL,sha256=GV9aMThwP_4oNCtvEC2ec3qUYutgWeAzklro_0m4WJQ,91
+ras_commander-0.42.0.dist-info/top_level.txt,sha256=i76S7eKLFC8doKcXDl3aiOr9RwT06G8adI6YuKbQDaA,14
+ras_commander-0.42.0.dist-info/RECORD,,