User Guide#

This guide describes how to install, configure, and use the PEM framework from source. The framework is organized as a collection of standalone Python modules, each targeting a specific analytical component.

See also

If you intend to extend or modify the framework, refer to Development.

Installation#

The PEM framework is distributed as source code. Each script is designed to run as an independent process within the broader workflow.

Clone the official repository using git:

git clone https://github.com/iporepos/pem.git
cd pem

Alternatively, download the latest release directly from GitHub:

iporepos/pem

Note

Ensure that git is properly installed and available in your system environment variables before attempting to clone the repository.

Install PyQGIS#

All Python scripts are designed to run within the QGIS Python environment (PyQGIS). Therefore, installing QGIS is a mandatory prerequisite.

  1. Download QGIS from the official website: https://qgis.org/download

  2. During installation, ensure that the bundled Python environment is included.

  3. During installation, ensure numpy, pandas and geopandas Python packages are included.

Warning

The geopandas Python package is not included as default for most QGIS versions.

Tip

For Windows users, installing QGIS via the OSGeo4W system is recommended. This allows the user to select all Python packages needed.

Install InVEST Workbench#

The Habitat Risk Index page — a core component of the PEM framework — is derived from the Habitat Risk Assessment model, part of the InVEST suite.

To ensure compatibility with the risk modeling workflow:

  1. Download and install the InVEST Workbench.

  2. Install on a supported operating system (Windows or macOS).

  3. Verify that the Habitat Risk Assessment model executes successfully.

Important

The Habitat Risk Index implemented in PEM assumes conceptual and methodological alignment with the InVEST Habitat Risk Assessment model.

Source Code#

The repository follows a standard src layout:

pem/                             # repository root
├── src/                         # source directory
│   └── pem/                     # package root
│       ├── risk.py              # Habitat Risk Index module
│       ├── conflict.py          # User Conflict Index module
│       ├── benefit.py           # Benefit Index module
│       ├── iduse.py             # Use Performance Index module
│       └── data/                # runtime data resources
└── docs/                        # documentation (if applicable)

Each module encapsulates a logically distinct index within the PEM framework.

Running Python via PyQGIS#

All python modules defines functions that are documented in the API page.

Because the framework is distributed as source code (not as an installed package), the functions in the modules should be dynamically loaded using importlib.

This approach ensures:

  • Execution inside the correct PyQGIS runtime.

  • Full access to QGIS core libraries.

  • No need for system-wide package installation.

Important

Always execute the scripts from the QGIS Python Console or from a Python interpreter explicitly bound to the QGIS environment.

See also

For PyQGIS scripting details, consult the PyQGIS Developer Cookbook.

Example: loading functions from the modules

The following template demonstrates how to dynamically load the module project.py and execute one of its functions

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

The workflow follows four conceptual stages:

  1. Dynamic module binding via importlib.

  2. Path configuration for input/output resources.

  3. Parameter definition (e.g., habitat grouping rules).

  4. Function execution, returning the generated output artifact.

This pattern is applicable to all PEM python modules Simply change the file path, parameters and target function accordingly.

Tip

For reproducibility, store your execution script alongside your project data and document all parameter choices explicitly. This ensures traceability of spatial preprocessing decisions.

PEM Project#

The PEM framework may be deployed by the user under the concept of a PEM Project.

File System Structure#

A file-based PEM Project can follow a standardized file system schema to ensure reproducibility, scenario management, and compatibility with all framework modules.

The structure below represents the recommended layout for a complete project.

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 data
│   │   └── benefit_users.csv          # Benefit table
│   │
│   ├── habitats/                      # Habitat rasters
│   │   ├── habitats_benthic.tif       # Rasterized Benthic habitat map
│   │   ├── habitats_benthic.csv       # Benthic habitat table
│   │   ├── habitats_pelagic.tif       # Rasterized Pelagic habitat map
│   │   ├── habitats_pelagic.csv       # Benthic habitat table
│   │   ├── benthic/                   # Benthic habitat footprints
│   │   │   ├── {habitat-group}.tif    # habitat group footprint
│   │   │   └── ...
│   │   └── pelagic/                   # Pelagic habitat footprints
│   │       ├── {habitat-group}.tif    # habitat group footprint
│   │       └── ...
│   │
│   ├── risk/                          # Habitat Risk model parameters
│   │   ├── baseline/
│   │   │   ├── benthic_info.csv       # Benthic info table for InVEST-HRA model
│   │   │   ├── benthic_scores.csv     # Benthic score table for InVEST-HRA model
│   │   │   ├── benthic_model.json     # Benthic run-file for InVEST-HRA model
│   │   │   ├── pelagic_info.csv       # Pelagic info table for InVEST-HRA model
│   │   │   ├── pelagic_scores.csv     # Pelagic score table for InVEST-HRA model
│   │   │   └── pelagic_model.json     # Benthic run-file for InVEST-HRA model
│   │   └── {scenario}/                # Alternative scenarios
│   │       └── ...
│   │
│   ├── roi/
│   │   ├── roi.shp                    # Shapefile for ROI (required by InVEST-HRA)
│   │   └── roi.tif                    # Boolean raster for ROI
│   │
│   └── users/                         # Ocean users configuration
│       ├── baseline/                  # Baseline scenario
│       │   ├── conflict.csv           # Spatial user conflict matrix
│       │   ├── oil.tif                # user raster density/intensity
│       │   ├── oil_footprint.tif      # user raster footprint
│       │   ├── fishing.tif            # (suggested users)
│       │   ├── fishing_footprint.tif  # (suggested users)
│       │   ├── {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
    │       └── ...
    │
    └── {scenario}/                    # Alternative scenario outputs

Important

Adherence to this directory structure is not mandatory but is strongly recommended. The rationale of the PEM framework relies on this layout.

Design Principles#

The PEM Project presented above has some core design principles.

1. Scenario Isolation

Each scenario (e.g., baseline, ssp1) maintains:

  • Dedicated ocean-use rasters.

  • Independent risk parameterization.

  • Separate output folders.

This guarantees clean scenario comparison and prevents cross-contamination of intermediate artifacts.

2. Bathymetry is the Single Source of Spatial Truth

The bathymetry.tif file defines:

  • Spatial resolution

  • Projection (CRS)

  • Raster extent

All derived rasters must conform strictly to this reference grid.

3. Modular Input Domains

Inputs are grouped by analytical domain:

  • habitats/ → ecological state

  • oceanuse/ → human pressures and interactions

  • risk/ → Habitat Risk parameterization

  • benefit/ → Benefit Index parameters

This separation aligns with the internal architecture of the PEM modules.

4. Deterministic Outputs

All primary indices are written to:

outputs/{scenario}/

Intermediate model artifacts are explicitly separated under:

outputs/{scenario}/intermediate/

This ensures traceability of derived layers such as InVEST-HRA results and their fuzzy-transformed counterparts.

Spatial Reference#

The PEM framework is architected around a canonical/reference raster: the bathymetry layer:

{project}/inputs/bathymetry.tif

This reference raster defines the spatial standard for the entire project and is a template for:

  • Coordinate Reference System (CRS)

  • Projection

  • Spatial resolution

  • Grid alignment

  • Spatial extent (bounding box)

Important

The bathymetry raster must be projected, not geodetic (i.e., not latitude/longitude).

This is because equal-area computations are invalid in geographic (degree-based) CRS. Also, the InVEST Habitat Risk Assessment model requires projected inputs.

Tip

For the Brazilian ocean space, the projected Coordinate Reference System (CRS) we strongly recommend is SIRGAS 2000 / Brazil Polyconic [EPSG 5880].

Tutorials#

This section provides step-by-step guides for configuring and operating the PEM workflow, from initial project setup to advanced model structuring and automation tasks.

See also

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

See also

Learn how to setup habitat groups in the scripts in Tutorial: Defining Ocean Habitat Groups.

See also

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

See also

Learn how to derive the Habitat Risk Index in Tutorial: Habitat Risk Index.

See also

Learn how to derive the Conflict Index in Tutorial: Conflict Index.