---
title: "Getting Started with Price Index Calculation using cbsREPS"
author: ""
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with Price Index Calculation using cbsREPS}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
bibliography: ./REFERENCES.bib
---

## Introduction

The `calculate_price_index()` function is the central entry point in `cbsREPS` for computing price indices using various **hedonic-based methods**. It supports four commonly used approaches:

- **Laspeyres** – hedonic double imputation base-weighted index  
- **Paasche** – hedonic double imputation current-weighted index  
- **Fisher** – geometric average of Laspeyres and Paasche(both hedonic double imputation) 
- **HMTS** – Hedonic Multilateral Time Series re-estimation Splicing

This vignette demonstrates how to apply each method using a consistent interface, making it easy to compare results across approaches.

The HMTS method implemented in cbsREPS is a multilateral, time-series-based index that balances stability, limited revision, and early detection of turning points in the context of property price indices [@51c4602ed48c4adbb7b7d15176d2da7a].

For broader context and international guidelines on the compilation of property price indices, including traditional methods such as hedonic double imputation Laspeyres, Paasche, and Fisher, we refer to Eurostat's Handbook on RPPIs [@eurostat2013rppi].

## Required Data

Before running any calculations, ensure that your dataset is available and contains the necessary variables:

```r
# Example dataset (you should already have this loaded)
head(data_constraxion)
```

The required variables include:
- `period_variable`: the time period
- `dependent_variable`: usually price
- `continuous_variables`: e.g., `floor_area`
- `categorical_variables`: e.g., `neighbourhood_code`

## Laspeyres Index

```r
Tbl_Laspeyres <- calculate_price_index(
  method = "laspeyres",
  dataset = data_constraxion,
  period_variable = "period",
  dependent_variable = "price",
  continuous_variables = "floor_area",
  categorical_variables = "neighbourhood_code",
  log_dependent = TRUE,
  reference_period = 2015,
  number_of_observations = TRUE,
  imputation = TRUE
)
head(Tbl_Laspeyres)
```

## Paasche Index

```r
Tbl_Paasche <- calculate_price_index(
  method = "paasche",
  dataset = data_constraxion,
  period_variable = "period",
  dependent_variable = "price",
  continuous_variables = "floor_area",
  categorical_variables = "neighbourhood_code",
  log_dependent = TRUE,
  reference_period = 2015,
  number_of_observations = TRUE,
  imputation = TRUE
)
head(Tbl_Paasche)
```

## Fisher Index (Geometric Mean)

```r
Tbl_Fisher <- calculate_price_index(
  method = "fisher",
  dataset = data_constraxion,
  period_variable = "period",
  dependent_variable = "price",
  continuous_variables = "floor_area",
  categorical_variables = "neighbourhood_code",
  log_dependent = TRUE,
  reference_period = 2015,
  number_of_observations = TRUE
)
head(Tbl_Fisher)
```

## HMTS Index (Advanced)

```r
HMTS <- calculate_price_index(
  method = "hmts",
  dataset = data_constraxion,
  period_variable = "period",
  dependent_variable = "price",
  continuous_variables = "floor_area",
  categorical_variables = "neighbourhood_code",
  log_dependent = TRUE,
  reference_period = 2015,
  number_of_observations = TRUE,
  periods_in_year = 4,
  production_since = NULL,
  number_preliminary_periods = 2,
  resting_points = TRUE
)

# Access specific tables
Tbl_HMTS_Index <- as.data.frame(HMTS$Index)
Tbl_HMTS_Analysis <- as.data.frame(HMTS$Matrix_HMTS_analysis)
head(Tbl_HMTS_Index)
```

## Summary

The `calculate_price_index()` function streamlines access to multiple hedonic index methods via a consistent interface. This allows analysts to easily compare outputs and select the most appropriate method for their context.

## References