Skip to contents

Conduct global sensitivity analysis (GSA) and uncertainty analysis on a Cost-Benefit Analysis (CBA) project model using variance-based Sobol indices.

Usage

perform_sa(
  sa_input,
  project = NULL,
  sobol_method = c("sobolmartinez", "sobol2002", "sobolSalt", "sobol2007", "soboljansen",
    "soboltouati", "nominal"),
  n = NULL,
  rate = NULL,
  verbose = getOption("floodam.cba.verbose"),
  ...
)

Arguments

sa_input

An object of class Case or a prepared sensitivity analysis input list generated by prepare_sa().

project

Character scalar, name of the project to analyze. If NULL (default) and sa_input is a Case, the first project differing from the reference baseline is automatically selected. Ignored if sa_input is already a prepared list.

sobol_method

Character scalar specifying the Sobol index estimation method from package sensitivity, or "nominal". One of "sobolmartinez" (default), "sobol2002", "sobolSalt", "sobol2007", "soboljansen", "soboltouati", or "nominal". If "nominal", only the deterministic baseline evaluation is performed and returned.

n

Integer scalar, Monte Carlo sample size for parameter sampling. If NULL (default), the value defined in sa_input[["n"]] is used.

rate

Discount rate specification. If NULL (default), the discount rate from sa_input[["rate"]] is used.

verbose

Logical scalar indicating whether progress messages and computation times should be printed (defaults to getOption("floodam.cba.verbose")).

...

Additional arguments forwarded to the selected Sobol function in package sensitivity.

Value

Depending on sobol_method:

  • If sobol_method = "nominal", an invisible 1-row numeric matrix of nominal parameters, baseline avoided damages, expected annual benefit (benefit), and net present value (npv) as returned by sa_calculate_nominal().

  • Otherwise, an invisible S3 object of class c("cba_uncertainty", "list") with components:

    • nominal: A 1-row numeric matrix of nominal parameters and model outputs as returned by sa_calculate_nominal().

    • u_a: A data.frame containing parameter draws and corresponding model outputs (impact, benefit, npv) for uncertainty analysis.

    • s_a: A named list with elements npv and benefit, each containing the Sobol sensitivity results (S for first-order indices, T for total-order indices, and V for variances).

    • input: The sa_input list used for the analysis.

Details

This function is the main high-level interface for uncertainty and sensitivity analysis in floodam.cba.

If sa_input is a Case object, prepare_sa() is called to extract and structure the required inputs for the specified project (or the first non-reference project if project = NULL).

When sobol_method = "nominal", the function computes only the baseline deterministic evaluation via sa_calculate_nominal() and returns it directly, skipping parameter sampling and sensitivity analysis.

For other values of sobol_method, the complete analysis workflow proceeds as follows:

  1. Nominal model values are evaluated with sa_calculate_nominal().

  2. Two independent sample design matrices x1 and x2 of size n are drawn with sa_draw_parameter().

  3. The model is evaluated via sa_model() on the combined sample design matrix rbind(x1, x2[-1, , drop = FALSE]) to obtain empirical distributions of avoided damages per stake/scenario, expected annual benefit (benefit), and net present value (npv) for uncertainty analysis (u_a).

  4. A variance-based Sobol sensitivity analysis is performed for both the net present value (npv) and annual benefit (benefit) using the estimator specified by sobol_method from the sensitivity package, estimating first-order (S) and total-order (T) sensitivity indices.

Additional arguments in ... are forwarded to the selected Sobol function (e.g., conf, nboot).

Author

Frédéric Grelot, frederic.grelot.1994_cran@m4x.org

Examples

case = import_case(
    system.file("extdata", "case", "simple.ods", package = "floodam.cba")
)
#> import Case from /tmp/RtmpvMoJJK/temp_libpath2b69f6f14b9e9/floodam.cba/extdata/case/simple.ods
#>  ... done

# Compute nominal indicators only
nom = perform_sa(case, sobol_method = "nominal", verbose = FALSE)
nom[, c("benefit", "npv")]
#>  benefit      npv 
#> 14049.17 77715.21 

# Perform full sensitivity analysis
result = perform_sa(case, n = 100, verbose = FALSE)
#> Registered S3 method overwritten by 'sensitivity':
#>   method    from 
#>   print.src dplyr
names(result)
#> [1] "nominal" "u_a"     "s_a"     "input"  
head(result$u_a)
#>   cost_investment_dam_raising cost_investment_dyke_raising
#> 1                    80000.00                     115000.0
#> 2                   117674.28                     146225.7
#> 3                    89695.22                     138410.9
#> 4                    80273.66                     164158.9
#> 5                    98660.60                     136107.5
#> 6                   101343.97                     134131.7
#>   cost_maintenance_dam_raising cost_maintenance_dyke_raising period_flood_min
#> 1                     2000.000                      3000.000         5.000000
#> 2                     2574.367                      3128.955         3.782655
#> 3                     2777.312                      3151.090         4.193699
#> 4                     2071.363                      3453.643         6.059661
#> 5                     2693.028                      3959.594         3.699967
#> 6                     2247.483                      4259.376         6.305820
#>   period_flood_A period_flood_B period_flood_C period_flood_max
#> 1       30.00000       50.00000      100.00000         250.0000
#> 2       21.85389       56.34189       74.39041         236.4530
#> 3       23.77807       55.49967       73.04394         268.6197
#> 4       32.33598       53.75976      111.12229         257.7296
#> 5       26.35045       49.44629       89.55161         210.8874
#> 6       32.54199       50.62145       75.42800         309.5597
#>   hydraulic_flood_min hydraulic_flood_A hydraulic_flood_B hydraulic_flood_C
#> 1           1.0000000          1.000000         1.0000000         1.0000000
#> 2           1.1845539          1.070972         0.7351822         0.8256280
#> 3           1.1995714          1.056358         0.8325568         0.7268325
#> 4           0.9832404          1.206752         0.8338089         0.9196160
#> 5           0.9996511          1.003721         1.0015320         0.7650055
#> 6           0.8000631          1.013704         0.7468123         0.7862226
#>   hydraulic_flood_max impact_activity impact_agriculture impact_dwelling
#> 1           1.0000000       1.0000000          1.0000000       1.0000000
#> 2           1.0893029       0.5458640          1.2740263       1.1489862
#> 3           0.9995212       1.0679173          0.8177189       0.9483542
#> 4           1.2239899       0.6884705          1.0471646       0.9996546
#> 5           1.1895072       1.2410526          1.2361958       1.1996214
#> 6           0.9653947       0.8232766          0.8269823       0.7155009
#>   activity_flood_min activity_flood_A activity_flood_B activity_flood_C
#> 1                  0        10000.000         80000.00        100000.00
#> 2                  0         5846.048         32104.76         45068.06
#> 3                  0        11281.027         71128.15         77619.70
#> 4                  0         8308.129         45924.23         63312.85
#> 5                  0        12456.701         99436.31         94941.21
#> 6                  0         8345.584         49186.65         64727.87
#>   activity_flood_max agriculture_flood_min agriculture_flood_A
#> 1                  0                     0           -5000.000
#> 2                  0                     0           -6822.230
#> 3                  0                     0           -4319.018
#> 4                  0                     0           -6318.338
#> 5                  0                     0           -6203.976
#> 6                  0                     0           -4191.575
#>   agriculture_flood_B agriculture_flood_C agriculture_flood_max
#> 1          -10000.000          -10000.000                     0
#> 2           -9366.414          -10518.718                     0
#> 3           -6807.974           -5943.447                     0
#> 4           -8731.352           -9629.893                     0
#> 5          -12380.897           -9456.966                     0
#> 6           -6176.006           -6501.922                     0
#>   dwelling_flood_min dwelling_flood_A dwelling_flood_B dwelling_flood_C
#> 1                  0         18750.00         375000.0         750000.0
#> 2                  0         23072.47         316767.8         711476.4
#> 3                  0         18783.77         296084.5         516971.0
#> 4                  0         22618.78         312570.3         689473.7
#> 5                  0         22576.59         450547.2         688287.7
#> 6                  0         13599.48         200379.3         421907.3
#>   dwelling_flood_max   benefit        npv
#> 1                  0 14049.167   77715.21
#> 2                  0 13253.352  -31444.66
#> 3                  0 12156.575  -37168.25
#> 4                  0 11106.233  -73533.64
#> 5                  0 16793.550   70752.34
#> 6                  0  7325.467 -206645.07
result$s_a$npv$S
#>                                   original        bias std. error  min. c.i.
#> cost_investment_dam_raising   -0.018952908 0.009496557 0.08828457 -0.2419456
#> cost_investment_dyke_raising  -0.028956571 0.010562988 0.08548549 -0.2326105
#> cost_maintenance_dam_raising  -0.027294429 0.010633581 0.08801490 -0.2470838
#> cost_maintenance_dyke_raising -0.009346950 0.008391025 0.08465245 -0.2164809
#> period_flood_min              -0.052762065 0.009318185 0.08404570 -0.2566295
#> period_flood_A                 0.110870385 0.014316450 0.09663378 -0.1212782
#> period_flood_B                 0.023325170 0.008014806 0.08203128 -0.1913179
#> period_flood_C                -0.039088225 0.009596649 0.08870477 -0.2679396
#> period_flood_max              -0.036650663 0.009320127 0.08592109 -0.2380513
#> hydraulic_flood_min           -0.036705014 0.010527339 0.08729315 -0.2538129
#> hydraulic_flood_A             -0.036597276 0.010905486 0.08643099 -0.2601856
#> hydraulic_flood_B             -0.006300277 0.011697203 0.09404268 -0.2330432
#> hydraulic_flood_C              0.022405277 0.014256376 0.09213898 -0.1893091
#> hydraulic_flood_max           -0.036705014 0.010527339 0.08729315 -0.2538129
#> impact_activity                0.008920821 0.010743163 0.08972179 -0.2138102
#> impact_agriculture            -0.032139744 0.010154155 0.08830896 -0.2487247
#> impact_dwelling                0.681879276 0.007454307 0.04911780  0.5873208
#>                                max. c.i.
#> cost_investment_dam_raising   0.14787381
#> cost_investment_dyke_raising  0.13386329
#> cost_maintenance_dam_raising  0.13578182
#> cost_maintenance_dyke_raising 0.13407932
#> period_flood_min              0.09516327
#> period_flood_A                0.29759215
#> period_flood_B                0.17184652
#> period_flood_C                0.12392323
#> period_flood_max              0.12384955
#> hydraulic_flood_min           0.12533395
#> hydraulic_flood_A             0.11473961
#> hydraulic_flood_B             0.17921071
#> hydraulic_flood_C             0.19482273
#> hydraulic_flood_max           0.12533395
#> impact_activity               0.17516795
#> impact_agriculture            0.13359389
#> impact_dwelling               0.79617437