pem.project#

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

See also

Learn how to setup a PEM Project in Tutorial: Setting Up a PEM Project.

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

Initialize the directory structure for a PEM project.

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

Extra notes

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.

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

# define the paths to the module file
# ------------------------------------------------------
file = "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", file)
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,
)

print(" ----- DONE -----")
pem.project.setup_roi(folder_project)[source]#

Prepares and processes the roi layer (Region of Interest)by reprojecting vector data and generating a corresponding raster mask.

Parameters:

folder_project (str) – The root directory path of the project containing necessary configuration and variables.

Returns:

A list containing the file path to the reprojected Shapefile and the path to the generated ROI raster.

Return type:

list

Expected sourced files

The roi layer is expected to be sourced from:

./{project}/inputs/vectors.gpkg|roi

Also, the reference raster is expected to be sourced from:

./{project}/inputs/bathymetry.tif
Script example
# !WARNING: run this in QGIS Python Environment
import importlib.util as iu

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

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

# 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)

output_files = module.setup_roi(
    folder_project=folder,
)

print(" ----- DONE -----")
pem.project.setup_habitats(folder_project, habitat_field, groups, to_byte=True)[source]#

Sets up habitat layers by reprojecting vector data, applying grouping logic, and generating categorized raster masks.

Parameters:

  • folder_project (str) – The root directory path of the project containing necessary configuration and variables.

  • habitat_field (str) – The attribute field name in the vector data representing the habitat classification.

  • groups (dict) – A dictionary containing grouping rules for benthic and pelagic habitats to aggregate specific classes.

  • to_byte (bool) – If True, the output raster will be exported as Byte (8-bit) with NoData 255; otherwise, Float32 with NoData -99999. Default value = True

Returns:

A list of file paths to the generated habitat TIF files.

Return type:

list

Extra notes

This function processes both benthic and pelagic habitat layers. It handles spatial reprojection, optional attribute grouping based on a lookup dictionary, and conversion to raster format. The final outputs are standardized rasters with consistent NoData values and data types (Byte or Float32) to ensure compatibility with downstream analysis. Also, a CSV file is generated for each habitat type for tracking the raster cell values.

Expected sourced files

The habitats layers are expected to be sourced from:

./{project}/inputs/vectors.gpkg|habitat_benthic
./{project}/inputs/vectors.gpkg|habitat_pelagic

Also, the reference raster is expected to be sourced from:

./{project}/inputs/bathymetry.tif
Script example
# !WARNING: run this in QGIS Python Environment
import importlib.util as iu

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

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

# define habitat code/id field
# ------------------------------------------------------
field = "code"

# define habitats grouping scheme for benthic
# ------------------------------------------------------

group_benthic = [
    {"name": "benthic_a", "values": ["MB3", "MC3"]},
    {"name": "benthic_b", "values": ["MB4", "MB5", "MB6"]},
    {"name": "benthic_b", "values": ["MC4", "MC5", "MC6"]},
    {"name": "benthic_c", "values": ["MD3"]},
    {"name": "benthic_d", "values": ["MD4", "MD5", "MD6"]},
    {"name": "benthic_e", "values": ["ME1"]},
    {"name": "benthic_f", "values": ["ME4", "MF4", "MF5"]},
    {"name": "benthic_f", "values": ["MG4", "MG6"]},
]

# define habitats grouping scheme for pelagic
# ------------------------------------------------------
group_pelagic = None  # if None, habitats are not grouped.

# 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.setup_habitats(
    folder_project=folder,
    habitat_field=field,
    groups={
        "benthic": group_benthic,
        "pelagic": group_pelagic
    },
)

print(" ----- DONE -----")
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.

Expected sourced files

The users vector layers are expected to be sourced from:

./{project}/inputs/vectors.gpkg|{user-vector-layer}

The users raster layers are expected to be sourced from:

./{project}/inputs/_sources/{user-raster-layer}.tif

Also, the reference raster is expected to be sourced from:

./{project}/inputs/bathymetry.tif
Script example
# !WARNING: run this in QGIS Python Environment
import importlib.util as iu

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

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

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

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

# this user has both vector and raster layers
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 },
    ]
}
# this user has only vector layers
group_windfarms = {
    "vectors": [
        {"name": "eolico_linhas_transmissao", "field": None, "weight": 1 },
        {"name": "eolico_torres", "field": None, "weight": 5 },
    ],
}

# this user has only raster layers
group_cargo = {
    "rasters": [
        {"name": "navegacao_densidade.tif", "weight": 1}
    ]
}
# setup groups dictionary
# ------------------------------------------------------
# define actual names for Ocean Users
groups = {
    "fisheries": group_fisheries,
    "windfarms": group_windfarms,
    "cargo": group_cargo,
}

# 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)

output_file = module.setup_users(
    folder_project=folder,
    groups=groups,
    scenario=scenario
)

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