---
title: "Index-number formulas"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Index-number formulas}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

Price indexes based on a generalized mean of price relatives constitute
a large family of bilateral index-number formulas that are consistent in
aggregation, and any index based on the generalized mean can be used to
make and aggregate elemental indexes. To see how to make superlative
indexes as well, let's start with a simple dataset of prices and
quantities for two businesses over three periods. We'll be making
extensive use of the *gpindex* package for lower-level price-index
functions; see the help pages for that package to get more detail.

```{r}
library(piar)
library(gpindex)

prices <- data.frame(
  period = rep(1:3, each = 6),
  product = paste0("P", 1:6),
  business = rep(c("B1", "B2"), each = 3),
  price = 1:18,
  quantity = 18:1
)

prices[c("back_price", "back_quantity")] <- 
  prices[back_period(prices$period, prices$product), c("price", "quantity")]

head(prices)
```

## Basic indexes

As seen in `vignette("piar")`, by default the `elemental_index()`
function calculates a Jevons index (equally-weighted geometric mean of
price relatives). Although this is the standard index-number formula for
making elemental indexes, many other types of index-numbers are
possible. Among the unweighted index-number formulas, the Carli index
(equally-weighted arithmetic mean of price relatives) is the historical
competitor to the Jevons, and requires specifying the order of the
generalized mean `r` when calling `elemental_index()`. An order of 1
corresponds to an arithmetic mean.

```{r}
prices |>
  elemental_index(price / back_price ~ period + business, r = 1)
```

The Coggeshall index (equally-weighted harmonic mean of price relatives)
is another competitor to the Jevons, but is seldom used in practice.
Despite it being more exotic, it is just as easy to make by specifying
an order `r` of -1.

```{r}
prices |>
  elemental_index(price / back_price ~ period + business, r = -1)
```

Weights can be added to make, for example, elemental indexes using the
geometric Laspeyres formula.

```{r}
prices |>
  elemental_index(
    price / back_price ~ period + business,
    weights = back_price * back_quantity
  )
```

The type of mean used to aggregate elemental indexes can be controlled
in the same way in the call to `aggregate()`. The default makes an
arithmetic index, but any type of generalized-mean index is possible.

## Superlative indexes

Many superlative indexes can be made by supplying unequal and
time-varying weights when making the elemental indexes, usually from
information about quantities. The Törnqvist index is a popular superlative
index-number formula, using average period-over-period value shares as
the weights in a geometric mean. As `elemental_index()` makes a
geometric index by default, all that is needed to make a Törnqvist index
is the weights.

```{r}
tw <- grouped(index_weights("Tornqvist"))

prices |>
  elemental_index(
    price / back_price ~ period + business,
    weights = tw(
      price, back_price, quantity, back_quantity,
      group = interaction(period, business)
    )
  )
```

Making a Fisher index is more complex because it does not belong to the
generalized-mean family. Despite this, it is possible to make weights to
represent a Fisher index as a generalized mean of any order.

```{r}
fw <- grouped(nested_transmute(0, c(1, -1), 0))

prices |>
  elemental_index(
    price / back_price ~ period + business,
    weights = fw(
      price / back_price, back_price * back_quantity, price * quantity,
      group = interaction(period, business)
    )
  )
```

Aggregating with a superlative index is more complex, and is the subject
of `vignette("superlative-aggregation")`.

## Product contributions

As shown in `vignette("contributions")`, supplying `contrib = TRUE` in the call
to `elemental_index()` makes percent-change product contributions for each index
value. The method used in this package is flexible and works well for a variety 
of different index-number formulas, but does not include all methods found in the
literature. (See the help page for `elemental_index()`, and the references therein,
for more detail about the exact methods.)

Let's extend the previous example by calculating product contributions for the
Fisher index using the default method.

```{r}
fisher_index <- prices |>
  elemental_index(
    price / back_price ~ period + business,
    weights = fw(
      price / back_price, back_price * back_quantity, price * quantity,
      group = interaction(period, business)
    ),
    contrib = TRUE
  )

contrib(fisher_index, "B1")
```

We can change the method used to make contributions for, say, business `B1` by making
a function to compute contributions according to a different method

```{r}
diewert_contributions <- function(p1, p0, q1, q0) {
  Pf <- fisher_index(p1, p0, q1, q0)
  Pl <- laspeyres_index(p1, p0, q0)
  wl <- scale_weights(index_weights("Laspeyres")(p0, q0))
  wp <- scale_weights(index_weights("HybridPaasche")(p0, q1))
  
  (1 / (1 + Pf) * wl + Pl / (1 + Pf) * wp) * (p1 / p0 - 1)
}
```

and using this function to replace the contributions for business `B1`.

```{r}
contrib(fisher_index, "B1") <- subset(prices, business == "B1") |>
  split(~period) |>
  sapply(
    \(df) diewert_contributions(
      df$price, df$back_price, df$quantity, df$back_quantity
    )
  )

contrib(fisher_index, "B1")
```

Aggregating the elemental indexes will then consistently aggregate the contributions
for both businesses, even though they use different methods.