Skip to contents

Note

An English version of this article is available: Uncertainty and sensitivity analysis: preparing inputs.

Vue d’ensemble

Le passage d’un objet Case complet (importé depuis un classeur .ods ou .xlsx via import_case()) aux données d’entrée du méta-modèle perform_sa() repose sur deux fonctions principales :

  1. prepare_uncertainty() : construit et valide la table uncertainty de l’objet Case (lue depuis l’onglet uncertainty s’il existe, ou générée à partir des valeurs par défaut du package) ;
  2. prepare_sa() : extrait et normalise le calendrier du projet, les coûts, les paramètres d’aléa et les dommages évités dans une liste structurée sa_input.

Illustrons cette étape sur le cas complete.ods fourni avec le package :

path = system.file("extdata", "case", "complete.ods", package = "floodam.cba")
case = import_case(path)
#> import Case from /usr/local/lib/R/site-library/floodam.cba/extdata/case/complete.ods
#>  ... done

Table des incertitudes (slot uncertainty)

Chaque paramètre incertain est défini par quatre colonnes : parameter, min, max et type ("relative" ou "absolute").

Lorsque import_case() lit un fichier sans onglet uncertainty explicite (ou lorsque prepare_uncertainty(case) est appelée directement), les bornes sont générées à partir de getOption("floodam.cba")[["uncertainty_default"]] :

getOption("floodam.cba")[["uncertainty_default"]]
#> $cost
#> $cost$min
#> [1] 0
#> 
#> $cost$max
#> [1] 0.5
#> 
#> $cost$type
#> [1] "relative"
#> 
#> 
#> $flood
#> $flood$min
#> [1] -0.3
#> 
#> $flood$max
#> [1] 0.3
#> 
#> $flood$type
#> [1] "relative"
#> 
#> 
#> $hydraulic
#> $hydraulic$min
#> [1] -0.3
#> 
#> $hydraulic$max
#> [1] 0.3
#> 
#> $hydraulic$type
#> [1] "relative"
#> 
#> 
#> $stake_dam
#> $stake_dam$min
#> [1] -0.5
#> 
#> $stake_dam$max
#> [1] 0.5
#> 
#> $stake_dam$type
#> [1] "relative"

Examinons la table uncertainty générée pour case :

knitr::kable(case["uncertainty"])
parameter min max type
cost_investment_nothing 0.000000 0.50000 relative
cost_investment_raising 0.000000 0.50000 relative
cost_investment_reinforcement 0.000000 0.50000 relative
cost_maintenance_nothing 0.000000 0.50000 relative
cost_maintenance_raising 0.000000 0.50000 relative
cost_maintenance_reinforcement 0.000000 0.50000 relative
period_flood_min 5.833333 10.83333 absolute
period_flood_med 52.500000 97.50000 absolute
period_flood_max 583.333333 1083.33333 absolute
hydraulic_flood_min -0.300000 0.30000 relative
hydraulic_flood_med -0.300000 0.30000 relative
hydraulic_flood_max -0.300000 0.30000 relative
stake_activity -0.500000 0.50000 relative
stake_agriculture -0.500000 0.50000 relative
stake_dwelling -0.500000 0.50000 relative
stake_public -0.500000 0.50000 relative

Deux propriétés importantes sont assurées automatiquement :

  • Non-chevauchement des périodes de retour : les bornes period_* sont converties en valeurs "absolute" et tronquées au point milieu entre deux périodes nominales adjacentes via prepare_flood_range(), garantissant que l’ordre des crues reste strictement croissant lors des tirages Monte Carlo.
  • Personnalisation : vous pouvez fournir vos propres bornes via un onglet uncertainty dans le tableur ou en passant un data.frame personnalisé à prepare_uncertainty(case, uncertainty = ...).

Construction de sa_input avec prepare_sa()

prepare_sa(case, project) assemble toutes les composantes nécessaires à l’évaluation d’un projet donné (ici "complete") :

sa_input = prepare_sa(case, "complete")
names(sa_input)
#> [1] "calendar"  "cost"      "flood"     "impact"    "case"      "project"  
#> [7] "reference" "rate"      "n"

Chaque élément est produit par une fonction dédiée :

1. Calendrier normalisé (prepare_sa_calendar())

prepare_sa_calendar() fusionne la chronique normalisée d’activation des bénéfices (benefit dans [0,1][0, 1], calculée à partir de la séquence d’états du projet et des dommages évités moyens annuels) avec les chroniques annuelles normalisées de décaissement de chaque poste de coût actif :

knitr::kable(head(sa_input[["calendar"]], 8), digits = 4)
year benefit investment_raising maintenance_raising investment_reinforcement maintenance_reinforcement
0 0.0000 0.00 0 0.0000 0.0
1 0.0000 0.00 0 0.1667 0.0
2 0.0000 0.00 0 0.4167 0.0
3 0.0000 0.00 0 0.4167 0.5
4 1.3545 0.08 0 0.0000 1.0
5 1.3545 0.12 0 0.0000 1.0
6 1.3545 0.80 0 0.0000 1.0
7 1.0000 0.00 1 0.0000 1.0

Les postes de coût dont le décaissement est nul sur tout l’horizon (par exemple une action de durée infinie dont after_maintenance ne s’active jamais) sont écartés à la fois de calendar et de cost.

2. Coûts du projet (prepare_sa_cost())

prepare_sa_cost() extrait les totaux nominaux d’investissement (cost_during) et de maintenance (cost_after) par action, appariés avec leurs bornes d’incertitude :

knitr::kable(sa_input[["cost"]])
parameter nominal min max type
1 investment_raising 2500 0 0.5 relative
2 investment_reinforcement 1200 0 0.5 relative
4 maintenance_raising 100 0 0.5 relative
5 maintenance_reinforcement -100 0 0.5 relative

Les économies de maintenance (valeurs négatives de cost_after) sont bien conservées afin que les incertitudes s’appliquent symétriquement aux flux de maintenance nets.

Note

Dans l’implémentation actuelle, prepare_sa() repose sur l’hypothèse que les coûts de la situation de référence (reference) sont nuls, sans calcul en différentiel entre project et reference.

3. Paramètres d’aléa (prepare_sa_flood())

prepare_sa_flood() associe les périodes de retour nominales globales (period_nominal) et l’efficacité hydraulique nominale (hydraulic_nominal = 1) à leurs bornes d’incertitude :

knitr::kable(sa_input[["flood"]])
scenario period_nominal period_min period_max period_type hydraulic_nominal hydraulic_min hydraulic_max hydraulic_type
flood_min 8.333333 5.833333 10.83333 absolute 1 -0.3 0.3 relative
flood_med 75.000000 52.500000 97.50000 absolute 1 -0.3 0.3 relative
flood_max 833.333333 583.333333 1083.33333 absolute 1 -0.3 0.3 relative

4. Dommages évités par enjeu (prepare_sa_impact())

prepare_sa_impact() calcule les dommages évités nominaux entre l’état initial et l’état final du projet (format_impact()), agrégés sur les secteurs et appariés aux incertitudes sur les enjeux (stake_*) :

knitr::kable(sa_input[["impact"]], digits = 2)
stake flood_min flood_med flood_max min max type
activity 0 1749.90 7998 -0.5 0.5 relative
agriculture 0 -1599.90 -4998 -0.5 0.5 relative
dwelling 0 -430.26 6498 -0.5 0.5 relative

5. Métadonnées du projet

Enfin, sa_input conserve les métadonnées utilisées par perform_sa() et les fonctions graphiques :

  • case : nom du cas d’étude (case["name"], ici "complete"), utilisé pour nommer les fichiers graphiques exportés ;
  • project : nom du projet évalué ("complete") ;
  • reference : nom du projet de référence ("baseline") ;
  • rate : chronique de taux d’actualisation (case["rate"]) ;
  • n : taille d’échantillon Monte Carlo par défaut (getOption("floodam.cba")[["n_uncertainty"]]).