% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/contrib.R
\name{contrib}
\alias{contrib}
\alias{contrib2DF}
\alias{contrib<-}
\alias{set_contrib}
\alias{set_contrib_from_index}
\title{Extract percent-change contributions}
\usage{
contrib(x, level = NULL, period = NULL, pad = 0)

contrib2DF(x, levels = NULL, period = NULL)

contrib(x, level = NULL, period = NULL) <- value

set_contrib(x, level = NULL, period = NULL, value)

set_contrib_from_index(x)
}
\arguments{
\item{x}{\verb{[piar_index]} A price index, as made by,
e.g., \code{\link[=elementary_index]{elementary_index()}}.}

\item{level, levels}{\verb{[character]} The level of an index for which
percent-change contributions
are desired, defaulting to the first level (usually the top-level for an
aggregate index). \code{contrib2DF()} can accept multiple levels.}

\item{period}{\verb{[character]} The time periods for which percent-change
contributions are desired, defaulting to all time periods.}

\item{pad}{\verb{[numeric(1)]} A numeric value to pad contributions so that they
fit into a
rectangular array when products differ over time. The default is 0.}

\item{value}{\verb{[matrix]} A numeric matrix of replacement contributions with a
row for each product and a column for each time period. Recycling occurs
along time periods.}
}
\value{
\code{contrib()} returns a matrix of percent-change contributions with a column
for each \code{period} and a row for each product (sorted) for which there are
contributions in \code{level}. Contributions are padded with \code{pad} to fit into a
rectangular array when products differ over time. The replacement methods
returns a copy of \code{x} with contributions given by the matrix \code{value}.
(\code{set_contrib()} is an alias that's easier to use with pipes.)
\code{set_contrib_from_index()} is a helper to return a copy of \code{x} with all
contributions set to the corresponding index value minus 1.

\code{contrib2DF()} returns a data frame of contributions with four
columns: \code{period}, \code{level}, \code{product}, and \code{value}.
}
\description{
Extract a matrix or data frame of percent-change contributions from a price
index.
}
\examples{
prices <- data.frame(
  rel = 1:8,
  period = rep(1:2, each = 4),
  ea = rep(letters[1:2], 4)
)

index <- elementary_index(prices, rel ~ period + ea, contrib = TRUE)

pias <- aggregation_structure(
  list(c("top", "top", "top"), c("a", "b", "c")),
  weights = 1:3
)

index <- aggregate(index, pias, na.rm = TRUE)

# Percent-change contributions for the top-level index.
contrib(index)

contrib2DF(index)

# Calculate EA contributions for the chained index.
arithmetic_contributions <- function(x, w, order = 1) {
  (x - 1) * transmute_weights(x, w, order, to = 1)
}

arithmetic_contributions(
  as.matrix(chain(index))[c("a", "b", "c"), 2],
  weights(pias)
)
}
\seealso{
Other index methods:
\code{\link[=[.piar_index]{[.piar_index()}},
\code{\link{aggregate.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[=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}
