Add docstrings and logfiles

Author: sjpfenninger

workflow/rules/automatic.smk

@@ -10,6 +10,8 @@ rule download_cutout_slope:
         vector="resources/user/shapes/{shape}.parquet",
     output:
         path="resources/automatic/cutout/{shape}/slope.tif",
+    log:
+        "logs/{shape}/download_cutout_slope.log",
     wrapper:
         "v7.2.0/geo/rasterio/clip-geotiff"
 
@@ -23,6 +25,8 @@ rule download_cutout_bathymetry:
         vector="resources/user/shapes/{shape}.parquet",
     output:
         path="resources/automatic/cutout/{shape}/bathymetry.tif",
+    log:
+        "logs/{shape}/download_cutout_bathymetry.log",
     wrapper:
         "v7.2.0/geo/rasterio/clip-geotiff"
 
@@ -34,6 +38,8 @@ rule download_globcover:
         url=internal["resources"]["automatic"]["globcover"],
     output:
         "resources/automatic/global/globcover.zip",
+    log:
+        "logs/download_globcover.log",
     conda:
         "../envs/shell.yaml"
     shell:
@@ -70,6 +76,8 @@ rule download_ghsl:
         url=internal["resources"]["automatic"]["ghsl"],
     output:
         "resources/automatic/global/ghsl_built_s.zip",
+    log:
+        "logs/download_ghsl.log",
     conda:
         "../envs/shell.yaml"
     shell:
@@ -86,6 +94,8 @@ rule unzip_ghsl:
         zipfile=rules.download_ghsl.output,
     output:
         "resources/automatic/global/ghsl_built_s.tif",
+    log:
+        "logs/unzip_ghsl.log",
     conda:
         "../envs/shell.yaml"
     shell:

workflow/rules/prepare.smk

@@ -9,6 +9,8 @@ rule cutout_landcover:
         landcover=rules.unzip_globcover.output,
     output:
         "resources/automatic/cutout/{shape}/landcover.tif",
+    log:
+        "logs/{shape}/cutout_landcover.log",
     conda:
         "../envs/default.yaml"
     shell:
@@ -25,6 +27,8 @@ rule cutout_settlement:
         settlement=rules.unzip_ghsl.output,
     output:
         "resources/automatic/cutout/{shape}/settlement.tif",
+    log:
+        "logs/{shape}/cutout_settlement.log",
     conda:
         "../envs/default.yaml"
     shell:

workflow/rules/process.smk

@@ -15,13 +15,16 @@ rule prepare_resampled_inputs:
             "resources/automatic/{shape}.resampled_inputs.png",
             category="resampled_input",
         ),
+    log:
+        "logs/{shape}/prepare_resampled_inputs.log",
     conda:
         "../envs/default.yaml"
     shell:
         """
+        set -x
         python "{input.script}" \
         "{input.shapes}" "{input.land_cover_path}" "{input.slope_path}" "{input.settlement_path}" "{input.bathymetry_path}" "{input.protected_area_path}" \
-        "{output.resampled_input}" "{output.plot}"
+        "{output.resampled_input}" "{output.plot}" 2> "{log}"
         """
 
 
@@ -41,12 +44,14 @@ rule area_potential:
             "results/{shape}/area_potential_{tech}.png",
             category="area_potential",
         ),
+    log:
+        "logs/{shape}/area_potential_{tech}.log",
     conda:
         "../envs/default.yaml"
     shell:
         """
         set -x
-        python "{input.script}" "{input.shapes}" "{input.resampled_path}" "{params.config}" "{params.buffer_crs}" "{output.area_potential}" "{output.plot}"
+        python "{input.script}" "{input.shapes}" "{input.resampled_path}" "{params.config}" "{params.buffer_crs}" "{output.area_potential}" "{output.plot}" 2> "{log}"
         """
 
 
@@ -66,6 +71,8 @@ rule area_potential_report:
             "results/{shape}/area_potential_report.html",
             category="area_potential_report",
         ),
+    log:
+        "logs/{shape}/area_potential_report.log",
     conda:
         "../envs/default.yaml"
     script:

workflow/scripts/area_potential.py

@@ -1,7 +1,8 @@
+"""This script calculates the area potential based on the provided configuration."""
+
 import click
 import geo
 import geopandas as gpd
-import matplotlib.pyplot as plt
 import xarray as xr
 import yaml
 
@@ -16,6 +17,20 @@
 def get_area_potential(
     shapes_path, resampled_path, config, buffer_crs, output_path, plot_path
 ):
+    """Calculate the area potential based on the provided configuration.
+
+    Args:
+        shapes_path (str): Path to the input shapes in the parquet format.
+        resampled_path (str): Path to the resampled input data in the NetCDF format.
+        config (str): Configuration YAML string.
+        buffer_crs (str): Coordinate Reference System for buffering shapes.
+        output_path (str): Path to save the resulting area potential raster.
+        plot_path (str): Path to save the plot of the area potential.
+
+    Returns:
+        None
+
+    """
     shapes = gpd.read_parquet(shapes_path)
     ds = xr.open_dataset(resampled_path, decode_coords="all")
     # FIXME: this is a workaround for the CRS not being set correctly; not sure why
@@ -82,7 +97,7 @@ def get_area_potential(
     potential_da.rio.to_raster(output_path, driver="GTiff", compress="LZW")
 
     plot = potential_da.plot()
-    plt.savefig(plot_path, bbox_inches="tight")
+    plot.savefig(plot_path, bbox_inches="tight")
 
 
 if __name__ == "__main__":

workflow/scripts/geo.py

@@ -1,3 +1,5 @@
+"""This module provides functions to buffer geometries using UTM projections."""
+
 import warnings
 
 import geopandas as gpd

workflow/scripts/report.py

@@ -1,10 +1,13 @@
+"""This script generates a report summarizing area potentials for different technologies."""
+
 import geopandas as gpd
 import pandas as pd
 import rioxarray as rxr
 import xarray as xr
 
 
 def report(shapes, resampled_path, area_potentials, csv_path, html_path):
+    """Generate a report summarizing area potentials for different technologies."""
     shapes = gpd.read_parquet(shapes)
     ds_inputs = xr.open_dataset(resampled_path, decode_coords="all")
     # FIXME: this is a workaround for the CRS not being set correctly; not sure why

workflow/scripts/resample.py

@@ -1,3 +1,5 @@
+"""This script resamples various geospatial datasets to a common shape and resolution."""
+
 import math
 
 import click
@@ -68,6 +70,7 @@
 
 
 def get_suitable_land_cover_type(ds_land_cover, suitable_land_cover_types):
+    """Convert raw GlobCover data to a dataset with suitable land cover types."""
     suitable_land_cover = xr.Dataset(coords=ds_land_cover.coords)
 
     # convert the input value to land cover type of interest
@@ -158,7 +161,7 @@ def _rasterize_regions(shapes, reference_raster):
 @click.argument("protected_area_path", type=str)
 @click.argument("output_path", type=str)
 @click.argument("plot_path", type=str)
-def get_same_shape_and_resolution(
+def resample_inputs(
     shapes_path,
     land_cover_path,
     slope_path,
@@ -168,6 +171,12 @@ def get_same_shape_and_resolution(
     output_path,
     plot_path,
 ):
+    """Resample various geospatial datasets to a common shape and resolution.
+
+    Results are saved to the specified output path in NetCDF format,
+    and a plot of the resampled data is saved to the specified plot path.
+
+    """
     shapes = gpd.read_parquet(shapes_path)
 
     ##
@@ -291,4 +300,4 @@ def get_same_shape_and_resolution(
 
 
 if __name__ == "__main__":
-    get_same_shape_and_resolution()
+    resample_inputs()

workflow/scripts/script_utils.py

@@ -1,9 +1,12 @@
+"""Utility functions."""
+
 import math
 
 import matplotlib.pyplot as plt
 
 
 def plot_all_dataset_variables(ds, ncols=2, savefig=None):
+    """Plot all variables in an xarray dataset on a grid of plots."""
     # Drop dimensionless variables
     ds = ds.drop_vars(lambda x: [v for v, da in x.variables.items() if not da.ndim])
 

workflow/scripts/unzip_like.py

@@ -1,3 +1,5 @@
+"""Emulates the `unzip` command across platforms."""
+
 import os
 import zipfile