chaining: Chain-linking, rebasing and index conversion

In hicp: Harmonised Index of Consumer Prices

Chain-linking, rebasing and index conversion

Description

Function unchain() unchains a chained index series. These unchained index series can be aggregated into higher-level indices using aggregate(). To obtain a long-term index series, the higher-level indices must be chained using function chain(). Function rebase() sets the index reference period. Monthly indices can be converted into quarterly and yearly indices or 12-month moving averages using function convert().

Usage

unchain(x, t, by=12, settings=list())

chain(x, t, by=12, settings=list())

rebase(x, t, t.ref="first", settings=list())

convert(x, t, type="year", settings=list())

Arguments

x	numeric vector of index values.
t	date vector in format YYYY-MM-DD with monthly frequency, that is, one observation per month. Quarterly and yearly frequencies are also supported.
by	for one-month or one-quarter overlap a single integer between 1 and 12 specifying the price reference period; for annual overlap using a full calendar year NULL.
t.ref	character specifying the index reference period either in format YYYY for a calendar year or YYYY-MM for a specific month or quarter. Can also be first or last to use the first or last available period. If t.ref contains multiple entries, these are processed in the order provided, and the first match is used for the rebasing.
type	type of converted index. Either year (for annual average), quarter (for quarterly average), or 12mavg (for a 12-month moving average).
settings	list of control settings to be used. The following settings are supported: chatty : logical indicating if package-specific warnings and info messages should be printed or not. The default is getOption("hicp.chatty"). freq : character specifying the frequency of t. Allowed values are month, quarter, year, and auto (the default). For auto, the frequency is internally derived from t. na.rm : logical indicating if averages for calendar years should also be computed when there are NAs and less than 12 months (or 4 quarters) present (for na.rm=TRUE). For the 12-month moving average in convert(), the calculations are always based on the last 12 months (or 4 quarters), meaning that only NAs are excluded. The default is na.rm=FALSE.

Details

Function unchain() sets the value of the first price reference period to NA although the value could be set to 100 (if by is not NULL) or 100 divided by the average of the year (if by=NULL). This is wanted to avoid aggregation of these values. Function chain() finally sets the values back to 100.

Value

Functions unchain(), chain(), rebase(), and convert(..., type="12mavg") return numeric values of the same length as x.

For type="year" and type="quarter", function convert() returns a named numeric vector of the length of quarters or years available in t, where the names correspond to the last month of the year or quarter.

Author(s)

Sebastian Weinand

References

European Commission, Eurostat, Harmonised Index of Consumer Prices (HICP) - Methodological Manual - 2024 edition, Publications Office of the European Union, 2024, https://data.europa.eu/doi/10.2785/055028.

See Also

aggregate

Examples

### EXAMPLE 1

t <- seq.Date(from=as.Date("2021-12-01"), to=as.Date("2024-12-01"), by="1 month")
p <- rnorm(n=length(t), mean=100, sd=5)

# rebase index to new reference period:
rebase(x=p, t=t, t.ref=c("1996","2022")) # 1996 not present so 2022 is used
rebase(x=p, t=t, t.ref=c("1996","first")) # 1996 not present so first period is used

# convert into quarterly index:
convert(x=p, t=t, type="q") # first quarter is not complete so NA

# unchaining and chaining gives initial results:
100*p/p[1]
chain(unchain(p, t, by=12), t, by=12)

# use annual overlap:
100*p/mean(p[1:12])
(res <- chain(unchain(p, t, by=NULL), t, by=NULL))
# note that for backwards compability, each month in the first
# year receives an index value of 100. this allows the same
# computation again:
chain(unchain(res, t, by=NULL), t, by=NULL)

### EXAMPLE 2: Working with published HICP data

library(data.table)
library(restatapi)
options(restatapi_cores=1) # set cores for testing on CRAN
options(hicp.chatty=FALSE) # suppress package messages and warnings

# get hicp index values for euro area with base 2015:
dt <- hicp::data(id="prc_hicp_midx", filter=list(unit="I15", geo="EA"))
dt[, "time":=as.Date(paste0(time, "-01"))]
setkeyv(x=dt, cols=c("unit","coicop","time"))

# unchain, chain, and rebase all euro area indices by coicop:
dt[, "dec_ratio" := unchain(x=values, t=time), by="coicop"]
dt[, "chained_index" := chain(x=dec_ratio, t=time), by="coicop"]
dt[, "index_own" := rebase(x=chained_index, t=time, t.ref="2015"), by="coicop"]

# convert all euro area indices into annual averages:
dta <- dt[, as.data.table(
              x=convert(x=values, t=time, type="year"), 
              keep.rownames=TRUE), by="coicop"]
setnames(x=dta, c("coicop","time","index"))
plot(index~as.Date(time), data=dta[coicop=="CP00",], type="l") # plot all-items index

hicp documentation built on Aug. 8, 2025, 6:30 p.m.