---
title: "Bayesian Unit Root Testing for Panel Data: BayesPanelUR"
author: "Shikhar Tyagi, Arvind Pandey, Bhupendra Singh, Vrijesh Tripathi"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Bayesian Unit Root Testing for Panel Data: BayesPanelUR}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
library(BayesPanelUR)
```

## 1. Introduction

Unit root testing in panel time series datasets is crucial in econometrics, financial modeling, and social sciences. Traditional single-equation Dickey-Fuller tests often suffer from low statistical power, especially over short time horizons. Panel unit root tests exploit cross-sectional information to significantly boost test power.

The `BayesPanelUR` package implements the Bayesian unit root test for Panel Autoregressive (PAR) time series models developed by **Kumar, Chaturvedi, and Afifa (2016)**. The testing procedure evaluates the difference stationarity ($H_0: \rho = 1$) against trend stationarity ($H_1: \rho \in (-a, 1)$) using the exact Posterior Odds Ratio (POR).

## 2. Model & Methodology

Consider a panel time series observation $y_{i,t}$ for cross-sectional units $i = 1, \dots, n$ and time periods $t = 1, \dots, T$:

$$y_{i,t} = \mu_i + \delta_i t + u_{i,t}$$

where $u_{i,t}$ is a stochastic error term following an AR(1) process:

$$u_{i,t} = \rho u_{i,t-1} + \epsilon_{i,t}, \quad \epsilon_{i,t} \sim iid \, N(0, \tau^{-1})$$

Incorporating augmentation terms of order $p$, the model under the alternative hypothesis $H_1$ is given by:

$$y_{i,t} - \rho y_{i,t-1} = \alpha_i + \beta_i t + \sum_{j=1}^p \theta_{i,j} \Delta y_{i,t-j} + \epsilon_{i,t}$$

and under the unit root null hypothesis $H_0: \rho = 1$:

$$\Delta y_{i,t} = \delta_i + \sum_{j=1}^p \theta_{i,j} \Delta y_{i,t-j} + \epsilon_{i,t}$$

Using natural conjugate prior distributions, the Posterior Odds Ratio ($\beta_{01}$) is derived via analytical marginalization and 1D numerical quadrature over $\rho \in (-a, 1)$.

## 3. Package Usage Example

We demonstrate `BayesPanelUR` using the included dataset `nps_nav`, which contains monthly Net Asset Value (NAV) records of Indian pension fund managers (ICICI, KM, SBI, UTI).

```{r example}
# Load sample dataset
data("nps_nav", package = "BayesPanelUR")
head(nps_nav)

# Extract matrix of NAV time series for 4 pension funds
nav_mat <- as.matrix(nps_nav[, 2:5])

# Perform Bayesian panel unit root test with linear trend
res <- bayes_panel_ur(nav_mat, p = 0)
print(res)

# View detailed summary of structural parameter estimates
summary(res)
```

## 4. Model with Augmentation Terms

To capture serial correlation in first differences, an augmentation term of order $p = 1$ or $p = 2$ can be included:

```{r augmentation}
# Test with augmentation order p = 2
res_aug <- bayes_panel_ur(nav_mat, p = 2)
print(res_aug)
```

## 5. Visualizing Posterior Density

The posterior distribution of the pooled autoregressive coefficient $\rho$ can be visualized using the `plot()` S3 method:

```{r plot_posterior, fig.width = 6, fig.height = 4}
plot(res_aug, type = "posterior")
```

## 6. References

- Kumar, J., Chaturvedi, A., & Afifa, U. (2016). Bayesian unit root test for panel data. *EERI Research Paper Series*, No. 14/2016, Economics and Econometrics Research Institute (EERI), Brussels. <https://hdl.handle.net/10419/179393>