new_coin {COINr}R Documentation

Create a new coin


Creates a new "coin" class object, or a "purse" class object (time-indexed collection of coins). A purse class object is created if panel data is supplied. Coins and purses are the main object classes used in COINr, although a number of functions also support other classes such as data frames and vectors.


  exclude = NULL,
  split_to = NULL,
  level_names = NULL,
  retain_all_uCodes_on_split = FALSE,
  quietly = FALSE



The indicator data and metadata of each unit


Indicator metadata


Optional character vector of any indicator codes (iCodes) to exclude from the coin(s).


This is used to split panel data into multiple coins, a so-called "purse". Should be either "all", or a subset of entries in iData$Time. See Details.


Optional character vector of names of levels. Must have length equal to the number of levels in the hierarchy (max(iMeta$Level, na.rm = TRUE)).


Logical: if panel data is input and split to a purse using split_to, this controls how units with no data at certain time points are handled. If set FALSE, then unit at time t with no data in any indicators will be removed completely from the coin for that time point. If TRUE, all units will be included in every time point. The latter option may be useful if you impute over time.


If TRUE, suppresses all messages


A coin object is fundamentally created by passing two data frames to new_coin(): iData which specifies the data points for each unit and indicator, as well as other optional variables; and iMeta which specifies details about each indicator/variable found in iData, including its type, name, position in the index, units, and other properties.

These data frames need to follow fairly strict requirements regarding their format and consistency. Run check_iData() and check_iMeta() to validate your data frames, and these should generate helpful error messages when things go wrong.

It is worth reading a little about coins and purses to use COINr. See vignette("coins") for more details.


iData should be a data frame with required column uCode which gives the code assigned to each unit (alphanumeric, not starting with a number). All other columns are defined by corresponding entries in iMeta, with the following special exceptions:


Required columns for iMeta are:

Optional columns that are recognised in certain functions are:

The iMeta data frame essentially gives details about each of the columns found in iData, as well as details about additional data columns eventually created by aggregating indicators. This means that the entries in iMeta must include all columns in iData, except the three special column names: uCode, uName, and Time. In other words, all column names of iData should appear in iMeta$iCode, except the three special cases mentioned. The iName column optionally can be used to give longer names to each indicator which can be used for display in plots.

iMeta also specifies the structure of the index, by specifying the parent of each indicator and aggregate. The Parent column must refer to entries that can be found in iCode. Try View(ASEM_iMeta) for an example of how this works.

Level is the "vertical" level in the hierarchy, where 1 is the bottom level (indicators), and each successive level is created by aggregating the level below according to its specified groups.

Direction is set to 1 if higher values of the indicator should result in higher values of the index, and -1 in the opposite case.

The Type column specifies the type of the entry: Indicator should be used for indicators at level 1. Aggregate for aggregates created by aggregating indicators or other aggregates. Otherwise set to Group if the variable is not used for building the index but instead is for defining groups of units. Set to Denominator if the variable is to be used for scaling (denominating) other indicators. Finally, set to Other if the variable should be ignored but passed through. Any other entries here will cause an error.

Note: this function requires the columns above as specified, but extra columns can also be added without causing errors.

Other arguments

The exclude argument can be used to exclude specified indicators. If this is specified, .$Data$Raw will be built excluding these indicators, as will all subsequent build operations. However the full data set will still be stored in .$Log$new_coin. The codes here should correspond to entries in the iMeta$iCode. This option is useful e.g. in generating alternative coins with different indicator sets, and can be included as a variable in a sensitivity analysis.

The split_to argument allows panel data to be used. Panel data must have a Time column in iData, which consists of some numerical time variable, such as a year. Panel data has multiple observations for each uCode, one for each unique entry in Time. The Time column is required to be numerical, because it needs to be possible to order it. To split panel data, specify split_to = "all" to split to a single coin for each of the unique entries in Time. Alternatively, you can pass a vector of entries in Time which allows to split to a subset of the entries to Time.

Splitting panel data results in a so-called "purse" class, which is a data frame of COINs, indexed by Time. See vignette("coins") for more details.

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


A "coin" object or a "purse" object.


# build a coin using example data frames
ASEM_coin <- new_coin(iData = ASEM_iData,
                      iMeta = ASEM_iMeta,
                      level_names = c("Indicator", "Pillar", "Sub-index", "Index"))
# view coin contents

# build example purse class
ASEM_purse <- new_coin(iData = ASEM_iData_p,
                       iMeta = ASEM_iMeta,
                       split_to = "all",
                       quietly = TRUE)
# view purse contents

# see vignette("coins") for further info

[Package COINr version 1.1.14 Index]