Acceptability

Introduction

We want to guide the user through the use of Python scripts implementing the “Acceptability” risk computation.

Related Python Codes

The wolfhece package includes several components that facilitate the evaluation of acceptability within the framework.

a. Command-Line Interface (CLI): an executable from CLI (Command Line Interface) wolf_accept. This allows users to execute calculations and analyses directly from the command line, offering flexibility and ease of use for advanced users.

b. Graphical User Interface (GUI): A more user-friendly graphical interface is available. The ‘Acceptability Manager’ can be launched directly via WOLF, or wolfaccept from CLI, and allows users to interact with the model more intuitively, making it accessible to users who may not be comfortable with command-line operations.

Note

Calculation Routines: The core calculation routines are distributed across several files, including func.py, acceptability.py, and Parallels.py. These files contain the essential algorithms and functions necessary for the acceptability calculations.

Unit Tests: A suite of unit tests is available. These tests compare the outputs of the acceptability calculations against a reference simulation output for Theux, ensuring accuracy and reliability in the results.

Acceptability overview

Throughout the code, the three basic steps for calculating acceptability are

• Base data creation : The model incorporates various layers of land use data of the whole Walloon region, including population density (number of inhabitants), economic activities (such as services, commercial, recreational, or agricultural activities), infrastructure (including transportation networks), potentially hazardous sites, environmental features (like water supply sources and natural sites), and other vulnerable elements such as architectural and cultural heritage.

• Vulnerability computation : Each layer is assigned a vulnerability level between 1 and 5. The raster which saves the maximum level of vulnerability encountered in the different layers for each cell of the domain is the “vulnerability raster”

• Acceptability computation : The acceptability refes to an integer score system ranging from -2 (unacceptable) to 2 (acceptable) based on the vulnerability level and the water level reached for each return period. This scoring system provides the local acceptability, reflecting the risk assessment for specific return periods. The latter is based on simulations results and a decided ‘acceptability function’ for ech layers and return period that corrolates for each level of vulnerability, a certain score. The final output involves combining these rasters using a weighted sum, with the weights normalized to ensure that the final acceptability score ranges from -2 to 2. This final output is called combined acceptability.

Note

In addition to the core computations, the manager includes a feature for exploring scenarios that deviate from the baseline. Here, “baseline” refers to the default condition in which all input information (e.g., vulnerability layers) is fully available.

Folder structure (working directory)

The python code requires the prior creation of a folder, with a precise structure. This working directory will store input data, but also output data and temporary files.

The directory must include three folders : - INPUT - TEMP - OUTPUT

Warning

More specifically, TEMP and OUTPUT can be created and structured by the code itself, but the folder INPUT must be created and filled by the user.

A full version of the INPUT folder can be found in this private repository acceptability_data.

Moreover, in addition to following the folder structure, the user must pay attention to the names of the study area and scenario, ensuring consistency throughout the structure. The code will create folders and subfolders using these names.

INPUT Folder

In the following descriptive table, the acronym “Study_Area / Scenario_name” designates a folder bearing the name of the study area, e.g. Bassin_Vesdre, containing another folder bearing the name of the scenario, e.g. Scenario_baseline.

SubFolders	Sub-subfolders and files name	Description
CSVs	Intermediate.csv	This file gives values for various Vulnerability and water depth values
	Ponderation.csv	This file gives the ponderation values
	Vulnerability.csv	This file assigns the vulnerability values to different shapefiles
DATABASE	Cadastre_Walloon.gpkg	Cadastre data with Parcels (CaPa) and Buildings (CaBu)
	GT_Resilience_dataRisques202010.gdb	Layers used in Vulnerability computation
	PICC_vDIFF.gdb	PICC dataset
	CE_IGN_TOP10V/CE_IGN_TOP10V.shp	Shapefile delineating river path, Vesdre valley rivers
EPU_STATIONS_NEW	AJOUT_PDET_EPU_DG03_STATIONS.shp	Shapefile with corrected EPU stations, used in changing BDREF_DGO3_PASH__SCHEMA_STATIONS_EPU file
STUDY_AREA	BASSIN_SA.shp	Shapefile delineating the study area
WATER_DEPTH	Study_Area / Scenario_name	Water depths rasters named T2.tif, T5.tif, etc., obtained by free surface interpolation (filling) of simulations for each scenario.
CHANGE_VULNE	Study_Area / Scenario_name	Locally modified vulnerability rasters for this scenario

TEMP Folder

Subfolder	Files and Description
Study_Area / DATABASES	CLIP_CADASTER / .gpkg - CaPa and CaBu (Cadaster data) clipped to the extent of the study area.
	CLIP_GDB / .gpkg - Clipped GDB file for the study area.
	CLIP_IGN_CE / CE_IGN_TOP10V.tiff - Clipped river raster for the entire Vesdre Valley.
	CLIP_PICC / .gpkg - PICC data clipped to the extent of the study area.
	CODE_VULNE / .gpkg - Vulnerability codes clipped to the extent of the study area.
	WITH_MODIF / .gpkg - GPKG file containing modified data as per project requirements.
Study_Area / VULNERABILITY	VULNERABILITY.tiff - Vulnerability raster for the entire study area.
	VULNERABILITY_Code.tiff - Vulnerability Code raster for the entire study area. Codes can be referred to in Vulnerability.csv.
Scenario_name / Q_FILES	Q_FILES - Intermediate files that assign values to raster cells based on Intermediate.csv.
Scenario_name / REMOVED_BUILDINGS	REMOVED_BUILDINGS - Rasters of removed buildings for each scenario.

OUTPUT Folder

Subfolder	Files and Description
Study_Area / Scenario_name / baseline	Acceptability_baseline.tiff - Acceptability raster for the baseline (no vuln``_`` scenarios).
	Acceptability_baseline_resampled.tiff - Baseline acceptability raster, adapted with a resampling size.
	Vulnerability_baseline.tiff - Baseline vulnerability raster (no vuln``_`` scenarios).
	Vulnerability_Code_baseline.tiff -Baseline vulnerability raster with codes indicating specific vulnerability values. Codes can be cross-referenced in Vulnerability.csv.
	Masked_River_extent_baseline -Mask of the riverbed trace for the baseline situation.
Study_Area / Scenario_name / vuln_scenarios	Acceptability_scenarios.tiff - Acceptability raster for the scenarios, accounting for the vuln``_`` scenarios.
	Acceptability_scenarios_resampled.tiff - Acceptability raster for scenarios, adapted with a resampling size.
	Vulnerability_scenarios.tiff - Vulnerability raster for the scenarios, accounting for the vuln``_`` scenarios.
	Masked_River_extent_scenarios.tiff (optionnal) -Mask of the riverbed trace for the scenarios situation. If not present, the mask of the baseline river was utilized.

Graphical User Interface (GUI)

A Graphical User Interface (GUI) was created to allow users to interact with the code through a user-friendly menu with buttons, windows, and other elements designed to facilitate code management. The GUI for acceptability is accessible via File > Create > Acceptability manager, as in the picture below.

And the manager appears, as in the picture below. The different parts of the window are explained later.

Computation step by step

The Acceptability Manager interface enables users to navigate and select directories, study areas, and scenarios, with step-by-step control over relevant data files.

The first step involves loading the main directory : Use the Main Directory button to select the primary folder, which must at least contain subdirectory named INPUT and its subfolders

Note

TEMP and OUTPUT will be created if not present.

Then, the user has two options: either he already has an acceptability file with study areas and scenarios including hydraulic simulations, or not.

Existing study area and scenario

1. Select a Study Area: In the second column, available study areas will be listed. Click on the appropriate study area to proceed.

2. Choose a Scenario: Upon selecting a study area, the third column displays associated scenarios. Select the desired scenario to view the corresponding data.

No file or new hydraulic scenario

When the user has no file or wishes to load a new hydraulic scenario, the second option consist in :

1. Load new hydraulic scenarios:

A window opens and asks the user (see comment at top left of window) to enter the simulations folder, named with the study area (e.g. Theux or Pepinster), then a second window opens and asks the user to point to the scenario (e.g scenario_actual) containing the simulation files. The latter must be named with ‘scenario_’. The window is then self-actualizing, displaying the study area (in the example ‘Theux’) and the selected scenario (in the example ‘scenario_actual’). The entire folder structure is created at this stage, without the user having to worry about it. In the event that the code detects changes in topography relative to a baseline (typically WOLF tif files called bath_) it duplicates them and sets them to 1 and places them in INPUT > CHANGE_VULNE. These consist of local rasters that can be used to take scenarios into account (see sections on taking scenarios into account below). Windows with reminder messages when it’s time to modify files will appear later.

2. Selecting simulations

In the next box is a checklist of ‘sim_’ simulations found in the simulation folder. The user is asked to check off those he wishes to take into account in his acceptability calculations. As a reminder, the calculation requires water heights throughout the entire domain (free surface interpolated in impermeable objects such as buildings) and for different return periods (at least one).

3. Interpolation inputs creation

The following button Check DEM inputs for interpolation is used to create the inputs needed to calculate the interpolation of free surfaces. In particular, a pure DEM (raster with ground elevations, without buildings or walls) corresponding to the project must be given, as the user doesn’t have it a priori, it must be generated. To do this, a window appears asking the user to point to the DEM in the baseline. Next, the user needs to modify the DTMmodifiers (local modification rasters) in INPUT > CHANGE_VULNE, taking into account topographic modifications only (e.g. widening of the river bed). Once done, the inputs are created automatically.

4. Creating hydraulic input for acceptability computations

The next button will generate the precise input required by the acceptability calculation: the water level for a certain return period reached in the study area. This button launches the interpolation routine and generates this data. Outputs are saved in INPUT > WATER_DEPTH > … > INTERP_WD. For details of the calculation, see the note below.

Other buttons/rows

The first line has three “check” buttons:

1. Check structure : Checks the INPUT, TEMP and OUTPUT structure of the main folder. It also checks for missing inputs and lists them (see logs). The TEMP and OUTPUT structure is corrected/created if this is not the case.

2. Check simulations : Allows the user to view the interpolated simulations that exist in the selected scenario.

3. Check ponderation : Allows the user to see the weighting coefficient that will be used for the weighted sum of acceptability rasters calculated for each return period. As a reminder, the score ranges from -2 to +2. For each level of vulnerability, a score between -2 and 2 is assigned according to water level and return period. Thus, for each simulated T, an acceptability raster is generated, where each cell has a score within this range. When the scores are combined, the final acceptability must remain within this range. This is why the weighting coefficients are defined so that their sum is equal to 1 and they are decreasing (monotonic), thus ensuring that the weighted sum remains between -2 and 2. An example is given below, with such coefficients calculated for three return periods : 2, 25, 50.

Note

The interpolation algorithm is:

1. Reading matrices (.bin): free surface elevation, mask/constraint, DEM

2. Identifying areas to fill: (value = 0.0)

3. Sorting areas to process in ascending order of the number of values

4. Processing areas in ascending order (nb - nbavoid with nbavoid = number of areas to ignore)

1. Identifying the sub-matrix containing the hole

2. Initializing the FMM (cells to fill + fringe cells with values to interpolate)

3. Calculating the FMM with information propagation (same weighting as distance)

4. The interpolated value is used only if it is higher than the mask/constraint

5. Retrieving interpolated elevations from partial matrices

6. Subtracting the DEM to obtain a water height [m]

7. Writing the result outputs

Note

An example of the simulation file to be loaded is shown in the figure below. Files must be named as “sim_T”, completed by the return period, e.g. ‘sim_T4’.

The third row of the manager specifies first the properties of the simulation rasters with which he output raster will be custom-designed. In particular, if the code does not detect interpolated files, the fields remain empty, otherwise the resolution, number of cells and origin will be displayed. Finally, the number of threads available for computation has to be specified. If the user selects more threads than available on the computer, the code will automatically default to the maximum possible.

The fourth row is about the DataBase Creation button, discussed at the beginning of this document. Next to this button, the user can check boxes corresponding to internal steps in the data creation database.

The fifth row is about is about the management of modified vulnerability scenarios ‘vuln``_``’, placed in INPUT > CHANGE_VULNE` :

1. Check scenarios: Checks whether ‘vuln``_``’ files exist in INPUT/CHANGE_VULNE, and displays them accordingly.

2. Update riverbed:

   This button allows to change the record of the riverbed trace if the scenarios envisaged modify it. Two options are available when activated: weither a file of the modified riverbed trace exists and you simply point to it, or not, and the code asks you to point to a low-flow simulation in the new trace. A calculation is automatically run to create the new trace. In particular for the following steps, if no scenario riverbed trace has been created (called Masked_riverbed_scenarios.tiff), then the baseline riverbed trace (Masked_riverbed_baseline.tiff) is used.

3. Accounting for scenarios

   This toggle button (i.e. ON/OFF button) has to be activated if vulnerability and acceptability calculations are to take these files into account. The button state is ‘ON’ if the box is grey, and ‘OFF’ otherwise.

4. Resampling [m]

   Finally, this box must be filled with a value in meter if the acceptability final raster is desired agglomerate. In addition, the toggle button Resampling must be activated is so (‘ON’ if the box is grey, ‘OFF’ otherwise).

The sixth row performs vulnerability calculations, generating the outputs Vulnerability_Code_baseline.tiff and Vulnerability_baseline.tiff in the directory OUTPUT\StudyArea_example\Scenario_example\baseline. If the user has added vulnerability scenarios to INPUT\CHANGE_VULNE\StudyArea_example\Scenario_example\baseline, the output reflecting these local changes will be named Vulnerability_scenario.tiff in the folder vuln_ scenarios. In addition, the stream trace file is stored in this output folder.

Similarly, in the same output directory, the final row calculates acceptability and produces Acceptability_baseline.tiff in the baseline scenario (and possibly Acceptability_scenarios.tiff in the vuln``_` scenarios` folder). Additionally, an aggregated file at the resampling size indicated earlier is generated if the toggle button Resampling size was activated.

By way of illustration, once the window has been loaded with a simulation, a study area and a scenario, the manager’s window could appear as shown in the example below.

Including scenarios

In addition to the main calculations, the manager includes a function for exploring scenarios that deviate from the baseline. Here, “baseline” refers to the default condition in which all input information is fully available (e.g. building occupancy, river course…).

For the study of “scenarios” that differ from a “baseline” situation, a raster overlay procedure is available in the manager. This takes an initial raster, and superimposes smaller rasters. This enables the necessary inputs to be modified to take account of changes made by a project.

These modifications will affect the calculation in two ways. Firstly, the reading of hydraulic simulations automatically recognizes potential changes in topography (‘bath’ file of simulations) and creates local rasters to be modified in INPUT > CHANGE_VULNE. These are initiated with default values, allowing the user to quickly notice whether or not they have been taken into account.

1. When processing hydrodynamic results, the acceptability routine requires interpolated free surface files. These are calculated with a routine that requires the DEM (MNT IN FRENCH) used for the simulations. As this file does not exist a priori (since we have a DEM with buildings and low walls), it must be generated. To do this, point to a baseline DEM via the ‘Check DEM inputs for interpolation’ button, then change the local modification rasters named ‘MNTmodifs’, generated in INPUT > CHANGE_VULNE after reading the simulation files pointed to via the ‘Load new hydraulic simulation’ button. Finally, the ‘Reading and interpolating free surface’ button creates the final DEM, and interpolates the simulations as required. An example is shown in the image below: on the left is the baseline file without project, in the middle the topographic changes and on the right the final result. As a reminder, the value ‘99999.0’ can be used on WOLF to hide data (and therefore not overlay anything).

2. When calculating vulnerability, if a building has changed function, its vulnerability value must be changed manually. In addition, the hydraulic scenario for the river alignment must also be taken into account, as well as any potential buildings removed from the baseline… The idea is the same: first calculate the vulnerability of the baseline (without scenarios), then overlay the vuln files.

Command-Line Interface (CLI)

If the user wants to execute the routine via the command line, this can be achieved using the wolf_accept script.

Help

First of all, the help command is omnipresent for displaying the arguments associated with the desired function, for example

wolf_accept --help

And the following output should be displayed

================= Command Line Interface for Acceptability routine =================

usage: wolf_accept [-h] {check,base_data_creation,vulnerability,acceptability} ...

A tool to obtain vulnerability and acceptability for regions in Walloon Region and particularly in Vesdre valley.

positional arguments:
  {check,base_data_creation,vulnerability,acceptability}
    check               Check the status and process data.
    base_data_creation  Create the base data needed for the vulnerability and acceptability rasters.
    vulnerability       Compute the total vulnerability raster.
    acceptability       Compute the acceptability rasters.

options:
  -h, --help            show this help message and exit

As indicated, four functions can be used and are detailed below. Each of these functions takes arguments, called ‘options’ in the CLI.

Warning

More specifically, each option must be preceded by a double hyphen ‘–’ with the name of the argument. On the other hand, the order of the arguments does not matter.

The help section below writes what the “–help” command tells the user.

Function “check”

This function launches the Accept_Manager class in the file acceptability.py, which automatically checks whether files are present or missing in the structure. It has multiple options that can be showed with the command wolf_accept check –help

- dir (str, optional): Path to the main directory containing all folders, setting the location for inputs and outputs. Default is 'Data'.
- GDB (str, optional): Name of the main GDB file, such as 'GT_Resilence_dataRisques202010.gdb'. Default is 'GT_Resilence_dataRisques202010.gdb'.
- CaPa (str, optional): Name of the Cadaster geopackage, e.g., 'Cadastre_Walloon.gpkg'. Default is 'Cadastre_Walloon.gpkg'.
- PICC (str, optional): Name of the PICC GDB file, e.g., 'PICC_vDIFF.gdb'. Default is 'PICC_vDIFF.gdb'.
- CE (str, optional): Name of the river extent file from IGN, such as 'CE_IGN_top10v.shp'. Default is 'CE_IGN_TOP10V/CE_IGN_TOP10V.shp'.
- scenario (str, optional): Scenario name. Default is 'Scenario1'.
- study_area (str, optional): Area of interest, such as 'Theux', 'Chaudfontaine', 'Eupen', etc. Default is 'Bassin_Vesdre'.

Note

Usage example: wolf_accept check –dir C:MainFolder –GDB GT_Resilence_dataRisques202010.gdb –scenario Scenario_example

Function “base_data_creation”

This function launches the python function Base_data_creation defined in acceptability.py that

• Step 1 : Clip the original gdb file to the study area

• Step 2 : Clip the Cadastre Walloon file to the study area

• Step 3 : Clip the PICC Walloon file to the study area

• step 4 : Clip and Rasterize the IGN top10v file

• Step 5 : Rasterize the IGN data “Course d’eau” to get the riverbed mask

• Step 6 : Pre-process the Vulnerability by saving the database with vulnerability levels and codes

• Step 7 : Rasterize the database

Different options can be indicated and can be shown with the command wolf_accept base_data_creation –help. They consist in giving the name of the right file needed in the input.

- dir (str, optional):
  Path to the main directory containing all folders, setting the location for inputs and outputs.
  Default is 'Data'.

- GDB (str, optional):
  Name of the main GDB file.
  Default is 'GT_Resilence_dataRisques202010.gdb'.

- study_area (str, optional):
  Name of the study area shapefile, such as 'Bassin_Vesdre.shp'.
  Default is 'Bassin_Vesdre.shp'.

- CaPa (str, optional):
  Name of the Cadaster geopackage, e.g., 'Cadastre_Walloon.gpkg'.
  Default is 'Cadastre_Walloon.gpkg'.

- PICC (str, optional):
  Name of the PICC GDB file, e.g., 'PICC_vDIFF.gdb'.
  Default is 'PICC_vDIFF.gdb'.

- CE (str, optional):
  Name of the river extent file from IGN, e.g., 'CE_IGN_TOP10V/CE_IGN_TOP10V.shp'.
  Default is 'CE_IGN_TOP10V/CE_IGN_TOP10V.shp'.

- resolution (float, optional):
  Resolution of the water depth files in meters.
  Default is 1.0.

- number_procs (int, optional):
  Number of processors to use.
  Default is 1.

- steps (int, optional, multiple):
  Step(s) to perform, specified as a space-separated list, e.g., '--steps 5 6 7'.
  Default is [1, 2, 3, 4, 5, 6, 7].

- Vuln_csv (str, optional):
  Path to the .csv file for the weights.
  Default is 'Vulnerability.csv'.

Note

Usage example: wolf_accept base_data_creation –dir C:MainFolder –GDB GT_Resilence_dataRisques202010.gdb –steps 3 4

Function vulnerability

This function launches the python function vulnerability defined in acceptability.py that has different steps. Note that steps 1, 2, and 3 must be launched for the first time. Then, to be more rapid, the steps can be selected as:

• Step 1: Compute the vulnerability rasters for the study area. The data will not be impacted by the scenario modifications. Two sub-steps: ‘10’ to compute the vulnerability and ‘11’ to compute the code associated with the vulnerability.

• Step 2: Compute the vulnerability rasters for the scenario. The data will be impacted by the scenario modifications.

• Step 3: Clip the vulnerability/code rasters to the simulation area.

Different options can be indicated and can be shown with the command wolf_accept vulnerability –help. They consist in giving the name of the right file needed in the input.

- dir (str, optional):
    Path to the main directory containing all folders, setting the location for inputs and outputs.
    Default is 'Data'.

- scenario (str, optional):
    Name of the scenario.
    Default is 'Scenario1'.

- study_area (str, optional):
    Area of interest, such as 'Theux', 'Chaudfontaine', 'Eupen', etc.
    Default is 'Bassin_Vesdre'.

- resolution (float, optional):
    Resolution for the vulnerability raster in meters.
    Default is 1.0.

- steps (int, optional, multiple):
    Step(s) to perform, specified as a space-separated list, e.g., '--steps 2 3 4'.
    Default is [1, 10, 11, 2, 3].

- Vuln_csv (str, optional):
    Path to the .csv file for vulnerability layers.
    Default is 'Vulnerability.csv'.

- Intermediate_csv (str, optional):
    Path to the .csv file for acceptability functions (scoring layers based on water depth).
    Default is 'Intermediate.csv'.

Note

Usage example: wolf_accept vulnerability –scenario Scenario_example –study_area Bassin_Vesdre –dir C:\example –steps 1 10 11

Function acceptability

This function launches the python function acceptability defined in acceptability.py that has different steps. Note that steps 1, 2, and 3 must be launched for the first time. Then, to be more rapid, the steps can be selected as:

• Step 1: Compute acceptability for each return period

• Step 2: Load/Reload the acceptability values from files

• Step 3: Compute the weigted sum of acceptability rasters for the ‘combined acceptability’ raster

Different options can be indicated and can be shown with the command wolf_accept acceptability –help. They consist in giving the name of the right file needed in the input.

- dir (str, optional):
    Path to the main directory containing all folders, setting the location for inputs and outputs.
    Default is 'Data'.

- study_area (str, optional):
    Name of the area of interest.
    Default is 'Bassin_Vesdre'.

- scenario (str, optional):
    Name of the scenario to use.
    Default is 'Scenario1'.

- coeff_auto (bool, optional):
    Indicates if weighting coefficients should be re-computed automatically.
    Default is True.

- Ponderation_csv (str, optional):
    Path to the .csv file from which weighting coefficients are read.
    Default is 'Ponderation.csv'.

- resample_size (int, optional):
    Resolution at which the final raster will be aggregated, in meters.
    Default is 100m.

- steps (int, optional, multiple):
    Specific step(s) to execute, given as a space-separated list, e.g., '--steps 2 3'.
    Default is [1, 2, 3].

Note

Usage example: wolf_accept acceptability –scenario Scenario_example –study_area Bassin_Vesdre –dir C:\Example –steps 1 2 3