Package 'PiChange'

Pi-Change: Change point detection with prior-informed penalties

Description

PI-Change detects multiple change points while allowing prespecified plausible locations to lower the local penalty. A typical analysis first records the prior assumptions with construct_penalty() and then fits the segmentation with pi_change(). The fitted object retains the observations, time index, prior specification, penalty, model settings, and ordered change points.

Author(s)

Maintainer: Shanshan Chen [email protected] [copyright holder]

Authors:

• Jonathon Jacobs [email protected] [copyright holder]

References

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

---

Build prior weights using non-overlapping center windows

Description

Build prior weights using non-overlapping center windows

Usage

build_prior_location(n, centers, width, type = "gaussian")

Arguments

n	Integer time series length.
centers	Numeric vector of prior centers.
width	Positive numeric width parameter.
type	Prior shape. One of "gaussian", "triangle", or "exponential".

Value

Numeric vector of prior-support weights.

---

Extract PI-Change change points

Description

Extract PI-Change change points

Usage

changepoints(object, ...)

## S3 method for class 'pi_change_fit'
changepoints(object, scale = c("index", "time"), boundaries = FALSE, ...)

Arguments

object	A fitted pi_change_fit object.
...	Reserved for future methods.
scale	Return observation "index" values or values on the original "time" scale.
boundaries	Include the beginning and ending boundaries.

Value

A vector of detected change point locations.

---

Construct a PI-Change penalty specification

Description

Constructs the time-varying penalty used by PI-Change and records the prior assumptions used to create it. Observed response values are not needed; supply either the number of observations (n) or their ordered time index (time). Prior widths are measured in observation positions, including when prior locations are supplied as dates.

Usage

construct_penalty(
  n = NULL,
  centers,
  width,
  method,
  family,
  time = NULL,
  windows = NULL,
  max_penalty = NULL,
  minimum_penalty = NULL,
  const_ratio = NULL
)

Arguments

n	Number of observations. Supply exactly one of n and time.
centers	Prespecified plausible change point locations. Use observation indices when supplying n, or values on the same scale as time when supplying time.
width	Positive numeric scalar or vector specifying the prior width in observation positions. A vector must have one value per center.
method	Penalty construction method: "mbic", "manual", or "const_ratio".
family	Segment distribution family: "normal" or "zag" (zero-adjusted gamma).
time	Optional strictly increasing numeric, Date, or POSIXt vector.
windows	Optional list with components L and U defining a window around each center. Values use the same scale as centers.
max_penalty, minimum_penalty	Penalty bounds required when method = "manual".
const_ratio	Positive ratio required when method = "const_ratio".

Value

A pi_penalty object containing the numeric penalty and complete prior specification.

References

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

Examples

penalty <- construct_penalty(
  n = 80,
  centers = 40,
  width = 5,
  method = "mbic",
  family = "normal"
)
penalty

---

Google workplace mobility summaries

Description

Processed workplace mobility summaries for the United States, New York City, the United Kingdom, and London. Values are mean percent changes from the pre-COVID baseline by date and region.

Usage

google_mobility_workplaces

Format

A data frame with columns:

date

Observation date.

region

Region label.

workplaces_percent_change_from_baseline

Mean workplace mobility percent change from baseline.

Source

Google LLC, "Google COVID-19 Community Mobility Reports", https://www.google.com/covid19/mobility/, accessed July 17, 2026.

---

Detect change points with a prior-informed penalty

Description

pi_change() locates change points in a univariate series using a time-varying penalty from construct_penalty() or a user-supplied numeric penalty. Scientific choices remain explicit: raw numeric penalties require both family and criterion; a pi_penalty object supplies its recorded family and can infer the "mbic" criterion when constructed by the MBIC method.

Usage

pi_change(
  data,
  penalty,
  family = NULL,
  criterion = NULL,
  min_seg_len = 2L,
  time = NULL
)

Arguments

data	Finite numeric vector containing the ordered series.
penalty	A pi_penalty object or numeric vector of length length(data) + 1.
family	Segment distribution family, "normal" or "zag". This is inferred from a pi_penalty object when omitted.
criterion	Segment cost criterion, "mll" or "mbic". This is inferred only for a penalty constructed with method = "mbic".
min_seg_len	Integer minimum segment length.
time	Optional ordered numeric, Date, or POSIXt index. When the penalty contains a time index, that index is used by default.

Value

A pi_change_fit object. Use changepoints() to extract detected locations and summary() or plot() to inspect the fit.

References

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

Examples

set.seed(1)
x <- c(rnorm(40, 0, 0.3), rnorm(40, 2, 0.3))
penalty <- construct_penalty(
  n = length(x), centers = 40, width = 5,
  method = "mbic", family = "normal"
)
fit <- pi_change(x, penalty, min_seg_len = 10)
changepoints(fit)

---

Evaluate concatenated Gaussian prior weights

Description

Evaluate concatenated Gaussian prior weights

Usage

pi_concat(t, centers, sigma, window = NULL)

Arguments

t	Numeric vector of locations at which to evaluate the prior.
centers	Numeric vector of prior centers.
sigma	Positive numeric scalar or vector of prior widths.
window	Optional list with components L and U.

Value

Numeric vector of prior-support weights in ⁠[0, 1]⁠.

---

Plot a PI-Change fit

Description

Displays the time-varying penalty above the observed series when the fit contains a pi_penalty specification. Prior centers and detected change points use both distinct colors and line types. Horizontal fitted lines show the estimated mean within each segment.

Usage

## S3 method for class 'pi_change_fit'
plot(
  x,
  ...,
  xlab = NULL,
  ylab = "Observed value",
  show_prior = TRUE,
  show_fitted = TRUE,
  show_penalty = TRUE,
  data_col = "#76BDE8",
  fitted_col = "#F06292",
  changepoint_col = "#00C853",
  prior_col = "#D62728",
  penalty_col = "#D62728",
  series_linewidth = 0.5,
  fitted_linewidth = 0.5,
  vertical_linewidth = 1,
  title = "PI-Change detection"
)

Arguments

x	A fitted pi_change_fit object.
...	Reserved for future extensions.
xlab, ylab	Axis labels for the data-series panel.
show_prior	Show prespecified prior centers.
show_fitted	Show fitted segment means.
show_penalty	Show the penalty panel when a structured penalty is available.
data_col, fitted_col, changepoint_col, prior_col, penalty_col	Colors for the observations, segment means, detected changes, prior centers, and penalty curve.
series_linewidth, fitted_linewidth, vertical_linewidth	Line widths for the observed series, segment means, and vertical prior/change lines.
title	Optional title for the data-series panel.

Value

Invisibly, a named list containing the penalty and data ggplots when the penalty panel is displayed; otherwise, the data-series ggplot.

---

Simulate zero-adjusted gamma observations

Description

Simulate zero-adjusted gamma observations

Usage

rzag(n, shape, scale, p0)

Arguments

n	Number of observations.
shape	Gamma shape parameter.
scale	Gamma scale parameter.
p0	Probability of observing zero.

Value

Numeric vector of simulated observations.

Examples

rzag(5, shape = 1, scale = 2, p0 = 0.25)

---

Summarize a PI-Change fit

Description

Summarize a PI-Change fit

Usage

## S3 method for class 'pi_change_fit'
summary(object, ...)

Arguments

object	A fitted pi_change_fit object.
...	Reserved for future methods.

Value

A summary.pi_change_fit object with segment summaries.

---

WTI Cushing spot oil prices

Description

West Texas Intermediate spot prices at Cushing, Oklahoma from 2000 through 2009, with the absolute daily price change used in the oil-price vignette.

Usage

wti_oil

Format

A data frame with columns:

date

Observation date.

price

WTI spot price in dollars per barrel.

abs_price_change

Absolute first difference in price.

Source

U.S. Energy Information Administration, Cushing, Oklahoma WTI Spot Price FOB, available from https://www.eia.gov/dnav/pet/hist/rwtcd.htm.

---