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
Uncertainty and sensitivity analysis: preparing inputs
2026-11-13
Note
Une version française de cet article est disponible : Analyse d’incertitude et de sensibilité : préparation des entrées.
Overview
The transition from a full deterministic Case object (imported from an .ods or .xlsx workbook via import_case()) to the meta-model inputs required by perform_sa() relies on two main functions:
-
prepare_uncertainty(): ensures a complete, validateduncertaintytable on theCaseobject (either imported from theuncertaintysheet or generated from package defaults); -
prepare_sa(): extracts and normalizes the project’s calendar, costs, flood hazard parameters, and avoided damages into a singlesa_inputlist.
Let us illustrate this workflow on the complete.ods case shipped with the package:
Uncertainty table (uncertainty slot)
Each uncertain parameter is described by four columns: parameter, min, max, and type ("relative" or "absolute").
When import_case() reads a file without an explicit uncertainty sheet (or when prepare_uncertainty(case) is called directly), bounds are generated automatically from 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"Let us inspect the resulting uncertainty table in 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 |
Notice two key properties:
-
Automatic non-overlapping return periods: return-period bounds (
period_*) are converted to"absolute"values and truncated at the midpoint between adjacent nominal return periods viaprepare_flood_range(), guaranteeing that flood scenarios remain strictly ordered during Monte Carlo sampling. -
User overrides: you can provide custom bounds either in an
uncertaintysheet in your spreadsheet or by passing a customdata.frametoprepare_uncertainty(case, uncertainty = ...).
Building sa_input with prepare_sa()
prepare_sa(case, project) assembles all components needed to evaluate a given project ("complete" here):
sa_input = prepare_sa(case, "complete")
names(sa_input)
#> [1] "calendar" "cost" "flood" "impact" "case" "project"
#> [7] "reference" "rate" "n"Each component corresponds to a dedicated helper function:
1. Normalized calendar (prepare_sa_calendar())
prepare_sa_calendar() merges the normalized benefit activation schedule (benefit in , computed from the project’s state sequence and avoided average annual damages) with the normalized annual disbursement schedules for each active cost item:
| 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 |
Note that cost items with zero disbursement across the entire horizon (for instance an action whose step_duration is Inf and whose after_maintenance never activates) are excluded from both calendar and cost.
2. Project costs (prepare_sa_cost())
prepare_sa_cost() extracts the nominal investment (cost_during) and maintenance (cost_after) totals per action and pairs them with their uncertainty bounds:
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 |
Maintenance savings (negative cost_after values) are preserved so that uncertainties apply symmetrically to net maintenance cash flows.
Note
In the current implementation,
prepare_sa()assumes that costs in the reference situation (reference) are zero, rather than computing differential costs betweenprojectandreference.
3. Flood hazard parameters (prepare_sa_flood())
prepare_sa_flood() pairs the global nominal return periods (period_nominal) and nominal hydraulic efficiency (hydraulic_nominal = 1) with their uncertainty bounds:
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. Avoided damages by stake (prepare_sa_impact())
prepare_sa_impact() computes the nominal avoided damages between the project’s initial and final states (format_impact()), aggregated across sectors and paired with stake uncertainty bounds (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. Project metadata
Finally, sa_input stores the metadata required by perform_sa() and the plotting functions:
-
case: case study name (case["name"],"complete"here), used in output filenames; -
project: evaluated project name ("complete"); -
reference: baseline project name ("baseline"); -
rate: discount rate schedule (case["rate"]); -
n: default Monte Carlo sample size (getOption("floodam.cba")[["n_uncertainty"]]).