Tutorial: Setting Up a PEM Project#

Overview of a PEM Project#

As introduced earlier, a PEM Project must adhere to a well-defined and standardized file system structure. The framework assumes a deterministic file system organization so that scripts can systematically discover, read, merge, and write datasets without manual intervention.

The typical project workflow is:

  1. Create the file system exactly as specified here.

  2. Populate the input directories with the required raster and vector layers for each scenario.

  3. Compute the Habitat Risk Index for the defined scenarios.

  4. Compute the Conflict Index for the defined scenarios.

  5. Compute the Benefit Index for the defined scenarios.

  6. Compute the Performance Index, integrating the previous indices.

Each stage can be executed using automated or semi-automated routines provided by the PEM scripts, ensuring reproducibility, traceability, and consistency across scenarios.

PEM Project file system layout
pem-project/                           # Project base folder
│
├── inputs/                            # Folder for all model inputs
│   │
│   ├── bathymetry.tif                 # Canonical raster (resolution, extent, CRS)
│   │
│   ├── vectors.gpkg                   # Core vector data container
│   ├── vectors.gpkg|roi               # Region of Interest (polygon layer)
│   ├── vectors.gpkg|hubs              # Land hubs (point layer)
│   ├── vectors.gpkg|habitat_benthic   # Benthic habitat map with attributes
│   ├── vectors.gpkg|habitat_pelagic   # Pelagic habitat map with attributes
│   ├── vectors.gpkg|...               # Additional optional layers
│   │
│   ├── _sources/                      # Helper folder for sourced datasets
│   │
│   ├── benefit/                       # Benefit Index parameters and data
│   │
│   ├── habitats/                      # Habitat rasters
│   │   ├── benthic.tif                # Rasterized Benthic habitat map
│   │   └── pelagic.tif                # Rasterized Pelagic habitat map
│   │
│   ├── risk/                          # Habitat Risk model parameters
│   │   ├── baseline/
│   │   │   ├── stressors_benthic.csv  # Stressor table (required by InVEST-HRA)
│   │   │   ├── scores_benthic.csv     # Criteria scores (required by InVEST-HRA)
│   │   │   ├── stressors_pelagic.csv
│   │   │   └── scores_pelagic.csv
│   │   │
│   │   └── {scenario}/                # Alternative scenarios
│   │
│   ├── roi/
│   │   ├── roi.shp                    # Shapefile for ROI (required by InVEST-HRA)
│   │   └── roi.tif                    # Boolean raster for ROI
│   │
│   └── users/                         # Ocean users configuration
│       ├── users.csv                  # Table of ocean users
│       ├── users_conflict.csv         # Spatial conflict matrix
│       │
│       ├── baseline/                  # Baseline scenario
│       │   ├── oilngas.tif            # raster footprint or density
│       │   ├── fisheries.tif          # (suggested users)
│       │   ├── windfarms.tif
│       │   ├── {username}.tif
│       │   └── ...
│       │
│       └── {scenario}/                # Alternative scenarios
│
└── outputs/                           # Model outputs
    │
    ├── baseline/
    │   ├── baseline_iduse.tif         # Use Performance Index
    │   ├── baseline_benefit.tif       # Benefit Index
    │   ├── baseline_conflict.tif      # Conflict Index
    │   ├── baseline_risk.tif          # Habitat Risk Index
    │   │
    │   └── intermediate/              # Intermediate artifacts
    │       ├── baseline_hra_benthic.tif      # InVEST output
    │       ├── baseline_hra_benthic_fz.tif   # fuzzy transform
    │       ├── baseline_hra_pelagic.tif
    │       └── baseline_hra_pelagic_fz.tif
    │
    └── {scenario}/                    # Alternative scenario outputs

1. Run Script: Setup the File System#

The PEM directory structure can be generated programmatically using the setup_folders function available in the project.py module, as shown below.

This procedure ensures that the project complies exactly with the required hierarchical layout expected by the framework.

To execute the setup, the user must provide:

  • The absolute path to the project.py module;

  • The absolute path to a base directory where the project folder will be created;

  • The project name;

  • An optional list of scenario names.

Note

The baseline scenario is always generated, regardless of whether it is explicitly included in the scenarios list.

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

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

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

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

# define scenario names
scenarios = [
    "baseline",
    "utopia",  # change here
    "distopia", # change here
    # add more if applicable
]

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

output_file = module.setup_folders(
    name=name,
    folder_base=base,
    scenarios=scenarios,
)

2. Manually Populate Bathymetry#

The file bathymetry.tif is the canonical raster of the PEM Project. It defines the reference grid, resolution, extent, and projected CRS used throughout all spatial computations.

The user must place the file at:

{project}/inputs/bathymetry.tif

3. Populate ROI#

The ROI (Region of Interest) is a polygon vector layer delimiting the analysis domain.

Manual Input#

The user must provide the ROI layer at:

{project}/inputs/vectors.gpkg|roi

It is recommended that the ROI uses the same projected CRS as bathymetry.tif. If necessary, reprojection can be handled automatically by the framework.

Script: Setup ROI#

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla mollis tincidunt erat eget iaculis. Mauris gravida ex quam, in porttitor lacus lobortis vitae. In a lacinia nisl. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Morbi et tempor sem. Nullam quam dolor, venenatis eget magna ut, accumsan mollis erat.

4. Populate Ocean Habitats#

Ocean benthic and pelagic habitat maps are required for the Habitat Risk Index assessment and for the delineation of biophysically grounded Management Units.

During processing, habitat layers are rasterized onto the canonical grid and encoded as a categorical (qualitative) raster, where each cell represents a specific habitat group identifier.

Manual Input#

Habitats are polygon vector layers classified into:

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

These layers are later rasterized onto the canonical grid defined by bathymetry.tif.

Technical recommendations:

  • No overlapping polygons within the same layer.

  • A unique identifier (ID or code) per habitat class.

  • Prefer single-part geometries (avoid multipart features when possible).

Habitat thematic detail is user-defined. The PEM framework allows aggregation into broader habitat groups at a later stage (e.g., grouping multiple mud-related classes into a single “mud” category).

Script: Setup Habitats#

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla mollis tincidunt erat eget iaculis. Mauris gravida ex quam, in porttitor lacus lobortis vitae. In a lacinia nisl. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Morbi et tempor sem. Nullam quam dolor, venenatis eget magna ut, accumsan mollis erat.

5. Populate Ocean Users#

Ocean Users represent spatially explicit human activities within the marine domain. Activities may overlap spatially both within the same economic sector and across different sectors.

For each scenario, user layers are ultimately transformed into a continuous intensity quantitative raster, representing the relative magnitude or footprint of each activity across the ocean space.

Manual Input: overview#

Multiple layers geometries and formats may exist per user economic sector and per scenario.

Examples:

  • Offshore wind: turbines (points) and cable corridors (lines).

  • Fisheries: polygon zones and rasterized intensity maps.

  • Oil extraction: distinct layers for baseline and future expansion scenarios.

Scenario grouping and categorization are handled later in the workflow.

See also

Learn how to setup layer groups in the scripts in Tutorial: Defining Ocean Users Groups.

Manual Input: vector layers#

Vector users may be points, lines, or polygons. Layers may include numeric attributes representing intensity, density, or effort (e.g., intensity, density).

The user must populate in the vectors.gpkg database, like:

{project}/inputs/vectors.gpkg|ocean_user_a_baseline
{project}/inputs/vectors.gpkg|ocean_user_a_utopia
{project}/inputs/vectors.gpkg|ocean_user_b

Recommendations:

  • Ensure the spatial extent is equal to or larger than the canonical raster.

  • Avoid using hyphens, blank space or any non-ASCII characters in layer naming

  • Maintain consistent attribute naming for quantitative fields.

Manual Input: Raster Layers#

Raster layers for ocean users may represent:

  • Boolean footprint layers; or

  • Continuous scalar fields (e.g., intensity, density, heat maps).

The user must place raster sources under:

{project}/inputs/_sources/ocean_user_c
{project}/inputs/_sources/ocean_user_d

Recommendations:

  • Ensure the spatial extent is equal to or larger than the canonical raster.

  • Maintain consistent resolution when possible (resampling is handled during reprojection).

Script: Setup Ocean Users#

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla mollis tincidunt erat eget iaculis. Mauris gravida ex quam, in porttitor lacus lobortis vitae. In a lacinia nisl. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Morbi et tempor sem. Nullam quam dolor, venenatis eget magna ut, accumsan mollis erat.