# Cyclic Wave Analysis

> Classical, wavelet-based, and circular feature extraction for density-based time-series clustering in R.

`cyclicwave` is a modular R package for feature extraction and density-based clustering of time-series data. It provides classical statistical features, discrete wavelet features, Hilbert-based phase representations, and circular statistical features.

The package applies the Hilbert transform to obtain the analytic signal and instantaneous phase of time-series data. The resulting phase values provide a circular representation that may help reveal periodic patterns, phase relationships, and circular behavior that may not be directly visible in the original signal. Circular statistics and circular distance measures can then be calculated from this phase representation.

The package includes DBSCAN and OPTICS for density-based clustering. These methods return cluster assignments and identify observations that are not assigned to dense regions as noise. Noise labels can be examined as part of the clustering results, but the package does not apply a separate anomaly detection algorithm.

The package also provides data preparation, cluster evaluation, visualization, and a comparison function that runs multiple feature extraction and clustering combinations.

## Installation

Install the package from a local source file:
  
  ```r
install.packages(
  "cyclicwave_0.1.0.tar.gz",
  repos = NULL,
  type = "source"
)
```

During package development, the package can be loaded directly from the project directory:
  
  ```r
devtools::load_all()
```

After installation, load the package with:
  
  ```r
library(cyclicwave)
```

## Quick Start

The following example applies DBSCAN to a simple two-dimensional dataset and evaluates the clustering result using the Davies-Bouldin Index.

```r
library(cyclicwave)

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),
  matrix(rnorm(60, mean = 10, sd = 0.5), ncol = 2)
)

result <- run_dbscan(
  X,
  eps = 1,
  min_pts = 5
)

result$n_clusters
result$n_noise
table(result$cluster)

dbi <- davies_bouldin(
  X,
  result$cluster
)

dbi

plot_clusters_pca(
  X,
  result$cluster
)
```

Lower Davies-Bouldin Index values generally indicate more compact and better-separated clusters.

## Authors

### Şule Şevval Karakaya

Department of Biomedical Engineering
Middle East Technical University
Ankara, Türkiye

Email: [sule.karakaya@metu.edu.tr](mailto:sule.karakaya@metu.edu.tr)

### Ahmet Bursalı

Department of Computer Science
Dokuz Eylül University
İzmir, Türkiye

Intelligent Application DC Department
Huawei Turkey R&D Center
İstanbul, Türkiye

Email: [ahmet.bursali@huawei.com](mailto:ahmet.bursali@huawei.com)

### Vilda Purutçuoğlu

Department of Biomedical Engineering
Middle East Technical University
Ankara, Türkiye

Department of Statistics
Middle East Technical University
Ankara, Türkiye

Email: [vpurutucu@metu.edu.tr](mailto:vpurutucu@metu.edu.tr)

## Dependencies

The package uses the following R packages:
  
  * `dbscan`
* `gsignal`
* `waveslim`
* `MASS`
* `e1071`
* `ggplot2`

The `FNN` package is optional and provides faster nearest-neighbor calculations for `plot_k_distance()`.

## License

This package is distributed under the MIT License. See the `LICENSE` file for details.
