pem.publish

This is the complete API reference for the publish python module of the pem system.

This module assembles the final published results for a scenario run: it publishes the grid and units layers to a single GeoPackage, warps the scenario’s raster maps (benefit, risk, conflict, performance, and any user-activity maps) to the target CRS, computes zonal statistics of each map over the grid, joins those statistics back onto the grid (normalized to the [0, 1] range), and finally aggregates the grid statistics by unit, via a non-spatial group-by on the unit id, joining the resulting means back onto each unit layer.

This module is intended to be run from within the QGIS Python environment, since it relies on the processing, osgeo, and qgis.core packages for raster warping and zonal statistics.

Script example

# !WARNING: run this in QGIS Python Environment
import importlib.util as iu

# define the paths to the module file
# ------------------------------------------------------
file = "path/to/publish.py"  # change here

# define the project folder
# ------------------------------------------------------
folder = "path/to/project_folder"  # change here

# define scenario
# ------------------------------------------------------
scenario = "baseline"

# define grid layer name
# ------------------------------------------------------
grid = "grid"

# define units layers
# ------------------------------------------------------
units = {
    "units_micro": {
        "layer": "upg_micro",
        "id": "id"
    },

    "units_macro": {
        "layer": "upg_macro",
        "id": "id"
    },
}

# call the function
# ------------------------------------------------------
# do not change here
spec = iu.spec_from_file_location("module", file)
module = iu.module_from_spec(spec)
spec.loader.exec_module(module)

ls_output = module.publish_results(
    folder_project=folder,
    scenario=scenario,
    grid_layer=grid,
    units_layers=units,
    grid_id_field="h3_index",
    crs_epsg=4326
)

print(" ----- DONE -----")

pem.publish.publish_results(folder_project, scenario, grid_layer, units_layers, grid_id_field, crs_epsg=4326)

Assemble and publish the final results of a scenario run.

This is the top-level entry point of the module. For a given project and scenario it builds a single output GeoPackage (outputs/<scenario>/results.gpkg) holding the grid layer, the units layers, and a set of derived statistics, by running the following steps in order:

1. Load the grid layer and each unit layer from the project’s input vector database, reprojecting both to crs_epsg if needed (see _load_and_reproject()).

2. For each unit layer, tag every grid row with the id of the unit polygon that contains its centroid (see _assign_unit_ids()), then publish both the grid and the unit layers to the output GeoPackage.

3. Warp the scenario’s raster maps (benefit, risk, conflict, performance, plus any user-activity maps found under inputs/users/<scenario>) to crs_epsg.

4. Compute zonal statistics (mean) of each warped map over the grid, then join the resulting per-map mean back onto the grid, normalized to the [0, 1] range (see _join_zonal_stats() and _normalize_minmax()), and republish the grid layer.

5. Aggregate the grid’s per-map statistics by unit, via a non-spatial group-by on each unit’s id, and join the resulting means back onto each unit layer non-destructively (see _aggregate_stats_by_unit()), republishing each unit layer.

Parameters:

• folder_project (str or pathlib.Path) – path to the project folder. Must contain an inputs/vectors.gpkg (holding the grid and unit layers) and an inputs/bathymetry.tif reference raster; see _get_project_vars().

• scenario (str) – name of the scenario to publish. Used to locate the scenario’s raster maps (<scenario>_<map>.tif) and the inputs/users/<scenario> folder, and as the output subfolder name under outputs/.

• grid_layer (str) – name of the grid layer in vectors.gpkg. Also used as the name under which the grid is published in the output GeoPackage.

• units_layers (dict) –

  mapping of unit layer name (as published in the output GeoPackage) to a dict with the keys "layer" (the source layer name in vectors.gpkg) and "id" (the name of that unit layer’s unique id field), e.g.:

  {
      "units_micro": {"layer": "upg_micro", "id": "id"},
      "units_macro": {"layer": "upg_macro", "id": "id"},
  }
  

• grid_id_field (str) – name of the stable unique id field on the grid layer, used to join the zonal statistics back onto it.

• crs_epsg (int) – EPSG code of the target CRS that the grid, unit layers, and raster maps are reprojected/warped to. Defaults to 4326.

Returns:

None. All results are written to outputs/<scenario>/results.gpkg in folder_project.

Return type:

None