Title:	Functional Change Point Detection and Analysis
Version:	2.1.0
Description:	Analyze functional data and its change points. Includes functionality to store and process data, summarize and validate assumptions, characterize and perform inference of change points, and provide visualizations. Data is stored as discretely collected observations without requiring the selection of basis functions. For more details see chapter 8 of Horvath and Rice (2024) <doi:10.1007/978-3-031-51609-2>. Additional papers are forthcoming. Focused works are also included in the documentation of corresponding functions.
Encoding:	UTF-8
Imports:	dplyr, fastmatrix, fda, ftsa, ggplot2, ggpubr, graphics, grDevices, MASS, methods, plot3D, plotly, rainbow, RColorBrewer, Rcpp, RcppArmadillo, Rfast, sandwich, scales, stats, tensorA, tidyr, vars
LinkingTo:	Rcpp, RcppArmadillo
RoxygenNote:	7.3.2
Suggests:	CompQuadForm, fda.usc, forecast, funData, jmuOutlier, knitr, lattice, rmarkdown, testthat (≥ 3.0.0)
Depends:	R (≥ 2.10)
LazyData:	true
URL:	https://jrvanderdoes.github.io/fChange/
Config/testthat/edition:	3
License:	GPL (≥ 3)
NeedsCompilation:	yes
Packaged:	2025-06-21 03:07:28 UTC; jerem
Author:	Jeremy VanderDoes [aut, cre, cph], Gregory Rice [aut], Martin Wendler [aut]
Maintainer:	Jeremy VanderDoes <jeremy.vanderdoes@gmail.com>
Repository:	CRAN
Date/Publication:	2025-06-21 03:30:02 UTC

General Information for fChange

Description

Analyze functional data and its change points. Includes functionality to store and process data, summarize and validate assumptions, characterize and perform inference of change points, and provide visualizations. Data is stored as discretely collected observations without requiring the selection of basis functions. For more details see chapter 8 of Horvath and Rice (2024) doi:10.1007/978-3-031-51609-2. Additional papers are forthcoming. Focused works are also included in the documentation of corresponding functions.

Author(s)

Maintainer: Jeremy VanderDoes jeremy.vanderdoes@gmail.com (ORCID) [copyright holder]

Authors:

• Gregory Rice

• Martin Wendler

See Also

Useful links:

• https://jrvanderdoes.github.io/fChange/

Pipe operator

Description

See tidyr::%>% for details.

Usage

lhs %>% rhs

Arguments

Value

The result of calling rhs(lhs).

S&P 500 Index Data

Description

Intraday prices for the S&P500 index (SPY) for 2019 to 2023 with holidays and weekends removed. Minutely resolution and daily observations.

Usage

SPYUS500

Format

SPY500

A dfts object.

Extract or Replace parts of dfts object

Description

Extract or replace subsets of dfts objects.

Usage

## S3 method for class 'dfts'
x[i, j, ...]

## S3 replacement method for class 'dfts'
x[i, j] <- value

Arguments

Value

A dfts object.

Examples

electricity[1:3]
electricity[1:3, ]
electricity[1:2, 1:4]
electricity[, 1:4]
tmp <- dfts(matrix(1:9, 3, 3))
tmp$data
tmp[1, 1] <- 10
tmp$data

ACF/PACF Functions

Description

This function computes the ACF/PACF of data. This can be applied on traditional scalar time series or functional time series defined in dfts().

Usage

acf(x, lag.max = NULL, ...)

## Default S3 method:
acf(x, lag.max = NULL, ...)

pacf(x, lag.max = NULL, ...)

## Default S3 method:
pacf(x, lag.max = NULL, ...)

## S3 method for class 'dfts'
acf(
  x,
  lag.max = NULL,
  alpha = 0.05,
  method = c("Welch", "MC", "Imhof"),
  WWN = TRUE,
  figure = TRUE,
  ...
)

## S3 method for class 'dfts'
pacf(x, lag.max = NULL, n_pcs = NULL, alpha = 0.95, figure = TRUE, ...)

Arguments

Value

List with ACF or PACF values and plots

• acfs/pacfs: Autocorrelation values for each lag of the functional time series.

• SWN_bound: The upper prediction bound for the i.i.d. distribution under strong white noise assumption.

• WWN_bound: The upper prediction bound for the i.i.d. distribution under weak white noise assumption.

• plot: Plot of autocorrelation values for each lag of the functional time series.

References

Mestre G., Portela J., Rice G., Munoz San Roque A., Alonso E. (2021). Functional time series model identification and diagnosis by means of auto- and partial autocorrelation analysis. Computational Statistics & Data Analysis, 155, 107108.

Mestre, G., Portela, J., Munoz San Roque, A., Alonso, E. (2020). Forecasting hourly supply curves in the Italian Day-Ahead electricity market with a double-seasonal SARMAHX model. International Journal of Electrical Power & Energy Systems, 121, 106083.

Kokoszka, P., Rice, G., Shang, H.L. (2017). Inference for the autocovariance of a functional time series under conditional heteroscedasticity Journal of Multivariate Analysis, 162, 32–50.

See Also

stats::acf(), sacf()

Examples

acf(1:10)
x <- generate_brownian_bridge(100, seq(0, 1, length.out = 20))
acf(x, 20)

x <- generate_brownian_bridge(100, seq(0, 1, length.out = 20))
pacf(x, lag.max = 10, n_pcs = 2)

Adaptive_bandwidth

Description

Computes the data-driven bandwidth using a method based on the spectral density operator which adapts to the functional data.

Usage

adaptive_bandwidth(
  X,
  kernel = bartlett_kernel,
  name = NULL,
  order = NULL,
  weighting = NULL
)

Arguments

Value

Scalar value of the data-adapted bandwidth.

References

Rice, G., & Shang, H. L. (2017). A Plug‐in Bandwidth Selection Procedure for Long‐Run Covariance Estimation with Stationary Functional Time Series. Journal of Time Series Analysis, 38(4), 591–609.

See Also

bartlett_kernel(), truncated_kernel(), parzen_kernel(), tukey_hanning_kernel(), quadratic_spectral_kernel(), daniell_kernel(), flat_top_kernel()

Examples

adaptive_bandwidth(generate_brownian_motion(100))
adaptive_bandwidth(electricity, parzen_kernel)

Estimate the autocorrelation function of the series

Description

Obtain the empirical autocorrelation function for the given lags of a functional time series, X. Given a functional time series, the sample autocovariance functions \hat{C}_{h}(u,v) are given by:

\hat{C}_{h}(u,v) = \frac{1}{N} \sum_{i=1}^{N-|h|}(X_{i}(u) - \overline{X}_{N}(u))(X_{i+|h|}(v) - \overline{X}_{N}(v))

where \overline{X}_{N}(u) = \frac{1}{N} \sum_{i = 1}^{N} X_{i}(t) denotes the sample mean function and h is the lag parameter. The autocorrelation functions are defined over the range (0,1) by normalizing these functions using the factor \int\hat{C}_{0}(u,u)du.

Usage

autocorrelation(X, lags)

Arguments

Value

Return a list or data.frame with the lagged autocorrelation function(s) estimated from the data. Each function is given by a (r x r) matrix, where r is the number of points observed in each curve.

See Also

autocovariance()

Examples

N <- 100
v <- seq(from = 0, to = 1, length.out = 10)
bbridge <- generate_brownian_bridge(N = N, v = v)
lagged_autocor <- autocorrelation(X = bbridge, lags = 0:1)

Estimate the autocovariance function of the series

Description

Obtain the empirical autocovariance function for the given lags of a functional time series, X. Given a functional time series, the sample autocovariance functions \hat{C}_{h}(u,v) are given by:

\hat{C}_{h}(u,v) = \frac{1}{N} \sum_{i=1}^{N-|h|}(Y_{i}(u) - \overline{X}_{N}(u))(Y_{i+|h|}(v) - \overline{X}_{N}(v))

where \overline{X}_{N}(u) = \frac{1}{N} \sum_{i = 1}^{N} X_{i}(t) denotes the sample mean function and h is the lag parameter.

Usage

autocovariance(X, lags = 0:1, center = TRUE)

Arguments

Value

Return a list or data.frame with the lagged autocovariance function(s) estimated from the data. Each function is given by a (r x r) matrix, where r is the number of points observed in each curve.

See Also

autocorrelation(), var()

Examples

v <- seq(0, 1, length.out = 20)
lagged_autocov <- autocovariance(
  X = generate_brownian_bridge(100, v = v),
  lags = 1
)

Average Functions for dfts Objects

Description

Compute the pointwise "average" values for dfts objects such as mean and median.

Usage

## S3 method for class 'dfts'
mean(x, na.rm = TRUE, ...)

## S3 method for class 'dfts'
median(x, na.rm = TRUE, ...)

Arguments

Value

Numeric vector

Examples

results <- mean(electricity)
results <- median(electricity)

Breast Cancer

Description

Percentage of cause-specific deaths out of total deaths for female breast cancer in the United States from 1950 to 2021.

Usage

cancer

Format

cancer

A data.frame with columns being the year and rows the age groups (5 years).

Generic Centering of Data

Description

Center data by removing the mean or median. Defining changes allow for regional centering.

Usage

center(object, changes = NULL, type = "mean", ...)

## Default S3 method:
center(object, changes = NULL, type = "mean", ...)

## S3 method for class 'data.frame'
center(object, changes = NULL, type = "mean", ...)

## S3 method for class 'matrix'
center(object, changes = NULL, type = "mean", ...)

## S3 method for class 'dfts'
center(object, changes = NULL, type = "mean", ...)

Arguments

Value

Centered data of the same format as the given data.

See Also

center.default(), center.data.frame(), center.matrix(), center.dfts()

Examples

center(1:10)

Compute (Overnight) Cumulative Intraday Returns

Description

Compute (Overnight) Cumulative Intraday Returns

Usage

cidr(X)

ocidr(X)

Arguments

Value

A dfts object with CIDR or OCIDRs

References

Rice, G., Wirjanto, T., & Zhao, Y. (2023). Exploring volatility of crude oil intraday return curves: A functional GARCH-X model. Journal of Commodity Markets, 32, 100361-.

Examples

tmp <- dfts(SPYUS500$data[, 1:100],
  name = "SP500 100 Days",
  labels = SPYUS500$labels[1:100], fparam = SPYUS500$fparam
)
cidr(tmp)
tmp <- dfts(SPYUS500$data[, 1:100],
  name = "SP500 100 Days",
  labels = SPYUS500$labels[1:100], fparam = SPYUS500$fparam
)
ocidr(tmp)

Change Point Confidence Intervals

Description

Compute confidence intervals for the data based on some changes. The current version is tuned to mean changes.

Usage

confidence_interval(
  X,
  changes,
  K = bartlett_kernel,
  h = 2 * ncol(X)^(1/5),
  weighting = 0.5,
  M = 5000,
  alpha = 0.1,
  method = "distribution"
)

Arguments

Value

Data.frame with the first column for the changes, second for the lower bounds of confidence intervals, and the third for the upper bounds of confidence intervals.

References

Horvath, L., & Rice, G. (2024). Change Point Analysis for Time Series (First edition.). Springer.

Aue, A., Rice, G., & Sonmez, O. (2018). Detecting and dating structural breaks in functional data without dimension reduction. Journal of the Royal Statistical Society. Series B, Statistical Methodology, 80(3), 509-529.

Examples

X <- cbind(
  generate_brownian_motion(100, v = seq(0, 1, 0.05))$data,
  generate_brownian_motion(100, v = seq(0, 1, 0.05))$data + 0.5
)
confidence_interval(X, 100, alpha = 0.1)
confidence_interval(X, changes = 100, alpha = 0.1, method = "simulation")

X <- generate_brownian_motion(200, v = seq(0, 1, 0.05))
confidence_interval(X, 100)
confidence_interval(X, 100, method = "simulation")

X <- cbind(
  generate_brownian_motion(200, v = seq(0, 1, 0.05))$data,
  generate_brownian_motion(100, v = seq(0, 1, 0.05))$data + 0.1,
  generate_brownian_motion(150, v = seq(0, 1, 0.05))$data - 0.05
)
confidence_interval(X, c(200, 300))

confidence_interval(X = electricity, changes = c(64, 120), alpha = 0.1)

dfts Objects

Description

The discrete functional time series (dfts) object is the main object in fChange. It stores functional data for use in functions throughout the package. Common functions have been extended to dfts. Details of the storage is best left to individual parameters descriptions and exploring examples.

Usage

dfts(
  X,
  name = NULL,
  labels = NULL,
  fparam = NULL,
  season = 1,
  inc.warnings = TRUE
)

as.dfts(X)

is.dfts(X)

Arguments

Value

dfts / as.dfts: dfts object

is.dfts: Boolean indicating if x is a dfts object or not

Examples

bm <- dfts(generate_brownian_motion(100, c(0, 0.1, 0.25, 0.5, 1)))

result <- dfts(electricity)
result <- as.dfts(electricity)
result <- is.dfts(electricity)

Group Generic Functions

Description

Group generic methods defined for things like Math, Ops, and so forth.

Usage

## S3 method for class 'dfts'
Math(x, ...)

## S3 method for class 'dfts'
Ops(e1, e2)

## S3 method for class 'dfts'
cumsum(x)

Arguments

Value

A dfts object with the applied operation

dfts object with data as cumsum

Examples

result <- sqrt(electricity)
result <- electricity + electricity
result1 <- electricity * electricity
cumsum(electricity)

Difference dfts

Description

Difference the functional data at some lag and iteration. For the \ell'th difference at lag m, the differenced series is defined as Y_i(t) = (1-B^m)^{\ell} X_i(t) where B is the backshift operator.

Usage

## S3 method for class 'dfts'
diff(x, lag = 1L, differences = 1L, ...)

Arguments

Value

A dfts object with the differenced values.

Examples

result <- diff(electricity, lag = 1)
result1 <- diff(electricity, differences = 2)

Dimension of dfts Object

Description

Retrieve the dimension of a dfts object.

Usage

## S3 method for class 'dfts'
dim(x, ...)

Arguments

Value

Numerics indicating the dimension of the dfts object.

Examples

results <- dim(electricity)

Spanish Spot Electricity Data

Description

The hourly electricity spot prices from Spain in 2014.

Usage

electricity

Format

electricity

A dfts object.

Source

<www.omie.es>

Change Point Detection

Description

Change point detection for dfts objects. Various change point methods are given, where single or multiple changes can be detected. Multiple change extensions currently include binary segmentation and elbow plots.

Usage

fchange(
  X,
  method = c("characteristic", "mean", "robustmean", "eigenjoint", "eigensingle",
    "trace", "covariance", "projmean", "projdistribution"),
  statistic = c("Tn", "Mn"),
  critical = c("simulation", "resample", "welch"),
  type = c("single", "segmentation", "elbow"),
  resample_blocks = "separate",
  replace = TRUE,
  max_changes = min(ncol(X), 20),
  changes = NULL,
  blocksize = 2 * ncol(X)^(1/5),
  eigen_number = 3,
  h = 2 * ncol(X)^(1/5),
  M = 1000,
  J = 50,
  W = space_measuring_functions(X = X, M = 20, space = "BM"),
  K = bartlett_kernel,
  alpha = 0.05,
  cov.res = 30,
  weighting = 1/4,
  TVE = 0.95,
  trim_function = function(X) {
     0
 },
  errors = "L2",
  recommendation_change_points = 2,
  recommendation_improvement = 0.15,
  silent.binary = FALSE,
  ...
)

Arguments

Value

When type is single, returns a list:

1. pvalue: p-value for detection of a change point.

2. location: location of the most likely change.

When type is elbow:

1. information: data.frame with the information on each change and the decrease in variability.

2. plots: list of plots showing the variability decrease or improvement

3. suggestion: list with plot and algorithmic change suggestion. The suggested changes are also returned.

When type is segmentation a data.frame with the locations and p-values is returned.

References

Aue, A., Rice, G., & Sonmez, O. (2018). Detecting and dating structural breaks in functional data without dimension reduction. Journal of the Royal Statistical Society. Series B, Statistical Methodology, 80(3), 509-529.

Wegner, L., Wendler, M. Robust change-point detection for functional time series based on U-statistics and dependent wild bootstrap. Stat Papers (2024).

Aue, A., Rice, G., & Sonmez, O. (2020). Structural break analysis for spectrum and trace of covariance operators. Environmetrics (London, Ont.), 31(1)

Horvath, L., Rice, G., & Zhao, Y. (2022). Change point analysis of covariance functions: A weighted cumulative sum approach. Journal of Multivariate Analysis, 189, 104877-.

Berkes, I., Gabrys, R.,Horvath, L. & P. Kokoszka (2009)., Detecting changes in the mean of functional observations Journal of the Royal Statistical Society, Series B 71, 927-946

Aue, A., Gabrys, R.,Horvath, L. & P. Kokoszka (2009)., Estimation of a change-point in the mean function of functional data Journal of Multivariate Analysis 100, 2254-2269.

Huskova, M., & Meintanis, S.G. (2006). Change Point Analysis based on Empirical Characteristic Functions. Metrika, 63, 145-168.

Examples

res <- fchange(electricity$data[, 1:20], method = "characteristic", critical = "welch")

Generate a Brownian Bridge Process

Description

Generate a functional time series from an iid Brownian Bridge process. If W(t) is a Wiener process, the Brownian Bridge is defined as W(t) - tW(1). Each functional observation is discretized on the points indicated in v.

Usage

generate_brownian_bridge(N, v = 30, sd = 1)

Arguments

Value

Functional time series (dfts) object.

Examples

bbridge <- generate_brownian_bridge(N = 100, v = c(0, 0.2, 0.6, 1, 1.3), sd = 2)
bbridge <- generate_brownian_bridge(N = 100, v = 10, sd = 1)

Generate a Brownian Motion Process

Description

Generate a functional time series according to an iid Brownian Motion process. Each observation is discretized on the points indicated in v.

Usage

generate_brownian_motion(N, v = 30, sd = 1)

Arguments

Value

Functional time series (dfts) object.

Examples

bmotion <- generate_brownian_motion(
  N = 100,
  v = c(0, 0.25, 0.4, 0.7, 1, 1.5), sd = 1
)
bmotion1 <- generate_brownian_motion(
  N = 100,
  v = 10, sd = 2
)

Generate Functional Data

Description

A general wrapper function to allow generation of functional data according to several approaches: bbridge, bmotion, kl, ou, and far1.

Usage

generate_data(fparam, data_details, burnin = 100)

Arguments

Value

A dfts object for the generated data.

See Also

generate_brownian_bridge(), generate_brownian_motion(), generate_far1(), generate_karhunen_loeve(), generate_ornstein_uhlenbeck()

Examples

result <- generate_data(
  fparam = 15,
  data_details = list(
    "bmotion" = list("N" = 100, "sd" = 1),
    "bbridge" = list("N" = 100, "sd" = 1),
    "bbridge" = list("N" = 100, "sd" = 1),
    "kl" = list(
      "N" = 100,
      "distribution" = "Normal",
      "eigenvalues" = 1 / 1:4,
      "mean" = 0, "dependence" = 0,
      "basis" = fda::create.bspline.basis(),
      "sd" = 1
    ),
    "ou" = list("N" = 100, "dependence" = 0),
    "far1" = list(
      "N" = 100, "dependence" = 0,
      "sd" = 1, "vary" = FALSE
    )
  )
)

Generate FAR(1) Data

Description

Function to generate data according to FAR(1) process.

Usage

generate_far1(N, resolution, sd = 1, dependence = 1/2, drop_first = FALSE)

Arguments

Value

dfts object of the data.

Examples

res <- generate_far1(20, 10)

Generate functional data

Description

generate_karhunen_loeve generates functional data via an autoregressive Karhunen-Loeve expansion. The approach easily accomondate change points in the mean, distribution, eigenvalues, eigenfunctions, and so forth. In a sense, the function creates m ‘groups’ of discretely observed functions with similar properties.

Usage

generate_karhunen_loeve(
  Ns,
  eigenvalues,
  basis,
  means,
  distribution,
  fparam,
  dependence = 0,
  burnin = 100,
  silent = TRUE,
  dof = NULL,
  shape = NULL,
  prev_eps = NULL
)

Arguments

Value

List with (1) dfts data and (2) the errors of the last iteration.

Examples

dat1 <- generate_karhunen_loeve(
  Ns = 100, eigenvalues = c(1 / (1:3)), basis = fda::create.bspline.basis(nbasis = 3, norder = 3),
  means = 0, distribution = "Normal",
  fparam = seq(0, 1, 0.1), dependence = 0, burnin = 100, silent = TRUE, dof = NULL, shape = NULL,
  prev_eps = NULL
)
dat2 <- generate_karhunen_loeve(
  Ns = 50, eigenvalues = c(1 / (1:4)), basis = fda::create.bspline.basis(nbasis = 4),
  means = 5, distribution = "exponential",
  fparam = seq(0, 1, 0.1), dependence = 0, burnin = 100, silent = TRUE, dof = NULL, shape = NULL,
  prev_eps = dat1$prev_eps
)

dat <- dfts(cbind(dat1$data$data, dat2$data$data), fparam = dat1$data$fparam)

Generate Data via Ornstein-Uhlenbeck Process

Description

Generate autoregressive process with errors according the Ornstein-Uhlenbeck process.

Usage

generate_ornstein_uhlenbeck(N, v, rho = 0)

Arguments

Value

A dfts object for the generated data.

Examples

generate_ornstein_uhlenbeck(N = 100, v = 20)

Functional Imputation

Description

Several basic imputation methods for missing values in functional data formatted as dfts objects.

Usage

impute(
  X,
  method = c("zero", "mean_obs", "median_obs", "mean_data", "median_data", "linear",
    "functional"),
  obs_share_data = FALSE
)

Arguments

Value

A dfts object of the data with missing values interpolated.

Examples

temp <- data.frame(
  c(NA, NA, 3:9, NA),
  c(NA, stats::rnorm(2), NA, stats::rnorm(6)),
  stats::rnorm(10),
  c(stats::rnorm(4), rep(NA, 3), stats::rnorm(3)),
  rep(NA, 10),
  c(stats::rnorm(1), rep(NA, 9)),
  c(stats::rnorm(9), NA),
  stats::rnorm(10),
  stats::rnorm(10),
  c(NA, NA, 3:9, NA)
)
impute(temp, method = "mean_obs")
impute(temp, method = "linear", obs_share_data = TRUE)

Kernel Functions

Description

There are an assortment of (vectorized) kernel functions located in the package.

Truncated Kernel: Kernel where 1, |x|\leq 1 and 0 otherwise. If x=0/0 then the value 1 is given.

Bartlett Kernel: Kernel where max(0,1-|x|), h\neq 0. If x=0/0 then the value 1 is given.

Parzen Kernel: Kernel where 1 - 6 * x^2 + 6 * |x|^3, |x|<=0.5, 2 * (1 - |x|)^3, 0.5<|x|<1, and 0, |x|>1. If x=0/0 then the value 1 is given.

Tukey-Hanning Kernel: Kernel where (1 + cos(\pi x) )/2, |x|<=1 and 0, |x|>1. If x=0/0 then the value 1 is given.

Quadratic Spectral Kernel: Kernel where \frac{25}{12\pi^2x^2} \left(\frac{sin(6\pi x/5)}{6\pi x/5} - cos(6\pi x/5) \right). If x=0/0 then the value 1 is given.

Daniell Kernel: Kernel where sin(pi * x) / (pi * x)*(1 + cos(pi*x)), abs(x)<=1. If x=0/0 then the value 1 is given.

Flat-Top Kernel: Kernel where min(1, max(1.1-|x|,0)),|x|\leq 1. If x=0/0 then the value 1 is given.

Usage

truncated_kernel(x)

bartlett_kernel(x)

parzen_kernel(x)

tukey_hanning_kernel(x)

quadratic_spectral_kernel(x)

daniell_kernel(x)

flat_top_kernel(x)

Arguments

Value

Values from given lag(s) in the kernel.

References

Horvath, L., & Rice, G. (2024). Change point analysis for time series (1st ed. 2024.). Springer Nature Switzerland.

L. Horvath, P. Kokoszka, G. Rice (2014) "Testing stationarity of functional time series", Journal of Econometrics, 179(1), 66-82.

Politis, D. N. (2003). Adaptive bandwidth choice. Journal of Nonparametric Statistics, 15(4-5), 517-533.

Politis, D. N. (2011). Higher-order accurate, positive semidefinite estimation of large-sample covariance and spectral density matrices. Econometric Theory, 27(4), 703-744.

Examples

truncated_kernel(-20:20 / 15)
bartlett_kernel(-20:20 / 15)
parzen_kernel(-20:20 / 15)
tukey_hanning_kernel(-20:20 / 15)
quadratic_spectral_kernel(-20:20 / 15)
daniell_kernel(-20:20 / 15)
flat_top_kernel(-20:20 / 15)

Functional KPSS Test

Description

Compute the Kwiatkowski–Phillips–Schmidt–Shin (KPSS) statistic for functional data.

Usage

kpss_test(
  X,
  method = c("simulation", "resample"),
  resample_blocks = "separate",
  M = 1000,
  blocksize = 2 * ncol(X)^(1/5),
  TVE = 1,
  replace = TRUE,
  return.info = FALSE
)

Arguments

Value

List with the following elements:

1. pvalue: p-value from the test.

2. statistic: test statistic computed on the data.

3. simulations: Theoretical values for the null distribution.

References

Chen, Y., & Pun, C. S. (2019). A bootstrap-based KPSS test for functional time series. Journal of Multivariate Analysis, 174, 104535.

Kokoszka, P., & Young, G. (2016). KPSS test for functional time series. Statistics, 50(5), 957-973.

Examples

kpss_test(generate_brownian_motion(100, v = seq(0, 1, length.out = 20)))
kpss_test(generate_brownian_motion(100, v = seq(0, 1, length.out = 20)),
  method = "resample", resample_blocks = "overlapping"
)

Lag dfts objects

Description

Compute a lagged version of a functional time series, shifting the time base back by a given number of observations.

Usage

## S3 method for class 'dfts'
lag(x, k = 1, ...)

Arguments

Value

A dfts object.

See Also

stats::lag(), diff.dfts()

Examples

result <- lag(electricity)

Estimate Long-run Covariance Kernel

Description

Estimate the long-run covariance kernel for functional data. That is, solve C_{\epsilon}(t,t') = \sum_{l=-\inf}^{\inf} \text{Cov}(\epsilon_0(t), \epsilon_l(t')) with sequence (\epsilon_i : i \in \mathbb{Z}) defined as the centered data (can center based on changes if given).

Usage

long_run_covariance(
  X,
  h = 2 * ncol(X)^(1/5),
  K = bartlett_kernel,
  changes = NULL
)

Arguments

Value

Symmetric data.frame of numerics with dim of ncol(data) x ncol(data).

Examples

result <- long_run_covariance(electricity, 2)

Max / Min for dfts Objects

Description

Get the observation(s) or pointwise values with the min / max values. When using type='Obs', the selected observation is the one with the minimum or maximum mean. When using type='fparam', the values are given pointwise.

Usage

## S3 method for class 'dfts'
max(x, type = c("Obs", "fparam"), na.rm = TRUE, ...)

## S3 method for class 'dfts'
min(x, type = c("Obs", "fparam"), na.rm = TRUE, ...)

Arguments

Value

A dfts object.

Examples

results <- max(electricity)
results <- min(electricity)

Generic Function for Principal Component Analysis

Description

This is a generic function to call PCA on various objects. The default method uses stats::prcomp().

Usage

pca(object, TVE = 1, ...)

## Default S3 method:
pca(object, ...)

## S3 method for class 'dfts'
pca(object, TVE = 1, ...)

Arguments

Value

Principal component data. Note that the scores are in x and the eigenfuctions in rotation. This is to keep consistency between existing pca methods in R, but may change in the future.

Examples

pca(1:10)
pca(electricity)

Functional PCA Components

Description

Evaluates the given pca components as a function.

Usage

pca_components(pca, components = 1:length(pca$sdev))

Arguments

Value

A dfts object of the pca component(s)

Examples

tmp <- pca(electricity, TVE = 0.1)
pca_components(tmp, components = 1)

Principal Component Exploration

Description

Computes the principal component projection and re-combined data with a myriad of figures to understand the projection process.

Usage

pca_examination(X, TVE = 0.95)

Arguments

Value

List with the following elements:

• figures: List with figures on all components, summaries, reconstructed values, and residuals.

• reconstruction: Reconstructed value from PCs.

• residuals: Difference between true and reconstruction.

See Also

pca.dfts()

Examples

results <- pca_examination(electricity, TVE = 0.9)

Plot dfts objects

Description

Provides various visualizations for functional data.

Usage

## S3 method for class 'dfts'
plot(
  x,
  changes = NULL,
  type = c("spaghetti", "fast", "rainbow", "banded", "acf", "pacf", "summary", "qq",
    "distribution", "change", "interval", "surface"),
  plot_title = x$name,
  val_axis_title = NULL,
  res_axis_title = NULL,
  FD_axis_title = NULL,
  eye = NULL,
  aspectratio = NULL,
  showticklabels = TRUE,
  lag.max = 20,
  d.max = 2,
  alpha = 0.05,
  TVE = 0.95,
  distribution = c("norm"),
  method = c("Welch", "MC", "Imhof"),
  legend = TRUE,
  highlight_changes = TRUE,
  intervals = confidence_interval(x, changes),
  int.gradual = TRUE,
  ...
)

Arguments

Value

Plot of varying types.

References

John Fox, & Sanford Weisberg (2019). An R Companion to Applied Regression. Sage.

Examples

plt <- plot(electricity)
plt <- plot(dfts(var(electricity)), type = "surface")

Functional Hypothesis Tests for Functional Data

Description

Computes a variety of portmanteau hypothesis tests for functional data in the form of dfts objects.

Usage

portmanteau_tests(
  X,
  test = c("variety", "single", "multi", "spectral", "independence", "imhof"),
  lag = 5,
  M = 1000,
  method = c("iid", "bootstrap"),
  kernel = bartlett_kernel,
  block_size = NULL,
  bandwidth = NULL,
  components = 3,
  resample_blocks = "separate",
  replace = FALSE,
  alpha = 0.05
)

Arguments

Details

The "single"-lag portmanteau test assesses the significance of empirical lagged autocovariance operators at a single lag lag. It tests the null hypothesis that the lag-h autocovariance operator is equal to 0. The test is designed for stationary functional time-series, and is valid under conditional heteroscedasticity conditions.

The "multi"-lag portmanteau test assesses the cumulative significance of empirical lagged autocovariance operators, up to a user-selected maximum lag lag. It tests the null hypothesis that the first lag-h autocovariance operators, h=1,\dots,lag, is equal to 0. The test is designed for stationary functional time-series, and is valid under conditional heteroscedasticity conditions.

The "spectral" portmanteau test measures the proximity of a functional time series to a white noise. Comparison is made to the constant spectral density operator of an uncorrelated series. The test is not for general white noise series, and may not hold under functional conditionally heteroscedastic assumptions.

The "independence" portmanteau test measures independence and identical distribution based lagged cross-variances from dimension reduction using functional principal components analysis. The test is not for general white noise series, and may not hold under functional conditionally heteroscedastic assumptions.

The "imhof" portmanteau test is an analogue of the "single-lag" test. While the "single-lag" test computes the limiting distribution of the test statistic via a Welch-Satterthwaite approximation, the "imhof" test directly computes the coefficients of the quadratic form in normal variables. Hence, the test is computationally expensive.

Value

List with results dependent on the test. In general, returns the pvalue, statistic, and simulations/quantile.

References

Kim, M., Kokoszka P., & Rice G. (2023) White noise testing for functional time series. Statist. Surv., 17, 119-168, DOI: 10.1214/23-SS143

Characiejus, V., & Rice, G. (2020). A general white noise test based on kernel lag-window estimates of the spectral density operator. Econometrics and Statistics, 13, 175–196.

Kokoszka P., & Rice G., & Shang H.L. (2017). Inference for the autocovariance of a functional time series under conditional heteroscedasticity. Journal of Multivariate Analysis, 162, 32-50.

Zhang X. (2016). White noise testing and model diagnostic checking for functional time series. Journal of Econometrics, 194, 76-95.

Gabrys R., & Kokoszka P. (2007). Portmanteau Test of Independence for Functional Observations. Journal of the American Statistical Association, 102:480, 1338-1348, DOI: 10.1198/016214507000001111.

Chen W.W. & Deo R.S. (2004). Power transformations to induce normality and their applications. Journal of the Royal Statistical Society: Series B (Statistical Methodology), 66, 117-130.

Examples

b <- generate_brownian_motion(100)
res0 <- portmanteau_tests(b, test = "single", lag = 2, M=50)
res1 <- portmanteau_tests(b, test = "multi", lag = 2, alpha = 0.01)
res2 <- portmanteau_tests(b,
  test = "spectral", alpha = 0.1,
  kernel = parzen_kernel,
  bandwidth = adaptive_bandwidth(b, kernel = parzen_kernel)
)
res3 <- portmanteau_tests(b, test = "independence", components = 2, lag = 2)

Print dfts objects

Description

Basic formatting to print a dfts object.

Usage

## S3 method for class 'dfts'
print(x, ...)

Arguments

Value

No return value, called to format printing of dfts object to console.

Examples

electricity

Projection-based functional data model

Description

Model and forecast functional data using a Hyndman and Ullah projection-based model.

Usage

projection_model(
  X,
  TVE = 0.95,
  forecast.model = c("ets", "arima"),
  n.ahead = 0,
  alpha = 0.05,
  check.cp = TRUE,
  sim.bounds = TRUE,
  M = 1000,
  transformation = NULL,
  ...
)

Arguments

Value

List with the following elements:

• data: List with data information.

• plots: List with various plots.

• residuals: dfts object for residuals from the fit.

• changes: vector of any changes when using detect.cp.

• parameters: List with fit parameters like pcs, TVE, model, and n.ahead.

References

Hyndman, R. J., & Shahid Ullah, M. (2007). Robust forecasting of mortality and fertility rates: A functional data approach. Computational Statistics & Data Analysis, 51(10), 4942-4956. https://doi.org/10.1016/j.csda.2006.07.028

Examples

result <- projection_model(dfts(electricity$data[, 50:100], season = 7),
  n.ahead = 1, TVE = 0.1, check.cp = FALSE, sim.bounds = FALSE
)

QQ Plot Generic Function

Description

A generic function which by produces a qq-plot of some data. By default, it uses stats::qqplot().

qqplot.dfts: Creates normal QQ plots on the principal components of functional data.

Usage

qqplot(x, ...)

## Default S3 method:
qqplot(x, ...)

## S3 method for class 'dfts'
qqplot(
  x,
  TVE = 0.95,
  d.max = NULL,
  alpha = 0.05,
  changes = NULL,
  legend = FALSE,
  ...
)

Arguments

Value

qqplot.default: returns results from stats::qqplot().

qqplot.dfts: ggplot2 for QQ plot.

See Also

stats::qqplot()

Examples

result <- qqplot(electricity, d.max = 3)

Quantile dfts

Description

Obtain the pointwise quantile information of functional data.

Usage

## S3 method for class 'dfts'
quantile(x, probs = seq(0, 1, 0.25), ...)

Arguments

Value

Matrix with columns for each requested quantile computed pointwise.

See Also

stats::quantile()

Examples

result <- quantile(electricity)
result1 <- quantile(electricity, probs = 0.95)

US Yield Curves

Description

Yield curves in the US for 1 - 360 month maturity from 1990 to 2023 (removing days without information, i.e. weekends and holidays).

Usage

rates

Format

rates

A dfts object.

Functional Spherical Autocorrelation Function

Description

This function offers a graphical summary of the fSACF of a functional time series (FTS) across different time lags h = 1:H. It also plots 100 \times (1-\alpha)\% confidence bounds developed under strong white noise (SWN) assumption for all lags h = 1:H.

Usage

sacf(X, lag.max = 20, alpha = 0.05, figure = TRUE)

Arguments

Details

This function computes and plots functional spherical autocorrelation coefficients at lag h, for h = 1:H. The fSACF at lag h is computed by the average of the inner product of lagged pairs of the series X_i and X_{i+h} that have been centered and scaled:

\tilde\rho_h=\frac{1}{N}\sum_{i=1}^{N-h} \langle \frac{X_i - \tilde{\mu}}{\|X_i - \tilde{\mu}\|}, \frac{X_{i+h} - \tilde{\mu}}{\|X_{i+h} - \tilde{\mu}\|} \rangle,\ \ \ \ 0 \le h < N,

where \tilde{\mu} is the estimated spatial median of the series. It also computes estimated asymptotic (1-\alpha)100 \% confidence lower and upper bounds, under the SWN assumption.

Value

List with sACF values and plots

References

Yeh C.K., Rice G., Dubin J.A. (2023). Functional spherical autocorrelation: A robust estimate of the autocorrelation of a functional time series. Electronic Journal of Statistics, 17, 650–687.

See Also

acf()

Examples

sacf(electricity)
sacf(generate_brownian_motion(100))

Generic Function for Variance and Standard Deviation Computation

Description

Generic function to compute the variance and standard deviations. The default uses stats::var() and stats::sd().

Usage

sd(object, ...)

## Default S3 method:
sd(object, ...)

## S3 method for class 'dfts'
sd(object, type = "pointwise", ...)

var(object, ...)

## Default S3 method:
var(object, ...)

## S3 method for class 'dfts'
var(object, type = c("operator", "pointwise"), ...)

Arguments

Value

Numeric(s) to explain the standard deviation / variance

See Also

stats::sd(), stats::var()

Examples

sd(1:10)
var(1:10)
sd(electricity, type = "pointwise")
var(electricity, type = "pointwise")
var(electricity, type = "operator")

Compute Spacing Measuring Functions

Description

This function is used to compute discretized functions, i.e. vectors, to explore functional spaces.

Usage

space_measuring_functions(X, M = 20, space = "BM")

Arguments

Value

Data.frame with columns of discretized functions describing the space. Columns are independent functions.

See Also

fchange()

Examples

space_measuring_functions(M = 10, space = "BM", X = electricity)
space_measuring_functions(M = 10, space = "PC", X = electricity)

Draw 3D Geoms for ggplot2

Description

This function adds 3D geoms such as points and paths to a ggplot2 plot.

Usage

stat_3D(
  mapping = NULL,
  data = NULL,
  geom = "point",
  position = "identity",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

Arguments

Value

No direct return value, called to be used with ggplot2::ggplot() in designing the plot.

References

Acker D (2024). gg3D: 3D perspective plots for ggplot2. R package version 0.0.0.9000.

Examples

dat <- electricity

data_lines <- cbind(data.frame("Time" = dat$fparam), dat$data) %>%
  tidyr::pivot_longer(cols = 1 + 1:ncol(dat$data))

colors_plot <- RColorBrewer::brewer.pal(11, "Spectral")
colors_plot <- grDevices::colorRampPalette(colors_plot)(ncol(dat$data))
data_lines$color <- rep(colors_plot, nrow(dat$data))
data_lines$name <- as.numeric(data_lines$name)

result <- ggplot2::ggplot(
  data_lines,
  ggplot2::aes(y = Time, x = name, z = value, color = color)
) +
  ggplot2::theme_void() +
  stat_3D(theta = 0, phi = 15, geom = "path") +
  ggplot2::scale_color_manual(
    breaks = data_lines$color,
    values = data_lines$color
  ) +
  ggplot2::guides(color = "none")

Functional Stationarity Test

Description

Stationarity test for functional time series with different methods on determining the critical values of the test statistic. The Monte Carlo method was constructed in Horvath et al. (2014), while the resample-based methods have not been validated in the literature (use the provided option at your discretion).

Usage

stationarity_test(
  X,
  statistic = "Tn",
  critical = c("simulation", "resample"),
  perm_method = "separate",
  M = 1000,
  blocksize = 2 * ncol(X)^(1/5),
  TVE = 1,
  replace = TRUE,
  return.info = FALSE
)

Arguments

Value

List with the following elements:

1. pvalue: p-value for the stationarity test.

2. statistic: test statistic from the test.

3. simulations: simulations which define the null distribution.

References

Horvath, L., Kokoszka, P., & Rice, G. (2014). Testing stationarity of functional time series. Journal of Econometrics, 179(1), 66-82.

Examples

res <- stationarity_test(
  generate_brownian_motion(100, v = seq(0, 1, length.out = 20)),
  critical = "resample", statistic = "Mn"
)
res2 <- stationarity_test(electricity)

Summary for dfts Object

Description

General summary function to view data overview. Several plots and test statistics are returned to give a general view of the data. More details can be found with more specialized functions.

Usage

## S3 method for class 'dfts'
summary(object, changes = NULL, lag.max = 20, d.max = 2, demean = FALSE, ...)

Arguments

Value

List with the elements:

1. summary_data: summary results for the data.

2. summary_plot: summary plot for the data.

See Also

base::summary()

Examples

# All parameters extremely low for speed
res <- summary(electricity[, 1:10], lag.max = 1, d.max=1, M=10)

Australian Temperature Data

Description

A list of daily minimum temperature data (1859 - 2012) from reporting station in Sydney, Australia. Any missing data was previously, linearly, interpolated and leap days were removed for consistency.

Usage

temperature

Format

temperature

A dfts object.

Source

<www.bom.gov.au>