ras-commander 0.33.0__py3-none-any.whl → 0.34.0__py3-none-any.whl

ras_commander/RasExamples.py

@@ -7,6 +7,16 @@ import shutil
 from typing import Union, List
 import csv
 from datetime import datetime
+import logging
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,  # Set the logging level to INFO
+    format='%(asctime)s - %(levelname)s - %(message)s',  # Log message format
+    handlers=[
+        logging.StreamHandler()  # Log to stderr
+    ]
+)
 
 class RasExamples:
     """
@@ -38,14 +48,12 @@ class RasExamples:
         folder_df (pd.DataFrame): DataFrame containing folder structure information.
         csv_file_path (Path): Path to the CSV file for caching project metadata.
 
-    
     Future Improvements:
     - Implement the ability for user-provided example projects (provided as a zip file) for their own repeatable examples. 
     - If the zip file is in the same folder structure as the HEC-RAS example projects, simple replace Example_Projects_6_5.zip and the folder structure will be automatically extracted from the zip file.
     - The actual RAS example projects haven't been updated much, but there is the structure here to handle future versions. Although this version of the code is probably fine for a few years, until HEC-RAS 2025 comes out. 
-       
     """
-
+    
     def __init__(self):
         """
         Initialize the RasExamples class.
@@ -54,7 +62,7 @@ class RasExamples:
         It initializes the base URL for downloads, valid versions, directory paths, and other essential
         attributes. It also creates the projects directory if it doesn't exist and loads the project data.
 
-        The method also prints the location of the example projects folder and calls _load_project_data()
+        The method also logs the location of the example projects folder and calls _load_project_data()
         to initialize the project data.
         """
         self.base_url = 'https://github.com/HydrologicEngineeringCenter/hec-downloads/releases/download/'
@@ -71,7 +79,7 @@ class RasExamples:
         self.csv_file_path = self.examples_dir / 'example_projects.csv'
 
         self.projects_dir.mkdir(parents=True, exist_ok=True)
-        print(f"Example projects folder: {self.projects_dir}")
+        logging.info(f"Example projects folder: {self.projects_dir}")
         self._load_project_data()
 
     def _load_project_data(self):
@@ -84,21 +92,29 @@ class RasExamples:
         self._find_zip_file()
         
         if not self.zip_file_path:
-            print("No example projects zip file found. Downloading...")
+            logging.info("No example projects zip file found. Downloading...")
             self.get_example_projects()
         
-        zip_modified_time = os.path.getmtime(self.zip_file_path)
+        try:
+            zip_modified_time = os.path.getmtime(self.zip_file_path)
+        except FileNotFoundError:
+            logging.error(f"Zip file not found at {self.zip_file_path}.")
+            return
         
         if self.csv_file_path.exists():
             csv_modified_time = os.path.getmtime(self.csv_file_path)
             
             if csv_modified_time >= zip_modified_time:
-                print("Loading project data from CSV...")
-                self.folder_df = pd.read_csv(self.csv_file_path)
-                print(f"Loaded {len(self.folder_df)} projects from CSV, use list_categories() and list_projects() to explore them")
+                logging.info("Loading project data from CSV...")
+                try:
+                    self.folder_df = pd.read_csv(self.csv_file_path)
+                    logging.info(f"Loaded {len(self.folder_df)} projects from CSV. Use list_categories() and list_projects() to explore them.")
+                except Exception as e:
+                    logging.error(f"Failed to read CSV file: {e}")
+                    self.folder_df = None
                 return
 
-        print("Extracting folder structure from zip file...")
+        logging.info("Extracting folder structure from zip file...")
         self._extract_folder_structure()
         self._save_to_csv()
 
@@ -108,8 +124,10 @@ class RasExamples:
             potential_zip = self.examples_dir / f"Example_Projects_{version.replace('.', '_')}.zip"
             if potential_zip.exists():
                 self.zip_file_path = potential_zip
-                print(f"Found zip file: {self.zip_file_path}")
+                logging.info(f"Found zip file: {self.zip_file_path}")
                 break
+        else:
+            logging.warning("No existing example projects zip file found.")
 
     def _extract_folder_structure(self):
         """
@@ -129,18 +147,25 @@ class RasExamples:
                         })
             
             self.folder_df = pd.DataFrame(folder_data).drop_duplicates()
-            print(f"Extracted {len(self.folder_df)} projects")
-            print("folder_df:")
-            display(self.folder_df)
+            logging.info(f"Extracted {len(self.folder_df)} projects.")
+            logging.debug(f"folder_df:\n{self.folder_df}")
+        except zipfile.BadZipFile:
+            logging.error(f"The file {self.zip_file_path} is not a valid zip file.")
+            self.folder_df = pd.DataFrame(columns=['Category', 'Project'])
         except Exception as e:
-            print(f"An error occurred while extracting the folder structure: {str(e)}")
+            logging.error(f"An error occurred while extracting the folder structure: {str(e)}")
             self.folder_df = pd.DataFrame(columns=['Category', 'Project'])
 
     def _save_to_csv(self):
         """Save the extracted folder structure to CSV file."""
         if self.folder_df is not None and not self.folder_df.empty:
-            self.folder_df.to_csv(self.csv_file_path, index=False)
-            print(f"Saved project data to {self.csv_file_path}")
+            try:
+                self.folder_df.to_csv(self.csv_file_path, index=False)
+                logging.info(f"Saved project data to {self.csv_file_path}")
+            except Exception as e:
+                logging.error(f"Failed to save project data to CSV: {e}")
+        else:
+            logging.warning("No folder data to save to CSV.")
 
     def get_example_projects(self, version_number='6.5'):
         """
@@ -155,9 +180,11 @@ class RasExamples:
         Raises:
             ValueError: If an invalid version number is provided.
         """
-        print(f"Getting example projects for version {version_number}")
+        logging.info(f"Getting example projects for version {version_number}")
         if version_number not in self.valid_versions:
-            raise ValueError(f"Invalid version number. Valid versions are: {', '.join(self.valid_versions)}")
+            error_msg = f"Invalid version number. Valid versions are: {', '.join(self.valid_versions)}"
+            logging.error(error_msg)
+            raise ValueError(error_msg)
 
         zip_url = f"{self.base_url}1.0.31/Example_Projects_{version_number.replace('.', '_')}.zip"
         
@@ -166,13 +193,18 @@ class RasExamples:
         self.zip_file_path = self.examples_dir / f"Example_Projects_{version_number.replace('.', '_')}.zip"
 
         if not self.zip_file_path.exists():
-            print(f"Downloading HEC-RAS Example Projects from {zip_url}. \n The file is over 400 MB, so it may take a few minutes to download....")
-            response = requests.get(zip_url)
-            with open(self.zip_file_path, 'wb') as file:
-                file.write(response.content)
-            print(f"Downloaded to {self.zip_file_path}")
+            logging.info(f"Downloading HEC-RAS Example Projects from {zip_url}. \nThe file is over 400 MB, so it may take a few minutes to download....")
+            try:
+                response = requests.get(zip_url, stream=True)
+                response.raise_for_status()
+                with open(self.zip_file_path, 'wb') as file:
+                    shutil.copyfileobj(response.raw, file)
+                logging.info(f"Downloaded to {self.zip_file_path}")
+            except requests.exceptions.RequestException as e:
+                logging.error(f"Failed to download the zip file: {e}")
+                raise
         else:
-            print("HEC-RAS Example Projects zip file already exists. Skipping download.")
+            logging.info("HEC-RAS Example Projects zip file already exists. Skipping download.")
 
         self._load_project_data()
         return self.projects_dir
@@ -185,10 +217,10 @@ class RasExamples:
             list: Available categories.
         """
         if self.folder_df is None or 'Category' not in self.folder_df.columns:
-            print("No categories available. Make sure the zip file is properly loaded.")
+            logging.warning("No categories available. Make sure the zip file is properly loaded.")
             return []
         categories = self.folder_df['Category'].unique()
-        print(f"Available categories: {', '.join(categories)}")
+        logging.info(f"Available categories: {', '.join(categories)}")
         return categories.tolist()
 
     def list_projects(self, category=None):
@@ -202,12 +234,14 @@ class RasExamples:
             list: List of project names.
         """
         if self.folder_df is None:
-            print("No projects available. Make sure the zip file is properly loaded.")
+            logging.warning("No projects available. Make sure the zip file is properly loaded.")
             return []
         if category:
             projects = self.folder_df[self.folder_df['Category'] == category]['Project'].unique()
+            logging.info(f"Projects in category '{category}': {', '.join(projects)}")
         else:
             projects = self.folder_df['Project'].unique()
+            logging.info(f"All available projects: {', '.join(projects)}")
         return projects.tolist()
 
     def extract_project(self, project_names: Union[str, List[str]]):
@@ -229,21 +263,29 @@ class RasExamples:
         extracted_paths = []
 
         for project_name in project_names:
-            print("----- RasExamples Extracting Project -----")
-            print(f"Extracting project '{project_name}'")
+            logging.info("----- RasExamples Extracting Project -----")
+            logging.info(f"Extracting project '{project_name}'")
             project_path = self.projects_dir / project_name
 
             if project_path.exists():
-                print(f"Project '{project_name}' already exists. Deleting existing folder...")
-                shutil.rmtree(project_path)
-                print(f"Existing folder for project '{project_name}' has been deleted.")
+                logging.info(f"Project '{project_name}' already exists. Deleting existing folder...")
+                try:
+                    shutil.rmtree(project_path)
+                    logging.info(f"Existing folder for project '{project_name}' has been deleted.")
+                except Exception as e:
+                    logging.error(f"Failed to delete existing project folder '{project_name}': {e}")
+                    continue
 
             if self.folder_df is None or self.folder_df.empty:
-                raise ValueError("No project information available. Make sure the zip file is properly loaded.")
+                error_msg = "No project information available. Make sure the zip file is properly loaded."
+                logging.error(error_msg)
+                raise ValueError(error_msg)
 
             project_info = self.folder_df[self.folder_df['Project'] == project_name]
             if project_info.empty:
-                raise ValueError(f"Project '{project_name}' not found in the zip file.")
+                error_msg = f"Project '{project_name}' not found in the zip file."
+                logging.error(error_msg)
+                raise ValueError(error_msg)
 
             category = project_info['Category'].iloc[0]
             
@@ -265,15 +307,15 @@ class RasExamples:
                                 with zip_ref.open(file) as source, open(extract_path, "wb") as target:
                                     shutil.copyfileobj(source, target)
 
-                print(f"Successfully extracted project '{project_name}' to {project_path}")
+                logging.info(f"Successfully extracted project '{project_name}' to {project_path}")
                 extracted_paths.append(project_path)
             except zipfile.BadZipFile:
-                print(f"Error: The file {self.zip_file_path} is not a valid zip file.")
+                logging.error(f"Error: The file {self.zip_file_path} is not a valid zip file.")
             except FileNotFoundError:
-                print(f"Error: The file {self.zip_file_path} was not found.")
+                logging.error(f"Error: The file {self.zip_file_path} was not found.")
             except Exception as e:
-                print(f"An unexpected error occurred while extracting the project: {str(e)}")
-            #print("----- RasExamples Extraction Complete -----")
+                logging.error(f"An unexpected error occurred while extracting the project: {str(e)}")
+            logging.info("----- RasExamples Extraction Complete -----")
         return extracted_paths
 
     def is_project_extracted(self, project_name):
@@ -287,18 +329,26 @@ class RasExamples:
             bool: True if the project is extracted, False otherwise.
         """
         project_path = self.projects_dir / project_name
-        return project_path.exists()
+        is_extracted = project_path.exists()
+        logging.info(f"Project '{project_name}' extracted: {is_extracted}")
+        return is_extracted
 
     def clean_projects_directory(self):
         """Remove all extracted projects from the example_projects directory."""
-        print(f"Cleaning projects directory: {self.projects_dir}")
+        logging.info(f"Cleaning projects directory: {self.projects_dir}")
         if self.projects_dir.exists():
-            shutil.rmtree(self.projects_dir)
+            try:
+                shutil.rmtree(self.projects_dir)
+                logging.info("All projects have been removed.")
+            except Exception as e:
+                logging.error(f"Failed to remove projects directory: {e}")
+        else:
+            logging.warning("Projects directory does not exist.")
         self.projects_dir.mkdir(parents=True, exist_ok=True)
-        print("Projects directory cleaned.")
+        logging.info("Projects directory cleaned and recreated.")
 
 # Example usage:
 # ras_examples = RasExamples()
 # extracted_paths = ras_examples.extract_project(["Bald Eagle Creek", "BaldEagleCrkMulti2D", "Muncie"])
 # for path in extracted_paths:
-#     print(f"Extracted to: {path}")
+#     logging.info(f"Extracted to: {path}")

ras_commander/RasGeo.py

@@ -5,8 +5,18 @@ from pathlib import Path
 from typing import List, Union
 from .RasPlan import RasPlan
 from .RasPrj import ras
+import logging
 import re
 
+# Configure logging at the module level
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(levelname)s - %(message)s',
+    # You can add a filename parameter here to log to a file
+    # filename='rasgeo.log',
+    # Uncomment the above line to enable file logging
+)
+
 class RasGeo:
     """
     A class for operations on HEC-RAS geometry files.
@@ -62,27 +72,38 @@ class RasGeo:
             geom_preprocessor_file = plan_path.with_suffix(geom_preprocessor_suffix)
             if geom_preprocessor_file.exists():
                 try:
-                    print(f"Deleting geometry preprocessor file: {geom_preprocessor_file}")
+                    logging.info(f"Deleting geometry preprocessor file: {geom_preprocessor_file}")
                     geom_preprocessor_file.unlink()
-                    print("File deletion completed successfully.")
+                    logging.info("File deletion completed successfully.")
                 except PermissionError:
+                    logging.error(f"Permission denied: Unable to delete geometry preprocessor file: {geom_preprocessor_file}.")
                     raise PermissionError(f"Unable to delete geometry preprocessor file: {geom_preprocessor_file}. Permission denied.")
                 except OSError as e:
+                    logging.error(f"Error deleting geometry preprocessor file: {geom_preprocessor_file}. {str(e)}")
                     raise OSError(f"Error deleting geometry preprocessor file: {geom_preprocessor_file}. {str(e)}")
             else:
-                print(f"No geometry preprocessor file found for: {plan_file}")
+                logging.warning(f"No geometry preprocessor file found for: {plan_file}")
         
         if plan_files is None:
-            print("Clearing all geometry preprocessor files in the project directory.")
+            logging.info("Clearing all geometry preprocessor files in the project directory.")
             plan_files_to_clear = list(ras_obj.project_folder.glob(r'*.p*'))
         elif isinstance(plan_files, (str, Path)):
             plan_files_to_clear = [plan_files]
+            logging.info(f"Clearing geometry preprocessor file for single plan: {plan_files}")
         elif isinstance(plan_files, list):
             plan_files_to_clear = plan_files
+            logging.info(f"Clearing geometry preprocessor files for multiple plans: {plan_files}")
         else:
+            logging.error("Invalid input type for plan_files.")
             raise ValueError("Invalid input. Please provide a string, Path, list of paths, or None.")
         
         for plan_file in plan_files_to_clear:
             clear_single_file(plan_file, ras_obj)
-        ras_obj.geom_df = ras_obj.get_geom_entries()
-
+        
+        # Update the geometry dataframe
+        try:
+            ras_obj.geom_df = ras_obj.get_geom_entries()
+            logging.info("Geometry dataframe updated successfully.")
+        except Exception as e:
+            logging.error(f"Failed to update geometry dataframe: {str(e)}")
+            raise

ras_commander/RasHdf.py

@@ -0,0 +1,248 @@
+
+
+import h5py
+import numpy as np
+import pandas as pd
+from typing import Union, List, Optional, Dict, Callable
+from scipy.spatial import KDTree
+
+class RasHdf:
+    """
+    A class containing utility functions for working with HDF files in the ras-commander library.
+    """
+
+    @staticmethod
+    def read_hdf_to_dataframe(hdf_dataset: h5py.Dataset, fill_value: Union[int, float, str] = -9999) -> pd.DataFrame:
+        """
+        Reads an HDF5 table using h5py and converts it into a pandas DataFrame, handling byte strings and missing values.
+
+        Args:
+            hdf_dataset (h5py.Dataset): The HDF5 table to read.
+            fill_value (Union[int, float, str], optional): The value to use for filling missing data. Defaults to -9999.
+
+        Returns:
+            pd.DataFrame: The resulting DataFrame with byte strings decoded and missing values replaced.
+
+        Example:
+            >>> with h5py.File('data.h5', 'r') as f:
+            ...     dataset = f['my_dataset']
+            ...     df = RasHdf.read_hdf_to_dataframe(dataset)
+            >>> print(df.head())
+        """
+        df = RasHdf.convert_to_dataframe_array(hdf_dataset)
+        byte_cols = [col for col in df.columns if isinstance(df[col].iloc[0], (bytes, bytearray))]
+        test_byte_cols = [col for col in df.columns if isinstance(df[col].iloc[-1], (bytes, bytearray))]
+        assert byte_cols == test_byte_cols, "Inconsistent byte string columns detected"
+        
+        try:
+            df[byte_cols] = df[byte_cols].applymap(lambda x: x.decode('utf-8'))
+        except Exception as e:
+            print(f'WARNING: {e} while decoding byte strings in {hdf_dataset.name}, resuming')
+        
+        df = df.replace({fill_value: np.NaN})
+        return df
+
+    @staticmethod
+    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: Union[int, float, str]) -> h5py.Dataset:
+        """
+        Saves 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]]], optional): A dictionary of attributes to add to the dataset. Defaults to None.
+            fill_value (Union[int, float, str], optional): The value to use for filling missing data. Defaults to -9999.
+            **kwargs: Additional keyword arguments passed to `hdf_parent_group.create_dataset()`.
+
+        Returns:
+            h5py.Dataset: The created HDF5 dataset within the parent group.
+
+        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 = RasHdf.save_dataframe_to_hdf(df, group, 'my_dataset')
+            >>> print(dataset)
+        """
+        df = dataframe.copy()
+
+        if df.columns.dtype == 'O':
+            df.columns = df.columns.str.replace('/', '-')
+        
+        df = df.fillna(fill_value)
+        
+        string_cols = [col for col in df.columns if isinstance(df[col].iloc[0], str)]
+        test_string_cols = [col for col in df.columns if isinstance(df[col].iloc[-1], str)]
+        assert string_cols == test_string_cols, "Inconsistent string columns detected"
+        
+        df[string_cols] = df[string_cols].applymap(lambda x: x.encode('utf-8')).astype('bytes')
+
+        if isinstance(df.columns, pd.RangeIndex):
+            arr = df.values
+        else:
+            arr_dt = [(col, df[col].dtype) for col in df.columns]
+            arr = np.empty((len(df),), dtype=arr_dt)
+            for col in df.columns:
+                arr[col] = df[col].values
+    
+        if dataset_name in hdf_parent_group:
+            del hdf_parent_group[dataset_name]
+        
+        dataset = hdf_parent_group.create_dataset(dataset_name, data=arr, **kwargs)
+        
+        if attributes:
+            dataset.attrs.update(attributes)
+        
+        return dataset
+
+    @staticmethod
+    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]])
+            >>> RasHdf.perform_kdtree_query(ref_points, query_points)
+            array([ 0, -1])
+        """
+        dist, snap = KDTree(reference_points).query(query_points, distance_upper_bound=max_distance)
+        snap[dist > max_distance] = -1
+        return snap
+
+    @staticmethod
+    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]])
+            >>> RasHdf.find_nearest_neighbors(points)
+            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
+
+    @staticmethod
+    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]]], optional): Columns or indices to group by. Defaults to None.
+            pivot_columns (Optional[Union[str, List[str]]], optional): Columns to pivot. Defaults to None.
+            level (Optional[int], optional): Level of multi-index to group by. Defaults to None.
+            n_dimensional (bool, optional): If True, use a pivot table for N-Dimensional consolidation. Defaults to False.
+            aggregation_method (Union[str, Callable], optional): Aggregation method, e.g., 'list' to aggregate into lists. Defaults to 'list'.
+
+        Returns:
+            pd.DataFrame: The consolidated DataFrame.
+
+        Example:
+            >>> df = pd.DataFrame({'A': [1, 1, 2], 'B': [4, 5, 6], 'C': [7, 8, 9]})
+            >>> RasHdf.consolidate_dataframe(df, group_by='A')
+               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
+
+    @staticmethod
+    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]})
+            >>> RasHdf.decode_byte_strings(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
+
+    @staticmethod
+    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])
+            >>> RasHdf.find_nearest_value(arr, 6)
+            5
+        """
+        array = np.asarray(array)
+        idx = (np.abs(array - target_value)).argmin()
+        return array[idx]
+