% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/impute_prices.R
\name{impute_prices}
\alias{impute_prices}
\alias{impute_prices.default}
\alias{impute_prices.matrix}
\alias{impute_prices.numeric}
\alias{impute_prices.data.frame}
\alias{carry_forward}
\alias{carry_backward}
\alias{shadow_price}
\title{Impute missing prices}
\usage{
impute_prices(x, ...)

\method{impute_prices}{default}(x, ...)

\method{impute_prices}{matrix}(
  x,
  period,
  product,
  ...,
  ea = NULL,
  weights = NULL,
  pias = NULL,
  r = c(0, 1),
  method = c("overall-mean", "carry-forward")
)

\method{impute_prices}{numeric}(
  x,
  period,
  product,
  ...,
  ea = NULL,
  weights = NULL,
  pias = NULL,
  r = c(0, 1),
  method = c("overall-mean", "carry-forward", "carry-backward")
)

\method{impute_prices}{data.frame}(x, formula, ..., ea = NULL, weights = NULL)

carry_forward(x, ...)

carry_backward(x, ...)

shadow_price(x, ...)
}
\arguments{
\item{x}{Either a numeric vector (or something that can be coerced into one),
a data frame of prices, or a two-column matrix of current prices
and back prices (in that order).}

\item{...}{Further arguments passed to or used by methods.}

\item{period}{A factor, or something that can be coerced into one, giving
the time period associated with each price in \code{x}. The ordering of time
periods follows of the levels of \code{period}, to agree with
\code{\link[=cut.Date]{cut()}}.}

\item{product}{A factor, or something that can be coerced into one, giving
the product associated with each price in \code{x}.}

\item{ea}{A factor, or something that can be coerced into one, giving the
elementary aggregate associated with each price in \code{x}. This is evaluated
in \code{x} for the data frame method. The default pools all data into one
elementary aggregate.}

\item{weights}{A numeric vector of weights for the prices in \code{x} (i.e.,
product weights), or something that can be coerced into one. The default is
to give each price equal weight. This is evaluated in \code{x} for the data
frame method.}

\item{pias}{A price index aggregation structure, or something that can be
coerced into one, as made with \code{\link[=aggregation_structure]{aggregation_structure()}}. The default
imputes from elementary indexes only (i.e., not recursively).}

\item{r}{A pair of numeric values. The first gives the order of the
generalized-mean price index used to calculate the
elementary price indexes, defaulting to a geometric index. The second
gives the order of the generalized-mean price index used to aggregate the
elementary price indexes, defaulting to an arithmetic index. Other values
are possible;
see \code{\link[gpindex:generalized_mean]{gpindex::generalized_mean()}} for details.}

\item{method}{Name of the imputation method, one of \code{"overall-mean"},
\code{"carry-forward"}, or \code{"carry-backward"}.}

\item{formula}{A two-sided formula, or something that can be coerced into
one, with prices on the left-hand
side and time periods and products on the right-hand side (in that order).}
}
\value{
A numeric vector or matrix of prices with missing values replaced
(where possible).
}
\description{
Impute missing prices using the carry forward/backward or the
self-correcting overall mean method.
}
\details{
The carry forward method replaces a missing price for a product by the price
for the same product in the previous period. It tends to push an index value
towards 1, and is usually avoided; see paragraph 6.61 in the CPI manual
(2020). The carry backwards method does the opposite, but this is rarely
used in practice.

The self-correcting overall mean method recursively imputes a missing price
by the value of
the price for the same product in the previous period multiplied by the
value of the period-over-period elementary index for the elementary aggregate
to which that product belongs. This requires computing and aggregating an
index (according to \code{pias}, unless \code{pias} is not supplied) for
each \code{period}. The index
values used to do the imputations are not returned because the index needs
to be recalculated to get correct percent-change contributions. It is
identical to simply
excluding missing price relatives in the index calculation, except in the
period that a missing product returns. For this reason care is needed when
using this method. It is sensitive to the assumption that a product does not
change over time, and in some cases it is safer to simply omit the missing
price relatives instead of imputing the missing prices.

Imputation works slightly differently depending on whether data are in a long
or wide format. When \code{x} is a two-column of matrix of current and back prices
(in that order), then imputation is done separately on the current price
at a point in time and the back price at the next point in time. When \code{x} is
a numeric vector then these two prices are necessarily the same.
}
\examples{
prices <- data.frame(
  price = c(1:7, NA),
  period = rep(1:2, each = 4),
  product = 1:4,
  ea = rep(letters[1:2], 4)
)

impute_prices(prices, price ~ period + product, method = "carry-forward")

impute_prices(
  prices,
  price ~ period + product,
  ea = ea,
  method = "overall-mean"
)

# Can also be done with current price-back price formulation.
prices$back_price <- with(
  prices,
  price[gpindex::back_period(period, product)]
)

impute_prices(
  prices,
  cbind(price, back_price) ~ period + product,
  ea = ea,
  method = "overall-mean"
)

}
\references{
IMF, ILO, OECD, Eurostat, UNECE, and World Bank. (2020).
\emph{Consumer Price Index Manual: Concepts and Methods}.
International Monetary Fund.
}
\seealso{
\code{\link[=price_relative]{price_relative()}} for making price relatives for the
same products over time.
}
