Getting Started with Pi-Change

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.

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
#> PI-Change fit
#>   Observations: 100 
#>   Family: normal 
#>   Criterion: mbic 
#>   Minimum segment length: 10 
#>   Detected change points: 1 
#>   Locations: 50
changepoints(fit)
#> [1] 50
summary(fit)
#> PI-Change fit summary
#> Family: normal  | Criterion: mbic 
#> Detected change points: 1 
#> 
#>  segment start_index end_index start_time end_time  n        mean        sd
#>        1           1        50          1       50 50 -0.05002537 0.3032399
#>        2          51       100         51      100 50  2.02820731 0.3002580
#>  proportion_zero
#>                0
#>                0

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.

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.

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")
#> [1] "2020-02-19"

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.

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
#> $`3`
#> [1] 50
#> 
#> $`6`
#> [1] 50
#> 
#> $`12`
#> [1] 50

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.

Getting Started with Pi-Change

A complete analysis

Using dates

Choosing the family

Sensitivity to prior width

Reference