Add docstrings to geospatial functions

Author: JoostGevaert

src/bedrock_ge/gi/geospatial.py

@@ -12,12 +12,32 @@
     BedrockGIDatabase,
     BedrockGIGeospatialDatabase,
     InSituTestSchema,
+    LocationSchema,
 )
 
 
 def create_brgi_geospatial_database(
     brgi_db: BedrockGIDatabase,
 ) -> BedrockGIGeospatialDatabase:
+    """Creates a Bedrock GI geospatial database from a Bedrock GI database.
+
+    Creates a Bedrock GI geospatial database by performing the following steps:
+    1. Creates a geospatial DataFrame for the Location table using the
+       `create_location_geodf` function.
+    2. Creates a geospatial DataFrame for the LonLatHeight table using the
+       `create_lon_lat_height_geodf` function.
+    3. Creates a dictionary of geospatial DataFrames for the In-Situ test tables
+       using the `interpolate_gi_geometry` function.
+    4. Creates a geospatial DataFrame for the Sample table using the
+       `interpolate_gi_geometry` function, if the Sample table exists.
+    5. Returns a BedrockGIGeospatialDatabase object.
+
+    Args:
+        brgi_db (BedrockGIDatabase): The Bedrock GI database to be converted.
+
+    Returns:
+        BedrockGIGeospatialDatabase: The resulting Bedrock GI geospatial database.
+    """
     location_geodf = create_location_geodf(brgi_db)
     lon_lat_height_geodf = create_lon_lat_height_geodf(brgi_db)
     insitu_test_geodfs = {}
@@ -44,6 +64,23 @@ def create_brgi_geospatial_database(
 
 
 def create_location_geodf(brgi_db: BedrockGIDatabase) -> gpd.GeoDataFrame:
+    """Creates a geospatial DataFrame for the Location table from a Bedrock GI database.
+
+    This function generates a GeoDataFrame for the Location table using the input
+    Bedrock GI database. It assumes the boreholes are vertical (for now) and calculates
+    elevation at the base of each borehole. It raises an error if multiple
+    horizontal or vertical coordinate reference systems (CRS) are found in the
+    project data.
+
+    Args:
+        brgi_db (BedrockGIDatabase): The Bedrock GI database containing location
+            data and project CRS information.
+
+    Returns:
+        gpd.GeoDataFrame: A GeoDataFrame with LineString geometries representing
+            vertical boreholes, using the compound CRS derived from the project's
+            horizontal and vertical CRS.
+    """
     # TODO: Implement logic to handle multiple CRS'es in the input GI data:
     #       1. Create WKT geometry for each location in original CRS
     #       2. Convert to WGS84 + EGM2008 orthometric height EPSG:9518
@@ -85,6 +122,23 @@ def create_location_geodf(brgi_db: BedrockGIDatabase) -> gpd.GeoDataFrame:
 
 
 def create_lon_lat_height_geodf(brgi_db: BedrockGIDatabase) -> gpd.GeoDataFrame:
+    """Creates GeoDataFrame with (lon, lat, height) for each location in a Bedrock GI database.
+
+    This function processes all GI locations in a Bedrock GI database, transforming the
+    (easting, northing, ground level elevation) coordinates to WGS84 (lon, lat)
+    + EGM2008 orthometric height coordinates, which have coordinate reference system EPSG:9518.
+    It returns a GeoDataFrame with the transformed longitude, latitude, and
+    EGM2008 ground level height, along with the corresponding point geometries in EPSG:9518.
+
+    Args:
+        brgi_db (BedrockGIDatabase): The source Bedrock Ground Investigation database
+            containing location and project information.
+
+    Returns:
+        gpd.GeoDataFrame: A GeoDataFrame with the transformed longitude, latitude,
+            and EGM2008 ground level height, along with the corresponding point
+            geometries in EPSG:9518.
+    """
     wgs84_egm2008_crs = CRS("EPSG:9518")
     crs_lookup = brgi_db.Project.set_index("project_uid")
     dfs = []
@@ -128,11 +182,30 @@ def create_lon_lat_height_geodf(brgi_db: BedrockGIDatabase) -> gpd.GeoDataFrame:
 
 
 def interpolate_gi_geometry(
-    insitu_test_df: DataFrame[InSituTestSchema], location_geodf: gpd.GeoDataFrame
+    insitu_test_df: DataFrame[InSituTestSchema],
+    location_geodf: DataFrame[LocationSchema],
 ) -> gpd.GeoDataFrame:
+    """Interpolates the geospatial geometry for a given In-Situ test DataFrame using its corresponding GI Location GeoDataFrame.
+
+    This function takes an In-Situ test DataFrame and a GI Location GeoDataFrame and
+    returns a GeoDataFrame with its geometry interpolated from the location GeoDataFrame.
+    The In-Situ test geometry is always a LineString or Point, depending on whether the
+    In-Situ test is performed at a specific depth or over a depth interval inside a borehole.
+    The geometry is calculated by linearly interpolating the depth values for each
+    In-Situ test row between the top and bottom of the corresponding location's LineString geometry.
+
+    Args:
+        insitu_test_df (DataFrame[InSituTestSchema]): The In-Situ test DataFrame
+            containing the depth values to be interpolated.
+        location_geodf (DataFrame[LocationSchema]): The location GeoDataFrame containing the
+            location geometry to be used for interpolation.
+
+    Returns:
+        gpd.GeoDataFrame: A GeoDataFrame containing the interpolated geospatial geometry
+            for the In-Situ test DataFrame.
+    """
     # TODO: implement a warning when interpolating GI geospatial geometry when
     # TODO: a single GI location has waaay too many rows in a certain In-Situ test.
-
     geodf = location_geodf[["location_uid", "geometry"]].merge(
         insitu_test_df,
         how="right",