Package {topcc}

Type:	Package
Title:	Topological Correlation Coefficient
Version:	1.2
Description:	Topological correlation coefficient is used to identify dependencies between Time-Dependent Objects and is applicable to objects such as time series, chaotic systems, and dynamic networks.
License:	GPL-3
Encoding:	UTF-8
LazyData:	true
Depends:	R (≥ 2.10)
Imports:	parallel
RoxygenNote:	7.3.2
NeedsCompilation:	no
Packaged:	2026-05-05 12:23:22 UTC; niech
Author:	Chun-Xiao Nie [aut, cre]
Maintainer:	Chun-Xiao Nie <niechunxiao2009@163.com>
Repository:	CRAN
Date/Publication:	2026-05-08 14:40:02 UTC

Auto Topological Correlation Coefficient (ATCC)

Description

Computes the auto topological correlation coefficient for a time series or a time-dependent object (TDO) at given lags. For each lag, the original input is split into two overlapping segments shifted by the lag, and the topological correlation coefficient (TCC) between the two segments is returned.

Usage

autotopcor(x, lags = 1, k1, type = c("series", "tdo"))

Arguments

Value

A numeric vector of ATCC values, one for each element of 'lags'.

References

Nie, Chun-Xiao. "Unveiling complex nonlinear dynamics in stock markets through topological data analysis." Physica A: Statistical Mechanics and its Applications 680 (2025): 131025. Nie, Chun-Xiao. "Persistence of return distribution sequence in financial markets." Communications in Nonlinear Science and Numerical Simulation 131 (2024): 107856.

See Also

['topcor()'] for the underlying topological correlation computation.

Examples

set.seed(123)
x <- rnorm(50)
atcc <- autotopcor(x, lags = 1:3, k1 = 2)

# Using a pre‑computed distance matrix (TDO)
D <- as.matrix(dist(x))
atcc_tdo <- autotopcor(D, lags = 1:3, k1 = 2, type = "tdo")

Significance Test for Auto Topological Correlation Coefficient

Description

Tests the significance of ATCC values at given lags using random shuffling. For time-series input ('type = "series"') the observations are permuted; for TDO input ('type = "tdo"') the time labels of the distance matrix are permuted via ['tdoshuffling()'].

Usage

autotopcortest(x, lags = 1, k1, nrand = 300, type = c("series", "tdo"))

Arguments

Value

A list with the following components:

References

Nie, Chun-Xiao. "Unveiling complex nonlinear dynamics in stock markets through topological data analysis." Physica A: Statistical Mechanics and its Applications 680 (2025): 131025. Nie, Chun-Xiao. "Persistence of return distribution sequence in financial markets." Communications in Nonlinear Science and Numerical Simulation 131 (2024): 107856.

See Also

['autotopcor()'], ['topcor()'], ['tdoshuffling()'].

Examples

set.seed(123)
x <- rnorm(50)
test_res <- autotopcortest(x, lags = 1, k1 = 2, nrand = 20,type="series")

indextest

Description

This dataset contains example data for demonstrating package functions.

Usage

indextest

Format

A data frame with 521 rows and 3 variables:

Time

Time

Price

Numeric,index price

Volume

Numeric,index price

Source

Simulated data for package examples.

Generate local random permutation surrogates for a time series

Description

This function randomly shuffles the observations within a specified window of a time series, leaving the rest unchanged. This is useful for creating surrogates that preserve local structure outside the window while destroying temporal order within it.

Usage

local_shuffle(s, w)

Arguments

Value

A numeric vector of the same length as s, with the values in the specified window randomly permuted.

Examples

s <- c(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
# Shuffle indices 3 to 7
s_shuffled <- local_shuffle(s, c(3, 7))
print(s_shuffled)

Significance test for TCC using shuffling (parallel version, with optional seed)

Description

Significance test for TCC using shuffling (parallel version, with optional seed)

Usage

paralleltopcortest(d1, d2, k, nrand, ncores = NULL, seed = NULL)

Arguments

Value

A list containing observed TCC, Z-score, random TCC values, and p-values.

Examples

x=rnorm(40,0,1)
y=x+rnorm(40,0,1)
result <- paralleltopcortest(as.matrix(dist(x)), as.matrix(dist(y)), c(1,39,1),20, ncores = 2)
# Run with seed for reproducibility
result_repro <- paralleltopcortest(as.matrix(dist(x)), as.matrix(dist(y)),
c(1,39,6), 20,ncores = 2, seed = 123)

Sliding window TCC significance test using local random permutation surrogates

Description

This function slides a window of fixed length over two time series, and for each window position it generates a distribution of TCC values under local random permutations (shuffling values within that window). The observed TCC (based on the original full series) is then compared to each window-specific distribution to compute a z-score.

Usage

sliding_window_tcc_test(s1, s2, l1, l2, k, nrand, ncores = NULL, seed = NULL)

Arguments

Value

A list with the following components:

Examples

s1 <- rnorm(40)
s2 <- rnorm(40)
result <- sliding_window_tcc_test(s1, s2, l1 = 10,
l2 = 5,k = c(1, 39, 1), nrand = 20, ncores = 2, seed = 123)

Calculate TCC after local random permutation of two time series within a window

Description

This function applies local shuffling to two time series within a specified window, computes Euclidean distance matrices for the shuffled series, and calculates the TCC between them using the tdotcc function.

Usage

tcc_local_shuffle(s1, s2, w, k)

Arguments

Value

The TCC value computed from the locally shuffled series.

Examples

s1 <- rnorm(100)
s2 <- rnorm(100)
tcc_val <- tcc_local_shuffle(s1, s2, w = c(30, 70), k = c(1, 99, 2))

Generate distribution of TCC values by repeatedly applying local shuffling (parallel)

Description

This function repeatedly applies local random permutation to two time series within a specified window, computes the TCC for each shuffled pair using tcc_local_shuffle, and returns the distribution of TCC values over many repetitions. Parallel computing is employed to accelerate the process.

Usage

tcc_local_shuffle_dist_parallel(
  s1,
  s2,
  w,
  k,
  nrand,
  ncores = NULL,
  seed = NULL
)

Arguments

Value

A numeric vector of length nrand containing the TCC values from each shuffling.

Examples

s1 <- rnorm(100)
s2 <- rnorm(100)
tcc_dist <- tcc_local_shuffle_dist_parallel(s1, s2,
w = c(30, 70), k = c(1, 99, 2), nrand = 20, ncores = 2)

Generate surrogates by shuffling (random permutation) of rows and columns.

Description

Generate surrogates by shuffling (random permutation) of rows and columns.

Usage

tdoshuffling(d)

Arguments

Value

The shuffled distance matrix (same dimensions, permuted rows and columns).

Examples

data("indextest")
r=diff(log(as.matrix(indextest[,c(2,3)])))
d_shuf <- tdoshuffling(as.matrix(dist(r[,1])))

Calculate Topological correlation Coefficient (TCC) between two TDOs

Description

Calculate Topological correlation Coefficient (TCC) between two TDOs

Usage

topcor(d1, d2, k)

Arguments

Value

TCC value (mean Jaccard similarity over the k range).

References

Nie, Chun-Xiao. "Nonlinear correlation analysis of time series based on complex network similarity." International Journal of Bifurcation and Chaos 30.15 (2020): 2050225. Nie, Chun-Xiao. "Topological similarity of time-dependent objects." Nonlinear Dynamics 111.1 (2023): 481-492.

Examples

x=rnorm(100,0,1)
y=x+rnorm(100,0,1)
tcc <- topcor(as.matrix(dist(x)), as.matrix(dist(y)), c(1,99,3))

Significance test for TCC using shuffling (serial version)

Description

Significance test for TCC using shuffling (serial version)

Usage

topcortest(d1, d2, k, nrand)

Arguments

Value

A list containing:

Examples

x=rnorm(40,0,1)
y=rnorm(40,0,1)
tcctest <- topcortest(as.matrix(dist(x)), as.matrix(dist(y)), c(1,39,2),20)