---
title: "Getting Started with Pi-Change"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with Pi-Change}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

PI-Change detects multiple change points while allowing external knowledge about
plausible locations to enter through a time-varying penalty. Prior locations are
soft: they lower the cost of a change nearby but do not force a change to occur,
and changes remain possible elsewhere.

## A complete analysis

The penalty specification is a scientific input. The user explicitly chooses
the prior center, its width in observation positions, the construction method,
and the segment family.

```{r}
library(PiChange)

set.seed(12)
y <- c(rnorm(50, 0, 0.35), rnorm(50, 2, 0.35))

penalty <- construct_penalty(
  n = length(y),
  centers = 48,
  width = 6,
  method = "mbic",
  family = "normal"
)

fit <- pi_change(y, penalty, min_seg_len = 10)
fit
changepoints(fit)
summary(fit)
```

The fitted object contains the original series, ordered change-point indices,
segment boundaries, penalty values, and complete prior specification. Its plot
uses light blue for the observed series, pink for fitted segment means, bright
green for detected changes, and dashed red lines for prior centers. The penalty
curve in the upper panel is also red.

```{r}
plot(fit)
```

## Using dates

When `time` is supplied, prior dates are matched to their nearest observations.
Widths continue to be measured in observation positions, which keeps the
meaning consistent with index-based analyses.

```{r}
dates <- as.Date("2020-01-01") + seq_along(y) - 1
dated_penalty <- construct_penalty(
  time = dates,
  centers = as.Date("2020-02-18"),
  width = 6,
  method = "mbic",
  family = "normal"
)
dated_fit <- pi_change(y, dated_penalty, min_seg_len = 10)
changepoints(dated_fit, scale = "time")
```

## Choosing the family

Use `family = "normal"` for approximately continuous Gaussian segment data.
Use `family = "zag"` for non-negative observations that combine exact zeros
with positive gamma-distributed values. PI-Change rejects negative observations
under the zero-adjusted gamma family.

## Sensitivity to prior width

There is no universally appropriate prior width. A narrow width concentrates
the penalty reduction close to a center; a wider value spreads that support over
more observation positions. Report whether conclusions persist over a
substantively reasonable range.

```{r}
widths <- c(3, 6, 12)
sensitivity <- lapply(widths, function(w) {
  p <- construct_penalty(
    n = length(y), centers = 48, width = w,
    method = "mbic", family = "normal"
  )
  changepoints(pi_change(y, p, min_seg_len = 10))
})
names(sensitivity) <- widths
sensitivity
```

For manual penalties, supply both `minimum_penalty` and `max_penalty`. The
minimum applies at strong prior support and the maximum away from prior centers.
Because these values directly control segmentation, they should be justified by
the application rather than treated as generic defaults.

## 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>.