| Title: | Cyclic Wave Analysis for Time-Series Clustering |
|---|---|
| Description: | A modular toolkit for feature extraction and density-based clustering of time-series data. It provides classical statistical, discrete wavelet, Hilbert-based phase, and circular statistical features. The Hilbert-based phase representation can support the analysis of periodic patterns, phase relationships, and circular behavior in time-series data. The package supports DBSCAN and OPTICS clustering, cluster evaluation, visualization, data preparation, and comparison of multiple feature extraction and clustering combinations. Methods are described in Karakaya and Purutcuoglu (2026) <doi:10.15672/hujms.1821412> and Karakaya et al. (2026) <doi:10.1007/978-3-032-17020-0_27>. |
| Authors: | Şule Şevval Karakaya [aut, cre], Ahmet Bursalı [aut], Vilda Purutçuoğlu [aut] |
| Maintainer: | Şule Şevval Karakaya <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.0 |
| Built: | 2026-07-03 15:13:38 UTC |
| Source: | https://github.com/cran/cyclicwave |
Calculates an observation-level circular distance measure using the shortest angular separation between pairs of angles.
a_star_statistic(theta)a_star_statistic(theta)
theta |
Numeric vector containing angles in radians. |
Maximum normalized angular distance value.
Calculates an observation-level circular distance measure based on pairwise cosine differences.
a_statistic(theta)a_statistic(theta)
theta |
Numeric vector containing angles in radians. |
Maximum normalized distance value.
Calculates the complex analytic signal of a numeric vector or matrix using the Hilbert transform.
analytic_signal(X, axis = c("time", "feature"))analytic_signal(X, axis = c("time", "feature"))
X |
Numeric vector, matrix, or data frame. |
axis |
Direction in which the Hilbert transform is applied. Available options are "time" and "feature". |
A complex matrix with the same dimensions as the input.
Matches each predicted cluster label to the true label with which it has the largest overlap.
best_map(true_labels, pred_labels)best_map(true_labels, pred_labels)
true_labels |
Vector containing the known class labels. |
pred_labels |
Vector containing the predicted cluster labels. |
A numeric vector containing the matched predicted labels.
Calculates an observation-level distance measure using chord lengths between angular values on the unit circle.
chord_length(theta)chord_length(theta)
theta |
Numeric vector containing angles in radians. |
Maximum normalized chord-length value.
Calculates the weighted or unweighted mean direction of angular values.
circ_mean(theta, weights = NULL)circ_mean(theta, weights = NULL)
theta |
Numeric vector containing angles in radians. |
weights |
Optional numeric vector containing observation weights. |
Mean direction in radians between -pi and pi.
Measures the concentration of angular values around their mean direction. Values close to 1 indicate strong concentration, while values close to 0 indicate greater angular dispersion.
circ_r(theta, weights = NULL)circ_r(theta, weights = NULL)
theta |
Numeric vector containing angles in radians. |
weights |
Optional numeric vector containing observation weights. |
Numeric value between 0 and 1.
Calculates circular standard deviation from the mean resultant length. Larger values indicate greater angular dispersion.
circ_std(theta, weights = NULL)circ_std(theta, weights = NULL)
theta |
Numeric vector containing angles in radians. |
weights |
Optional numeric vector containing observation weights. |
Non-negative numeric value.
Measures angular dispersion using the mean resultant length. Values close to 0 indicate low dispersion, while values close to 1 indicate high dispersion.
circ_var(theta, weights = NULL)circ_var(theta, weights = NULL)
theta |
Numeric vector containing angles in radians. |
weights |
Optional numeric vector containing observation weights. |
Numeric value between 0 and 1.
Calculates one or more circular statistics for the same angular vector.
circular_distance_measures( theta, weights = NULL, measures = c("mardia_kurtosis", "M_statistic", "a_statistic", "a_star_statistic", "chord_length") )circular_distance_measures( theta, weights = NULL, measures = c("mardia_kurtosis", "M_statistic", "a_statistic", "a_star_statistic", "chord_length") )
theta |
Numeric vector containing angles in radians. |
weights |
Optional numeric vector containing observation weights. Weights are required for Mardia kurtosis and the M statistic. |
measures |
Character vector containing the names of the measures to calculate. |
Named numeric vector containing the selected measure values.
Calculates clustering accuracy after matching predicted cluster labels to the known class labels.
cluster_accuracy(true_labels, pred_labels)cluster_accuracy(true_labels, pred_labels)
true_labels |
Vector containing the known class labels. |
pred_labels |
Vector containing the predicted cluster labels. |
A numeric accuracy value between 0 and 1.
Applies multiple feature extraction and clustering methods to the same dataset. Each feature and clustering combination is evaluated using the selected performance measures.
compare_methods( data, feature_methods, cluster_methods, metrics = c("dbi", "n_clusters", "n_noise"), true_labels = NULL, normalize = NULL, verbose = TRUE )compare_methods( data, feature_methods, cluster_methods, metrics = c("dbi", "n_clusters", "n_noise"), true_labels = NULL, normalize = NULL, verbose = TRUE )
data |
Numeric matrix or data frame containing the input data. |
feature_methods |
Named list of feature extraction functions. Each function must accept data as input and return a feature matrix. |
cluster_methods |
Named list of clustering method specifications. Each entry must contain a clustering function and may contain its parameter values. |
metrics |
Character vector containing the evaluation measures. Available options are "dbi", "accuracy", "n_clusters", and "n_noise". |
true_labels |
Optional vector containing the known class labels. It is required when accuracy is selected. |
normalize |
Optional normalization method passed to prepare_features. Available options are "zscore", "range", or NULL. |
verbose |
Logical value indicating whether progress information should be displayed. |
A data frame containing one row for each feature and clustering method combination and the selected evaluation results.
Calculates instantaneous phase from the Hilbert analytic signal.
compute_phase(X, axis = c("time", "feature"))compute_phase(X, axis = c("time", "feature"))
X |
Numeric vector, matrix, or data frame. |
axis |
Direction in which the Hilbert transform is applied. Available options are "time" and "feature". |
A numeric matrix with the same dimensions as the input. Phase values are returned in radians between -pi and pi.
Calculates the Davies-Bouldin Index for a clustering result. The index compares within-cluster spread with the distance between cluster centers. Lower values indicate more compact and separated clusters.
davies_bouldin(X, labels, noise_label = 0)davies_bouldin(X, labels, noise_label = 0)
X |
Numeric feature matrix. Rows represent observations and columns represent features. |
labels |
Integer vector containing the cluster label of each observation. |
noise_label |
Label used for noise observations. Default is 0. |
A numeric value containing the Davies-Bouldin Index. Returns NA when fewer than two clusters remain after removing noise.
Extracts row-based circular features from a phase matrix. Each row is treated as one observation and each column as one phase value.
extract_circular_features(phase)extract_circular_features(phase)
phase |
Numeric matrix containing phase values in radians. |
Numeric matrix containing mean phase, chord-based phase difference, and circular correlation distance for each row.
Finds the point with the largest perpendicular distance from the line connecting the first and last values of a sorted sequence.
find_elbow(values)find_elbow(values)
values |
Numeric vector sorted in ascending order. |
Integer index of the detected elbow point.
Calculates the difference between consecutive observations in each column. A row of zeros is added at the beginning so that the output has the same number of rows as the input.
first_difference(X)first_difference(X)
X |
Numeric vector, matrix, or data frame. |
A numeric matrix containing first differences.
Converts a wide matrix into a single value vector and creates a matching group label for each original column.
flatten_with_zones(X)flatten_with_zones(X)
X |
Numeric matrix. Rows represent observations and columns represent groups or zones. |
A list containing the flattened values and their corresponding group labels.
Divides numeric values into groups using selected quantile cut points and assigns an integer label to each value.
label_by_quantile(values, probs = c(1/3, 2/3))label_by_quantile(values, probs = c(1/3, 2/3))
values |
Numeric vector to be labelled. |
probs |
Numeric vector containing quantile cut points between 0 and 1. The default values create three groups. |
An integer vector containing one group label for each value.
Calculates a leave-one-out circular statistic that measures how strongly one angular observation affects the mean resultant length.
M_statistic(theta, weights)M_statistic(theta, weights)
theta |
Numeric vector containing angles in radians. |
weights |
Numeric vector containing observation weights. |
Maximum M statistic across all observations.
Calculates a weighted multivariate kurtosis measure after representing angular values as points on the unit circle.
mardia_kurtosis(theta, weights)mardia_kurtosis(theta, weights)
theta |
Numeric vector containing angles in radians. |
weights |
Numeric vector containing observation weights. |
Numeric kurtosis value.
Normalizes each feature column using z-score or range scaling.
normalize_features(X, method = c("zscore", "range"))normalize_features(X, method = c("zscore", "range"))
X |
Numeric matrix or data frame. Rows represent observations and columns represent features. |
method |
Normalization method. Available options are "zscore" and "range". |
Numeric matrix with the same dimensions as the input.
Projects a feature matrix onto its first two principal components and displays the clustering result in two dimensions.
plot_clusters_pca(X, labels, noise_label = 0)plot_clusters_pca(X, labels, noise_label = 0)
X |
Numeric feature matrix. Rows represent observations and columns represent features. |
labels |
Cluster label assigned to each observation. |
noise_label |
Label used for noise observations. Default is 0. |
A ggplot object containing the two-dimensional cluster graph.
Creates a sorted k-nearest-neighbor distance graph to support the selection of the epsilon parameter for density-based clustering.
plot_k_distance(X, k = 5, distance = c("euclidean", "manhattan"))plot_k_distance(X, k = 5, distance = c("euclidean", "manhattan"))
X |
Numeric feature matrix. Rows represent observations and columns represent features. |
k |
Number of nearest neighbors used in the distance calculation. |
distance |
Distance measure. Available options are "euclidean" and "manhattan". |
A ggplot object containing the sorted k-distance graph.
Creates a reachability graph from an OPTICS result. Lower values generally represent denser regions, while higher values may indicate sparse regions or transitions between clusters.
plot_reachability(optics_result, log_scale = FALSE, epsilon = NULL)plot_reachability(optics_result, log_scale = FALSE, epsilon = NULL)
optics_result |
Result returned by run_optics. |
log_scale |
Logical value indicating whether reachability values should be shown on a logarithmic scale. |
epsilon |
Optional numeric value displayed as a horizontal reference line. |
A ggplot object containing the reachability graph.
Electricity consumption and weather measurements recorded at 10-minute intervals in three zones of Tetouan, Morocco.
power_consumptionpower_consumption
A data frame with 13,906 rows and 9 variables:
Date and time of the observation.
Ambient temperature.
Relative humidity.
Wind speed.
General diffuse solar radiation.
Diffuse solar radiation.
Electricity consumption in Zone 1.
Electricity consumption in Zone 2.
Electricity consumption in Zone 3.
UCI Machine Learning Repository, Tetouan City Power Consumption dataset.
Converts input features to a matrix, replaces missing values, and optionally applies normalization before clustering.
prepare_features(X, normalize = NULL)prepare_features(X, normalize = NULL)
X |
Numeric matrix or data frame containing extracted features. |
normalize |
Optional normalization method. Available options are "zscore", "range", or NULL. |
A numeric matrix prepared for further analysis.
Calculates moving summary statistics for each column of a numeric signal. The window is centered on each observation and becomes shorter near the beginning and end of the signal.
rolling_stats(X, window_size = 10, stats = c("mean", "sd", "max", "min"))rolling_stats(X, window_size = 10, stats = c("mean", "sd", "max", "min"))
X |
Numeric vector, matrix, or data frame. Rows represent observations and columns represent signals. |
window_size |
Positive integer defining the moving window length. |
stats |
Character vector containing the statistics to calculate. Available options are "mean", "sd", "max", and "min". |
A named list containing one numeric matrix for each selected statistic.
Applies DBSCAN to a numeric feature matrix. The algorithm identifies dense groups of observations and labels observations outside these groups as noise.
run_dbscan(X, eps, min_pts)run_dbscan(X, eps, min_pts)
X |
Numeric matrix or data frame. Rows represent observations and columns represent features. |
eps |
Maximum distance used to define the neighbourhood of a point. |
min_pts |
Minimum number of points required to form a dense region. |
A list containing cluster labels, the number of clusters, the number of noise observations, the method name, and parameter values.
set.seed(1) X <- rbind( matrix(rnorm(60, mean = 0, sd = 0.5), ncol = 2), matrix(rnorm(60, mean = 5, sd = 0.5), ncol = 2) ) result <- run_dbscan(X, eps = 1, min_pts = 5) result$n_clusters result$n_noise table(result$cluster)set.seed(1) X <- rbind( matrix(rnorm(60, mean = 0, sd = 0.5), ncol = 2), matrix(rnorm(60, mean = 5, sd = 0.5), ncol = 2) ) result <- run_dbscan(X, eps = 1, min_pts = 5) result$n_clusters result$n_noise table(result$cluster)
Applies an OPTICS-based procedure to a numeric feature matrix. The function orders observations according to local density and calculates reachability values used to represent cluster structure.
run_optics(X, eps, min_pts, distance = c("euclidean", "manhattan"))run_optics(X, eps, min_pts, distance = c("euclidean", "manhattan"))
X |
Numeric matrix or data frame. Rows represent observations and columns represent features. |
eps |
Maximum distance used to find neighbouring observations. |
min_pts |
Minimum number of neighbouring points required to define a dense region. |
distance |
Distance measure. Available options are "euclidean" and "manhattan". |
A list containing cluster labels, the number of clusters, the number of noise observations, reachability values, observation order, the method name, and parameter values.
set.seed(1) X <- rbind( matrix(rnorm(60, mean = 0, sd = 0.5), ncol = 2), matrix(rnorm(60, mean = 5, sd = 0.5), ncol = 2) ) result <- run_optics( X, eps = 1.5, min_pts = 5, distance = "euclidean" ) result$n_clusters result$n_noise head(result$reachability)set.seed(1) X <- rbind( matrix(rnorm(60, mean = 0, sd = 0.5), ncol = 2), matrix(rnorm(60, mean = 5, sd = 0.5), ncol = 2) ) result <- run_optics( X, eps = 1.5, min_pts = 5, distance = "euclidean" ) result$n_clusters result$n_noise head(result$reachability)
Divides a numeric signal into consecutive non-overlapping windows. Values that do not complete a full window are omitted.
segment_signal(x, window_size)segment_signal(x, window_size)
x |
Numeric vector containing the signal. |
window_size |
Positive integer defining the number of values in each window. |
A list of numeric vectors with equal window lengths.
Extracts numeric columns from a data frame and returns them as a matrix.
select_numeric_columns(data)select_numeric_columns(data)
data |
Data frame containing numeric and non-numeric columns. |
A numeric matrix containing only the numeric columns.
Energy consumption and production-related measurements recorded at 15-minute intervals during 2018 at a steel production facility in South Korea.
steel_industrysteel_industry
A data frame with 35,040 rows and 11 variables:
Date and time of the observation.
Electricity consumption in kilowatt-hours.
Lagging reactive power.
Leading reactive power.
Carbon dioxide emissions.
Lagging current power factor.
Leading current power factor.
Number of seconds since midnight.
Weekday or weekend category.
Day of the week.
Electricity load category.
UCI Machine Learning Repository, Steel Industry Energy Consumption dataset.
Reduces the number of rows by keeping every selected row interval.
thin_data(data, step = 1)thin_data(data, step = 1)
data |
Data frame or matrix. |
step |
Positive integer indicating the interval between retained rows. A value of 1 keeps all rows. |
A data frame or matrix containing the selected rows.
Applies a multi-level discrete wavelet decomposition and reconstructs the signal using only the approximation information.
wavelet_approx(x, wavelet = "d4", n_levels = 2)wavelet_approx(x, wavelet = "d4", n_levels = 2)
x |
Numeric vector containing the signal. |
wavelet |
Wavelet filter name accepted by the waveslim package. |
n_levels |
Positive integer defining the number of decomposition levels. |
Numeric vector containing the reconstructed approximation signal.
Applies a single-level discrete wavelet transform to a numeric signal. The function returns approximation and detail coefficients.
wavelet_transform(x, wavelet = c("db1", "db4"))wavelet_transform(x, wavelet = c("db1", "db4"))
x |
Numeric vector containing the signal. |
wavelet |
Wavelet type. Available options are "db1" and "db4". |
A list containing the approximation coefficients in cA and the detail coefficients in cD.
Divides a numeric signal into consecutive non-overlapping windows and calculates selected summary statistics for each window.
window_moments( x, window_size = 4, stats = c("mean", "sd", "skewness", "kurtosis") )window_moments( x, window_size = 4, stats = c("mean", "sd", "skewness", "kurtosis") )
x |
Numeric vector containing the signal. |
window_size |
Positive integer defining the number of observations in each window. |
stats |
Character vector containing the statistics to calculate. Available options are "mean", "sd", "skewness", "kurtosis", "range", and "energy". |
A numeric matrix in which rows represent windows and columns represent the selected statistics.
Converts angular values to the standard interval from -pi to pi.
wrap_to_pi(x)wrap_to_pi(x)
x |
Numeric vector or matrix containing angles in radians. |
Values with the same dimensions as the input, wrapped to the interval from -pi inclusive to pi exclusive.