Aggregate a price index over subperiods

Aggregate an index over subperiods by taking the (usually arithmetic) mean of index values over consecutive windows of subperiods.

Usage

# S3 method for class 'chainable_piar_index'
mean(
  x,
  ...,
  weights = NULL,
  window = ntime(x),
  na.rm = FALSE,
  contrib = TRUE,
  r = 1
)

# S3 method for class 'direct_piar_index'
mean(
  x,
  ...,
  weights = NULL,
  window = ntime(x),
  na.rm = FALSE,
  contrib = TRUE,
  r = 1
)

Arguments

x: A price index, as made by, e.g., elemental_index().
...: Not currently used.
weights: A numeric vector of weights for the index values in x, or something that can be coerced into one. The default is equal weights. It is usually easiest to specify these weights as a matrix with a row for each index value in x and a column for each time period.
window: A positive integer giving the size of the window used to average index values across subperiods. The default averages over all periods in x. Non-integers are truncated towards 0.
na.rm: Should missing values be removed? By default, missing values are not removed. Setting na.rm = TRUE is equivalent to overall mean imputation.
contrib: Aggregate percent-change contributions in x (if any)?
r: Order of the generalized mean to aggregate index values. 0 for a geometric index (the default for making elemental indexes), 1 for an arithmetic index (the default for aggregating elemental indexes and averaging indexes over subperiods), or -1 for a harmonic index (usually for a Paasche index). Other values are possible; see gpindex::generalized_mean() for details.

Value

A price index, averaged over subperiods, that inherits from the same class as x.

Details

The mean() method constructs a set of non-overlapping windows of length window, starting in the first period of the index, and takes the mean of each index value in these windows for each level of the index. The last window is discarded if it is incomplete (with a warning), so that index values are always averaged over window periods. The names for the first time period in each window form the new names for the aggregated time periods.

Percent-change contributions are aggregated if contrib = TRUE by treating each product-subperiod pair as a unique product, then following the same approach as aggregate(). The number of the subperiod is appended to product names to make them unique across subperiods.

An optional vector of weights can be specified when aggregating index values over subperiods, which is often useful when aggregating a Paasche index; see section 4.3 of Balk (2008) for details.

References

Balk, B. M. (2008). Price and Quantity Index Numbers. Cambridge University Press.

Examples

index <- as_index(matrix(c(1:12, 12:1), 2, byrow = TRUE))

# Turn a monthly index into a quarterly index
mean(index, window = 3)
#> Period-over-period price index for 2 levels over 4 time periods 
#>    1 4 7 10
#> 1  2 5 8 11
#> 2 11 8 5  2