Import and export

One of the most useful functions is export_to_excel(). This can be used to export the contents of a coin to Excel at at any point in its construction, and is very simple to run. We first build the example coin:

library(COINr)

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

Then export to Excel:

# export coin to Excel
export_to_excel(coin, fname = "example_coin_results.xlsx")

This exports every data frame in the coin to a separate tab in the workbook, named according to its position in the coin. By default it excludes the Log of the coin, but this can be optionally included. The function is very useful for passing the results to people who don’t use R (let’s face it, that’s most people).

Data can also be imported directly into COINr from the COIN Tool which is an Excel-based tool for building and analysing composite indicators, similar in fact to COINr¹. With the import_coin_tool() function you can import data directly from the COIN Tool to cross check or extend your analysis in COINr.

To demonstrate, we can take the example version of the COIN Tool, which you can download here. Then it’s as simple as running:

# make sure file is in working directory!
coin_import <- import_coin_tool("COIN_Tool_v1_LITE_exampledata.xlsm",
                                makecodes = TRUE, out2 = "coin")

This will directly generate a coin from the COIN Tool.

Converting from older COINr versions

COINr changed drastically from v0.6 to v1.0. So drastically that I skipped several version numbers. From v1.0, the main object of COINr is called a “coin” and this is different from the “COIN” used up to v0.6.x. If you have worked in COINr before v1.0, you can use the COIN_to_coin() function to convert old COINs into new coins:

coin <- COIN_to_coin(COIN)

This comes with some limitations: any data sets present in the coin will not be passed on unless recover_dsets = TRUE. However, if this is specified, the coin cannot be regenerated because it is not possible to translate the log from the older COIN class (called the “Method”) to the log in the new coin class. Still, the conversion avoids having to reformat iData and iMeta.

Other useful functions

Here we list some accessory functions that could be useful in some circumstances.

The rank_df() function converts a data frame to ranks, ignoring non-numeric columns. Taking some sample data:

X <- ASEM_iData[1:5,c(2,10:12)]
X
#>   uCode       GDP Population      LPI
#> 1   AUT 390.79999   8735.453 4.097985
#> 2   BEL 467.95527  11429.336 4.108538
#> 3   BGR  53.23964   7084.571 2.807685
#> 4   HRV  51.23100   4189.353 3.160829
#> 5   CYP  20.04623   1179.551 2.999061

This looks like

rank_df(X)
#>   uCode GDP Population LPI
#> 1   AUT   2          2   2
#> 2   BEL   1          1   1
#> 3   BGR   3          3   5
#> 4   HRV   4          4   3
#> 5   CYP   5          5   4

The replace_df() function replaces values found anywhere in a data frame with corresponding new values:

replace_df(X, data.frame(old = c("AUT", "BEL"), new = c("test1", "test2")))
#>   uCode       GDP Population      LPI
#> 1 test1 390.79999   8735.453 4.097985
#> 2 test2 467.95527  11429.336 4.108538
#> 3   BGR  53.23964   7084.571 2.807685
#> 4   HRV  51.23100   4189.353 3.160829
#> 5   CYP  20.04623   1179.551 2.999061

The round_df() rounds to a specified number of decimal places, ignoring non-numeric columns:

round_df(X, 1)
#>   uCode   GDP Population LPI
#> 1   AUT 390.8     8735.5 4.1
#> 2   BEL 468.0    11429.3 4.1
#> 3   BGR  53.2     7084.6 2.8
#> 4   HRV  51.2     4189.4 3.2
#> 5   CYP  20.0     1179.6 3.0

The signif_df() is equivalent but for a number of significant figures:

signif_df(X, 3)
#>   uCode   GDP Population  LPI
#> 1   AUT 391.0       8740 4.10
#> 2   BEL 468.0      11400 4.11
#> 3   BGR  53.2       7080 2.81
#> 4   HRV  51.2       4190 3.16
#> 5   CYP  20.0       1180 3.00

Finally, the compare_df() function gives a detailed comparison between two similar data frames that are indexed by a specified column. This function is tailored to compare results in composite indicators. Say you have a set of results from COINr and want to cross check against a separate calculation. Often, you end up with a data frame with the same columns, but possibly in a different order. Rows could be in a different order but are indexed by an identifier, here “uCode”. The compare_df() function gives a detailed comparison between the two data frames and points out any differences.

We’ll demonstrate this by copying the example data frame, altering some values and seeing what happens:

# copy
X1 <- X

# change three values
X1$GDP[3] <- 101
X1$Population[1] <- 10000
X1$Population[2] <- 70000

# reorder
X1 <- X1[order(X1$uCode), ]

# now compare
compare_df(X, X1, matchcol = "uCode")
#> $Same
#> [1] FALSE
#> 
#> $Details
#>       Column TheSame                          Comment NDifferent
#> 1      uCode    TRUE      Non-numerical and identical          0
#> 2        GDP   FALSE Numerical and different at 5 sf.          1
#> 3 Population   FALSE Numerical and different at 5 sf.          2
#> 4        LPI    TRUE Numerical and identical to 5 sf.          0
#> 
#> $Differences
#> $Differences$GDP
#>   uCode      df1 df2
#> 3   BGR 53.23964 101
#> 
#> $Differences$Population
#>   uCode       df1   df2
#> 1   AUT  8735.453 10000
#> 2   BEL 11429.336 70000

The output is a list with several entries. First, it tells us that the two data frames are not the same. The “Details” data frame lists each column and says whether it is identical or not, and how many different points there are. Finally, the “Differences” list has one entry for each column that differs, and details the value of the point from the first data frame compared to the value from the second.

From experience, this kind of output can be very helpful in quickly zooming in on differences between possibly large data frames of results. It is mainly intended for the use case described above, where the data frames are known to be similar, are of the same size, but we want to check for precise differences.