Coins
The Normalise() method for coins follows the familiar
format: you have to specify:
xthe coinglobal_specsdefault specifications to apply to all indicatorsindiv_specsindividual specifications to overrideglobal_specsfor specific indicators, if requireddirectionsa data frame specifying directions - this overrides the directions iniMetaif specifiedout2whether to output an updated coin or simply a data frame
Let’s begin with a simple example. We build the example coin and normalise the raw data.
library(COINr)
# build example coin
coin <- build_example_coin(up_to = "new_coin")
#> iData checked and OK.
#> iMeta checked and OK.
#> Written data set to .$Data$Raw
# normalise the raw data set
coin <- Normalise(coin, dset = "Raw")
#> Written data set to .$Data$NormalisedWe can compare one of the raw and un-normalised indicators side by side.
plot_scatter(coin, dsets = c("Raw", "Normalised"), iCodes = "Goods")
This plot also illustrates the linear nature of the min-max transformation.
The default normalisation uses the min-max approach, scaling
indicators onto the \([0, 100]\)
interval. But we can change the normalisation type and its parameters
using the global_specs argument.
coin <- Normalise(coin, dset = "Raw",
global_specs = list(f_n = "n_zscore",
f_n_para = list(c(10,2))))
#> Written data set to .$Data$Normalised
#> (overwritten existing data set)Again, let’s plot an example of the result:
plot_scatter(coin, dsets = c("Raw", "Normalised"), iCodes = "Goods")
Again, the z-score transformation is linear. It simply puts the resulting indicator on a different scale.
Notice the syntax of global_specs. If specified, it
takes entries f_n (the name of the function to apply to
each column) and f_n_para (any further arguments to
f_n, not including x). Importantly,
f_n_para must be specified as a list, even if it
only contains one parameter.
Note that COINr has a number of normalisation functions built
in, all of which are of the form n_*(), such as
n_minmax(), n_borda(), etc. Type
n_ in the R Studio console and press the Tab key to see a
list, or else browse the COINr functions alphabetically.
Calling external functions
Since f_n points to a function name, any function can be
passed to Normalise() as long as it is available in the
namespace. To illustrate, consider an example where we want to
categorise into discrete bins. We can use base R’s cut()
function for this purpose. We simply need to specify the number of bins.
We could directly call cut(), but for clarity we will
create a simple wrapper function around it, then pass that function to
Normalise().
# wrapper function
f_bin <- function(x, nbins){
cut(x, breaks = nbins, labels = FALSE)
}
# pass wrapper to normalise, specify 5 bins
coin <- Normalise(coin, dset = "Raw",
global_specs = list(f_n = "f_bin",
f_n_para = list(nbins = 5)))
#> Written data set to .$Data$Normalised
#> (overwritten existing data set)To illustrate the difference with the linear transformations above, we again plot the raw against normalised indicator:
plot_scatter(coin, dsets = c("Raw", "Normalised"), iCodes = "Goods")
Obviously this is not linear.
Generally, the requirements of a function to be passed to
Normalise() are that its first argument should be
x, a numeric vector, and it should return a numeric vector
of the same length as x. It should also be able to handle
NAs. Any further arguments can be passed via the
f_n_para entry.
Directions
By default, the directions are taken from the coin. These will have
been specified as the Direction column of
iMeta when constructing a coin with
new_coin(). However, you can specify different directions
using the directions argument of normalise():
in this case you need to specify a data frame with two columns:
iCode (with an entry for each indicator code found in the
target data set) and Direction giving the direction as -1
or 1.
To show an example, we take the existing directions from the coin, modify them slightly, and then run the normalisation function again:
# get directions from coin
directions <- coin$Meta$Ind[c("iCode", "Direction")]
head(directions, 10)
#> iCode Direction
#> 9 Goods 1
#> 10 Services 1
#> 11 FDI 1
#> 12 PRemit 1
#> 13 ForPort 1
#> 31 Renew 1
#> 32 PrimEner -1
#> 33 CO2 -1
#> 34 MatCon -1
#> 35 Forest -1We’ll change the direction of the “Goods” indicator and re-normalise:
# change Goods to -1
directions$Direction[directions$iCode == "Goods"] <- -1
# re-run (using min max default)
coin <- Normalise(coin, dset = "Raw", directions = directions)
#> Written data set to .$Data$Normalised
#> (overwritten existing data set)Individual normalisation
Finally let’s explore how to specify different normalisation methods
for different indicators. The indiv_specs argument takes a
named list for each indicator, and will override the specifications in
global_specs. If indiv_specs is specified, we
only need to include sub-lists for indicators that differ from
global_specs.
To illustrate, we can use a contrived example where we might want to
apply min-max to all indicators except two. For those, we apply a rank
transformation and distance to maximum approach. Note, that since the
default of global_specs is min-max, we don’t need to
specify that at all here.
# individual specifications:
# LPI - borda scores
# Flights - z-scores with mean 10 and sd 2
indiv_specs <- list(
LPI = list(f_n = "n_borda"),
Flights = list(f_n = "n_zscore",
f_n_para = list(m_sd = c(10, 2)))
)
# normalise
coin <- Normalise(coin, dset = "Raw", indiv_specs = indiv_specs)
#> Written data set to .$Data$Normalised
#> (overwritten existing data set)
# a quick look at the first three indicators
get_dset(coin, "Normalised")[1:4] |>
head(10)
#> uCode LPI Flights Ship
#> 1 AUS 36 9.889993 66.14497
#> 2 AUT 44 9.588735 0.00000
#> 3 BEL 45 9.711512 97.14314
#> 4 BGD 4 8.529810 45.80661
#> 5 BGR 7 8.741971 37.40495
#> 6 BRN 9 8.433044 35.38920
#> 7 CHE 42 10.563483 0.00000
#> 8 CHN 30 13.235114 100.00000
#> 9 CYP 14 8.721372 55.21211
#> 10 CZE 31 9.001961 0.00000This example is meant to be illustrative of the functionality of
Normalise(), rather than being a sensible normalisation
strategy, because the indicators are now on very different ranges.
In practice, if different normalisation strategies are selected, it is a good idea to keep the indicators on similar ranges, otherwise the effects will be very unequal in the aggregation step.
Use of targets
A particular type of normalisation is “distance to target”. This normalises indicators by the distance of each value to a specified target. Targets may often have a political or business meaning, such as e.g. emissions targets or sales targets.
Targets should be input into a coin using the iMeta
argument when building the coin using new_coin(). In fact,
the built-in example data has targets for all indicators:
head(ASEM_iMeta[c("iCode", "Target")])
#> iCode Target
#> 1 LPI 4.118031
#> 2 Flights 200.332655
#> 3 Ship 20.113377
#> 4 Bord 115.900000
#> 5 Elec 104.670585
#> 6 Gas 90.060420(Note that these targets are fabricated just for the purposes of an example)
To use distance-to-target normalisation, we call the
n_dist2targ() function. Like other built in normalisation
functions, this normalises a vector using a specified target. We can’t
use the f_n_para entry in Normalise() here
because this would only pass a single target value, whereas we need to
use a different target for each indicator.
However, COINr has a special case built in so that targets from
iMeta can be used automatically. Simply set
global_specs = list(f_n = "n_dist2targ"), and the
Normalise() function will automatically retrieve targets
from iMeta$Target. If targets are not present, this will
generate an error. Note that the directions of indicators are also
passed to n_dist2targ() - see that function documentation
for how the normalisation is performed depending on the direction
specified.
Our normalisation will then look like this:
coin <- Normalise(coin, dset = "Raw", global_specs = list(f_n = "n_dist2targ"))It is also possible to specify the cap_max parameter of
n_dist2targ() as follows:
coin <- Normalise(coin, dset = "Raw", global_specs = list(f_n = "n_dist2targ", f_n_para = list(cap_max = TRUE)))