COINr (version 1.1.14)

get_opt_weights: Weight optimisation

Description

This function provides optimised weights to agree with a pre-specified vector of "target importances".

Usage

get_opt_weights(
  coin,
  itarg = NULL,
  dset,
  Level,
  cortype = "pearson",
  optype = "balance",
  toler = NULL,
  maxiter = NULL,
  weights_to = NULL,
  out2 = "list"
)

Value

If out2 = "coin" returns an updated coin object with a new set of weights in .$Meta$Weights, plus details of the optimisation in .$Analysis. Else if out2 = "list" the same outputs (new weights plus details of optimisation) are wrapped in a list.

Arguments

coin

coin object

itarg

a vector of (relative) target importances. For example, c(1,2,1) would specify that the second indicator should be twice as "important" as the other two.

dset

Name of the aggregated data set found in coin$Data which results from calling Aggregate().

Level

The aggregation level to apply the weight adjustment to. This can only be one level.

cortype

The type of correlation to use - can be either "pearson", "spearman" or "kendall". See stats::cor.

optype

The optimisation type. Either "balance", which aims to balance correlations according to a vector of "importances" specified by itarg (default), or "infomax" which aims to maximise overall correlations.

toler

Tolerance for convergence. Defaults to 0.1 (decrease for more accuracy, increase if convergence problems).

maxiter

Maximum number of iterations. Default 500.

weights_to

Name to write the optimised weight set to, if out2 = "coin".

out2

Where to output the results. If "coin" (default for coin input), appends to updated coin, creating a new list of weights in .$Parameters$Weights. Otherwise if "list" outputs to a list (default).

Details

This is a linear version of the weight optimisation proposed in this paper: tools:::Rd_expr_doi("10.1016/j.ecolind.2017.03.056"). Weights are optimised to agree with a pre-specified vector of "importances". The optimised weights are returned back to the coin.

See vignette("weights") for more details on the usage of this function and an explanation of the underlying method. Note that this function calculates correlations without considering statistical significance.

This function replaces the now-defunct weightOpt() from COINr < v1.0.

Examples

# build example coin
coin <- build_example_coin(quietly = TRUE)

# check correlations between level 3 and index
get_corr(coin, dset = "Aggregated", Levels = c(3, 4))

# optimise weights at level 3
l_opt <- get_opt_weights(coin, itarg = "equal", dset = "Aggregated",
                        Level = 3, weights_to = "OptLev3", out2 = "list")

# view results
tail(l_opt$WeightsOpt)

l_opt$CorrResultsNorm