fdars: Functional Data Analysis in 'Rust'

Description

Functional data analysis tools with a high-performance 'Rust' backend. Provides methods for functional data manipulation, depth computation, distance metrics, regression, and statistical testing. Supports both 1D functional data (curves) and 2D functional data (surfaces). Methods are described in Ramsay and Silverman (2005, ISBN:978-0-387-40080-8) "Functional Data Analysis" and Ferraty and Vieu (2006, ISBN:978-0-387-30369-7) "Nonparametric Functional Data Analysis".

Author(s)

Maintainer: Simon Müller simon.mueller@muon-stat.com

See Also

Useful links:

• https://sipemu.github.io/fdars-r/

• https://github.com/sipemu/fdars-r

• Report bugs at https://github.com/sipemu/fdars-r/issues

Package initialization

Description

Package initialization

Usage

.onLoad(libname, pkgname)

Asymmetric Cosine Kernel

Description

Asymmetric Cosine Kernel

Usage

AKer.cos(u)

Arguments

Value

Kernel values at u (0 for u < 0).

Examples

u <- seq(-0.5, 1.5, length.out = 100)
plot(u, AKer.cos(u), type = "l", main = "Asymmetric Cosine Kernel")

Asymmetric Epanechnikov Kernel

Description

Asymmetric Epanechnikov Kernel

Usage

AKer.epa(u)

Arguments

Value

Kernel values at u (0 outside [0, 1]).

Examples

u <- seq(-0.5, 1.5, length.out = 100)
plot(u, AKer.epa(u), type = "l", main = "Asymmetric Epanechnikov Kernel")

Asymmetric Normal Kernel

Description

Asymmetric Normal Kernel

Usage

AKer.norm(u)

Arguments

Value

Kernel values at u (0 for u < 0).

Examples

u <- seq(-0.5, 3, length.out = 100)
plot(u, AKer.norm(u), type = "l", main = "Asymmetric Normal Kernel")

Asymmetric Quartic Kernel

Description

Asymmetric Quartic Kernel

Usage

AKer.quar(u)

Arguments

Value

Kernel values at u (0 outside [0, 1]).

Examples

u <- seq(-0.5, 1.5, length.out = 100)
plot(u, AKer.quar(u), type = "l", main = "Asymmetric Quartic Kernel")

Asymmetric Triweight Kernel

Description

Asymmetric Triweight Kernel

Usage

AKer.tri(u)

Arguments

Value

Kernel values at u (0 outside [0, 1]).

Examples

u <- seq(-0.5, 1.5, length.out = 100)
plot(u, AKer.tri(u), type = "l", main = "Asymmetric Triweight Kernel")

Asymmetric Uniform Kernel

Description

Asymmetric Uniform Kernel

Usage

AKer.unif(u)

Arguments

Value

Kernel values at u (0 outside [0, 1]).

Examples

u <- seq(-0.5, 1.5, length.out = 100)
plot(u, AKer.unif(u), type = "l", main = "Asymmetric Uniform Kernel")

Cross-Validation for Smoother Selection

Description

Compute leave-one-out cross-validation criterion for a smoother.

Usage

CV.S(S.type, tt, h, y, Ker = "norm", w = NULL)

Arguments

Value

The cross-validation score (mean squared prediction error).

Examples

tt <- seq(0, 1, length.out = 50)
y <- sin(2 * pi * tt) + rnorm(50, sd = 0.1)
cv_score <- CV.S(S.NW, tt, h = 0.1, y = y)

Generalized Cross-Validation for Smoother Selection

Description

Compute GCV criterion: RSS / (1 - tr(S)/n)^2

Usage

GCV.S(S.type, tt, h, y, Ker = "norm", w = NULL)

Arguments

Value

The GCV score.

Examples

tt <- seq(0, 1, length.out = 50)
y <- sin(2 * pi * tt) + rnorm(50, sd = 0.1)
gcv_score <- GCV.S(S.NW, tt, h = 0.1, y = y)

Integrated Cosine Kernel

Description

Integral of Ker.cos from -1 to u.

Usage

IKer.cos(u)

Arguments

Value

Cumulative integral values.

Examples

u <- seq(-1.5, 1.5, length.out = 100)
plot(u, IKer.cos(u), type = "l", main = "Integrated Cosine Kernel")

Integrated Epanechnikov Kernel

Description

Integral of Ker.epa from -1 to u.

Usage

IKer.epa(u)

Arguments

Value

Cumulative integral values.

Examples

u <- seq(-1.5, 1.5, length.out = 100)
plot(u, IKer.epa(u), type = "l", main = "Integrated Epanechnikov Kernel")

Integrated Normal Kernel

Description

Integrated Normal Kernel

Usage

IKer.norm(u)

Arguments

Value

Cumulative integral of normal kernel from -Inf to u.

Examples

u <- seq(-3, 3, length.out = 100)
plot(u, IKer.norm(u), type = "l", main = "Integrated Normal Kernel")

Integrated Quartic Kernel

Description

Integral of Ker.quar from -1 to u.

Usage

IKer.quar(u)

Arguments

Value

Cumulative integral values.

Examples

u <- seq(-1.5, 1.5, length.out = 100)
plot(u, IKer.quar(u), type = "l", main = "Integrated Quartic Kernel")

Integrated Triweight Kernel

Description

Integral of Ker.tri from -1 to u.

Usage

IKer.tri(u)

Arguments

Value

Cumulative integral values.

Examples

u <- seq(-1.5, 1.5, length.out = 100)
plot(u, IKer.tri(u), type = "l", main = "Integrated Triweight Kernel")

Integrated Uniform Kernel

Description

Integral of Ker.unif from -1 to u.

Usage

IKer.unif(u)

Arguments

Value

Cumulative integral values.

Examples

u <- seq(-1.5, 1.5, length.out = 100)
plot(u, IKer.unif(u), type = "l", main = "Integrated Uniform Kernel")

Cosine Kernel

Description

Cosine Kernel

Usage

Ker.cos(u)

Arguments

Value

Kernel values at u (0 outside [-1, 1]).

Examples

u <- seq(-1.5, 1.5, length.out = 100)
plot(u, Ker.cos(u), type = "l", main = "Cosine Kernel")

Epanechnikov Kernel

Description

Epanechnikov Kernel

Usage

Ker.epa(u)

Arguments

Value

Kernel values at u (0 outside [-1, 1]).

Examples

u <- seq(-1.5, 1.5, length.out = 100)
plot(u, Ker.epa(u), type = "l", main = "Epanechnikov Kernel")

Kernel Functions

Description

Symmetric, asymmetric, and integrated kernel functions for nonparametric smoothing and density estimation. Normal (Gaussian) Kernel

Usage

Ker.norm(u)

Arguments

Value

Kernel values at u.

Examples

u <- seq(-3, 3, length.out = 100)
plot(u, Ker.norm(u), type = "l", main = "Normal Kernel")

Quartic (Biweight) Kernel

Description

Quartic (Biweight) Kernel

Usage

Ker.quar(u)

Arguments

Value

Kernel values at u (0 outside [-1, 1]).

Examples

u <- seq(-1.5, 1.5, length.out = 100)
plot(u, Ker.quar(u), type = "l", main = "Quartic Kernel")

Triweight Kernel

Description

Triweight Kernel

Usage

Ker.tri(u)

Arguments

Value

Kernel values at u (0 outside [-1, 1]).

Examples

u <- seq(-1.5, 1.5, length.out = 100)
plot(u, Ker.tri(u), type = "l", main = "Triweight Kernel")

Uniform (Rectangular) Kernel

Description

Uniform (Rectangular) Kernel

Usage

Ker.unif(u)

Arguments

Value

Kernel values at u (0 outside [-1, 1]).

Examples

u <- seq(-1.5, 1.5, length.out = 100)
plot(u, Ker.unif(u), type = "l", main = "Uniform Kernel")

Unified Symmetric Kernel Interface

Description

Evaluates a symmetric kernel function by name.

Usage

Kernel(u, type.Ker = "norm")

Arguments

Value

Kernel values at u.

Examples

u <- seq(-1.5, 1.5, length.out = 100)
plot(u, Kernel(u, "epa"), type = "l")
lines(u, Kernel(u, "norm"), col = "red")

Unified Asymmetric Kernel Interface

Description

Evaluates an asymmetric kernel function by name.

Usage

Kernel.asymmetric(u, type.Ker = "norm")

Arguments

Value

Kernel values at u.

Examples

u <- seq(-0.5, 1.5, length.out = 100)
plot(u, Kernel.asymmetric(u, "epa"), type = "l")

Unified Integrated Kernel Interface

Description

Evaluates an integrated kernel function by name.

Usage

Kernel.integrate(u, Ker = "norm", a = -1)

Arguments

Value

Cumulative integral values.

Examples

u <- seq(-1.5, 1.5, length.out = 100)
plot(u, Kernel.integrate(u, "epa"), type = "l")

Arithmetic Operations for Functional Data

Description

Perform elementwise arithmetic on fdata objects. Supports addition, subtraction, multiplication, division, and exponentiation between two fdata objects or between an fdata object and a numeric scalar.

Usage

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

Arguments

Value

An fdata object with the result.

Examples

fd1 <- fdata(matrix(1:20, 4, 5))
fd2 <- fdata(matrix(21:40, 4, 5))
fd1 + fd2
fd1 * 2
3 - fd1

K-Nearest Neighbors Smoother Matrix

Description

Compute a smoother matrix using adaptive bandwidth based on the k nearest neighbors. The bandwidth at each point is the distance to the k-th nearest neighbor.

Usage

S.KNN(tt, knn, Ker = "norm", w = NULL, cv = FALSE)

Arguments

Value

An n x n smoother matrix S.

Examples

tt <- seq(0, 1, length.out = 50)
S <- S.KNN(tt, knn = 10)

Local Cubic Regression Smoother Matrix

Description

Convenience function for Local Polynomial Regression with degree 3.

Usage

S.LCR(tt, h, Ker = "norm", w = NULL, cv = FALSE)

Arguments

Value

An n x n smoother matrix S.

Examples

tt <- seq(0, 1, length.out = 50)
S <- S.LCR(tt, h = 0.15)

Local Linear Regression Smoother Matrix

Description

Compute the Local Linear Regression (LLR) smoother matrix. LLR has better boundary bias properties than Nadaraya-Watson.

Usage

S.LLR(tt, h, Ker = "norm", w = NULL, cv = FALSE)

Arguments

Value

An n x n smoother matrix S.

Examples

tt <- seq(0, 1, length.out = 50)
S <- S.LLR(tt, h = 0.1)

Local Polynomial Regression Smoother Matrix

Description

Compute the Local Polynomial Regression smoother matrix of degree p. Special cases: p=0 is Nadaraya-Watson, p=1 is Local Linear Regression.

Usage

S.LPR(tt, h, p = 1, Ker = "norm", w = NULL, cv = FALSE)

Arguments

Value

An n x n smoother matrix S.

Examples

tt <- seq(0, 1, length.out = 50)
S <- S.LPR(tt, h = 0.1, p = 2)  # Local quadratic regression

Smoothing Functions for Functional Data

Description

Functions for computing smoothing matrices and applying kernel smoothing to functional data. Nadaraya-Watson Kernel Smoother Matrix

Usage

S.NW(tt, h, Ker = "norm", w = NULL, cv = FALSE)

Arguments

Details

Compute the Nadaraya-Watson kernel smoother matrix.

Value

An n x n smoother matrix S such that smooth(y) = S %*% y.

Examples

tt <- seq(0, 1, length.out = 50)
S <- S.NW(tt, h = 0.1)
dim(S)  # 50 x 50

Subset method for fdata objects

Description

Subset method for fdata objects

Usage

## S3 method for class 'fdata'
x[i, j, drop = FALSE]

Arguments

Value

An fdata object containing the selected subset.

Subset method for irregFdata objects

Description

Subset method for irregFdata objects

Usage

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

Arguments

Value

An irregFdata object containing the selected subset.

Add Measurement Error to Functional Data

Description

Adds independent Gaussian noise to functional data observations.

Usage

addError(fdataobj, sd = 0.1, type = c("pointwise", "curve"), seed = NULL)

Arguments

Value

An fdata object with added noise.

See Also

simFunData, sparsify

Examples

t <- seq(0, 1, length.out = 100)
fd_clean <- simFunData(n = 20, argvals = t, M = 5, seed = 42)
fd_noisy <- addError(fd_clean, sd = 0.1)

oldpar <- par(mfrow = c(1, 2))
plot(fd_clean, main = "Clean Data")
plot(fd_noisy, main = "With Noise (sd = 0.1)")
par(oldpar)

# Higher noise level
fd_very_noisy <- addError(fd_clean, sd = 0.5)
plot(fd_very_noisy, main = "High Noise (sd = 0.5)")

Analyze Peak Timing Variability

Description

For short series (e.g., 3-5 years of yearly data), this function detects one peak per cycle and analyzes how peak timing varies between cycles. Uses Fourier basis smoothing for peak detection.

Usage

analyze.peak.timing(fdataobj, period, smooth_nbasis = NULL)

Arguments

Details

The variability score is computed as std_timing / 0.1, capped at 1. A score > 0.5 suggests peaks are shifting substantially between cycles. The timing_trend indicates if peaks are systematically moving earlier or later over time.

Fourier basis smoothing is ideal for seasonal signals because it naturally captures periodic patterns.

Value

A list with components:

peak_times

Vector of peak times

peak_values

Vector of peak values

normalized_timing

Position within cycle (0-1 scale)

mean_timing

Mean normalized timing

std_timing

Standard deviation of normalized timing

range_timing

Range of normalized timing (max - min)

variability_score

Variability score (0 = stable, 1 = highly variable)

timing_trend

Linear trend in timing (positive = peaks getting later)

cycle_indices

Cycle indices (1-indexed)

Examples

# 5 years of yearly data where peak shifts
t <- seq(0, 5, length.out = 365 * 5)
periods <- c(1, 1, 1, 1, 1)  # 5 complete years
# Peaks shift: March (0.2), April (0.3), May (0.4), April (0.3), March (0.2)
peak_phases <- c(0.2, 0.3, 0.4, 0.3, 0.2)
X <- sin(2 * pi * t + rep(peak_phases, each = 365))
fd <- fdata(matrix(X, nrow = 1), argvals = t)

result <- analyze.peak.timing(fd, period = 1)
print(result$variability_score)  # Shows timing variability

Convert Irregular Functional Data to Regular Grid

Description

Creates a regular fdata object from an irregFdata object by interpolating or placing NA at unobserved points.

Usage

## S3 method for class 'irregFdata'
as.fdata(x, argvals = NULL, method = c("na", "linear", "nearest"), ...)

as.fdata(x, ...)

## S3 method for class 'fdata'
as.fdata(x, ...)

Arguments

Value

An fdata object with NA for unobserved points (unless interpolated).

See Also

sparsify, irregFdata

Examples

# Create sparse data
t <- seq(0, 1, length.out = 100)
fd <- simFunData(n = 10, argvals = t, M = 5, seed = 42)
ifd <- sparsify(fd, minObs = 10, maxObs = 30, seed = 123)

# Convert back to regular grid with NA
fd_na <- as.fdata(ifd)

# Convert with linear interpolation
fd_interp <- as.fdata(ifd, method = "linear")

Autoperiod: Hybrid FFT + ACF Period Detection

Description

Implements the Autoperiod algorithm (Vlachos et al. 2005) which combines FFT-based candidate detection with ACF validation and gradient ascent refinement for robust period estimation.

Usage

autoperiod(
  fdataobj,
  n_candidates = 5,
  gradient_steps = 10,
  detrend_method = c("none", "linear", "auto")
)

Arguments

Details

The Autoperiod algorithm works in three stages:

1. Candidate Detection: Finds peaks in the FFT periodogram

2. ACF Validation: Validates each candidate using the autocorrelation function. Checks that the ACF shows a peak at the candidate period, and applies harmonic analysis to distinguish fundamental periods from harmonics.

3. Gradient Refinement: Refines each candidate using gradient ascent on the ACF to find the exact period that maximizes the ACF peak.

The final period is chosen based on the product of normalized FFT power and ACF validation score.

Value

A list of class "autoperiod_result" with components:

period

Best detected period

confidence

Combined confidence (normalized FFT power * ACF validation)

fft_power

FFT power at the detected period

acf_validation

ACF validation score (0-1)

n_candidates

Number of candidates evaluated

candidates

Data frame of all candidate periods with their scores

References

Vlachos, M., Yu, P., & Castelli, V. (2005). On periodicity detection and structural periodic similarity. In Proceedings of the 2005 SIAM International Conference on Data Mining.

See Also

sazed for an ensemble method, estimate.period for simpler single-method estimation

Examples

# Generate seasonal data with period = 2
t <- seq(0, 20, length.out = 400)
X <- matrix(sin(2 * pi * t / 2) + 0.1 * rnorm(400), nrow = 1)
fd <- fdata(X, argvals = t)

# Detect period using Autoperiod
result <- autoperiod(fd)
print(result)

# View all candidates
print(result$candidates)

Create a ggplot for fdata objects

Description

For 1D functional data, plots curves as lines with optional coloring by external variables. For 2D functional data, plots surfaces as heatmaps with contour lines.

Usage

## S3 method for class 'fdata'
autoplot(
  object,
  color = NULL,
  alpha = NULL,
  show.mean = FALSE,
  show.ci = FALSE,
  ci.level = 0.9,
  palette = NULL,
  ...
)

Arguments

Details

Use autoplot() to get the ggplot object without displaying it. Use plot() to display the plot (returns invisibly).

Value

A ggplot object.

Examples

library(ggplot2)
# Get ggplot object without displaying
fd <- fdata(matrix(rnorm(200), 20, 10))
p <- autoplot(fd)

# Customize the plot
p + theme_minimal()

# Color by numeric variable
y <- rnorm(20)
autoplot(fd, color = y)

# Color by category with mean and CI
groups <- factor(rep(c("A", "B"), each = 10))
autoplot(fd, color = groups, show.mean = TRUE, show.ci = TRUE)

Autoplot method for irregFdata objects

Description

Autoplot method for irregFdata objects

Usage

## S3 method for class 'irregFdata'
autoplot(object, ..., alpha = 0.7)

Arguments

Value

A ggplot object.

AIC for Basis Representation

Description

Computes the Akaike Information Criterion for a basis representation. Lower AIC indicates better model (balancing fit and complexity).

Usage

basis.aic(
  fdataobj,
  nbasis,
  type = c("bspline", "fourier"),
  lambda = 0,
  pooled = TRUE
)

Arguments

Details

AIC is computed as:

AIC = n \log(RSS/n) + 2 \cdot edf

When pooled = TRUE, the criterion uses total observations and total effective degrees of freedom (n_curves * edf). When pooled = FALSE, the criterion is computed for each curve separately and the mean is returned.

Value

The AIC value (scalar).

BIC for Basis Representation

Description

Computes the Bayesian Information Criterion for a basis representation. BIC penalizes complexity more strongly than AIC for larger samples.

Usage

basis.bic(
  fdataobj,
  nbasis,
  type = c("bspline", "fourier"),
  lambda = 0,
  pooled = TRUE
)

Arguments

Details

BIC is computed as:

BIC = n \log(RSS/n) + \log(n) \cdot edf

When pooled = TRUE, the criterion uses total observations and total effective degrees of freedom (n_curves * edf). When pooled = FALSE, the criterion is computed for each curve separately and the mean is returned.

Value

The BIC value (scalar).

GCV Score for Basis Representation

Description

Computes the Generalized Cross-Validation score for a basis representation. Lower GCV indicates better fit with appropriate complexity.

Usage

basis.gcv(
  fdataobj,
  nbasis,
  type = c("bspline", "fourier"),
  lambda = 0,
  pooled = TRUE
)

Arguments

Details

GCV is computed as:

GCV = \frac{RSS/n}{(1 - edf/n)^2}

where RSS is the residual sum of squares and edf is the effective degrees of freedom (trace of the hat matrix).

When pooled = TRUE, the criterion is computed globally across all curves. When pooled = FALSE, the criterion is computed for each curve separately and the mean is returned. Use pooled = FALSE when curves have heterogeneous noise levels.

Value

The GCV score (scalar).

Examples

t <- seq(0, 1, length.out = 50)
X <- matrix(sin(2 * pi * t) + rnorm(50, sd = 0.1), nrow = 1)
fd <- fdata(X, argvals = t)

# Compare GCV for different nbasis
gcv_5 <- basis.gcv(fd, nbasis = 5)
gcv_10 <- basis.gcv(fd, nbasis = 10)
gcv_20 <- basis.gcv(fd, nbasis = 20)

Basis Representation Functions for Functional Data

Description

Functions for representing functional data using basis expansions, including B-splines, Fourier bases, and P-splines with penalization. Reconstruct Functional Data from Basis Coefficients

Usage

basis2fdata(
  coefs,
  argvals,
  nbasis = NULL,
  type = c("bspline", "fourier"),
  rangeval = NULL
)

Arguments

Details

Given basis coefficients, reconstruct the functional data by evaluating the basis expansion at specified argument values.

The reconstruction computes X(t) = sum(coef_k * B_k(t)) where B_k are the basis functions evaluated at argvals.

Value

An fdata object with reconstructed curves.

Examples

# Create some functional data
t <- seq(0, 1, length.out = 100)
X <- matrix(sin(2 * pi * t), nrow = 1)
fd <- fdata(X, argvals = t)

# Project to basis and reconstruct
coefs <- fdata2basis(fd, nbasis = 15, type = "fourier")
fd_recon <- basis2fdata(coefs, argvals = t, type = "fourier")

Reconstruct 2D Functional Data from Tensor Product Basis Coefficients

Description

Reconstructs 2D surfaces from tensor product basis coefficients.

Usage

basis2fdata_2d(
  coefs,
  argvals,
  nbasis.s,
  nbasis.t,
  type = c("bspline", "fourier")
)

Arguments

Value

A 2D fdata object.

Functional Boxplot

Description

Creates a functional boxplot for visualizing the distribution of functional data. The boxplot shows the median curve, central 50 percent envelope, fence (equivalent to whiskers), and outliers.

Usage

## S3 method for class 'fdata'
boxplot(
  x,
  prob = 0.5,
  factor = 1.5,
  depth.func = depth.MBD,
  show.outliers = TRUE,
  col.median = "black",
  col.envelope = "magenta",
  col.fence = "pink",
  col.outliers = "red",
  ...
)

Arguments

Details

The functional boxplot (Sun & Genton, 2011) generalizes the standard boxplot to functional data using depth ordering:

• Median: The curve with maximum depth

• Central region: Envelope of curves with top 50 percent depth

• Fence: 1.5 times the envelope width beyond the central region

• Outliers: Curves that exceed the fence at any point

Value

A list of class 'fbplot' with components:

median

Index of the median curve

central

Indices of curves in the central region

outliers

Indices of outlier curves

depth

Depth values for all curves

plot

The ggplot object

References

Sun, Y. and Genton, M.G. (2011). Functional boxplots. Journal of Computational and Graphical Statistics, 20(2), 316-334.

See Also

depth.MBD for the default depth function, outliers.boxplot for outlier detection using functional boxplots

Examples

# Create functional data with outliers
set.seed(42)
t <- seq(0, 1, length.out = 50)
X <- matrix(0, 30, 50)
for (i in 1:28) X[i, ] <- sin(2*pi*t) + rnorm(50, sd = 0.2)
X[29, ] <- sin(2*pi*t) + 2  # Magnitude outlier
X[30, ] <- cos(2*pi*t)       # Shape outlier
fd <- fdata(X, argvals = t)

# Create functional boxplot
fbp <- boxplot(fd)

CFDAutoperiod: Clustered Filtered Detrended Autoperiod

Description

Implements the CFDAutoperiod algorithm (Puech et al. 2020) which applies first-order differencing for detrending, then uses density-based clustering of spectral peaks and ACF validation on the original signal.

Usage

cfd.autoperiod(fdataobj, cluster_tolerance = 0.1, min_cluster_size = 1)

Arguments

Details

The CFDAutoperiod algorithm works in five stages:

1. Differencing: First-order differencing removes polynomial trends

2. FFT: Computes periodogram on the detrended signal

3. Peak Detection: Finds all peaks above the noise floor

4. Clustering: Groups nearby period candidates into clusters

5. ACF Validation: Validates cluster centers using the ACF of the original (non-differenced) signal

This method is particularly effective for:

• Signals with strong polynomial trends

• Multiple concurrent periodicities

• Signals where spectral leakage creates nearby spurious peaks

Value

A list of class "cfd_autoperiod_result" with components:

period

Primary detected period (best validated cluster center)

confidence

Combined confidence (ACF validation * spectral power)

acf_validation

ACF validation score for the primary period

n_periods

Number of validated period clusters

periods

All detected period cluster centers

confidences

Confidence scores for each detected period

References

Puech, T., Boussard, M., D'Amato, A., & Millerand, G. (2020). A fully automated periodicity detection in time series. In Advanced Analytics and Learning on Temporal Data (pp. 43-54). Springer.

See Also

autoperiod for the original Autoperiod algorithm, sazed for an ensemble method

Examples

# Generate data with trend
t <- seq(0, 20, length.out = 400)
X <- matrix(0.2 * t + sin(2 * pi * t / 2), nrow = 1)
fd <- fdata(X, argvals = t)

# CFDAutoperiod handles trends via differencing
result <- cfd.autoperiod(fd)
print(result)

# Multiple periods detected
X2 <- matrix(sin(2 * pi * t / 2) + 0.5 * sin(2 * pi * t / 5), nrow = 1)
fd2 <- fdata(X2, argvals = t)
result2 <- cfd.autoperiod(fd2)
print(result2$periods)  # All detected periods

Classify Seasonality Type

Description

Classifies the type of seasonality in functional data. Particularly useful for short series (3-5 years) to identify stable vs variable timing patterns.

Usage

classify.seasonality(
  fdataobj,
  period,
  strength_threshold = NULL,
  timing_threshold = NULL
)

Arguments

Details

Classification types:

• StableSeasonal: Regular peaks with consistent timing

• VariableTiming: Regular peaks but timing shifts between cycles

• IntermittentSeasonal: Some cycles seasonal, some not

• NonSeasonal: No clear seasonality

Value

A list with components:

is_seasonal

Logical: is the series seasonal overall?

has_stable_timing

Logical: is peak timing stable across cycles?

timing_variability

Timing variability score (0-1)

seasonal_strength

Overall seasonal strength

cycle_strengths

Per-cycle seasonal strength

weak_seasons

Indices of weak/missing seasons (0-indexed)

classification

One of: "StableSeasonal", "VariableTiming", "IntermittentSeasonal", "NonSeasonal"

peak_timing

Peak timing analysis (if peaks detected)

Examples

# Pure seasonal signal
t <- seq(0, 10, length.out = 500)
X <- matrix(sin(2 * pi * t / 2), nrow = 1)
fd <- fdata(X, argvals = t)

result <- classify.seasonality(fd, period = 2)
print(result$classification)  # "StableSeasonal"

Fuzzy C-Means Clustering for Functional Data

Description

Performs fuzzy c-means clustering on functional data, where each curve has a membership degree to each cluster rather than a hard assignment.

Usage

cluster.fcm(fdataobj, ncl, m = 2, max.iter = 100, tol = 1e-06, seed = NULL)

Arguments

Details

Fuzzy c-means minimizes the objective function:

J = \sum_{i=1}^n \sum_{c=1}^k u_{ic}^m ||X_i - v_c||^2

where u_ic is the membership of curve i in cluster c, v_c is the cluster center, and m is the fuzziness parameter.

The membership degrees are updated as:

u_{ic} = 1 / \sum_{j=1}^k (d_{ic}/d_{ij})^{2/(m-1)}

When m approaches 1, FCM becomes equivalent to hard k-means. As m increases, the clusters become softer (more overlap). m = 2 is the most common choice.

Value

A list of class 'fuzzycmeans.fd' with components:

membership

Matrix of membership degrees (n x ncl). Each row sums to 1.

cluster

Hard cluster assignments (argmax of membership).

centers

An fdata object containing the cluster centers.

objective

Final value of the objective function.

fdataobj

The input functional data object.

See Also

cluster.kmeans for hard clustering

Examples

# Create functional data with THREE groups - one genuinely overlapping
set.seed(42)
t <- seq(0, 1, length.out = 50)
n <- 45
X <- matrix(0, n, 50)

# Group 1: Sine waves centered at 0
for (i in 1:15) X[i, ] <- sin(2*pi*t) + rnorm(50, sd = 0.2)
# Group 2: Sine waves centered at 1.5 (clearly separated from group 1)
for (i in 16:30) X[i, ] <- sin(2*pi*t) + 1.5 + rnorm(50, sd = 0.2)
# Group 3: Between groups 1 and 2 (true overlap - ambiguous membership)
for (i in 31:45) X[i, ] <- sin(2*pi*t) + 0.75 + rnorm(50, sd = 0.3)

fd <- fdata(X, argvals = t)

# Fuzzy clustering reveals the overlap
fcm <- cluster.fcm(fd, ncl = 3, seed = 123)

# Curves in group 3 (31-45) have split membership - this is the key benefit!
cat("Membership for curves 31-35 (overlap region):\n")
print(round(fcm$membership[31:35, ], 2))

# Compare to hard clustering which forces a decision
km <- cluster.kmeans(fd, ncl = 3, seed = 123)
cat("\nHard vs Fuzzy assignment for curve 35:\n")
cat("K-means cluster:", km$cluster[35], "\n")
cat("FCM memberships:", round(fcm$membership[35, ], 2), "\n")

K-Means++ Center Initialization

Description

Initialize cluster centers using the k-means++ algorithm, which selects centers with probability proportional to squared distance from existing centers.

Usage

cluster.init(fdataobj, ncl, metric = "L2", seed = NULL)

Arguments

Value

An fdata object containing the initial cluster centers.

Examples

t <- seq(0, 1, length.out = 50)
X <- matrix(rnorm(30 * 50), 30, 50)
fd <- fdata(X, argvals = t)
init_centers <- cluster.init(fd, ncl = 3)

Clustering Functions for Functional Data

Description

Functions for clustering functional data, including k-means and related algorithms. Functional K-Means Clustering

Usage

cluster.kmeans(
  fdataobj,
  ncl,
  metric = "L2",
  max.iter = 100,
  nstart = 10,
  seed = NULL,
  draw = FALSE,
  ...
)

Arguments

Details

Performs k-means clustering on functional data using the specified metric. Uses k-means++ initialization for better initial centers.

When metric is a string ("L2", "L1", "Linf"), the entire k-means algorithm runs in Rust with parallel processing, providing 50-200x speedup.

When metric is a function, distances are computed using that function. Functions like metric.lp, metric.hausdorff, and metric.DTW have Rust backends and remain fast. Semimetric functions (semimetric.*) are computed in R and will be slower for large datasets.

Value

A list of class 'cluster.kmeans' with components:

cluster

Integer vector of cluster assignments (1 to ncl).

centers

An fdata object containing the cluster centers.

withinss

Within-cluster sum of squares for each cluster.

tot.withinss

Total within-cluster sum of squares.

size

Number of observations in each cluster.

fdataobj

The input functional data object.

Examples

# Create functional data with two groups
t <- seq(0, 1, length.out = 50)
n <- 30
X <- matrix(0, n, 50)
true_cluster <- rep(1:2, each = 15)
for (i in 1:n) {
  if (true_cluster[i] == 1) {
    X[i, ] <- sin(2*pi*t) + rnorm(50, sd = 0.1)
  } else {
    X[i, ] <- cos(2*pi*t) + rnorm(50, sd = 0.1)
  }
}
fd <- fdata(X, argvals = t)

# Cluster with string metric (fast Rust path)
result <- cluster.kmeans(fd, ncl = 2, metric = "L2")
table(result$cluster, true_cluster)

# Cluster with metric function (also fast - Rust backend)
result2 <- cluster.kmeans(fd, ncl = 2, metric = metric.lp)

# Cluster with semimetric (flexible but slower)
result3 <- cluster.kmeans(fd, ncl = 2, metric = semimetric.pca, ncomp = 3)

Optimal Number of Clusters for Functional K-Means

Description

Determines the optimal number of clusters for functional k-means clustering using various criteria: elbow method, silhouette score, or Calinski-Harabasz index.

Usage

cluster.optim(
  fdataobj,
  ncl.range = 2:10,
  criterion = c("silhouette", "CH", "elbow"),
  metric = "L2",
  max.iter = 100,
  nstart = 10,
  seed = NULL,
  ...
)

Arguments

Details

Silhouette score: Measures how similar each curve is to its own cluster compared to other clusters. Values range from -1 to 1, with higher being better. Optimal k maximizes the mean silhouette.

Calinski-Harabasz index: Ratio of between-cluster to within-cluster dispersion. Higher values indicate better defined clusters. Optimal k maximizes CH.

Elbow method: Plots total within-cluster sum of squares vs k. The optimal k is at the "elbow" where adding more clusters doesn't significantly reduce WSS. This is subjective and best assessed visually using plot().

Value

A list of class 'cluster.optim' with components:

optimal.k

Optimal number of clusters based on criterion

criterion

Name of criterion used

scores

Vector of criterion values for each k

ncl.range

Range of k values tested

models

List of cluster.kmeans objects for each k

best.model

The cluster.kmeans object for optimal k

Examples

# Create functional data with 3 groups
set.seed(42)
t <- seq(0, 1, length.out = 50)
n <- 60
X <- matrix(0, n, 50)
true_k <- rep(1:3, each = 20)
for (i in 1:n) {
  if (true_k[i] == 1) {
    X[i, ] <- sin(2*pi*t) + rnorm(50, sd = 0.1)
  } else if (true_k[i] == 2) {
    X[i, ] <- cos(2*pi*t) + rnorm(50, sd = 0.1)
  } else {
    X[i, ] <- sin(4*pi*t) + rnorm(50, sd = 0.1)
  }
}
fd <- fdata(X, argvals = t)

# Find optimal k using silhouette
opt <- cluster.optim(fd, ncl.range = 2:6, criterion = "silhouette")
print(opt)
plot(opt)

Functional Covariance Function

Description

Computes the covariance function (surface) for functional data. For 1D: Cov(s, t) = E[(X(s) - mu(s))(X(t) - mu(t))] For 2D: Covariance across the flattened domain.

Usage

cov(fdataobj, ...)

Arguments

Value

A list with components:

cov

The covariance matrix (m x m for 1D, (m1m2) x (m1m2) for 2D)

argvals

The evaluation points (same as input)

mean

The mean function

Examples

# 1D functional data
t <- seq(0, 1, length.out = 50)
X <- matrix(0, 20, 50)
for (i in 1:20) X[i, ] <- sin(2*pi*t) + rnorm(50, sd = 0.2)
fd <- fdata(X, argvals = t)
cov_result <- cov(fd)
image(cov_result$cov, main = "Covariance Surface")

Seasonal-Trend Decomposition

Description

Decomposes functional data into trend, seasonal, and remainder components. Similar to STL (Seasonal-Trend decomposition using LOESS).

Usage

decompose(
  fdataobj,
  period = NULL,
  method = c("additive", "multiplicative"),
  trend_method = c("loess", "spline"),
  bandwidth = 0.3,
  n_harmonics = 3
)

Arguments

Details

For additive decomposition: data = trend + seasonal + remainder. The trend is extracted using LOESS or spline smoothing, then the seasonal component is estimated by fitting Fourier harmonics to the detrended data.

For multiplicative decomposition: data = trend * seasonal * remainder. This is achieved by log-transforming the data, applying additive decomposition, and back-transforming. Use this when the seasonal amplitude grows with the trend level.

Value

A list with components:

trend

fdata object with trend component

seasonal

fdata object with seasonal component

remainder

fdata object with remainder/residual

period

Period used for decomposition

method

Decomposition method ("additive" or "multiplicative")

See Also

detrend for simple trend removal, seasonal.strength for measuring seasonality

Examples

# Additive seasonal pattern
t <- seq(0, 20, length.out = 400)
X <- matrix(2 + 0.3 * t + sin(2 * pi * t / 2.5), nrow = 1)
fd <- fdata(X, argvals = t)

result <- decompose(fd, period = 2.5, method = "additive")
# plot(result$trend)      # Linear trend
# plot(result$seasonal)   # Sinusoidal seasonal
# plot(result$remainder)  # Residual noise

# Multiplicative pattern (amplitude grows with level)
X_mult <- matrix((2 + 0.3 * t) * (1 + 0.3 * sin(2 * pi * t / 2.5)), nrow = 1)
fd_mult <- fdata(X_mult, argvals = t)

result_mult <- decompose(fd_mult, period = 2.5, method = "multiplicative")

Depth Functions for Functional Data

Description

Functions for computing various depth measures for functional data. Compute Functional Data Depth

Usage

depth(
  fdataobj,
  fdataori = NULL,
  method = c("FM", "mode", "RP", "RT", "BD", "MBD", "MEI", "FSD", "KFSD", "RPD"),
  ...
)

Arguments

Details

Unified interface for computing various depth measures for functional data.

Available methods:

FM

Fraiman-Muniz depth - integrates univariate depths over domain

mode

Modal depth - based on kernel density estimation

RP

Random projection depth - projects to random directions

RT

Random Tukey depth - halfspace depth via random projections

BD

Band depth - proportion of bands containing the curve (1D only)

MBD

Modified band depth - allows partial containment (1D only)

MEI

Modified epigraph index - proportion of time below other curves (1D only)

FSD

Functional spatial depth - based on spatial signs

KFSD

Kernel functional spatial depth - smoothed FSD

RPD

Random projection with derivatives - includes curve derivatives

Value

A numeric vector of depth values, one per curve in fdataobj.

Examples

fd <- fdata(matrix(rnorm(100), 10, 10))

# Different depth methods
depth(fd, method = "FM")
depth(fd, method = "mode")
depth(fd, method = "RP")

Band Depth

Description

Wrapper for depth(method = "BD"). Useful as a function argument.

Usage

depth.BD(fdataobj, fdataori = NULL, ...)

Arguments

Value

Numeric vector of depth values.

See Also

depth

Fraiman-Muniz Depth

Description

Wrapper for depth(method = "FM"). Useful as a function argument.

Usage

depth.FM(fdataobj, fdataori = NULL, ...)

Arguments

Value

Numeric vector of depth values.

See Also

depth

Functional Spatial Depth

Description

Wrapper for depth(method = "FSD"). Useful as a function argument.

Usage

depth.FSD(fdataobj, fdataori = NULL, ...)

Arguments

Value

Numeric vector of depth values.

See Also

depth

Kernel Functional Spatial Depth

Description

Wrapper for depth(method = "KFSD"). Useful as a function argument.

Usage

depth.KFSD(fdataobj, fdataori = NULL, ...)

Arguments

Value

Numeric vector of depth values.

See Also

depth

Modified Band Depth

Description

Wrapper for depth(method = "MBD"). Useful as a function argument.

Usage

depth.MBD(fdataobj, fdataori = NULL, ...)

Arguments

Value

Numeric vector of depth values.

See Also

depth

Modified Epigraph Index

Description

Wrapper for depth(method = "MEI"). Useful as a function argument.

Usage

depth.MEI(fdataobj, fdataori = NULL, ...)

Arguments

Value

Numeric vector of depth values.

See Also

depth

Random Projection Depth

Description

Wrapper for depth(method = "RP"). Useful as a function argument.

Usage

depth.RP(fdataobj, fdataori = NULL, ...)

Arguments

Value

Numeric vector of depth values.

See Also

depth

Random Projection Depth with Derivatives

Description

Wrapper for depth(method = "RPD"). Useful as a function argument.

Usage

depth.RPD(fdataobj, fdataori = NULL, ...)

Arguments

Value

Numeric vector of depth values.

See Also

depth

Random Tukey Depth

Description

Wrapper for depth(method = "RT"). Useful as a function argument.

Usage

depth.RT(fdataobj, fdataori = NULL, ...)

Arguments

Value

Numeric vector of depth values.

See Also

depth

Modal Depth

Description

Wrapper for depth(method = "mode"). Useful as a function argument.

Usage

depth.mode(fdataobj, fdataori = NULL, ...)

Arguments

Value

Numeric vector of depth values.

See Also

depth

Compute functional derivative

Description

Compute the numerical derivative of functional data. Uses finite differences for fast computation via Rust.

Usage

deriv(
  fdataobj,
  nderiv = 1,
  method = "diff",
  class.out = "fdata",
  nbasis = NULL,
  ...
)

Arguments

Details

For 1D functional data (curves), computes the nth derivative. For 2D functional data (surfaces), computes partial derivatives:

• ds: partial derivative with respect to s (first argument)

• dt: partial derivative with respect to t (second argument)

• dsdt: mixed partial derivative

Value

For 1D data: an 'fdata' object containing the derivative values. For 2D data: a list with components ds, dt, and dsdt, each an 'fdata' object containing the respective partial derivative.

Examples

# Create smooth curves
t <- seq(0, 2*pi, length.out = 100)
X <- matrix(0, 10, 100)
for (i in 1:10) X[i, ] <- sin(t + i/5)
fd <- fdata(X, argvals = t)

# First derivative (should be approximately cos)
fd_deriv <- deriv(fd, nderiv = 1)

Detect Peaks in Functional Data

Description

Detects local maxima (peaks) in functional data using derivative zero-crossings. Returns peak times, values, and prominence measures.

Usage

detect.peaks(
  fdataobj,
  min_distance = NULL,
  min_prominence = NULL,
  smooth_first = FALSE,
  smooth_nbasis = NULL,
  detrend_method = c("none", "linear", "auto")
)

Arguments

Details

Peak prominence measures how much a peak stands out from its surroundings. It is computed as the height difference between the peak and the highest of the two minimum values on either side, normalized by the data range.

Fourier basis smoothing is ideal for seasonal signals because it naturally captures periodic patterns without introducing boundary artifacts.

For data with trends, use detrend_method to remove the trend before detecting peaks. This prevents the trend from affecting peak prominence calculations.

Value

A list with components:

peaks

List of data frames, one per curve, with columns: time, value, prominence

inter_peak_distances

List of numeric vectors with distances between consecutive peaks

mean_period

Mean inter-peak distance across all curves (estimates period)

Examples

# Generate data with clear peaks
t <- seq(0, 10, length.out = 200)
X <- matrix(sin(2 * pi * t / 2), nrow = 1)
fd <- fdata(X, argvals = t)

# Detect peaks
peaks <- detect.peaks(fd, min_distance = 1.5)
print(peaks$mean_period)  # Should be close to 2

# With automatic Fourier smoothing (GCV selects nbasis)
peaks_smooth <- detect.peaks(fd, min_distance = 1.5, smooth_first = TRUE)

# With detrending for trending data
X_trend <- matrix(2 + 0.5 * t + sin(2 * pi * t / 2), nrow = 1)
fd_trend <- fdata(X_trend, argvals = t)
peaks_det <- detect.peaks(fd_trend, detrend_method = "linear")

Seasonal Analysis Functions for Functional Data

Description

Functions for analyzing seasonal patterns in functional data including period estimation, peak detection, seasonal strength measurement, and detection of seasonality changes. Detect Period with Multiple Methods

Usage

detect.period(
  fdataobj,
  method = c("sazed", "autoperiod", "cfd", "fft", "acf"),
  ...
)

Arguments

Details

Unified interface for period detection that dispatches to specialized algorithms based on the chosen method. Provides a single entry point for all period detection functionality.

Method selection guidance:

• sazed: Best general-purpose choice. Combines 5 methods and uses voting - robust across signal types with no tuning needed.

• autoperiod: Good when you need candidate details and gradient-refined estimates. Slightly more precise than SAZED.

• cfd: Best for signals with strong polynomial trends. Also detects multiple concurrent periods.

• fft: Fastest, but sensitive to noise and trends.

• acf: Simple but effective for clean periodic signals.

Value

A period detection result. The exact class depends on the method:

sazed_result

For SAZED method

autoperiod_result

For Autoperiod method

cfd_autoperiod_result

For CFD method

period_estimate

For FFT and ACF methods

See Also

sazed, autoperiod, cfd.autoperiod, estimate.period, detect.periods

Examples

# Generate seasonal data
t <- seq(0, 20, length.out = 400)
X <- matrix(sin(2 * pi * t / 2) + 0.1 * rnorm(400), nrow = 1)
fd <- fdata(X, argvals = t)

# Default (SAZED) - most robust
result <- detect.period(fd)
print(result$period)

# Autoperiod with custom settings
result <- detect.period(fd, method = "autoperiod", n_candidates = 10)

# CFDAutoperiod for trended data
X_trend <- matrix(0.3 * t + sin(2 * pi * t / 2), nrow = 1)
fd_trend <- fdata(X_trend, argvals = t)
result <- detect.period(fd_trend, method = "cfd")

# Simple FFT for speed
result <- detect.period(fd, method = "fft")

Detect Multiple Concurrent Periods

Description

Detects multiple periodicities in functional data using iterative residual subtraction. At each iteration, the dominant period is detected using FFT, its sinusoidal component is subtracted, and the process repeats on the residual until stopping criteria are met.

Usage

detect.periods(
  fdataobj,
  max_periods = 3,
  min_confidence = 0.5,
  min_strength = 0.2,
  detrend_method = c("auto", "none", "linear")
)

Arguments

Details

The function uses two stopping criteria:

• FFT confidence: How prominent the dominant frequency is

• Seasonal strength: How much variance is explained by the periodicity

Both must exceed their thresholds for detection to continue. Higher thresholds result in fewer (but more reliable) detected periods.

Periods are detected in order of amplitude (FFT power), not period length. A weak yearly cycle will be detected after a strong weekly cycle.

Trends can interfere with period detection. The default "auto" detrending automatically selects an appropriate method to remove trends.

Value

A list with components:

periods

Numeric vector of detected periods

confidence

FFT confidence for each period

strength

Seasonal strength for each period

amplitude

Amplitude of the sinusoidal component

phase

Phase of the sinusoidal component (radians)

n_periods

Number of periods detected

See Also

estimate.period for single period estimation, detrend for standalone detrending

Examples

# Signal with two periods: 2 and 7
t <- seq(0, 20, length.out = 400)
X <- sin(2 * pi * t / 2) + 0.6 * sin(2 * pi * t / 7)
fd <- fdata(matrix(X, nrow = 1), argvals = t)

# Detect multiple periods
result <- detect.periods(fd, max_periods = 3)
print(result$periods)  # Should find approximately 2 and 7
print(result$n_periods)  # Should be 2

Detect Changes in Seasonality

Description

Detects points in time where seasonality starts (onset) or stops (cessation) by monitoring time-varying seasonal strength.

Usage

detect.seasonality.changes(
  fdataobj,
  period,
  threshold = 0.3,
  window_size = NULL,
  min_duration = NULL
)

Arguments

Value

A list with components:

change_points

Data frame with columns: time, type ("onset" or "cessation"), strength_before, strength_after

strength_curve

Time-varying seasonal strength used for detection

Examples

# Signal that starts non-seasonal, becomes seasonal, then stops
t <- seq(0, 30, length.out = 600)
X <- ifelse(t < 10, rnorm(sum(t < 10), sd = 0.3),
            ifelse(t < 20, sin(2 * pi * t[t >= 10 & t < 20] / 2),
                   rnorm(sum(t >= 20), sd = 0.3)))
X <- matrix(X, nrow = 1)
fd <- fdata(X, argvals = t)

# Detect changes
changes <- detect.seasonality.changes(fd, period = 2)
print(changes$change_points)  # Should show onset ~10, cessation ~20

Detect Seasonality Changes with Automatic Threshold

Description

Detects points where seasonality starts or stops, using automatic threshold selection instead of a fixed value.

Usage

detect.seasonality.changes.auto(
  fdataobj,
  period,
  threshold_method = "otsu",
  threshold_value = NULL,
  window_size = NULL,
  min_duration = NULL
)

Arguments

Details

Otsu's method automatically finds the optimal threshold for separating seasonal from non-seasonal regions based on the strength distribution. This is particularly useful when you don't know the appropriate threshold for your data.

Value

A list with components:

change_points

Data frame with time, type, strength_before, strength_after

strength_curve

Time-varying seasonal strength used for detection

computed_threshold

The threshold that was computed/used

Examples

# Signal that transitions from seasonal to non-seasonal
t <- seq(0, 20, length.out = 400)
X <- ifelse(t < 10, sin(2 * pi * t / 2), rnorm(sum(t >= 10), sd = 0.3))
X <- matrix(X, nrow = 1)
fd <- fdata(X, argvals = t)

# Detect changes with Otsu threshold
changes <- detect.seasonality.changes.auto(fd, period = 2)
print(changes$computed_threshold)

Detect Amplitude Modulation in Seasonal Time Series

Description

Detects whether the amplitude of a seasonal pattern changes over time (amplitude modulation). Uses either Hilbert transform or wavelet analysis to extract the time-varying amplitude envelope.

Usage

detect_amplitude_modulation(
  fdataobj,
  period,
  method = c("hilbert", "wavelet"),
  modulation_threshold = 0.15,
  seasonality_threshold = 0.3
)

Arguments

Details

The function first checks if seasonality is present using the spectral method (which is robust to amplitude modulation). If seasonality is detected, it extracts the amplitude envelope and analyzes its variation.

Hilbert method: Uses Hilbert transform to compute the analytic signal and extract instantaneous amplitude. Fast but assumes narrowband signals.

Wavelet method: Uses Morlet wavelet transform at the target period. More robust to noise and non-stationarity.

Modulation types:

• stable: Constant amplitude (modulation_score < threshold)

• emerging: Amplitude increases over time (amplitude_trend > 0.3)

• fading: Amplitude decreases over time (amplitude_trend < -0.3)

• oscillating: Amplitude varies but no clear trend

• non_seasonal: No seasonality detected

Value

A list with components:

is_seasonal

Logical, whether seasonality is detected

seasonal_strength

Overall seasonal strength (spectral method)

has_modulation

Logical, whether amplitude modulation is detected

modulation_type

Character: "stable", "emerging", "fading", "oscillating", or "non_seasonal"

modulation_score

Coefficient of variation of amplitude (0 = stable)

amplitude_trend

Trend in amplitude (-1 to 1): negative = fading, positive = emerging

amplitude_curve

Time-varying amplitude (fdata object)

time_points

Time points for the amplitude curve

Examples

# Generate data with emerging seasonality
t <- seq(0, 1, length.out = 200)
amplitude <- 0.2 + 0.8 * t  # Amplitude grows over time
X <- matrix(amplitude * sin(2 * pi * t / 0.2), nrow = 1)
fd <- fdata(X, argvals = t)

result <- detect_amplitude_modulation(fd, period = 0.2)
print(result$modulation_type)  # "emerging"
print(result$amplitude_trend)  # Positive value

# Compare Hilbert vs Wavelet methods
result_hilbert <- detect_amplitude_modulation(fd, period = 0.2, method = "hilbert")
result_wavelet <- detect_amplitude_modulation(fd, period = 0.2, method = "wavelet")

Remove Trend from Functional Data

Description

Removes trend from functional data using various methods. This is useful for preprocessing data before seasonal analysis when the data has a significant trend component.

Usage

detrend(
  fdataobj,
  method = c("linear", "polynomial", "diff1", "diff2", "loess", "auto"),
  degree = 2,
  bandwidth = 0.3,
  return_trend = FALSE
)

Arguments

Details

For series with polynomial trends, "linear" or "polynomial" methods are appropriate. For more complex trends, "loess" provides flexibility. The "auto" method compares linear, polynomial (degree 2 and 3), and LOESS, selecting the method with lowest AIC.

Differencing methods ("diff1", "diff2") reduce the series length by 1 or 2 points respectively. The resulting fdata has correspondingly shorter argvals.

Value

If return_trend = FALSE, an fdata object with detrended data. If return_trend = TRUE, a list with components:

detrended

fdata object with detrended data

trend

fdata object with estimated trend

method

Method used for detrending

rss

Residual sum of squares per curve

See Also

decompose for full seasonal decomposition

Examples

# Generate data with linear trend and seasonal component
t <- seq(0, 10, length.out = 200)
X <- matrix(2 + 0.5 * t + sin(2 * pi * t / 2), nrow = 1)
fd <- fdata(X, argvals = t)

# Detrend with linear method
fd_detrended <- detrend(fd, method = "linear")

# Now estimate period on detrended data
period <- estimate.period(fd_detrended)
print(period$period)  # Should be close to 2

# Get both trend and detrended data
result <- detrend(fd, method = "linear", return_trend = TRUE)
# plot(result$trend)  # Shows the linear trend

Convert DataFrame to 2D functional data

Description

Converts a data frame in long format to a 2D fdata object (surfaces). The expected format is: one identifier column, one column for the s-dimension index, and multiple columns for the t-dimension values.

Usage

df_to_fdata2d(
  df,
  id_col = 1,
  s_col = 2,
  t_cols = NULL,
  names = NULL,
  metadata = NULL
)

Arguments

Details

The expected data frame structure is:

• Column 1 (id_col): Surface identifier (e.g., "surface_1", "surface_2")

• Column 2 (s_col): Index for the s-dimension (row index of surface)

• Columns 3+ (t_cols): Values for each t-dimension point (columns of surface)

Each unique identifier represents one surface. For each surface, there should be m1 rows (one per s-value), and m2 t-columns, resulting in an m1 x m2 surface.

Value

An object of class 'fdata' with 2D functional data.

Examples

# Create example data frame
df <- data.frame(
  id = rep(c("surf1", "surf2"), each = 5),
  s = rep(1:5, 2),
  t1 = rnorm(10),
  t2 = rnorm(10),
  t3 = rnorm(10)
)
fd <- df_to_fdata2d(df)
print(fd)

# With metadata
meta <- data.frame(group = c("A", "B"), value = c(1.5, 2.3))
fd <- df_to_fdata2d(df, metadata = meta)

Generate Eigenfunction Basis

Description

Evaluates orthonormal eigenfunction bases at specified argument values. These eigenfunctions can be used for Karhunen-Loeve simulation.

Usage

eFun(argvals, M, type = c("Fourier", "Poly", "PolyHigh", "Wiener"))

Arguments

Details

The eigenfunctions are orthonormal with respect to the L2 inner product: integral(phi_j * phi_k) = 1 if j == k, 0 otherwise.

Fourier

Suitable for periodic data. First function is constant.

Poly

Orthonormalized Legendre polynomials. Good for smooth data.

PolyHigh

Legendre polynomials starting at degree 2, useful when linear and constant components are handled separately.

Wiener

Eigenfunctions of the Brownian motion covariance. Eigenvalues decay as 1/((k-0.5)*pi)^2.

Value

A matrix of dimension length(argvals) x M containing the eigenfunction values. Each column is an eigenfunction, normalized to have unit L2 norm on [0, 1].

See Also

eVal, simFunData

Examples

t <- seq(0, 1, length.out = 100)

# Generate Fourier basis
phi_fourier <- eFun(t, M = 5, type = "Fourier")
matplot(t, phi_fourier, type = "l", lty = 1,
        main = "Fourier Eigenfunctions", ylab = expression(phi(t)))

# Generate Wiener eigenfunctions
phi_wiener <- eFun(t, M = 5, type = "Wiener")
matplot(t, phi_wiener, type = "l", lty = 1,
        main = "Wiener Eigenfunctions", ylab = expression(phi(t)))

# Check orthonormality (should be identity matrix)
dt <- diff(t)[1]
gram <- t(phi_fourier) %*% phi_fourier * dt
round(gram, 2)

Generate Eigenvalue Sequence

Description

Generates eigenvalue sequences with different decay patterns. These control the variance contribution of each mode in Karhunen-Loeve simulation.

Usage

eVal(M, type = c("linear", "exponential", "wiener"))

Arguments

Details

The eigenvalues control how much variance each eigenfunction contributes to the simulated curves:

linear

Slow decay, higher modes contribute more variation. Produces rougher curves.

exponential

Fast decay, higher modes contribute very little. Produces smoother curves.

wiener

Specific decay matching Brownian motion. Use with Wiener eigenfunctions for true Brownian motion simulation.

Value

A numeric vector of length M containing the eigenvalues in decreasing order.

See Also

eFun, simFunData

Examples

# Compare decay patterns
lambda_lin <- eVal(20, "linear")
lambda_exp <- eVal(20, "exponential")
lambda_wie <- eVal(20, "wiener")

plot(1:20, lambda_lin, type = "b", log = "y", ylim = c(1e-10, 1),
     main = "Eigenvalue Decay Patterns", xlab = "k", ylab = expression(lambda[k]))
lines(1:20, lambda_exp, col = "red", type = "b")
lines(1:20, lambda_wie, col = "blue", type = "b")
legend("topright", c("Linear", "Exponential", "Wiener"),
       col = c("black", "red", "blue"), lty = 1, pch = 1)

Estimate Seasonal Period using FFT

Description

Estimates the dominant period in functional data using Fast Fourier Transform and periodogram analysis.

Usage

estimate.period(
  fdataobj,
  method = c("fft", "acf"),
  max_lag = NULL,
  detrend_method = c("none", "linear", "auto")
)

Arguments

Details

The function computes the periodogram of the mean curve and finds the frequency with maximum power. The confidence measure indicates how pronounced the dominant frequency is relative to the background.

For data with trends, the detrend_method parameter can significantly improve period estimation accuracy. Strong trends can mask the true seasonal period.

Value

A list with components:

period

Estimated period

frequency

Dominant frequency (1/period)

power

Power at the dominant frequency

confidence

Confidence measure (ratio of peak power to mean power)

Examples

# Generate seasonal data with period = 2
t <- seq(0, 10, length.out = 200)
X <- matrix(sin(2 * pi * t / 2) + rnorm(200, sd = 0.1), nrow = 1)
fd <- fdata(X, argvals = t)

# Estimate period
result <- estimate.period(fd, method = "fft")
print(result$period)  # Should be close to 2

# With trend - detrending improves estimation
X_trend <- matrix(2 + 0.5 * t + sin(2 * pi * t / 2), nrow = 1)
fd_trend <- fdata(X_trend, argvals = t)
result <- estimate.period(fd_trend, detrend_method = "linear")

Create a functional data object

Description

Creates an fdata object for 1D functional data (curves) or 2D functional data (surfaces). For 2D data, the internal storage uses a flattened matrix format [n, m1*m2] where each row represents a surface stored in row-major order.

Usage

fdata(
  mdata,
  argvals = NULL,
  rangeval = NULL,
  names = NULL,
  fdata2d = FALSE,
  id = NULL,
  metadata = NULL
)

Arguments

Details

For 2D functional data, surfaces are stored internally as a flattened matrix where each row is a surface in row-major order. To extract a single surface as a matrix, use subsetting with drop = TRUE or reshape manually:

# Extract surface i as matrix
surface_i <- fd[i, drop = TRUE]
# Or manually:
surface_i <- matrix(fd$data[i, ], nrow = fd$dims[1], ncol = fd$dims[2])

Value

An object of class 'fdata' containing:

data

The data matrix. For 2D: flattened [n, m1*m2] format

argvals

Evaluation points

rangeval

Range of arguments

names

Plot labels

fdata2d

Logical indicating if 2D

dims

For 2D only: c(m1, m2) grid dimensions

id

Character vector of observation identifiers

metadata

Data frame of additional covariates (or NULL)

Examples

# Create 1D functional data (curves)
x <- matrix(rnorm(100), nrow = 10, ncol = 10)
fd <- fdata(x, argvals = seq(0, 1, length.out = 10))

# Create with identifiers and metadata
meta <- data.frame(group = rep(c("A", "B"), 5), endpoint = rnorm(10))
fd <- fdata(x, id = paste0("patient_", 1:10), metadata = meta)

# Access metadata
fd$id
fd$metadata$group

# Create 2D functional data from 3D array [n, m1, m2]
surfaces <- array(rnorm(500), dim = c(5, 10, 10))
fd2d <- fdata(surfaces)

# Access individual surface as matrix
surface_1 <- fd2d[1, drop = TRUE]

Bootstrap Functional Data

Description

Generate bootstrap samples from functional data. Supports naive bootstrap (resampling curves with replacement) and smooth bootstrap (adding noise based on estimated covariance structure).

Usage

fdata.bootstrap(
  fdataobj,
  n.boot = 200,
  method = c("naive", "smooth"),
  variance = NULL,
  seed = NULL
)

Arguments

Value

A list of class 'fdata.bootstrap' with components:

boot.samples

List of n.boot fdata objects, each a bootstrap sample

original

The original fdata object

method

The bootstrap method used

n.boot

Number of bootstrap replications

Examples

# Create functional data
t <- seq(0, 1, length.out = 50)
X <- matrix(0, 20, 50)
for (i in 1:20) X[i, ] <- sin(2*pi*t) + rnorm(50, sd = 0.1)
fd <- fdata(X, argvals = t)

# Naive bootstrap
boot_naive <- fdata.bootstrap(fd, n.boot = 100, method = "naive")

# Smooth bootstrap
boot_smooth <- fdata.bootstrap(fd, n.boot = 100, method = "smooth")

Bootstrap Confidence Intervals for Functional Statistics

Description

Compute bootstrap confidence intervals for functional statistics such as the mean function, depth values, or regression coefficients.

Usage

fdata.bootstrap.ci(
  fdataobj,
  statistic,
  n.boot = 200,
  alpha = 0.05,
  method = c("percentile", "basic", "normal"),
  seed = NULL
)

Arguments

Value

A list of class 'fdata.bootstrap.ci' with components:

estimate

The statistic computed on the original data

ci.lower

Lower confidence bound

ci.upper

Upper confidence bound

boot.stats

Matrix of bootstrap statistics (n.boot x length(statistic))

alpha

The significance level used

method

The CI method used

Examples

# Create functional data
t <- seq(0, 1, length.out = 50)
X <- matrix(0, 20, 50)
for (i in 1:20) X[i, ] <- sin(2*pi*t) + rnorm(50, sd = 0.1)
fd <- fdata(X, argvals = t)

# Bootstrap CI for the mean function (returns numeric vector)
ci_mean <- fdata.bootstrap.ci(fd,
  statistic = function(x) as.numeric(mean(x)$data),
  n.boot = 100)

# Bootstrap CI for depth values
ci_depth <- fdata.bootstrap.ci(fd,
  statistic = function(x) depth.FM(x),
  n.boot = 100)

Center functional data

Description

Subtract the mean function from each curve.

Usage

fdata.cen(fdataobj)

Arguments

Value

A centered 'fdata' object.

Examples

fd <- fdata(matrix(rnorm(100), 10, 10))
fd_centered <- fdata.cen(fd)

Convert Functional Data to Basis Coefficients

Description

Project functional data onto a basis system and return coefficients. Supports B-spline and Fourier basis. Works with both regular fdata and irregular irregFdata objects.

Usage

fdata2basis(x, nbasis = 10, type = c("bspline", "fourier"), ...)

## S3 method for class 'fdata'
fdata2basis(x, nbasis = 10, type = c("bspline", "fourier"), ...)

## S3 method for class 'irregFdata'
fdata2basis(x, nbasis = 10, type = c("bspline", "fourier"), ...)

Arguments

Details

For regular fdata objects, all curves are projected onto the same basis evaluated at the common grid points.

For irregular irregFdata objects, each curve is individually fitted to the basis using least squares at its own observation points. This is the preferred approach for sparse/irregularly sampled data as it avoids interpolation artifacts.

Value

A matrix of coefficients (n x nbasis).

Examples

# Regular fdata
t <- seq(0, 1, length.out = 50)
X <- matrix(0, 20, 50)
for (i in 1:20) X[i, ] <- sin(2*pi*t) + rnorm(50, sd = 0.1)
fd <- fdata(X, argvals = t)
coefs <- fdata2basis(fd, nbasis = 10, type = "bspline")

# Irregular fdata (sparsified)
ifd <- sparsify(fd, minObs = 10, maxObs = 20, seed = 42)
coefs_irreg <- fdata2basis(ifd, nbasis = 10, type = "bspline")

Convert 2D Functional Data to Tensor Product Basis Coefficients

Description

Projects 2D functional data (surfaces) onto a tensor product basis, which is the Kronecker product of two 1D bases.

Usage

fdata2basis_2d(
  fdataobj,
  nbasis.s = 10,
  nbasis.t = 10,
  type = c("bspline", "fourier")
)

Arguments

Details

The tensor product basis is defined as:

B_{2d}(s, t) = B_s(s) \otimes B_t(t)

Value

A matrix of coefficients [n x (nbasis.s * nbasis.t)].

Examples

# Create 2D surface data
s <- seq(0, 1, length.out = 20)
t <- seq(0, 1, length.out = 20)
surface <- outer(sin(2*pi*s), cos(2*pi*t))
fd2d <- fdata(array(surface, dim = c(1, 20, 20)))

# Project to tensor product basis
coefs <- fdata2basis_2d(fd2d, nbasis.s = 7, nbasis.t = 7, type = "fourier")

Cross-Validation for Basis Function Number Selection

Description

Selects the optimal number of basis functions using k-fold cross-validation or generalized cross-validation.

Usage

fdata2basis_cv(
  fdataobj,
  nbasis.range = 4:20,
  type = c("bspline", "fourier"),
  criterion = c("GCV", "CV", "AIC", "BIC"),
  kfold = 10,
  lambda = 0
)

Arguments

Value

A list with:

optimal.nbasis

Optimal number of basis functions

scores

Score for each nbasis value

nbasis.range

The tested nbasis values

criterion

The criterion used

fitted

fdata object fitted with optimal nbasis

Examples

set.seed(42)
t <- seq(0, 1, length.out = 50)
X <- matrix(0, 20, 50)
for (i in 1:20) X[i, ] <- sin(4 * pi * t) + rnorm(50, sd = 0.1)
fd <- fdata(X, argvals = t)

# Find optimal nbasis
cv_result <- fdata2basis_cv(fd, nbasis.range = 5:15, type = "fourier")
print(cv_result$optimal.nbasis)

Convert Functional Data to fd class

Description

Converts an fdata object to an fd object from the fda package. Requires the fda package to be installed.

Usage

fdata2fd(fdataobj, nbasis = 10, type = c("bspline", "fourier"))

Arguments

Value

An object of class 'fd' from the fda package.

Examples

t <- seq(0, 1, length.out = 50)
X <- matrix(0, 20, 50)
for (i in 1:20) X[i, ] <- sin(2*pi*t) + rnorm(50, sd = 0.1)
fd <- fdata(X, argvals = t)
fd_obj <- fdata2fd(fd, nbasis = 10)

Convert Functional Data to Principal Component Scores

Description

Performs functional PCA and returns principal component scores for functional data. Uses SVD on centered data.

Usage

fdata2pc(fdataobj, ncomp = 2, lambda = 0, norm = TRUE)

Arguments

Value

A list with components:

d

Singular values (proportional to sqrt of eigenvalues)

rotation

fdata object containing PC loadings

x

Matrix of PC scores (n x ncomp)

mean

Mean function (numeric vector)

fdataobj.cen

Centered fdata object

call

The function call

Examples

t <- seq(0, 1, length.out = 50)
X <- matrix(0, 20, 50)
for (i in 1:20) X[i, ] <- sin(2*pi*t) + rnorm(50, sd = 0.1)
fd <- fdata(X, argvals = t)
pc <- fdata2pc(fd, ncomp = 3)

Convert Functional Data to PLS Scores

Description

Performs Partial Least Squares regression and returns component scores for functional data using the NIPALS algorithm.

Usage

fdata2pls(fdataobj, y, ncomp = 2, lambda = 0, norm = TRUE)

Arguments

Value

A list with components:

weights

Matrix of PLS weights (m x ncomp)

scores

Matrix of PLS scores (n x ncomp)

loadings

Matrix of PLS loadings (m x ncomp)

call

The function call

Examples

t <- seq(0, 1, length.out = 50)
X <- matrix(0, 20, 50)
for (i in 1:20) X[i, ] <- sin(2*pi*t) + rnorm(50, sd = 0.1)
y <- rowMeans(X) + rnorm(20, sd = 0.1)
fd <- fdata(X, argvals = t)
pls <- fdata2pls(fd, y, ncomp = 3)

Functional Equivalence Test (TOST)

Description

Tests whether two functional means are equivalent within an equivalence margin delta, based on the supremum norm. Uses the approach of Dette & Kokot (2021) with a simultaneous confidence band.

Usage

fequiv.test(
  fdataobj1,
  fdataobj2 = NULL,
  delta,
  mu0 = NULL,
  n.boot = 1000,
  alpha = 0.05,
  method = c("multiplier", "percentile"),
  seed = NULL
)

Arguments

Value

An object of class fequiv.test with components:

statistic

Observed sup-norm of the mean difference

delta

Equivalence margin used

critical.value

Bootstrap critical value for the SCB

scb.lower

Lower bound of simultaneous confidence band

scb.upper

Upper bound of simultaneous confidence band

diff.mean

Estimated mean difference curve (numeric vector)

reject

Logical; TRUE if equivalence is declared

p.value

Bootstrap p-value

alpha

Significance level used

method

Bootstrap method used

argvals

Argument values (time grid)

n1

Sample size of first group

n2

Sample size of second group (NA for one-sample)

boot.stats

Vector of bootstrap sup-norm statistics

data.name

Description of input data

Hypotheses

H0

sup_t |mu1(t) - mu2(t)| >= delta (NOT equivalent)

H1

sup_t |mu1(t) - mu2(t)| < delta (equivalent)

Equivalence is declared when the entire (1-2*alpha) simultaneous confidence band for the mean difference lies within [-delta, delta].

References

Dette, H. and Kokot, K. (2021). Detecting relevant differences in the covariance operators of functional time series. Biometrika, 108(4):895–913.

Examples

set.seed(42)
t_grid <- seq(0, 1, length.out = 50)
X1 <- fdata(matrix(rnorm(30 * 50), 30, 50), argvals = t_grid)
X2 <- fdata(matrix(rnorm(25 * 50, mean = 0.1), 25, 50), argvals = t_grid)

result <- fequiv.test(X1, X2, delta = 1, n.boot = 500)
print(result)
plot(result)

Statistical Tests for Functional Data

Description

Functions for hypothesis testing with functional data. Test for Functional Linear Model

Usage

flm.test(fdataobj, y, B = 500, ...)

Arguments

Details

Tests the goodness-of-fit for a functional linear model using the projected Cramer-von Mises statistic.

Value

A list of class 'htest' with components:

statistic

The test statistic

p.value

Bootstrap p-value

method

Name of the test

Examples

fd <- fdata(matrix(rnorm(200), 20, 10))
y <- rnorm(20)

test_result <- flm.test(fd, y, B = 100)
test_result$p.value

Test for Equality of Functional Means

Description

Tests whether the mean function equals a specified value.

Usage

fmean.test.fdata(fdataobj, mu0 = NULL, B = 500, ...)

Arguments

Value

A list of class 'htest' with components:

statistic

The test statistic

p.value

Bootstrap p-value

method

Name of the test

Examples

fd <- fdata(matrix(rnorm(200), 20, 10))

test_result <- fmean.test.fdata(fd, B = 100)
test_result$p.value

Functional Basis Regression

Description

Fits a functional linear model using basis expansion (ridge regression). Uses the anofox-regression Rust backend for efficient L2-regularized regression.

Usage

fregre.basis(fdataobj, y, basis.x = NULL, basis.b = NULL, lambda = 0, ...)

Arguments

Value

A fitted regression object of class 'fregre.fd' with components:

Cross-Validation for Functional Basis Regression

Description

Performs k-fold cross-validation to select the optimal regularization parameter (lambda) for functional basis regression.

Usage

fregre.basis.cv(fdataobj, y, kfold = 10, lambda.range = NULL, seed = NULL, ...)

Arguments

Value

A list with components:

optimal.lambda

Optimal regularization parameter

cv.errors

Mean squared prediction error for each lambda

cv.se

Standard error of cv.errors

model

Fitted model with optimal lambda

Nonparametric Functional Regression

Description

Fits a functional regression model using kernel smoothing (Nadaraya-Watson). Supports fixed bandwidth (h), or k-nearest neighbors with global (kNN.gCV) or local (kNN.lCV) cross-validation.

Usage

fregre.np(
  fdataobj,
  y,
  h = NULL,
  knn = NULL,
  type.S = c("S.NW", "kNN.gCV", "kNN.lCV"),
  Ker = "norm",
  metric = metric.lp,
  ...
)

Arguments

Details

Three smoothing approaches are available:

Fixed bandwidth (type.S = "S.NW"): Uses a single bandwidth h for all predictions. If h is not provided, it is set to the median of non-zero pairwise distances.

k-NN Global CV (type.S = "kNN.gCV"): Selects a single optimal k for all observations using leave-one-out cross-validation. The bandwidth at each point is set to include k neighbors.

k-NN Local CV (type.S = "kNN.lCV"): Selects an optimal k_i for each observation i, allowing adaptive smoothing. Useful when the data has varying density across the functional space.

Value

A fitted regression object of class 'fregre.np' with components:

fitted.values

Fitted values

residuals

Residuals

h.opt

Optimal/used bandwidth (for type.S = "S.NW")

knn

Number of neighbors used (for kNN methods)

k.opt

Optimal k value(s) - scalar for global, vector for local

type.S

Type of smoother used

Ker

Kernel type used

fdataobj

Original functional data

y

Response vector

mdist

Distance matrix

sr2

Residual variance

metric

Metric function used

call

The function call

Examples

# Create functional data
t <- seq(0, 1, length.out = 50)
n <- 50
X <- matrix(0, n, 50)
for (i in 1:n) X[i, ] <- sin(2*pi*t) * i/n + rnorm(50, sd = 0.1)
y <- rowMeans(X) + rnorm(n, sd = 0.1)
fd <- fdata(X, argvals = t)

# Fixed bandwidth
fit1 <- fregre.np(fd, y, h = 0.5)

# k-NN with global CV
fit2 <- fregre.np(fd, y, type.S = "kNN.gCV", knn = 20)

# k-NN with local CV
fit3 <- fregre.np(fd, y, type.S = "kNN.lCV", knn = 20)

Cross-Validation for Nonparametric Functional Regression

Description

Performs k-fold cross-validation to select the optimal bandwidth parameter (h) for nonparametric functional regression.

Usage

fregre.np.cv(
  fdataobj,
  y,
  kfold = 10,
  h.range = NULL,
  metric = metric.lp,
  seed = NULL,
  ...
)

Arguments

Value

A list with components:

optimal.h

Optimal bandwidth parameter

cv.errors

Mean squared prediction error for each h

cv.se

Standard error of cv.errors

model

Fitted model with optimal h

Nonparametric Regression with Multiple Functional Predictors

Description

Fits a nonparametric regression model with multiple functional predictors using a weighted combination of distance matrices.

Usage

fregre.np.multi(
  fdataobj.list,
  y,
  weights = NULL,
  h = NULL,
  knn = NULL,
  type.S = c("S.NW", "kNN.gCV", "kNN.lCV"),
  Ker = "norm",
  metric = metric.lp,
  cv.grid = NULL,
  cv.folds = 5,
  ...
)

Arguments

Value

An object of class 'fregre.np.multi' containing:

fdataobj.list

List of functional predictors

y

Response vector

weights

Weights used (or optimized)

weights.cv

CV results if weights = "cv"

fitted.values

Fitted values

residuals

Residuals

D.list

List of distance matrices

D.combined

Combined distance matrix

Examples

# Create two functional predictors
set.seed(42)
n <- 50
m <- 30
t_grid <- seq(0, 1, length.out = m)

X1 <- matrix(0, n, m)
X2 <- matrix(0, n, m)
for (i in 1:n) {
  X1[i, ] <- sin(2 * pi * t_grid) * i/n + rnorm(m, sd = 0.1)
  X2[i, ] <- cos(2 * pi * t_grid) * i/n + rnorm(m, sd = 0.1)
}
y <- rowMeans(X1) + 0.5 * rowMeans(X2) + rnorm(n, sd = 0.1)

fd1 <- fdata(X1, argvals = t_grid)
fd2 <- fdata(X2, argvals = t_grid)

# Fit with equal weights
fit1 <- fregre.np.multi(list(fd1, fd2), y)

# Fit with cross-validated weights
fit2 <- fregre.np.multi(list(fd1, fd2), y, weights = "cv")

Functional Regression

Description

Functions for functional regression models. Functional Principal Component Regression

Usage

fregre.pc(fdataobj, y, ncomp = NULL, ...)

Arguments

Details

Fits a functional linear model using principal component regression.

Value

A fitted regression object of class 'fregre.fd' with components:

Cross-Validation for Functional PC Regression

Description

Performs k-fold cross-validation to select the optimal number of principal components for functional PC regression.

Usage

fregre.pc.cv(fdataobj, y, kfold = 10, ncomp.range = NULL, seed = NULL, ...)

Arguments

Value

A list with components:

optimal.ncomp

Optimal number of components

cv.errors

Mean squared prediction error for each ncomp

cv.se

Standard error of cv.errors

model

Fitted model with optimal ncomp

Examples

# Create functional data with a linear relationship
set.seed(42)
t <- seq(0, 1, length.out = 50)
X <- matrix(0, 100, 50)
for (i in 1:100) X[i, ] <- sin(2*pi*t) * i/100 + rnorm(50, sd = 0.1)
beta_true <- cos(2*pi*t)
y <- X %*% beta_true + rnorm(100, sd = 0.5)
fd <- fdata(X, argvals = t)

# Cross-validate to find optimal number of PCs
cv_result <- fregre.pc.cv(fd, y, ncomp.range = 1:10)

Geometric Median of Functional Data

Description

Computes the geometric median (L1 median) of functional data using Weiszfeld's iterative algorithm. The geometric median minimizes the sum of L2 distances to all curves/surfaces, making it robust to outliers.

Usage

gmed(fdataobj, max.iter = 100, tol = 1e-06)

Arguments

Details

The geometric median y minimizes:

\sum_{i=1}^n ||X_i - y||_{L2}

Unlike the mean (L2 center), the geometric median is robust to outliers because extreme values have bounded influence (influence function is bounded).

The Weiszfeld algorithm is an iteratively reweighted least squares method that converges to the geometric median.

Value

An fdata object containing the geometric median function (1D or 2D).

See Also

mean.fdata for the (non-robust) mean function, median for depth-based median

Examples

# Create functional data with an outlier
t <- seq(0, 1, length.out = 50)
X <- matrix(0, 20, 50)
for (i in 1:19) X[i, ] <- sin(2*pi*t) + rnorm(50, sd = 0.1)
X[20, ] <- sin(2*pi*t) + 5  # Large outlier
fd <- fdata(X, argvals = t)

# Compare mean vs geometric median
mean_curve <- mean(fd)
gmed_curve <- gmed(fd)

# The geometric median is less affected by the outlier

Compute Distance/Similarity Between Groups of Functional Data

Description

Computes various distance and similarity measures between pre-defined groups of functional curves.

Usage

group.distance(
  fdataobj,
  groups,
  method = c("centroid", "hausdorff", "depth", "all"),
  metric = "lp",
  p = 2,
  depth.method = "FM",
  ...
)

Arguments

Value

An object of class 'group.distance' containing:

centroid

Centroid distance matrix (if method includes centroid)

hausdorff

Hausdorff distance matrix (if method includes hausdorff)

depth

Depth-based similarity matrix (if method includes depth)

groups

Unique group labels

group.sizes

Number of curves per group

method

Methods used

Examples

# Create grouped functional data
set.seed(42)
n <- 30
m <- 50
t_grid <- seq(0, 1, length.out = m)
X <- matrix(0, n, m)
for (i in 1:15) X[i, ] <- sin(2 * pi * t_grid) + rnorm(m, sd = 0.1)
for (i in 16:30) X[i, ] <- cos(2 * pi * t_grid) + rnorm(m, sd = 0.1)
fd <- fdata(X, argvals = t_grid)
groups <- factor(rep(c("A", "B"), each = 15))

# Compute all distance measures
gd <- group.distance(fd, groups, method = "all")
print(gd)

Permutation Test for Group Differences

Description

Tests whether groups of functional data are significantly different using permutation testing.

Usage

group.test(
  fdataobj,
  groups,
  n.perm = 1000,
  statistic = c("centroid", "ratio"),
  ...
)

Arguments

Details

Null Hypothesis (H0): All groups come from the same distribution. That is, the group labels are exchangeable and there is no systematic difference between the functional curves in different groups.

Alternative Hypothesis (H1): At least one group differs from the others in terms of location (mean function) or dispersion.

The test works by:

1. Computing a test statistic on the observed data

2. Repeatedly permuting the group labels and recomputing the statistic

3. Calculating the p-value as the proportion of permuted statistics >= observed

Two test statistics are available:

• "centroid": Sum of pairwise L2 distances between group mean functions. Sensitive to differences in group locations (means).

• "ratio": Ratio of between-group to within-group variance, similar to an F-statistic. Sensitive to both location and dispersion.

A small p-value (e.g., < 0.05) indicates evidence against H0, suggesting that the groups are significantly different.

Value

An object of class 'group.test' containing:

statistic

Observed test statistic

p.value

Permutation p-value

perm.dist

Permutation distribution of test statistic

n.perm

Number of permutations used

Examples

set.seed(42)
n <- 30
m <- 50
t_grid <- seq(0, 1, length.out = m)
X <- matrix(0, n, m)
for (i in 1:15) X[i, ] <- sin(2 * pi * t_grid) + rnorm(m, sd = 0.1)
for (i in 16:30) X[i, ] <- cos(2 * pi * t_grid) + rnorm(m, sd = 0.1)
fd <- fdata(X, argvals = t_grid)
groups <- factor(rep(c("A", "B"), each = 15))

# Test for significant difference
gt <- group.test(fd, groups, n.perm = 500)
print(gt)

Default Bandwidth

Description

Compute a default bandwidth as the 15th percentile of pairwise distances.

Usage

h.default(fdataobj, ...)

Arguments

Value

A scalar bandwidth value.

Examples

tt <- seq(0, 1, length.out = 50)
h <- h.default(tt)

Inner Product of Functional Data

Description

Compute the inner product of two functional data objects. <f, g> = integral(f(t) * g(t) dt)

Usage

inprod.fdata(fdata1, fdata2 = NULL)

Arguments

Value

A matrix of inner products. If fdata1 has n1 curves and fdata2 has n2 curves, returns an n1 x n2 matrix.

Examples

t <- seq(0, 1, length.out = 100)
X1 <- matrix(sin(2*pi*t), nrow = 1)
X2 <- matrix(cos(2*pi*t), nrow = 1)
fd1 <- fdata(X1, argvals = t)
fd2 <- fdata(X2, argvals = t)
# Inner product of sin and cos over [0,1] should be 0
inprod.fdata(fd1, fd2)

Estimate Instantaneous Period

Description

For signals with time-varying frequency (drifting period), estimates the instantaneous period at each time point using the Hilbert transform.

Usage

instantaneous.period(fdataobj)

Arguments

Details

The Hilbert transform is used to compute the analytic signal, from which the instantaneous phase is extracted. The derivative of the phase gives the instantaneous frequency, and 1/frequency gives the period.

This is particularly useful for signals where the period is not constant, such as circadian rhythms with drift or frequency-modulated signals.

Value

A list with fdata objects:

period

Instantaneous period at each time point

frequency

Instantaneous frequency at each time point

amplitude

Instantaneous amplitude (envelope) at each time point

Examples

# Chirp signal with increasing frequency
t <- seq(0, 10, length.out = 500)
freq <- 0.5 + 0.1 * t  # Frequency increases from 0.5 to 1.5
X <- matrix(sin(2 * pi * cumsum(freq) * diff(c(0, t))), nrow = 1)
fd <- fdata(X, argvals = t)

# Estimate instantaneous period
inst <- instantaneous.period(fd)
# plot(inst$period)  # Shows decreasing period over time

Utility Functions for Functional Data Analysis

Description

Various utility functions including integration, inner products, random process generation, and prediction metrics. Simpson's Rule Integration

Usage

## S3 method for class 'irregFdata'
int.simpson(x, ...)

int.simpson(x, ...)

## S3 method for class 'fdata'
int.simpson(x, ...)

Arguments

Details

Integrate functional data over its domain using Simpson's rule (composite trapezoidal rule for non-uniform grids). Works with both regular fdata and irregular irregFdata objects.

Value

A numeric vector of integrals, one per curve.

Examples

t <- seq(0, 1, length.out = 100)
X <- matrix(0, 10, 100)
for (i in 1:10) X[i, ] <- sin(2*pi*t)
fd <- fdata(X, argvals = t)
integrals <- int.simpson(fd)  # Should be approximately 0

# Also works with irregular data
ifd <- sparsify(fd, minObs = 20, maxObs = 50, seed = 123)
integrals_irreg <- int.simpson(ifd)

Create an Irregular Functional Data Object

Description

Creates an irregFdata object for functional data where each observation is sampled at potentially different points. This is common in longitudinal studies, sparse sampling, and sensor data with missing values.

Usage

irregFdata(
  argvals,
  X,
  rangeval = NULL,
  names = NULL,
  id = NULL,
  metadata = NULL
)

Arguments

Value

An object of class irregFdata containing:

argvals

List of observation time vectors

X

List of value vectors

n

Number of observations

rangeval

Domain range

names

Plot labels

id

Observation identifiers

metadata

Additional covariates

See Also

sparsify, as.fdata.irregFdata, fdata

Examples

# Create irregular functional data directly
argvals <- list(
  c(0.0, 0.3, 0.7, 1.0),
  c(0.0, 0.2, 0.5, 0.8, 1.0),
  c(0.1, 0.4, 0.9)
)
X <- list(
  c(0.1, 0.5, 0.3, 0.2),
  c(0.0, 0.4, 0.6, 0.4, 0.1),
  c(0.3, 0.7, 0.2)
)
ifd <- irregFdata(argvals, X)
print(ifd)
plot(ifd)

Check if an Object is Irregular Functional Data

Description

Check if an Object is Irregular Functional Data

Usage

is.irregular(x)

Arguments

Value

TRUE if x is of class irregFdata, FALSE otherwise.

Examples

fd <- fdata(matrix(rnorm(100), 10, 10))
is.irregular(fd)  # FALSE

ifd <- sparsify(fd, minObs = 3, maxObs = 7)
is.irregular(ifd)  # TRUE

Add Covariance Functions

Description

Combines two covariance functions by addition.

Usage

kernel.add(kernel1, kernel2)

Arguments

Value

A combined covariance function.

Examples

# Combine Gaussian with white noise
k_signal <- kernel.gaussian(variance = 1, length_scale = 0.2)
k_noise <- kernel.whitenoise(variance = 0.1)
k_total <- kernel.add(k_signal, k_noise)

t <- seq(0, 1, length.out = 50)
fd <- make.gaussian.process(n = 5, t = t, cov = k_total)

Brownian Motion Covariance Function

Description

Computes the Brownian motion (Wiener process) covariance function:

k(s, t) = \sigma^2 \min(s, t)

Usage

kernel.brownian(variance = 1)

Arguments

Details

The Brownian motion covariance produces sample paths that start at 0 and have independent increments. The covariance between two points equals the variance times the minimum of their positions.

This covariance is only defined for 1D domains starting at 0.

Value

A covariance function object of class 'kernel_brownian'.

See Also

kernel.gaussian, make.gaussian.process

Examples

# Generate Brownian motion paths
cov_func <- kernel.brownian(variance = 1)
t <- seq(0, 1, length.out = 100)
fd <- make.gaussian.process(n = 10, t = t, cov = cov_func)
plot(fd)

Exponential Covariance Function

Description

Computes the exponential covariance function:

k(s, t) = \sigma^2 \exp\left(-\frac{|s-t|}{\ell}\right)

Usage

kernel.exponential(variance = 1, length_scale = 1)

Arguments

Details

This is equivalent to the Matern covariance with \nu = 0.5. Sample paths are continuous but not differentiable (rough).

The exponential covariance function produces sample paths that are continuous but nowhere differentiable, resulting in rough-looking curves. It is a special case of the Matern family with \nu = 0.5.

Value

A covariance function object of class 'kernel_exponential'.

See Also

kernel.gaussian, kernel.matern, make.gaussian.process

Examples

# Create an exponential covariance function
cov_func <- kernel.exponential(variance = 1, length_scale = 0.2)

# Evaluate covariance matrix
t <- seq(0, 1, length.out = 50)
K <- cov_func(t)

# Generate rough GP samples
fd <- make.gaussian.process(n = 10, t = t, cov = cov_func)
plot(fd)

Gaussian (Squared Exponential) Covariance Function

Description

Computes the Gaussian (RBF/squared exponential) covariance function:

k(s, t) = \sigma^2 \exp\left(-\frac{(s-t)^2}{2\ell^2}\right)

Usage

kernel.gaussian(variance = 1, length_scale = 1)

Arguments

Details

This kernel produces infinitely differentiable (very smooth) sample paths.

The Gaussian covariance function, also known as the squared exponential or radial basis function (RBF) kernel, is one of the most commonly used covariance functions. It produces very smooth sample paths because it is infinitely differentiable.

The length scale parameter controls how quickly the correlation decays with distance. Larger values produce smoother, more slowly varying functions.

Value

A covariance function object of class 'kernel_gaussian'.

See Also

kernel.exponential, kernel.matern, make.gaussian.process

Examples

# Create a Gaussian covariance function
cov_func <- kernel.gaussian(variance = 1, length_scale = 0.2)

# Evaluate covariance matrix on a grid
t <- seq(0, 1, length.out = 50)
K <- cov_func(t)
image(K, main = "Gaussian Covariance Matrix")

# Generate Gaussian process samples
fd <- make.gaussian.process(n = 10, t = t, cov = cov_func)
plot(fd)

Linear Covariance Function

Description

Computes the linear covariance function:

k(s, t) = \sigma^2 (s - c)(t - c)

Usage

kernel.linear(variance = 1, offset = 0)

Arguments

Details

The linear covariance function produces sample paths that are linear functions. It is useful when the underlying process is expected to have a linear trend.

Value

A covariance function object of class 'kernel_linear'.

See Also

kernel.polynomial, make.gaussian.process

Examples

# Generate linear function samples
cov_func <- kernel.linear(variance = 1)
t <- seq(0, 1, length.out = 50)
fd <- make.gaussian.process(n = 10, t = t, cov = cov_func)
plot(fd)

Matern Covariance Function

Description

Computes the Matern covariance function with smoothness parameter \nu:

k(s, t) = \sigma^2 \frac{2^{1-\nu}}{\Gamma(\nu)} \left(\sqrt{2\nu}\frac{|s-t|}{\ell}\right)^\nu K_\nu\left(\sqrt{2\nu}\frac{|s-t|}{\ell}\right)

Usage

kernel.matern(variance = 1, length_scale = 1, nu = 1.5)

Arguments

Details

where K_\nu is the modified Bessel function of the second kind.

The Matern family of covariance functions provides flexible control over the smoothness of sample paths through the \nu parameter. As \nu increases, sample paths become smoother. The Matern family includes the exponential (\nu = 0.5) and approaches the Gaussian kernel as \nu \to \infty.

For computational efficiency, special cases \nu \in \{0.5, 1.5, 2.5, \infty\} use simplified closed-form expressions.

Value

A covariance function object of class 'kernel_matern'.

See Also

kernel.gaussian, kernel.exponential, make.gaussian.process

Examples

# Create Matern covariance functions with different smoothness
cov_rough <- kernel.matern(nu = 0.5)    # Equivalent to exponential
cov_smooth <- kernel.matern(nu = 2.5)   # Twice differentiable

t <- seq(0, 1, length.out = 50)

# Compare sample paths
fd_rough <- make.gaussian.process(n = 5, t = t, cov = cov_rough, seed = 42)
fd_smooth <- make.gaussian.process(n = 5, t = t, cov = cov_smooth, seed = 42)

Multiply Covariance Functions

Description

Combines two covariance functions by multiplication.

Usage

kernel.mult(kernel1, kernel2)

Arguments

Value

A combined covariance function.

Examples

# Multiply periodic with Gaussian for locally periodic behavior
k_periodic <- kernel.periodic(period = 0.3)
k_gaussian <- kernel.gaussian(length_scale = 0.5)
k_prod <- kernel.mult(k_periodic, k_gaussian)

Periodic Covariance Function

Description

Computes the periodic covariance function:

k(s, t) = \sigma^2 \exp\left(-\frac{2\sin^2(\pi|s-t|/p)}{\ell^2}\right)

Usage

kernel.periodic(variance = 1, length_scale = 1, period = 1)

Arguments

Details

The periodic covariance function produces sample paths that are periodic with the specified period. It is useful for modeling seasonal or cyclical patterns in functional data.

Value

A covariance function object of class 'kernel_periodic'.

See Also

kernel.gaussian, make.gaussian.process

Examples

# Generate periodic function samples
cov_func <- kernel.periodic(period = 0.5, length_scale = 0.5)
t <- seq(0, 2, length.out = 100)
fd <- make.gaussian.process(n = 5, t = t, cov = cov_func)
plot(fd)

Polynomial Covariance Function

Description

Computes the polynomial covariance function:

k(s, t) = \sigma^2 (s \cdot t + c)^p

Usage

kernel.polynomial(variance = 1, offset = 0, degree = 2)

Arguments

Details

The polynomial covariance function produces sample paths that are polynomial functions of degree at most degree. Setting degree = 1 and offset = 0 gives the linear kernel.

Value

A covariance function object of class 'kernel_polynomial'.

See Also

kernel.linear, make.gaussian.process

Examples

# Generate quadratic function samples
cov_func <- kernel.polynomial(degree = 2, offset = 1)
t <- seq(0, 1, length.out = 50)
fd <- make.gaussian.process(n = 10, t = t, cov = cov_func)
plot(fd)

White Noise Covariance Function

Description

Computes the white noise covariance function:

k(s, t) = \sigma^2 \mathbf{1}_{s = t}

Usage

kernel.whitenoise(variance = 1)

Arguments

Details

where \mathbf{1}_{s = t} is 1 if s = t and 0 otherwise.

The white noise covariance function represents independent noise at each point. It can be added to other covariance functions to model observation noise.

Value

A covariance function object of class 'kernel_whitenoise'.

See Also

kernel.gaussian, make.gaussian.process

Examples

# White noise covariance produces independent samples at each point
cov_func <- kernel.whitenoise(variance = 0.1)
t <- seq(0, 1, length.out = 50)
K <- cov_func(t)
# K is diagonal

Covariance Kernel Functions for Gaussian Processes

Description

Parametric covariance functions (kernels) used to define the covariance structure of Gaussian processes. These can be used with make_gaussian_process to generate synthetic functional data.

Value

No return value. This page documents the family of kernel functions.

Local Averages Feature Extraction

Description

Extracts features from functional data by computing local averages over specified intervals. This is a simple but effective dimension reduction technique for functional data.

Usage

localavg.fdata(fdataobj, n.intervals = 10, intervals = NULL)

Arguments

Details

Local averages provide a simple way to convert functional data to multivariate data while preserving local structure. Each curve is summarized by its average value over each interval.

This can be useful as a preprocessing step for classification or clustering methods that require fixed-dimensional input.

Value

A matrix with n rows (curves) and one column per interval, containing the local average for each curve in each interval.

Examples

# Create functional data
t <- seq(0, 1, length.out = 100)
X <- matrix(0, 20, 100)
for (i in 1:20) X[i, ] <- sin(2*pi*t) + rnorm(100, sd = 0.1)
fd <- fdata(X, argvals = t)

# Extract 5 local average features
features <- localavg.fdata(fd, n.intervals = 5)
dim(features)  # 20 x 5

# Use custom intervals
intervals <- cbind(c(0, 0.25, 0.5), c(0.25, 0.5, 1))
features2 <- localavg.fdata(fd, intervals = intervals)

Lomb-Scargle Periodogram

Description

Computes the Lomb-Scargle periodogram for period detection in unevenly-sampled data. The Lomb-Scargle method is designed for irregularly spaced observations and reduces to the standard periodogram for evenly-spaced data.

Usage

lomb.scargle(fdataobj, oversampling = 4, nyquist_factor = 1)

Arguments

Details

The Lomb-Scargle periodogram is particularly useful when:

• Data has gaps or missing observations

• Sampling is not uniform (e.g., astronomical observations)

• Working with irregular functional data

The algorithm follows Scargle (1982) with significance estimation from Horne & Baliunas (1986). For each test frequency, it computes:

P(\omega) = \frac{1}{2\sigma^2} \left[ \frac{(\sum_j (y_j - \bar{y}) \cos\omega(t_j - \tau))^2}{\sum_j \cos^2\omega(t_j - \tau)} + \frac{(\sum_j (y_j - \bar{y}) \sin\omega(t_j - \tau))^2}{\sum_j \sin^2\omega(t_j - \tau)} \right]

where \tau is a phase shift chosen to make the sine and cosine terms orthogonal.

Value

A list of class "lomb_scargle_result" with components:

frequencies

Vector of evaluated frequencies

periods

Corresponding periods (1/frequency)

power

Normalized Lomb-Scargle power at each frequency

peak_period

Period with highest power

peak_frequency

Frequency with highest power

peak_power

Maximum power value

false_alarm_probability

False alarm probability at peak

significance

Significance level (1 - FAP)

References

Scargle, J.D. (1982). Studies in astronomical time series analysis. II. Statistical aspects of spectral analysis of unevenly spaced data. The Astrophysical Journal, 263, 835-853.

Horne, J.H., & Baliunas, S.L. (1986). A prescription for period analysis of unevenly sampled time series. The Astrophysical Journal, 302, 757-763.

See Also

estimate.period, sazed

Examples

# Regular sampling
t <- seq(0, 10, length.out = 200)
X <- matrix(sin(2 * pi * t / 2), nrow = 1)
fd <- fdata(X, argvals = t)
result <- lomb.scargle(fd)
print(result)

# Irregular sampling (simulated)
set.seed(42)
t_irreg <- sort(runif(100, 0, 10))
X_irreg <- matrix(sin(2 * pi * t_irreg / 2), nrow = 1)
fd_irreg <- fdata(X_irreg, argvals = t_irreg)
result_irreg <- lomb.scargle(fd_irreg)

Magnitude-Shape Outlier Detection for Functional Data

Description

Performs Magnitude-Shape (MS) outlier detection for functional data. Each curve is represented as a point in 2D space where the x-axis represents magnitude outlyingness and the y-axis represents shape outlyingness.

Usage

magnitudeshape(
  fdataobj,
  depth.func = depth.MBD,
  cutoff.quantile = 0.993,
  col.normal = "black",
  col.outliers = "red",
  label = "index",
  label_all = FALSE,
  ...
)

Arguments

Details

The MS plot (Dai & Genton, 2019) decomposes functional outlyingness into:

• Magnitude Outlyingness (MO): Based on pointwise median of directional outlyingness - captures shift outliers

• Shape Outlyingness (VO): Based on variability of directional outlyingness - captures shape outliers

Outliers are detected using the chi-squared distribution with cutoff at the specified quantile.

Value

A list of class 'magnitudeshape' with components:

MO

Magnitude outlyingness values

VO

Shape (variability) outlyingness values

outliers

Indices of detected outliers

cutoff

Chi-squared cutoff value used

plot

The ggplot object

References

Dai, W. and Genton, M.G. (2019). Directional outlyingness for multivariate functional data. Computational Statistics & Data Analysis, 131, 50-65.

Examples

# Create functional data with outliers
set.seed(42)
t <- seq(0, 1, length.out = 50)
X <- matrix(0, 30, 50)
for (i in 1:28) X[i, ] <- sin(2*pi*t) + rnorm(50, sd = 0.2)
X[29, ] <- sin(2*pi*t) + 2  # Magnitude outlier
X[30, ] <- sin(4*pi*t)       # Shape outlier
fd <- fdata(X, argvals = t)

# Create MS plot
ms <- magnitudeshape(fd)

# With IDs and metadata
fd <- fdata(X, argvals = t, id = paste0("curve_", 1:30))
ms <- magnitudeshape(fd, label = "id")

Generate Gaussian Process Samples

Description

Generates functional data samples from a Gaussian process with the specified mean and covariance functions.

Usage

make.gaussian.process(n, t, cov = kernel.gaussian(), mean = 0, seed = NULL)

Arguments

Details

This function generates samples from a Gaussian process with the specified covariance structure. The samples are generated by computing the Cholesky decomposition of the covariance matrix and multiplying by standard normal random variables.

For 2D functional data, pass t as a list of two vectors representing the grid in each dimension.

Value

An fdata object containing the generated samples.

See Also

kernel.gaussian, kernel.matern, kernel.exponential

Examples

# Generate smooth GP samples with Gaussian covariance
t <- seq(0, 1, length.out = 100)
fd <- make.gaussian.process(n = 20, t = t,
                            cov = kernel.gaussian(length_scale = 0.2),
                            seed = 42)
plot(fd)

# Generate rough GP samples with exponential covariance
fd_rough <- make.gaussian.process(n = 20, t = t,
                                  cov = kernel.exponential(length_scale = 0.1),
                                  seed = 42)
plot(fd_rough)

# Generate 2D GP samples (surfaces)
s <- seq(0, 1, length.out = 20)
t2 <- seq(0, 1, length.out = 20)
fd2d <- make.gaussian.process(n = 5, t = list(s, t2),
                              cov = kernel.gaussian(length_scale = 0.3),
                              seed = 42)
plot(fd2d)

# Generate GP with non-zero mean
mean_func <- function(t) sin(2 * pi * t)
fd_mean <- make.gaussian.process(n = 10, t = t,
                                 cov = kernel.gaussian(variance = 0.1),
                                 mean = mean_func, seed = 42)
plot(fd_mean)

Matrix Profile for Motif Discovery and Period Detection

Description

Computes the Matrix Profile using the STOMP (Scalable Time series Ordered-search Matrix Profile) algorithm. The Matrix Profile stores the z-normalized Euclidean distance between each subsequence and its nearest neighbor, enabling efficient motif discovery and period detection for non-sinusoidal patterns.

Usage

matrix.profile(fdataobj, subsequence_length = NULL, exclusion_zone = 0.5)

Arguments

Details

The Matrix Profile algorithm (Yeh et al., 2016; Zhu et al., 2016) is particularly suited for:

• Non-sinusoidal repeating patterns (unlike FFT/spectral methods)

• Motif discovery (finding repeated subsequences)

• Anomaly detection (subsequences with no good match)

The STOMP variant uses O(n^2) time complexity but is highly cache-efficient. For very long series (>10000 points), consider downsampling.

Period detection is based on "arc analysis": counting how often the nearest neighbor is a fixed distance away. Peaks in arc counts indicate periodicity.

Value

A list of class "matrix_profile_result" with components:

profile

Numeric vector of minimum z-normalized distances at each position

profile_index

Integer vector of nearest neighbor indices (1-based)

subsequence_length

Subsequence length used

detected_periods

Candidate periods detected from arc analysis (top 5)

arc_counts

Arc counts at each index distance (for diagnostics)

primary_period

Most prominent detected period

confidence

Confidence score (0-1) based on arc prominence

References

Yeh, C. C. M., et al. (2016). Matrix profile I: All pairs similarity joins for time series: A unifying view that includes motifs, discords and shapelets. ICDM 2016.

Zhu, Y., et al. (2016). Matrix profile II: Exploiting a novel algorithm and GPUs to break the one hundred million barrier for time series motifs and joins. ICDM 2016.

See Also

estimate.period, sazed, lomb.scargle

Examples

# Periodic sawtooth wave (non-sinusoidal)
t <- seq(0, 10, length.out = 200)
period <- 2
X <- matrix((t %% period) / period, nrow = 1)
fd <- fdata(X, argvals = t)

# Compute Matrix Profile
result <- matrix.profile(fd, subsequence_length = 30)
print(result)
plot(result)

# Sine wave for comparison
X_sine <- matrix(sin(2 * pi * t / period), nrow = 1)
fd_sine <- fdata(X_sine, argvals = t)
result_sine <- matrix.profile(fd_sine, subsequence_length = 30)

Compute functional mean

Description

Computes the pointwise mean function across all observations. This is an S3 method for the generic mean function.

Usage

## S3 method for class 'fdata'
mean(x, ...)

Arguments

Value

For 1D fdata: a numeric vector containing the mean function values. For 2D fdata: an fdata object containing the mean surface.

Examples

# 1D functional data
fd <- fdata(matrix(rnorm(100), 10, 10))
fm <- mean(fd)

# 2D functional data
X <- array(rnorm(500), dim = c(5, 10, 10))
fd2d <- fdata(X, argvals = list(1:10, 1:10), fdata2d = TRUE)
fm2d <- mean(fd2d)

Estimate Mean Function for Irregular Data

Description

Estimates the mean function from irregularly sampled functional data.

Usage

## S3 method for class 'irregFdata'
mean(
  x,
  argvals = NULL,
  method = c("basis", "kernel"),
  nbasis = 15,
  type = c("bspline", "fourier"),
  bandwidth = NULL,
  kernel = c("epanechnikov", "gaussian"),
  ...
)

Arguments

Details

The "basis" method (default) works by:

1. Fitting basis functions to each curve via least squares

2. Reconstructing each curve on the target grid

3. Averaging the reconstructed curves

This approach preserves the functional structure and typically gives more accurate estimates than kernel smoothing.

The "kernel" method uses Nadaraya-Watson estimation, pooling all observations across curves. This is faster but may be less accurate for structured functional data.

Value

An fdata object containing the estimated mean function.

Examples

t <- seq(0, 1, length.out = 100)
fd <- simFunData(n = 50, argvals = t, M = 5, seed = 42)
ifd <- sparsify(fd, minObs = 10, maxObs = 30, seed = 123)

# Recommended: basis method
mean_fd <- mean(ifd)
plot(mean_fd, main = "Estimated Mean Function")

# Alternative: kernel method
mean_kernel <- mean(ifd, method = "kernel", bandwidth = 0.1)

Compute Functional Median

Description

Returns the curve with maximum depth using the specified depth method.

Usage

median(
  fdataobj,
  method = c("FM", "mode", "RP", "RT", "BD", "MBD", "FSD", "KFSD", "RPD"),
  ...
)

Arguments

Value

The curve (as fdata object) with maximum depth.

Examples

fd <- fdata(matrix(rnorm(100), 10, 10))
med <- median(fd)
med_mode <- median(fd, method = "mode")

Distance Metrics for Functional Data

Description

Functions for computing various distance metrics between functional data. Compute Distance Metric for Functional Data

Usage

metric(fdataobj, fdataref = NULL, method = "lp", ...)

Arguments

Details

Unified interface for computing various distance metrics between functional data objects. This function dispatches to the appropriate specialized distance function based on the method parameter.

This function provides a convenient unified interface for all distance computations in fdars. The additional arguments in ... are passed to the underlying distance function:

• lp: lp, w

• hausdorff: (none)

• dtw: p, w

• pca: ncomp

• deriv: nderiv, lp

• basis: nbasis, basis, nderiv

• fourier: nfreq

• hshift: max_shift

• kl: eps, normalize

Value

A distance matrix.

Examples

fd <- fdata(matrix(rnorm(200), 20, 10))

# Using different distance methods
D_lp <- metric(fd, method = "lp")
D_hausdorff <- metric(fd, method = "hausdorff")
D_pca <- metric(fd, method = "pca", ncomp = 3)

# Cross-distances
fd2 <- fdata(matrix(rnorm(100), 10, 10))
D_cross <- metric(fd, fd2, method = "lp")

Dynamic Time Warping for Functional Data

Description

Computes the Dynamic Time Warping distance between functional data. DTW allows for non-linear alignment of curves.

Usage

metric.DTW(fdataobj, fdataref = NULL, p = 2, w = NULL, ...)

Arguments

Value

A distance matrix.

Examples

fd <- fdata(matrix(rnorm(100), 10, 10))
D <- metric.DTW(fd)

Hausdorff Metric for Functional Data

Description

Computes the Hausdorff distance between functional data objects. The Hausdorff distance treats each curve as a set of points (t, f(t)) in 2D space and computes the maximum of the minimum distances.

Usage

metric.hausdorff(fdataobj, fdataref = NULL, ...)

Arguments

Value

A distance matrix.

Examples

fd <- fdata(matrix(rnorm(100), 10, 10))
D <- metric.hausdorff(fd)

Kullback-Leibler Divergence Metric for Functional Data

Description

Computes the symmetric Kullback-Leibler divergence between functional data treated as probability distributions. Curves are first normalized to be valid probability density functions.

Usage

metric.kl(fdataobj, fdataref = NULL, eps = 1e-10, normalize = TRUE, ...)

Arguments

Details

The symmetric KL divergence is computed as:

D_{KL}(f, g) = \frac{1}{2}[KL(f||g) + KL(g||f)]

where

KL(f||g) = \int f(t) \log\frac{f(t)}{g(t)} dt

When normalize = TRUE, curves are first shifted to be non-negative (by subtracting the minimum and adding eps), then normalized to integrate to 1. This makes them valid probability density functions.

The symmetric KL divergence is always non-negative and equals zero only when the two distributions are identical. However, it does not satisfy the triangle inequality.

Value

A distance matrix based on symmetric KL divergence.

Examples

# Create curves that look like probability densities
t <- seq(0, 1, length.out = 100)
X <- matrix(0, 10, 100)
for (i in 1:10) {
  # Shifted Gaussian-like curves
  X[i, ] <- exp(-(t - 0.3 - i/50)^2 / 0.02) + rnorm(100, sd = 0.01)
}
fd <- fdata(X, argvals = t)

# Compute KL divergence
D <- metric.kl(fd)

Lp Metric for Functional Data

Description

Computes the Lp distance between functional data objects using numerical integration (Simpson's rule). Works with both regular fdata and irregular irregFdata objects.

Usage

## S3 method for class 'irregFdata'
metric.lp(x, p = 2, ...)

metric.lp(x, ...)

## S3 method for class 'fdata'
metric.lp(x, y = NULL, p = 2, w = 1, ...)

Arguments

Value

A distance matrix.

Examples

# Regular fdata
fd <- fdata(matrix(rnorm(100), 10, 10))
D <- metric.lp(fd)  # Self-distances

# Irregular fdata
ifd <- sparsify(fd, minObs = 3, maxObs = 7, seed = 42)
D_irreg <- metric.lp(ifd)

Compute Lp Norm of Functional Data

Description

Generic function to compute Lp norms for functional data objects. Works with both regular fdata and irregular irregFdata objects.

Usage

norm(x, p = 2, ...)

## S3 method for class 'fdata'
norm(x, p = 2, ...)

## S3 method for class 'irregFdata'
norm(x, p = 2, ...)

Arguments

Value

A numeric vector of norms, one per curve.

Examples

# Regular fdata
fd <- fdata(matrix(rnorm(100), 10, 10))
norms <- norm(fd)

# Irregular fdata
ifd <- sparsify(fd, minObs = 3, maxObs = 7, seed = 42)
norms_irreg <- norm(ifd)

Normalize functional data

Description

Scales each curve to have Lp norm equal to 1.

Usage

normalize(fdataobj, p = 2)

Arguments

Value

A normalized 'fdata' object where each curve has unit norm.

Examples

fd <- fdata(matrix(rnorm(100), 10, 10), argvals = seq(0, 1, length.out = 10))
fd_norm <- normalize(fd)
norm(fd_norm)  # All values should be 1

Optimize Bandwidth Using Cross-Validation

Description

Find the optimal bandwidth by minimizing CV or GCV criterion.

Usage

optim.np(
  fdataobj,
  S.type,
  h.range = NULL,
  criterion = "GCV",
  Ker = "norm",
  ...
)

Arguments

Value

A list with optimal bandwidth and CV/GCV score.

Examples

tt <- seq(0, 1, length.out = 50)
y <- sin(2 * pi * tt) + rnorm(50, sd = 0.1)
fd <- fdata(matrix(y, nrow = 1), argvals = tt)
result <- optim.np(fd, S.NW)

Outliergram for Functional Data

Description

Creates an outliergram plot that displays MEI (Modified Epigraph Index) versus MBD (Modified Band Depth) for outlier detection. Points below the parabolic boundary are identified as outliers, and each outlier is classified by type.

Usage

outliergram(fdataobj, factor = 1.5, mei_threshold = 0.25, ...)

Arguments

Details

The outliergram plots MEI on the x-axis versus MBD on the y-axis. For a sample of size n, the theoretical relationship is bounded by the finite-sample parabola (Arribas-Gil & Romo, 2014, Proposition 1):

MBD \le a_0 + a_1 \cdot MEI + a_2 \cdot MEI^2

where a_0 = -2/(n(n-1)), a_1 = 2(n+1)/(n-1), a_2 = -2(n+1)/(n-1).

Shape outliers are detected using a boxplot fence on the vertical distances below the parabola: a curve is flagged when its distance exceeds Q_3 + \mathrm{factor} \times IQR.

Value

An object of class 'outliergram' with components:

fdataobj

The input functional data

mei

MEI values for each curve

mbd

MBD values for each curve

outliers

Indices of detected outliers

outlier_type

Character vector of outlier types ("shape") for each detected outlier

n_outliers

Number of outliers detected

factor

The factor used for threshold adjustment

parabola

Coefficients of the parabolic boundary (a0, a1, a2)

threshold

The boxplot-fence threshold for distance below the parabola

dist_to_parabola

Vertical distance below the parabola for each curve (positive values indicate the point is below the parabola)

References

Arribas-Gil, A. and Romo, J. (2014). Shape outlier detection and visualization for functional data: the outliergram. Biostatistics, 15(4), 603-619.

See Also

depth for depth computation, magnitudeshape for an alternative outlier visualization.

Examples

# Create functional data with different outlier types
set.seed(42)
t <- seq(0, 1, length.out = 50)
X <- matrix(0, 32, 50)
for (i in 1:29) X[i, ] <- sin(2 * pi * t) + rnorm(50, sd = 0.2)
X[30, ] <- sin(2 * pi * t) + 2       # magnitude outlier (high)
X[31, ] <- sin(2 * pi * t) - 2       # magnitude outlier (low)
X[32, ] <- sin(4 * pi * t)           # shape outlier
fd <- fdata(X, argvals = t)

# Create outliergram
og <- outliergram(fd)
print(og)
plot(og, color_by_type = TRUE)

Outlier Detection using Functional Boxplot

Description

Detects outliers based on the functional boxplot method. Curves that exceed the fence (1.5 times the central envelope width) at any point are flagged as outliers.

Usage

outliers.boxplot(
  fdataobj,
  prob = 0.5,
  factor = 1.5,
  depth.func = depth.MBD,
  ...
)

Arguments

Value

A list of class 'outliers.fdata' with components:

outliers

Indices of detected outliers

depths

Depth values for all curves

cutoff

Not used (for compatibility)

fdataobj

Original fdata object

See Also

boxplot.fdata for functional boxplot visualization

Examples

# Create functional data with outliers
set.seed(42)
t <- seq(0, 1, length.out = 50)
X <- matrix(0, 30, 50)
for (i in 1:28) X[i, ] <- sin(2*pi*t) + rnorm(50, sd = 0.2)
X[29, ] <- sin(2*pi*t) + 2  # Magnitude outlier
X[30, ] <- cos(2*pi*t)       # Shape outlier
fd <- fdata(X, argvals = t)

# Detect outliers
out <- outliers.boxplot(fd)
print(out)

Outlier Detection for Functional Data

Description

Functions for detecting outliers in functional data using depth measures. Outlier Detection using Weighted Depth

Usage

outliers.depth.pond(
  fdataobj,
  nb = 200,
  dfunc = depth.mode,
  threshold_method = c("quantile", "mad", "iqr"),
  quan = 0.05,
  k = NULL,
  ...
)

Arguments

Details

Detects outliers based on depth with bootstrap resampling. The threshold for outlier detection can be computed using different methods.

The function first computes depth values for all curves, then uses bootstrap resampling to obtain weighted depths that are more robust to sampling variability.

Threshold Methods:

• quantile: Flags curves with depth below the specified quantile. With quan = 0.1, approximately 10% of curves would be flagged under the null hypothesis of no outliers. Suitable when you expect a specific proportion of outliers.

• mad: Uses median(depths) - k * MAD(depths) as threshold. More robust because MAD is not influenced by extreme values. With k = 2.5, this corresponds roughly to a 1-2% false positive rate under normality.

• iqr: Uses Q1 - k * IQR as threshold, similar to boxplot outlier detection. With k = 1.5, corresponds to the standard boxplot fence.

Value

A list of class 'outliers.fdata' with components:

outliers

Indices of detected outliers

depths

Depth values for all curves

weighted_depths

Bootstrap-weighted depth values

cutoff

Depth cutoff used

threshold_method

Method used for threshold computation

fdataobj

Original fdata object

Examples

# Create data with outliers
set.seed(42)
t <- seq(0, 1, length.out = 50)
X <- matrix(0, 30, 50)
for (i in 1:28) X[i, ] <- sin(2*pi*t) + rnorm(50, sd = 0.2)
X[29, ] <- sin(2*pi*t) + 3  # outlier
X[30, ] <- -sin(2*pi*t)     # outlier
fd <- fdata(X, argvals = t)


# Default: quantile method with 95th percentile (bottom 5%)
out1 <- outliers.depth.pond(fd, nb = 50)

# More permissive: bottom 10%
out1b <- outliers.depth.pond(fd, nb = 50, quan = 0.1)

# MAD method (more robust)
out2 <- outliers.depth.pond(fd, nb = 50, threshold_method = "mad", k = 2.5)

# IQR method (boxplot-like)
out3 <- outliers.depth.pond(fd, nb = 50, threshold_method = "iqr", k = 1.5)

Outlier Detection using Trimmed Depth

Description

Detects outliers based on depth trimming.

Usage

outliers.depth.trim(fdataobj, trim = 0.1, dfunc = depth.mode, ...)

Arguments

Value

A list of class 'outliers.fdata' with components:

outliers

Indices of detected outliers

depths

Depth values for all curves

cutoff

Depth cutoff used

Examples

fd <- fdata(matrix(rnorm(200), 20, 10))
out <- outliers.depth.trim(fd, trim = 0.1)

LRT-based Outlier Detection for Functional Data

Description

Detects outliers using the Likelihood Ratio Test approach based on Febrero-Bande et al. Uses bootstrap to estimate a threshold and iteratively removes curves exceeding this threshold. Implemented in Rust for high performance with parallelized bootstrap.

Usage

outliers.lrt(
  fdataobj,
  nb = 200,
  smo = 0.05,
  trim = 0.1,
  seed = NULL,
  percentile = 0.99
)

Arguments

Value

A list of class 'outliers.fdata' with components:

outliers

Indices of detected outliers

distances

Normalized distances for all curves

threshold

Bootstrap threshold used

percentile

Percentile used for threshold

fdataobj

Original fdata object

Examples

t <- seq(0, 1, length.out = 50)
X <- matrix(0, 30, 50)
for (i in 1:30) X[i, ] <- sin(2*pi*t) + rnorm(50, sd = 0.1)
# Add an outlier
X[1, ] <- X[1, ] + 3
fd <- fdata(X, argvals = t)
out <- outliers.lrt(fd, nb = 100)

# More sensitive detection
out_sensitive <- outliers.lrt(fd, nb = 100, percentile = 0.95)

LRT Outlier Detection Threshold

Description

Computes the bootstrap threshold for LRT-based outlier detection. This is a highly parallelized Rust implementation providing significant speedup over pure R implementations.

Usage

outliers.thres.lrt(
  fdataobj,
  nb = 200,
  smo = 0.05,
  trim = 0.1,
  seed = NULL,
  percentile = 0.99
)

Arguments

Value

The threshold value at the specified percentile.

Examples

t <- seq(0, 1, length.out = 50)
X <- matrix(0, 30, 50)
for (i in 1:30) X[i, ] <- sin(2*pi*t) + rnorm(50, sd = 0.1)
fd <- fdata(X, argvals = t)
thresh <- outliers.thres.lrt(fd, nb = 100)

# More sensitive detection (95th percentile)
thresh_sensitive <- outliers.thres.lrt(fd, nb = 100, percentile = 0.95)

Plot method for amplitude_modulation objects

Description

Plot method for amplitude_modulation objects

Usage

## S3 method for class 'amplitude_modulation'
plot(x, ...)

Arguments

Value

Invisibly returns the input object x.

Plot method for basis.auto objects

Description

Plot method for basis.auto objects

Usage

## S3 method for class 'basis.auto'
plot(
  x,
  which = c("all", "fourier", "pspline"),
  show.original = TRUE,
  max.curves = 20,
  ...
)

Arguments

Value

A ggplot object (invisibly).

Plot method for basis.cv objects

Description

Plot method for basis.cv objects

Usage

## S3 method for class 'basis.cv'
plot(x, ...)

Arguments

Value

A ggplot object (invisibly).

Plot Method for cluster.fcm Objects

Description

Plot Method for cluster.fcm Objects

Usage

## S3 method for class 'cluster.fcm'
plot(x, type = c("curves", "membership"), ...)

Arguments

Value

A ggplot object.

Plot Method for cluster.kmeans Objects

Description

Plot Method for cluster.kmeans Objects

Usage

## S3 method for class 'cluster.kmeans'
plot(x, ...)

Arguments

Value

A ggplot object.

Plot Method for cluster.optim Objects

Description

Plot Method for cluster.optim Objects

Usage

## S3 method for class 'cluster.optim'
plot(x, ...)

Arguments

Value

A ggplot object.

Plot method for fdata objects

Description

Displays a plot of functional data. For 1D functional data, plots curves as lines with optional coloring. For 2D functional data, plots surfaces as heatmaps with contour lines.

Usage

## S3 method for class 'fdata'
plot(
  x,
  color = NULL,
  alpha = NULL,
  show.mean = FALSE,
  show.ci = FALSE,
  ci.level = 0.9,
  palette = NULL,
  ...
)

Arguments

Details

This function displays the plot immediately. To get the ggplot object without displaying (e.g., for customization), use autoplot.fdata.

Value

The ggplot object (invisibly).

Examples

library(ggplot2)
# Display plot immediately
fd <- fdata(matrix(rnorm(200), 20, 10))
plot(fd)

# To get ggplot object without displaying, use autoplot:
p <- autoplot(fd)

Plot FPCA Results

Description

Visualize functional principal component analysis results with multiple plot types: component perturbation plots, variance explained (scree plot), or score plots.

Usage

## S3 method for class 'fdata2pc'
plot(
  x,
  type = c("components", "variance", "scores"),
  ncomp = 3,
  multiple = 2,
  show_both_directions = TRUE,
  ...
)

Arguments

Details

The "components" plot shows the mean function (black) with perturbations in the direction of each principal component. The perturbation is computed as: mean +/- multiple * sqrt(variance_explained) * PC_loading. All lines are solid and differentiated by color only.

The "variance" plot shows a scree plot with the proportion of variance explained by each component as a bar chart.

The "scores" plot shows a scatter plot of observations in PC space, typically PC1 vs PC2.

Value

A ggplot object (invisibly).

See Also

fdata2pc for computing FPCA.

Examples

t <- seq(0, 1, length.out = 50)
X <- matrix(0, 30, 50)
for (i in 1:30) X[i, ] <- sin(2*pi*t + runif(1, 0, pi)) + rnorm(50, sd = 0.1)
fd <- fdata(X, argvals = t)
pc <- fdata2pc(fd, ncomp = 3)

# Plot PC components (mean +/- perturbations)
plot(pc, type = "components")

# Scree plot
plot(pc, type = "variance")

# Score plot
plot(pc, type = "scores")

Plot method for fequiv.test

Description

Creates a ggplot showing the mean difference curve, simultaneous confidence band, and equivalence margins.

Usage

## S3 method for class 'fequiv.test'
plot(x, ...)

Arguments

Value

A ggplot object (invisibly).

Plot method for group.distance

Description

Plot method for group.distance

Usage

## S3 method for class 'group.distance'
plot(x, type = c("heatmap", "dendrogram"), which = NULL, ...)

Arguments

Value

A ggplot object (for heatmap) or NULL (for dendrogram, uses base graphics).

Plot method for irregFdata objects

Description

Plot method for irregFdata objects

Usage

## S3 method for class 'irregFdata'
plot(
  x,
  ...,
  col = NULL,
  lty = 1,
  lwd = 1,
  main = NULL,
  xlab = NULL,
  ylab = NULL,
  add = FALSE,
  alpha = 0.7
)

Arguments

Value

Invisibly returns the input object x.

Plot method for lomb_scargle_result objects

Description

Plot method for lomb_scargle_result objects

Usage

## S3 method for class 'lomb_scargle_result'
plot(x, ...)

Arguments

Value

Invisibly returns NULL.

Plot Method for magnitudeshape Objects

Description

Plot Method for magnitudeshape Objects

Usage

## S3 method for class 'magnitudeshape'
plot(x, ...)

Arguments

Value

The ggplot object (invisibly).

Plot method for matrix_profile_result objects

Description

Plot method for matrix_profile_result objects

Usage

## S3 method for class 'matrix_profile_result'
plot(x, type = c("profile", "arcs", "both"), ...)

Arguments

Value

Invisibly returns NULL.

Plot Method for Outliergram Objects

Description

Creates a scatter plot of MEI vs MBD with the parabolic boundary and identified outliers highlighted.

Usage

## S3 method for class 'outliergram'
plot(
  x,
  col_normal = "gray60",
  col_outlier = "red",
  color_by_type = FALSE,
  show_parabola = TRUE,
  show_threshold = TRUE,
  label = "index",
  label_all = FALSE,
  ...
)

Arguments

Value

A ggplot object (invisibly).

Plot method for outliers.fdata objects

Description

Plot method for outliers.fdata objects

Usage

## S3 method for class 'outliers.fdata'
plot(x, col.outliers = "red", ...)

Arguments

Value

A ggplot object.

Plot method for pspline objects

Description

Plot method for pspline objects

Usage

## S3 method for class 'pspline'
plot(x, ...)

Arguments

Value

A ggplot object (invisibly).

Plot method for pspline.2d objects

Description

Plot method for pspline.2d objects

Usage

## S3 method for class 'pspline.2d'
plot(x, ...)

Arguments

Value

A ggplot object (invisibly).

Plot Method for register.fd Objects

Description

Plot Method for register.fd Objects

Usage

## S3 method for class 'register.fd'
plot(x, type = c("registered", "original", "both"), ...)

Arguments

Value

A ggplot object.

Plot method for ssa_result objects

Description

Plot method for ssa_result objects

Usage

## S3 method for class 'ssa_result'
plot(x, type = c("decomposition", "spectrum"), curves = 1, ...)

Arguments

Value

Invisibly returns NULL.

Plot method for stl_result objects

Description

Plot method for stl_result objects

Usage

## S3 method for class 'stl_result'
plot(x, curves = 1, ...)

Arguments

Value

Invisibly returns NULL.

Mean Absolute Error

Description

Compute the Mean Absolute Error between predicted and actual values.

Usage

pred.MAE(y_true, y_pred)

Arguments

Value

The mean absolute error.

Examples

y_true <- c(1, 2, 3, 4, 5)
y_pred <- c(1.1, 2.2, 2.9, 4.1, 4.8)
pred.MAE(y_true, y_pred)

Mean Squared Error

Description

Compute the Mean Squared Error between predicted and actual values.

Usage

pred.MSE(y_true, y_pred)

Arguments

Value

The mean squared error.

Examples

y_true <- c(1, 2, 3, 4, 5)
y_pred <- c(1.1, 2.2, 2.9, 4.1, 4.8)
pred.MSE(y_true, y_pred)

R-Squared (Coefficient of Determination)

Description

Compute the R-squared value between predicted and actual values.

Usage

pred.R2(y_true, y_pred)

Arguments

Value

The R-squared value.

Examples

y_true <- c(1, 2, 3, 4, 5)
y_pred <- c(1.1, 2.2, 2.9, 4.1, 4.8)
pred.R2(y_true, y_pred)

Root Mean Squared Error

Description

Compute the Root Mean Squared Error between predicted and actual values.

Usage

pred.RMSE(y_true, y_pred)

Arguments

Value

The root mean squared error.

Examples

y_true <- c(1, 2, 3, 4, 5)
y_pred <- c(1.1, 2.2, 2.9, 4.1, 4.8)
pred.RMSE(y_true, y_pred)

Predict Method for Functional Regression (fregre.fd)

Description

Predictions from a fitted functional regression model (fregre.pc or fregre.basis).

Usage

## S3 method for class 'fregre.fd'
predict(object, newdata = NULL, ...)

Arguments

Value

A numeric vector of predicted values.

Examples

# Create functional data
t <- seq(0, 1, length.out = 50)
X <- matrix(0, 30, 50)
for (i in 1:30) X[i, ] <- sin(2*pi*t) * i/30 + rnorm(50, sd = 0.1)
y <- rowMeans(X) + rnorm(30, sd = 0.1)
fd <- fdata(X, argvals = t)

# Fit model
fit <- fregre.pc(fd, y, ncomp = 3)

# Predict on new data
X_new <- matrix(sin(2*pi*t) * 0.5, nrow = 1)
fd_new <- fdata(X_new, argvals = t)
predict(fit, fd_new)

Predict Method for Nonparametric Functional Regression (fregre.np)

Description

Predictions from a fitted nonparametric functional regression model.

Usage

## S3 method for class 'fregre.np'
predict(object, newdata = NULL, ...)

Arguments

Value

A numeric vector of predicted values.

Examples

# Create functional data
t <- seq(0, 1, length.out = 50)
X <- matrix(0, 30, 50)
for (i in 1:30) X[i, ] <- sin(2*pi*t) * i/30 + rnorm(50, sd = 0.1)
y <- rowMeans(X) + rnorm(30, sd = 0.1)
fd <- fdata(X, argvals = t)

# Fit model
fit <- fregre.np(fd, y)

# Predict on new data
X_new <- matrix(sin(2*pi*t) * 0.5, nrow = 1)
fd_new <- fdata(X_new, argvals = t)
predict(fit, fd_new)

Predict method for fregre.np.multi

Description

Predict method for fregre.np.multi

Usage

## S3 method for class 'fregre.np.multi'
predict(object, newdata.list = NULL, ...)

Arguments

Value

Predicted values.

Print method for amplitude_modulation objects

Description

Print method for amplitude_modulation objects

Usage

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

Arguments

Value

Invisibly returns the input object x.

Print method for autoperiod_result objects

Description

Print method for autoperiod_result objects

Usage

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

Arguments

Value

Invisibly returns the input object x.

Print method for basis.auto objects

Description

Print method for basis.auto objects

Usage

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

Arguments

Value

Invisibly returns the input object x.

Print method for basis.cv objects

Description

Print method for basis.cv objects

Usage

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

Arguments

Value

Invisibly returns the input object x.

Print method for cfd_autoperiod_result objects

Description

Print method for cfd_autoperiod_result objects

Usage

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

Arguments

Value

Invisibly returns the input object x.

Print Method for cluster.fcm Objects

Description

Print Method for cluster.fcm Objects

Usage

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

Arguments

Value

Invisibly returns the input object x.

Print Method for cluster.kmeans Objects

Description

Print Method for cluster.kmeans Objects

Usage

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

Arguments

Value

Invisibly returns the input object x.

Print Method for cluster.optim Objects

Description

Print Method for cluster.optim Objects

Usage

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

Arguments

Value

Invisibly returns the input object x.

Print method for decomposition objects

Description

Print method for decomposition objects