% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/aggregate.piar_index.R
\name{aggregate.piar_index}
\alias{aggregate.piar_index}
\alias{aggregate.chainable_piar_index}
\alias{aggregate.direct_piar_index}
\title{Aggregate elementary price indexes}
\usage{
\method{aggregate}{chainable_piar_index}(
  x,
  pias,
  ...,
  pias2 = NULL,
  na.rm = FALSE,
  contrib = TRUE,
  order = 1,
  r = order,
  include_ea = TRUE,
  duplicate_contrib = c("sum", "make.unique"),
  impute_rules = NULL
)

\method{aggregate}{direct_piar_index}(
  x,
  pias,
  ...,
  pias2 = NULL,
  na.rm = FALSE,
  contrib = TRUE,
  order = 1,
  r = order,
  include_ea = TRUE,
  duplicate_contrib = c("sum", "make.unique"),
  impute_rules = NULL
)
}
\arguments{
\item{x}{\verb{[piar_index]} A price index, usually made by \code{\link[=elementary_index]{elementary_index()}}.}

\item{pias}{\verb{[piar_aggregation_structure]} A price index
aggregation structure or something that can be coerced into one. This can
be made with \code{\link[=aggregation_structure]{aggregation_structure()}}.}

\item{...}{Not currently used.}

\item{pias2}{\verb{[piar_aggregation_structure]} An optional secondary
aggregation structure, usually with current-period weights, to make a
superlative index. See details.}

\item{na.rm}{\verb{[logical(1)]} Should missing values be removed? By default,
missing values are not removed. Setting \code{na.rm = TRUE} is equivalent to
overall-mean imputation.}

\item{contrib}{\verb{[logical(1)]} Aggregate percent-change contributions in \code{x}?
By default contributions are aggregated.}

\item{order}{\verb{[numeric(1)]} Order of the generalized mean to aggregate
index values. 0 for a
geometric index (the default for making elementary indexes), 1 for an
arithmetic index (the default for aggregating elementary indexes and
averaging indexes over subperiods), or -1 for a harmonic index (usually for
a Paasche index). Other values are possible; see
\code{\link[=gmean]{gmean()}} for details. If \code{pias2} is given then the
index is aggregated with a quadratic mean of order \code{2*r}.}

\item{r}{Deprecated.}

\item{include_ea}{\verb{[logical(1)]} Should indexes for the elementary aggregates
be included along with the aggregated indexes? By default, all index values
are returned.}

\item{duplicate_contrib}{\verb{[character(1)]} The method to deal with duplicate
product contributions. Either \code{"make.unique"} to treat duplicate
products as distinct products and make their names unique
with \code{\link[=make.unique]{make.unique()}} or \code{"sum"} to add contributions for each product
(the default).}

\item{impute_rules}{\verb{[function]} (Experimental) A function that applies
imputation rules to the elementary indexes in each time period prior to
aggregation.
It takes two arguments, the elementary indexes for a given time period and
the (price updated) aggregation structure, and must return back the
elementary indexes.}
}
\value{
An aggregate price index that inherits from the class of \code{x}.
}
\description{
Aggregate elementary price indexes with a price index aggregation structure.
}
\details{
The \code{aggregate()} method loops over each time period in \code{x} and
\enumerate{
\item aggregates the elementary indexes with \code{\link[=gmean]{gmean()}} for each level
of \code{pias};
\item aggregates percent-change contributions for each level of
\code{pias} (if there are any and \code{contrib = TRUE});
\item price updates the weights in \code{pias} with \code{\link[=update_weights]{update_weights()}} (only for
period-over-period elementary indexes).
}

The result is a collection of aggregated period-over-period indexes that
can be chained together to get a fixed-base index when \code{x} are
period-over-period elementary indexes. Otherwise, when \code{x} are fixed-base
elementary indexes, the result is a collection of aggregated fixed-base
(direct) indexes.

By default, missing elementary indexes will propagate when aggregating the
index. Missing elementary indexes can be due to both missingness of these
values in \code{x}, and the presence of elementary aggregates in \code{pias}
that are not part of \code{x}. Setting \code{na.rm = TRUE} ignores missing
values, and is equivalent to overall-mean (or parental) imputation. As an
aggregated price index generally cannot have missing values (for otherwise
it can't be chained over time and weights can't be price updated), any
missing values for a level of \code{pias} are removed and recursively replaced
by the value of its immediate parent.

In most cases aggregation is done with an arithmetic mean (the default), and
this is detailed in chapter 8 (pp. 190--198) of the CPI manual (2020), with
analogous details in chapter 9 of the PPI manual (2004).
Aggregating with a non-arithmetic mean follows the same steps, except that
the elementary indexes are aggregated with a mean of a different order (e.g.,
harmonic for a Paasche index), and the method for price updating the weights
is slightly different. Note that, because aggregation is done with a
generalized mean, the resulting index is consistent-in-aggregation at each
point in time.

Aggregating percent-change contributions uses the method in chapter 9 of the
CPI manual (equations 9.26 and 9.28) when aggregating with an arithmetic
mean. With a non-arithmetic mean, arithmetic weights are constructed using
\code{\link[=transmute_weights]{transmute_weights()}} in order to apply this method.

There may not be contributions for all prices relatives in an elementary
aggregate if the elementary indexes are built from several sources (as with
\code{\link[=merge.piar_index]{merge()}}). In this case the contribution for
a price relative in the aggregated index will be correct, but the sum of all
contributions will not equal the change in the value of the index.

If two aggregation structures are given then the steps above are done for
each aggregation structure, with the aggregation for \code{pias} done with a
generalized mean of order \code{order} the aggregation for \code{pias2} done with a
generalized mean of order \code{-order}. The resulting indexes are combined with a
geometric mean to make a superlative quadratic mean of order \code{2*order} index.
Percent-change contributions are combined using a generalized van IJzeren
decomposition; see \code{\link[=transmute_weights2]{transmute_weights2()}} for details.
}
\note{
For large indexes it can be much faster to turn the aggregation structure
into an aggregation matrix with
\code{\link[=as.matrix.piar_aggregation_structure]{as.matrix()}}, then aggregate
elementary indexes as a matrix operation when there are no missing
values. See the examples for details.
}
\examples{
prices <- data.frame(
  rel = 1:8,
  period = rep(1:2, each = 4),
  ea = rep(letters[1:2], 4)
)

# A two-level aggregation structure.
pias <- aggregation_structure(
  list(c("top", "top", "top"), c("a", "b", "c")),
  weights = 1:3
)

# Calculate Jevons elementary indexes.
(elementary <- elementary_index(prices, rel ~ period + ea))

# Aggregate (note the imputation for elementary index 'c').
(index <- aggregate(elementary, pias, na.rm = TRUE))

# Aggregation can equivalently be done as matrix multiplication.
as.matrix(pias) \%*\% as.matrix(chain(index[letters[1:3]]))
}
\references{
Balk, B. M. (2008). \emph{Price and Quantity Index Numbers}.
Cambridge University Press.

ILO, IMF, UNECE, OECD, and World Bank. (2004).
\emph{Producer Price Index Manual: Theory and Practice}.
International Monetary Fund.

IMF, ILO, OECD, Eurostat, UNECE, and World Bank. (2020).
\emph{Consumer Price Index Manual: Concepts and Methods}.
International Monetary Fund.

von der Lippe, P. (2007). \emph{Index Theory and Price Statistics}. Peter Lang.
}
\seealso{
Other index methods:
\code{\link[=[.piar_index]{[.piar_index()}},
\code{\link[=as.data.frame.piar_index]{as.data.frame.piar_index()}},
\code{\link[=as.ts.piar_index]{as.ts.piar_index()}},
\code{\link[=chain]{chain()}},
\code{\link[=contrib]{contrib()}},
\code{\link[=head.piar_index]{head.piar_index()}},
\code{\link[=is.na.piar_index]{is.na.piar_index()}},
\code{\link[=levels.piar_index]{levels.piar_index()}},
\code{\link{mean.piar_index}},
\code{\link[=merge.piar_index]{merge.piar_index()}},
\code{\link[=split.piar_index]{split.piar_index()}},
\code{\link[=stack.piar_index]{stack.piar_index()}},
\code{\link[=time.piar_index]{time.piar_index()}},
\code{\link[=window.piar_index]{window.piar_index()}}
}
\concept{index methods}
