Merge remote-tracking branch 'origin/main' into dev

Author: JoostGevaert

src/bedrock_ge/gi/ags/read.py

@@ -54,13 +54,12 @@ def ags3_to_dfs(ags3_data: str) -> Dict[str, pd.DataFrame]:
     """Converts AGS 3 data to a dictionary of pandas DataFrames.
 
     Args:
-        ags_data (str): The AGS 3 data as a string.
+        ags3_data (str): The AGS 3 data as a string.
 
     Returns:
         Dict[str, pd.DataFrame]: A dictionary of pandas DataFrames, where each key represents a group name from AGS 3 data,
         and the corresponding value is a pandas DataFrame containing the data for that group.
     """
-
     # Initialize dictionary and variables used in the AGS 3 read loop
     ags3_dfs = {}
     line_type = "line_0"
@@ -154,7 +153,7 @@ def ags4_to_dfs(ags4_data: str) -> Dict[str, pd.DataFrame]:
     """Converts AGS 4 data to a dictionary of pandas DataFrames.
 
     Args:
-        ags_data (str): The AGS 4 data as a string.
+        ags4_data (str): The AGS 4 data as a string.
 
     Returns:
         Dict[str, pd.DataFrame]: A dictionary of pandas DataFrames, where each key represents a group name from AGS 4 data,

src/bedrock_ge/gi/ags/transform.py

@@ -30,20 +30,20 @@ def ags3_db_to_no_gis_brgi_db(
     various types of geotechnical data including project information, locations,
     samples, lab tests, and in-situ measurements.
 
+    The mapping process:
+    1. Project Data: Converts AGS 3 'PROJ' group to Bedrock's 'Project' table
+    2. Location Data: Converts AGS 3 'HOLE' group to Bedrock's 'Location' table
+    3. Sample Data: Converts AGS 3 'SAMP' group to Bedrock's 'Sample' table
+    4. Other Data: Handles lab tests, in-situ measurements, and miscellaneous tables
+
     Args:
         ags3_db (Dict[str, pd.DataFrame]): A dictionary containing AGS 3 data tables,
             where keys are table names and values are pandas DataFrames.
         crs (CRS): Coordinate Reference System for the project data.
 
     Returns:
         Dict[str, pd.DataFrame]: A dictionary containing Bedrock GI database tables,
-            where keys are table names and values are transformed pandas DataFrames.
-
-    The mapping process:
-    1. Project Data: Converts AGS 3 'PROJ' group to Bedrock's 'Project' table
-    2. Location Data: Converts AGS 3 'HOLE' group to Bedrock's 'Location' table
-    3. Sample Data: Converts AGS 3 'SAMP' group to Bedrock's 'Sample' table
-    4. Other Data: Handles lab tests, in-situ measurements, and miscellaneous tables
+        where keys are table names and values are transformed pandas DataFrames.
 
     Note:
         The function creates a copy of the input database to avoid modifying the original data.

src/bedrock_ge/gi/ags/validate.py

@@ -5,7 +5,7 @@ def check_ags_proj_group(ags_proj: pd.DataFrame) -> bool:
     """Checks if the AGS 3 or AGS 4 PROJ group is correct.
 
     Args:
-        proj_df (pd.DataFrame): The DataFrame with the PROJ group.
+        ags_proj (pd.DataFrame): The DataFrame with the PROJ group.
 
     Raises:
         ValueError: If AGS 3 of AGS 4 PROJ group is not correct.

src/bedrock_ge/gi/concatenate.py

@@ -22,7 +22,6 @@ def concatenate_databases(
     Returns:
         dict: A dictionary of concatenated pandas DataFrames.
     """
-
     # Create a new dict to store the concatenated dataframes
     concatenated_dict = {key: df.dropna(axis=1, how="all") for key, df in db1.items()}
 

src/bedrock_ge/gi/gis_geometry.py

@@ -28,8 +28,8 @@ def calculate_gis_geometry(
 
     Returns:
         Dict[str, gpd.GeoDataFrame]: Dictionary containing the Bedrock GI database tables
-            with added GIS geometry. All tables are converted to GeoDataFrames with
-            appropriate CRS and geometry columns.
+        with added GIS geometry. All tables are converted to GeoDataFrames with
+        appropriate CRS and geometry columns.
 
     Raises:
         ValueError: If the projects in the database use different Coordinate Reference Systems (CRS).
@@ -109,12 +109,12 @@ def calculate_location_gis_geometry(
         crs (pyproj.CRS): The Coordinate Reference System (CRS) to use for the GIS geometry.
 
     Returns:
-        gpd.GeoDataFrame: The GIS geometry for the given GI locations, with *additional* columns:
-            longitude: The longitude of the location in the WGS84 CRS.
-            latitude: The latitude of the location in the WGS84 CRS.
-            wgs84_ground_level_height: The height of the ground level of the location in the WGS84 CRS.
-            elevation_at_base: The elevation at the base of the location.
-            geometry: The GIS geometry of the location.
+        gpd.GeoDataFrame: The GIS geometry for the given GI locations, with additional columns:
+            - longitude: The longitude of the location in the WGS84 CRS.
+            - latitude: The latitude of the location in the WGS84 CRS.
+            - wgs84_ground_level_height: The height of the ground level of the location in the WGS84 CRS.
+            - elevation_at_base: The elevation at the base of the location.
+            - geometry: The GIS geometry of the location.
     """
     # Calculate Elevation at base of GI location
     brgi_location["elevation_at_base"] = (
@@ -156,8 +156,7 @@ def calculate_location_gis_geometry(
 def calculate_wgs84_coordinates(
     from_crs: CRS, easting: float, northing: float, elevation: Union[float, None] = None
 ) -> Tuple:
-    """Transforms coordinates from an arbitrary Coordinate Reference System (CRS) to
-    the WGS84 CRS, which is the standard for geodetic coordinates.
+    """Transforms coordinates from an arbitrary Coordinate Reference System (CRS) to the WGS84 CRS, which is the standard for geodetic coordinates.
 
     Args:
         from_crs (pyproj.CRS): The pyproj.CRS object of the CRS to transform from.
@@ -231,10 +230,10 @@ def calculate_in_situ_gis_geometry(
         crs (CRS): The Coordinate Reference System of the in-situ data.
 
     Returns:
-        gpd.GeoDataFrame: The GIS geometry for the given in-situ data, with *additional* columns:
-            elevation_at_top: The elevation at the top of the in-situ data.
-            elevation_at_base: The elevation at the base of the in-situ data.
-            geometry: The GIS geometry of the in-situ data.
+        gpd.GeoDataFrame: The GIS geometry for the given in-situ data, with additional columns:
+        - elevation_at_top: The elevation at the top of the in-situ data.
+        - elevation_at_base: The elevation at the base of the in-situ data.
+        - geometry: The GIS geometry of the in-situ data.
     """
     location_child = brgi_in_situ.copy()
 

src/bedrock_ge/gi/validate.py

@@ -19,7 +19,7 @@
 def check_brgi_database(brgi_db: Dict[str, Union[pd.DataFrame, gpd.GeoDataFrame]]):
     """Validates the structure and relationships of a 'Bedrock Ground Investigation' (BRGI) database (which is a dictionary of DataFrames).
 
-    This function checks that all tables in the BGI database conform to their respective schemas
+    This function checks that all tables in the BRGI database conform to their respective schemas
     and that all foreign key relationships are properly maintained. It validates the following tables:
     - Project
     - Location
@@ -28,21 +28,22 @@ def check_brgi_database(brgi_db: Dict[str, Union[pd.DataFrame, gpd.GeoDataFrame]
     - Lab_TESTY (not yet implemented)
 
     Args:
-        brgi_db (Dict): A dictionary containing the BGI database tables, where keys are table names
-            and values are the corresponding data tables (DataFrame or GeoDataFrame).
+        brgi_db (Dict[str, Union[pd.DataFrame, gpd.GeoDataFrame]]): A dictionary
+            containing the BRGI database tables, where keys are table names and
+            values are the corresponding data tables (DataFrame or GeoDataFrame).
 
     Returns:
         bool: True if all tables are valid and relationships are properly maintained.
 
     Example:
         ```python
-        brgi_geodb = {
+        brgi_db = {
             "Project": project_df,
             "Location": location_gdf,
             "Sample": sample_gdf,
-            "InSitu_ISPT": in_situ_ispt_gdf
+            "InSitu_ISPT": in_situ_ispt_gdf,
         }
-        check_brgi_database(brgi_geodb)
+        check_brgi_database(brgi_db)
         ```
     """
     for table_name, table in brgi_db.items():
@@ -82,16 +83,17 @@ def check_no_gis_brgi_database(
 ):
     """Validates the structure and relationships of a 'Bedrock Ground Investigation' (BGI) database without GIS geometry.
 
-    This function performs the same validation as check_brgi_database but uses schemas that don't require
-    GIS geometry. It validates the following tables:
+    This function performs the same validation as `check_brgi_database` but uses schemas
+    that don't require GIS geometry. It validates the following tables:
     - Project (never has GIS geometry)
     - Location (without GIS geometry)
     - Sample (without GIS geometry)
     - InSitu_TESTX (without GIS geometry)
     - Lab_TESTY (not yet implemented)
 
     Args:
-        brgi_db (Dict): A dictionary containing the Bedrock GI database tables, where keys are table names
+        brgi_db (Dict[str, Union[pd.DataFrame, gpd.GeoDataFrame]]): A dictionary
+            containing the Bedrock GI database tables, where keys are table names
             and values are the corresponding data tables (DataFrame or GeoDataFrame).
 
     Returns:
@@ -103,7 +105,7 @@ def check_no_gis_brgi_database(
             "Project": projects_df,
             "Location": locations_df,
             "Sample": samples_df,
-            "InSitu_measurements": insitu_df
+            "InSitu_measurements": insitu_df,
         }
         check_no_gis_brgi_database(brgi_db)
         ```

src/bedrock_ge/gi/write.py

@@ -12,18 +12,17 @@ def write_gi_db_to_gpkg(
     """Writes a database with Bedrock Ground Investigation data to a GeoPackage file.
 
     Writes a dictionary of DataFrames containing Bedrock Ground Investigation data to a
-    GeoPackage file. Each DataFrame will be saved in a separate table named by the keys
-    of the dictionary.
+    [GeoPackage file](https://www.geopackage.org/). Each DataFrame will be saved in a
+    separate table named by the keys of the dictionary.
 
     Args:
-        brgi_dfs (dict): A dictionary where keys are brgi table names and values are DataFrames
+        brgi_db (dict): A dictionary where keys are brgi table names and values are DataFrames
             with brgi data.
         gpkg_path (str): The name of the output GeoPackage file.
 
     Returns:
         None
     """
-
     # Create a GeoDataFrame from the dictionary of DataFrames
     for sheet_name, brgi_table in brgi_db.items():
         sanitized_table_name = sanitize_table_name(sheet_name)
@@ -56,7 +55,6 @@ def write_gi_db_to_excel(
     Returns:
         None
     """
-
     # Create an Excel writer object
     with pd.ExcelWriter(excel_path, engine="openpyxl") as writer:
         for sheet_name, df in gi_db.items():
@@ -78,7 +76,7 @@ def sanitize_table_name(sheet_name):
         sheet_name (str): The original sheet name.
 
     Returns:
-        sanitized_name (str): A sanitized sheet name with invalid characters and spaces replaced.
+        sanitized_name: A sanitized sheet name with invalid characters and spaces replaced.
     """
     # Trim to a maximum length of 31 characters
     trimmed_name = sheet_name.strip()[:31]