---
title: "Pi-Change: Oil Price Application"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Pi-Change: Oil Price Application}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 4
)
```

This vignette analyzes absolute daily changes in WTI spot oil prices from 2000
through 2009. The prior locations correspond to events used in the original
application script: rising prices around 2003, Hurricane Katrina, Iran sanctions,
and the 2008 global recession. This example illustrates how PI-Change can use
geopolitical and economic event times as soft prior support for structural
changes in the observed series.

```{r}
library(PiChange)
library(ggplot2)

data("wti_oil")

event_dates <- as.Date(c("2003-01-01", "2005-08-26", "2006-12-23", "2008-07-01"))
penalty <- construct_penalty(
  time = wti_oil$date,
  centers = event_dates,
  width = 26 * 5,
  method = "mbic",
  family = "zag"
)
fit <- pi_change(wti_oil$abs_price_change, penalty, min_seg_len = 13 * 5)

change_indices <- changepoints(fit)
wti_oil[change_indices, c("date", "price", "abs_price_change")]
```

```{r, fig.height=6}
plot(
  fit,
  ylab = "Absolute daily price change",
  title = "WTI oil price volatility with PI-Change estimates"
)
```

Here `width = 26 * 5` represents 130 observation positions, approximately six
months of trading days, while `min_seg_len = 13 * 5` requires approximately one
quarter of trading days per segment. These are application-specific choices,
not universal defaults. The original dates, matched observation indices, and
penalty values are retained in `fit$penalty`.

## Reference

Jacobs, J. and Chen, S. (2026). *Pi-Change: A Prior-Informed Multiple Change
Point Detection Algorithm*. <https://doi.org/10.48550/arXiv.2605.01003>.