Correlation-Based Clustering Tree

Description

Builds a binary tree for clustering time series data based on covariates. The splitting criterion minimizes the average absolute Pearson correlation between time series across child nodes.

Usage

COR(X, Y, control = list())

Arguments

Details

The algorithm recursively partitions the data by finding splits that minimize the average absolute correlation between time series in different child nodes. Statistical significance of each split is assessed via a permutation test.

At each node, the optimal split is found by exhaustively searching over all covariates and candidate split points. The permutation test shuffles the time series labels to generate a null distribution for the test statistic.

Value

An object of class "FACT" containing:

frame

A data frame describing the tree structure, with one row per node containing split variable, split value, test statistic, and p-value. A smaller test statistic suggests more heterogeneity between child nodes.

membership

An integer vector of length N indicating the terminal node assignment for each observation.

control

The control parameters used.

terms

Metadata including covariate names and data dimensions.

See Also

FACT for factor model-based clustering, gendata for generating synthetic data, print.FACT and plot.FACT for visualization.

Examples

# Generate synthetic data
data <- gendata(seed = 42, T = 100, N = c(50, 50, 50, 50))

# Build correlation-based tree
result <- COR(data$X, data$Y, control = list(R = 99, alpha = 0.05))

# Examine results
print(result)
plot(result)
table(result$membership, data$group)

Factor-Augmented Clustering Tree

Description

Builds a binary tree for clustering time series data based on covariates, using a group factor model framework. The splitting criterion evaluates whether child nodes exhibit distinct factor structures.

Usage

FACT(
  X,
  Y,
  r_a = 8,
  r_b = 4,
  method = c("threshold", "permutation"),
  control = list()
)

Arguments

Details

The FACT algorithm clusters time series by recursively partitioning them based on their underlying factor structures. At each node, the method:

1. Searches for the optimal split across all covariates and candidate points.

2. Computes a test statistic based on the overlap of factor spaces between the two child nodes.

3. Decides whether to split using either a threshold rule or permutation test.

Value

An object of class "FACT" containing:

frame

A data frame describing the tree structure, with one row per node. Includes split variable, split value, test statistic, and p-value (if applicable). A smaller test statistic indicates stronger evidence of heterogeneous factor structures between child nodes.

membership

An integer vector of length N indicating the terminal node assignment for each observation.

control

The control parameters used.

terms

Metadata including covariate names, data dimensions, and the values of r_a and r_b.

method

The splitting method used.

References

Hu, J., Li, T., Luo, Z., & Wang, X. Factor-Augmented Clustering Tree for Time Series.

See Also

COR for correlation-based clustering, gendata for generating synthetic data, print.FACT and plot.FACT for visualization.

Examples

data <- gendata(seed = 123, T = 200, N = c(50, 50, 50, 50))
tree1 <- FACT(data$X, data$Y, r_a = 8, r_b = 4, method = "threshold")
print(tree1)

Calculate Split Statistic

Description

Computes the split statistic for a candidate partition based on the overlap of factor spaces between two child nodes.

Usage

calculate_split_statistic(Y_L, Y_R, r_a, r_b)

Arguments

Value

The calculated split statistic. Returns 'Inf' if a node is too small.

Find the Best Split for a Node

Description

Internal function to iterate through all possible split points in all covariates to find the split that minimizes the split statistic.

Usage

find_best_split(X_node, Y_node, indices, r_a, r_b, control)

Arguments

Value

A list containing the best split found, including the statistic, split variable, split value, and indices for the left and right children.

Find Best Split Using Correlation Criterion

Description

Searches for the optimal split point that minimizes the average absolute correlation between time series across child nodes.

Usage

find_best_split_COR(X_node, Y_node, indices, control)

Arguments

Value

A list containing the best split found, including the statistic, split variable, split value, and indices for the left and right children.

Generate Synthetic Group Factor Model Data

Description

Generates synthetic time series data with a multi-group factor structure, along with associated covariates. Useful for Monte Carlo simulation. the FACT and COR algorithms.

Usage

gendata(
  seed = 1,
  T = 100,
  N = c(100, 100, 100, 100),
  r0 = 2,
  r = c(2, 2, 2, 2),
  M = 4,
  sigma = 1,
  p = 10,
  mu = 3,
  type_F = "Independent",
  type_X = "Uniform",
  type_noise = "Gaussian"
)

Arguments

Details

The data generating process follows a group factor model:

Y_m = G \Lambda_m' + F_m \Gamma_m' + E_m, \quad m = 1, \ldots, M

where:

• G: T \times r_0 matrix of global factors (shared across groups)

• \Lambda_m: N_m \times r_0 global factor loadings for group m

• F_m: T \times r_m matrix of local factors for group m

• \Gamma_m: N_m \times r_m local factor loadings for group m

• E_m: T \times N_m idiosyncratic error matrix

Both global and local factors follow AR(1) processes with coefficient 0.5. Factor loadings are drawn from standard normal distributions.

Value

A list containing:

Y

A T \times N numeric matrix of time series, where N = \sum N_m.

X

A N \times p numeric matrix of covariates.

G

The T \times r_0 matrix of true global factors.

r0

Number of global factors.

r

Vector of local factor counts per group.

group

Integer vector of length N indicating true group membership (values 1 through M).

Note

The default covariate generation (type_X = "Uniform" or "Gaussian") assumes M = 4 groups with a specific hierarchical structure: groups 1-2 vs 3-4 are separated by the first covariate, and within each pair, groups are separated by additional covariates.

See Also

FACT for building factor-augmented clustering trees, COR for correlation-based clustering.

Examples

data <- gendata(seed = 123, T = 200, N = c(100, 50, 50, 200), r0 = 1, r = c(2, 2, 2, 3), M = 4)
Y <- data$Y
X <- data$X

Plot a FACT Tree Object

Description

Generates a visual plot of the FACT tree structure.

Usage

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

Arguments

Value

No return value, called for side effects (plotting).

Print a FACT Tree Object

Description

Provides a concise textual representation of the FACT tree structure.

Usage

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

Arguments

Value

Invisibly returns the original 'FACT' object.