pem.project module#

{Short module description (1-3 sentences)} todo docstring

pem.project.setup_project(name, folder_base, scenarios=None)[source]#

Initialize the directory structure for a PEM project.

Note

This function creates a standardized hierarchy of folders for inputs and outputs. It also handles the creation of scenario-specific subdirectories and intermediate folders within each output directory.

Parameters:

  • name (str) – The name of the project, used as the root folder name.

  • folder_base (str or pathlib.Path) – The base directory where the project structure will be created.

  • scenarios (list) – [optional] A list of scenario names to create specific subfolders for.

Returns:

A list of all directory paths created during the setup process.

Return type:

list

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

# define the paths to the module
# ----------------------------------------
the_module = "path/to/project.py"  # change here

# define the base folder
# ----------------------------------------
folder_base = "path/to/folder"  # change here

# define project name
# ----------------------------------------
project_name = "narnia"  # change here

# define scenario names
# ----------------------------------------
# change here
scenarios = [
    "baseline",
    "utopia",
    "distopia",
]

# call the function
# ----------------------------------------
spec = iu.spec_from_file_location("module", the_module)
module = iu.module_from_spec(spec)
spec.loader.exec_module(module)

output_file = module.setup_folders(
    name=project_name,
    folder_base=folder_base,
    scenarios=scenarios,
)
pem.project.setup_roi(folder_project)[source]#
pem.project.setup_habitats(folder_project, habitat_field='code', groups=None, to_byte=True)[source]#
pem.project.setup_users(folder_project, groups, scenario='baseline')[source]#

Configures the OceanUse analysis by processing vector and raster data into weighted thematic user groups.

Parameters:

  • folder_project (str) – The root directory path of the project.

  • groups (dict) – The master Layer Group dictionary defining the hierarchical structure of raster and vector layers with their associated weights.

  • scenario (str) – The name of the analysis scenario, used for organizing output subdirectories. Default value = baseline

Returns:

[optional] No value is returned by this function.

Return type:

None

Extra notes

This function orchestrates a multi-step geospatial workflow: 1. Validates the existence of project folders and core input files (bathymetry and vector databases). 2. Extracts spatial metadata (CRS, Extent, Resolution) from the reference raster. 3. Processes defined groups by clipping/rasterizing vectors and aligning external rasters. 4. Applies normalization and weighted map algebra to layers within each group to produce a final thematic surface.

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

# define the paths to the module
the_module = "path/to/project.py" # change here

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

# define the analysis scenario
scenario = "baseline" # change here

# define layer groups
# change "name", "field" and "weight"

group_fisheries = {
    "vectors": [
        {"name": "fisheries_traps", "field": None, "weight": 2 },
        {"name": "fisheries_seines", "field": "intensity", "weight": 3 },
    ],
    "rasters": [
        {"name": "fisheries_gillnets.tif", "weight": 10 },
        {"name": "fisheries_longlines.tif", "weight": 5 },
    ]
}
group_windfarms = {
    "vectors": [
        {"name": "windfarms", "field": None, "weight": 5 },
    ],
}

# setup groups dictionary
# define actual names for Ocean Users
groups = {
    "fisheries": group_fisheries,
    "windfarms": group_windfarms,
}

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

output_file = module.setup_users(
    folder_project=folder_project,
    groups=groups,
    scenario=scenario
)
pem.project.util_raster_blank(output_raster, input_raster)[source]#

Creates a blank (zero-valued) raster based on the extent, resolution, and CRS of an existing input raster.

Parameters:

  • output_raster (str) – name for the resulting blank raster file (without extension).

  • input_raster (str) – The path to the source raster file whose properties (extent, resolution, CRS) will be used.

Returns:

The full path to the newly created blank raster file.

Return type:

str

Notes

This function uses the QGIS processing algorithm native:rastercalc (Raster calculator). It works by multiplying every cell in the input raster by zero, effectively preserving the metadata (extent, resolution, CRS) while setting all data values to zero. The output raster is a new file and does not modify the input raster.

pem.project.util_rasterize_layer(input_raster, input_db=None, input_layer=None, burn_value=1, use_field=None, add=False, extra='')[source]#
pem.project.util_extractextent_vectors(input_db, layers, folder_output, dst_ext, dst_crs='5880', name_out='extractextent')[source]#

Extracts specific vector layers based on a spatial extent and saves them to a GeoPackage.

Note

Iterates through a list of layers from an input database, clips each to the provided spatial bounds using the native:extractbyextent algorithm, and appends the result to a destination GeoPackage.

Parameters:

  • input_db (str) – Path to the source database or vector file.

  • layers (list) – List of layer names to be extracted from the source.

  • folder_output (str) – Directory where the output file will be saved.

  • dst_ext (dict) – Dictionary containing the spatial bounds with keys xmin, xmax, ymin, and ymax.

  • dst_crs (str) – Coordinate Reference System identifier for the extent. Default value = 5880

  • name_out (str) – Filename for the output GeoPackage (without extension). Default value = extractextent

Returns:

The file path to the generated GeoPackage.

Return type:

str

pem.project.util_reproject_vectors(input_db, layers, folder_output, dst_crs='5880', name_out='reprojected')[source]#

Reprojects a list of vector layers from a source database to a specified coordinate reference system and saves them into a new GeoPackage.

Parameters:

  • input_db (str) – Path to the source database containing the layers.

  • layers (list) – List of layer names to be reprojected.

  • folder_output (str) – Directory path where the output GeoPackage will be stored.

  • dst_crs (str) – The EPSG code for the destination coordinate reference system. Default value = 5880

Returns:

The file path to the generated GeoPackage containing the reprojected layers.

Return type:

str

Note

The function utilizes native:reprojectlayer and stores all processed layers within a single .gpkg file named reprojected.gpkg.

todo script example

pem.project.util_normalize_rasters(ls_rasters, suffix='fz', force_vmin=0)[source]#
pem.project.util_get_raster_stats(input_raster, band=1, full=False)[source]#

Calculates the statistics for a specified band of a given raster file.

Parameters:

  • input_raster (str) – Full path to the input raster file.

  • band (int) – The band number to calculate statistics for. Default value = 1

Returns:

A dictionary containing the raster band’s mean, standard deviation, minimum, maximum, sum, and element count.

Return type:

dict

Notes

The function uses QGIS classes internally to read the raster and compute statistics. The keys in the returned dictionary are mean, sd, min, max, sum, and count.

pem.project.util_get_raster_crs(file_input, code_only=True)[source]#

Extracts the Coordinate Reference System (CRS) from a raster file.

Parameters:

  • file_input (str) – The file path to the raster source.

  • code_only (bool) – Whether to return only the numerical ID (e.g., 31983) or the full authority ID (e.g., EPSG:31983). Default value = True

Returns:

The CRS identifier as a string.

Return type:

str

todo script example

pem.project.util_get_raster_extent(file_input)[source]#

Retrieves the spatial bounding coordinates of a raster file as a dictionary.

Parameters:

file_input (str) – The path to the input raster file.

Returns:

A dictionary containing the xmin, xmax, ymin, and ymax coordinates.

Return type:

dict

pem.project.util_get_raster_resolution(file_input)[source]#
pem.project.util_get_vector_fields(file_input, layer_name)[source]#

Retrieves a list of all attribute field names from a specific layer within a vector file.

Parameters:

  • file_input (str) – The path to the source vector database or file.

  • layer_name (str) – The name of the specific layer to access.

Returns:

A list of strings representing the field names in the layer.

Return type:

list

pem.project.util_read_raster(file_input, n_band=1, metadata=True)[source]#

Read a raster (GeoTIFF) file

Parameters:

  • file_input (str) – path to raster file

  • n_band (int) – number of the band to read

  • metadata (bool) – option to return

Returns:

dictionary with “data” and (optional) “metadata”

Return type:

dict

pem.project.util_write_raster(grid_output, dc_metadata, file_output, n_band=1, nodata_value=-99999)[source]#

Write a numpy array to raster

Parameters:

  • grid_output (numpy.ndarray) – 2D numpy array

  • dc_metadata (dict) – dict with metadata

  • file_output (str) – path to output raster file

  • n_band (int) – number of the band to write

  • nodata_value (float or int) – numeric value to represent NoData

Returns:

path to the written file

Return type:

str