ppd: Prices Production and Development

#' Prices Production and Development
#' @description A collection of useful tools to simplify working with price indices in R.
#' 
#' Run \code{news(package = 'ppd')} for news.
#' @details 
#' Here's a quick way to get started.
#' \itemize{
#' \item The \code{\link[ppd]{year_month}} function extends some features of R's Date class for monthly/quarterly/annual data.
#' \item Functions that start with 'rs' are useful for making repeat-sale price indices.
#' \item A variety of averages can be calculated with \code{\link[ppd]{generalized_mean}}, particularly \code{\link[ppd]{geomean}}.
#' }
#' @references Kirby-McGregor, M. and Martin, S. (2019). An R package for calculating repeat-sale price indices. Romanian Statistical Review, 3: 17-33.
#' @examples 
#' #### Common price-index manipulations ####
#' 
#' # Turn a monthly index into a quarterly index
#' aggregate(index ~ quarter + city, 
#'           transform(sample_index, quarter = year_quarter(date)), 
#'           mean, 
#'           subset = complete_quarters(date, city)
#' )
#' 
#' # Turn a monthly index into an annual index
#' aggregate(index ~ year + city, 
#'           transform(sample_index, year = year(date)), 
#'           mean, 
#'           subset = complete_years_m(date, city)
#' )
#' 
#' # Works with dplyr too
#' \dontrun{
#' sample_index %>%
#'   filter(complete_years_m(date, city)) %>%
#'   group_by(city, year = year(date)) %>%
#'   summarize(index = mean(index))
#' }
#' 
#' # Calculate quarter-over-quarter change
#' 
#' sample_index$qoq <- 
#'   unsplit(
#'     lapply(
#'       split(sample_index, sample_index$city), 
#'       function(x) with(x, (index / index[match(year_month(date, -3), date)] - 1) * 100)
#'     ), 
#'     sample_index$city
#'   )
#' 
#' # Works with dplyr too
#' \dontrun{
#' sample_index %>%
#'   group_by(city) %>%
#'   mutate(qoq = (index / index[match(year_month(date, -3), date)] - 1) * 100)
#' }
#' 
#' # Turn a year into a base period
#' sample_index$index <- 
#' unsplit(
#'   lapply(
#'     split(sample_index, sample_index$city),
#'     function(x)
#'       with(x, index / mean(index[year(date) == "2017-01-01" & 
#'                                    complete_years_m(date)]) * 100)
#'   ),
#'   sample_index$city
#' )
#' 
#' # Works with dplyr too
#' \dontrun{
#' sample_index %>%
#'   group_by(city) %>%
#'   mutate(index = index / mean(index[year(date) == "2017-01-01" &
#'                                       complete_years_m(date)]) * 100)
#' }
#' 
#' #### Calculating a price index ####
#' 
#' # Make some price relatives over two periods for five groups
#' price_rel <- data.frame(pr = runif(10, 0.5, 1.5),
#'                         group = letters[1:5],
#'                         weight = sample(1:10),
#'                         stringsAsFactors = FALSE
#'                         )
#' 
#' # Arithmetic index
#' sapply(split(price_rel, price_rel$group), function(x) weighted.mean(x$pr, x$weight))
#' 
#' # Geometric index
#' sapply(split(price_rel, price_rel$group), function(x) geomean(x$pr, x$weight))
#' 
#' # Paasche index if weights are current-period expenditure/revenue shares
#' sapply(split(price_rel, price_rel$group), function(x) harmean(x$pr, x$weight))
#' 
#' # Aggregation structure
#' agg <- list(ab = c("a", "b"), cd = c("c", "d"), a2e = letters[1:5])
#' pias <- pias_matrix(agg, tapply(price_rel$weight, price_rel$group, sum))
#' elemental_index <- sapply(split(price_rel, price_rel$group), function(x) geomean(x$pr, x$weight))
#' (pias %*% elemental_index)[, 1]
#' 
#' # Make some microdata
#' price_micro <- data.frame(price = runif(11, 1 ,2),
#'                           ea = factor(c(rep("a", 5), rep("b", 6))),
#'                           period = factor(c(1, 1, 2, 2, 2, 1, 1, 1, 1, 2, 2))
#'                          )
#'                          
#' # Unbalanced Jevons index
#' X <- model.matrix(~ ea + ea:period - 1, price_micro)
#' X0 <- X[, seq_len(nlevels(price_micro$ea))]
#' X1 <- X[, -seq_len(nlevels(price_micro$ea))]
#' y <- log(price_micro$price)
#' r <- X1 - X0 %*% solve(crossprod(X0), crossprod(X0, X1))
#' v <- y - X0 %*% solve(crossprod(X0), crossprod(X0, y))
#' b <- solve(crossprod(r), crossprod(r, v))
#' exp(b) * 100
#' 
#' # Unbalanced Dutot index
#' mm <- model.matrix(~ ea:period - 1, price_micro)
#' Y <- rowSums(mm[, seq_len(nlevels(price_micro$ea))] * price_micro$price)
#' X <- mm[, -seq_len(nlevels(price_micro$ea))] * price_micro$price
#' Z <- mm / colSums(mm)[col(mm)]
#' Z <- Z[, -seq_len(nlevels(price_micro$ea))] + c(Z[, seq_len(nlevels(price_micro$ea))])
#' b <- solve(crossprod(Z, X), crossprod(Z, Y))
#' 100 / b
#'
#' @docType package
#' @name ppd
"_PACKAGE"