---
title: "Matrix aggregation"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Matrix aggregation}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

Aggregating a price index can be done as a matrix operation. Although
this approach is less flexible than the `aggregate()` method used in
`vignette("piar")` (i.e., there can be no missing elemental indexes), it
can be considerably faster for larger indexes.

Let's start by building the index in `vignette("piar")` again.

```{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 a fixed-base index.
elementals <- ms_prices |>
  transform(
    relative = price_relative(price, period = period, product = product),
    business = factor(business, levels = ms_weights$business)
  ) |>
  elemental_index(relative ~ period + business, na.rm = TRUE)

index <- elementals |>
  aggregate(pias, na.rm = TRUE) |>
  chain()

index
```

The key to do this aggregation as a matrix operation is to first turn
the aggregation structure into an aggregation matrix.

```{r}
pias_matrix <- as.matrix(pias)

pias_matrix
```

Multiplying this matrix with a matrix of fixed-base elemental indexes
now computes the aggregate index in each time period.

```{r}
pias_matrix %*% as.matrix(index[levels(pias)$business])
```

## Computing the shadow of an index

It's often useful to determine which higher-level index values are
missing, and subsequently get imputed during aggregation (i.e., compute
the shadow of an index). This is simple to do if there's an elemental
index for each elemental aggregate in the aggregation structure.

The idea is to aggregate an indicator for missingness to get a matrix
that gives the share of missing elemental indexes for each higher-level
index.

```{r}
pias_matrix <- as.matrix(pias) > 0 

pias_matrix %*% is.na(elementals) / rowSums(pias_matrix)
```

A value of 1 means that there are no non-missing elemental indexes, and
that the value for this level of the index is imputed from its parent in
the aggregation structure. A value below 1 but above zero means that
some but not all elemental indexes are missing, and the index value for
this level is based on the non-missing elemental indexes. A value of
zero means there's no imputation for this level of the index.

## Sparse matrices

Aggregation structures are naturally sparse. Although using a dense
aggregation matrix does not matter for small indexes, it quickly becomes
inefficient for large indexes---in this case it is better to make a
sparse aggregation matrix.

```{r}
as.matrix(pias, sparse = TRUE)
```