sensitivity: Sensitivity analysis
In COINr: Composite Indicator Construction and Analysis

Description Usage Arguments Details Value See Also Examples

Performs global uncertainty and sensitivity analysis on a COIN.

sensitivity(
  COIN,
  v_targ,
  SA_specs,
  N,
  SA_type = "UA",
  NrepWeights = 1000,
  store_results = "results+params",
  Nboot = NULL,
  quietly = FALSE
)

`COIN`	A COIN (this function does not support data frame input)
`v_targ`	The target variable to perform SA or UA on. Currently just supports one variable, which should be an indicator/aggregate code present in `.$Data$Aggregated`.
`SA_specs`	A list which specifies which variables to perturb, and which alternatives/distributions to use
`N`	The number of Monte Carlo replications.
`SA_type`	The type of analysis to run. `"UA"` runs an uncertainty analysis. `"SA"` runs a sensitivity analysis (which anyway includes an uncertainty analysis).
`NrepWeights`	The number of weight-replications to generate. Default 1000.
`store_results`	Which results to store `"onlyresults"` only stores scores, ranks and rank statistics (e.g. mean, median, quantiles) `"results+params"` (default) stores all of the above, plus a record of the parameter values used for each replication `"results+method"` stores all of the above, plus the full `.$Method` list of each replication `"results+COIN"` stores all results and the complete COIN of each replication (this could result in a very large list).
`Nboot`	Number of bootstrap draws for estimates of confidence intervals on sensitivity indices. If this is not specified, bootstrapping is not applied. Ignored if `SA_type = "UA"`.
`quietly`	If `FALSE` (default), gives progress messages. Set `TRUE` to suppress these.

To perform a sensitivity or uncertainty analysis, you must specify which parameters/assumptions to vary and what their alternative values are. This is the SA_specs argument below. To understand how this works, please see the COINr online documentation.

The output of this function can be visualised with the functions plotSARanks() and plotSA().

Sensitivity analysis results as a list, containing:

.$Scores a data frame with a row for each unit, and columns are the scores for each replication.
.$Parameters a record of the parameters used for each iteration
.$Ranks as .$Scores but for unit ranks
.$RankStats summary statistics for ranks of each unit
.$Nominal the nominal scores and ranks of each unit (i.e. from the original COIN)
Some information on the time elapsed, average time, and the parameters perturbed.
Depending on the setting of store_results, may also contain a list of Methods or a list of COINs for each replication.

plotSARanks() Plot confidence intervals of ranks following UA or SA
plotSA() Plot sensitivity indices following a sensitivity analysis

# build ASEM COIN up to aggregation
ASEM <- build_ASEM()

# define noise to be applied to weights
nspecs <- data.frame(AgLevel = c(2,3), NoiseFactor = c(0.25,0.25))

# create list specifying assumptions to vary and alternatives
SAspecs <- list(
  impute = list(imtype = c("indgroup_mean", "ind_mean", "none")),
  normalise = list(ntype = c("minmax", "rank", "dist2max")),
  weights = list(NoiseSpecs = nspecs, Nominal = "Original")
)

# run uncertainty analysis
# here we set N deliberately much lower than normal to enable quick testing
# Would recommend in a practical case to increase to perhaps 500 (more is always better)
SAresults <- sensitivity(ASEM, v_targ = "Index",
                         SA_specs = SAspecs,
                         N = 15,
                         SA_type = "UA")

# to run a sensitivity analysis set SA_type = "SA" (takes longer)