---
title: "Contributions"
vignette: >
  %\VignetteIndexEntry{Contributions}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
knitr:
  opts_chunk: 
    collapse: true
    comment: '#>'
---

## Product contributions

It's often convenient to decompose an index into the (additive)
contribution of each price relative, also known as the percent-change
contribution. This can be done with the same work flow used in
`vignette("piar")`, specifying `contrib = TRUE` when calling
`elementary_index()`. (See `vignette("decomposing-indexes")` for the underlying
theory.)

```{r}
library(piar)

# Make an aggregation structure.
ms_weights[c("level1", "level2")] <-
  expand_classification(ms_weights$classification)

pias <- ms_weights[c("level1", "level2", "business", "weight")] |>
  as_aggregation_structure()

# Make elementary index with contributions.
elementals <- ms_prices |>
  transform(
    relative = price_relative(price, period = period, product = product)
  ) |>
  elementary_index(
    relative ~ period + business,
    product = product,
    na.rm = TRUE,
    contrib = TRUE
  )
```

As with index values, percent-change contributions for a given level of
the index can be extracted as a matrix.

```{r}
contrib(elementals, level = "B1")
```

Or as a data frame.

```{r}
contrib2DF(elementals, level = "B1")
```

Aggregating the elementary indexes automatically aggregates
percent-change contributions, so no extra steps are needed after the
elementary indexes are made.

```{r}
index <- aggregate(elementals, pias, na.rm = TRUE)

contrib(index)
```

## Index contributions

After an index has been calculated, it's often useful to compute the
contribution of higher-level indexes towards the total index. The
easiest way to do this with a collection of pre-computed index values is
to simply coerce them into an index object with the index values as
contributions and reaggregate with a restricted aggregation structure.

```{r}
index <- as_index(as.matrix(index), contrib = TRUE)
```

If the index values are already an index object, it's also possible to
directly replace the contributions with the `set_contrib_from_index()` function.
We can now cut the aggregation structure to keep only the top two levels and
reaggregate to get the contribution of the second-level indexes to the
top level index.

```{r}
set_contrib_from_index(index) |>
  aggregate(cut(pias, 2)) |>
  contrib()
```

The same approach works with a fixed-base index as well.

```{r}
chain(index) |>
  set_contrib_from_index() |>
  aggregate(cut(pias, 2)) |>
  contrib()
```
