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 schen3@vcu.edu [copyright holder]

Authors:

• Jonathon Jacobs jacobsjr@vcu.edu [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

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

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

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

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

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

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

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

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.