Skip to contents

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:

  1. prepare_uncertainty(): ensures a complete, validated uncertainty table on the Case object (either imported from the uncertainty sheet or generated from package defaults);
  2. prepare_sa(): extracts and normalizes the project’s calendar, costs, flood hazard parameters, and avoided damages into a single sa_input list.

Let us illustrate this workflow on the complete.ods case shipped with the 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

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 via prepare_flood_range(), guaranteeing that flood scenarios remain strictly ordered during Monte Carlo sampling.
  • User overrides: you can provide custom bounds either in an uncertainty sheet in your spreadsheet or by passing a custom data.frame to prepare_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 [0,1][0, 1], computed from the project’s state sequence and avoided average annual damages) with the normalized annual disbursement schedules for each active cost item:

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

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 between project and reference.

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