hicp (version 1.1.0)

chaining: Chain-linking, rebasing and index conversion

Description

The function unchain() unchains an annually chain-linked index series. The unchained indices can be aggregated into higher-level indices, which can be chain-linked using the function chain() to obtain a long-term index series. The function rebase() sets the reference period of the chain-linked index.

The function convert() allows to convert monthly indices into quarterly and yearly indices or 12-month moving averages.

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())

Value

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

For type="year" and type="quarter", the 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

Sebastian Weinand

Arguments

x

numeric vector of index values.

t

date vector of monthly (i.e., one observation per month), quarterly or yearly frequency in format YYYY-MM-DD.

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

The 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. The function chain() finally sets the values back to 100.

References

European Commission, Eurostat, Harmonised Index of Consumer Prices (HICP) - Methodological Manual - 2024 edition, Publications Office of the European Union, 2024, tools:::Rd_expr_doi("10.2785/055028").

See Also

aggregate

Examples

### EXAMPLE 1

# sample monthly price index:
t <- seq.Date(from=as.Date("2022-12-01"), to=as.Date("2025-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","2023")) # 1996 not present so 2023 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
# \donttest{
library(data.table)
library(restatapi)
options(restatapi_cores=1) # set cores for testing on CRAN
options(hicp.chatty=FALSE) # suppress package messages and warnings

# import monthly price indices for euro area:
dtm <- hicp::data(id="prc_hicp_minr", filters=list(unit="I25", geo="EA"))
dtm[, "time":=as.Date(paste0(time, "-01"))]
setkeyv(x=dtm, cols=c("unit","coicop18","time"))

# unchain, chain, and rebase all euro area indices by COICOP:
dtm[, "dec_ratio" := unchain(x=values, t=time), by="coicop18"]
dtm[, "chained_index" := chain(x=dec_ratio, t=time), by="coicop18"]
dtm[, "index_own" := rebase(x=chained_index, t=time, t.ref="2025"), by="coicop18"]

# convert all monthly indices into annual averages:
dta <- dtm[, as.data.table(
              x=convert(x=values, t=time, type="year"), 
              keep.rownames=TRUE), by="coicop18"]
setnames(x=dta, c("coicop18","time","index"))
plot(index~as.Date(time), data=dta[coicop18=="TOTAL",], type="l")
# }