Fuzzy Spectral Clustering with Variable-Weighted Adjacency Matrices

Jesse S. Ghashti and John R. J. Thompson

2025-10-04

Introduction

The FuzzySpec package implements the FVIBES (Fuzzy Variable-Importance Based Eigenspace Separation) algorithm, a fuzzy spectral clustering procedure that incorporates variable-weighted distance metrics and adaptive adjacency matrix constructions. This package accompanies the paper Variable-Weighted Adjacency Constructions for Fuzzy Spectral Clustering by Ghashti, Hare, and Thompson (2025).

The key features of this package include:

Package Overview

There are three primary functions needed to conduct FVIBES clustering:

  1. Build an adjacency matrix from the data using make.adjacency()

  2. Perform fuzzy spectral clustering using fuzzy.spectral.clustering()

  3. Optionally, examine results results with 2D visualization function plot.fuzzy() or compare to true class labels using clustering.accuracy().

Installation

Install the latest release version of FuzzySpec from GitHub or with the following:

library(devtools)
install_github("ghashti-j/FuzzySpec")
library(FuzzySpec)

Sample Usage

The basic steps using built-in function are provided below.

  1. First we generate a synthetic dataset spirals, see the help file for gen.fuzzy() for more options and information.
set.seed(1)
data <- FuzzySpec::gen.fuzzy(n = 300, dataset = "spirals", noise = 0.15) # data generation
FuzzySpec::plot.fuzzy(data, plotFuzzy = TRUE, colorCluster = TRUE) # plot data generating process

  1. Build a variable-weighted locally-adaptive adjacency matrix, corresponding to the adjacency \(\mathbf{W}^{(\text{vwla-id})}\) in Ghashti et al. (2025):
W <- FuzzySpec::make.adjacency(
  data = data$X,
  method = "vw",           # variable-weighted distances
  isLocWeighted = TRUE,    # Locally-adaptive scaling
  scale = FALSE            # scaling not required for kernel methods
)
#> Multistart 1 of 3 |Multistart 1 of 3 |Multistart 1 of 3 |Multistart 1 of 3 /Multistart 1 of 3 -Multistart 1 of 3 |Multistart 1 of 3 |Multistart 2 of 3 |Multistart 2 of 3 |Multistart 2 of 3 /Multistart 2 of 3 -Multistart 2 of 3 |Multistart 2 of 3 |Multistart 2 of 3 /Multistart 3 of 3 |Multistart 3 of 3 |Multistart 3 of 3 /Multistart 3 of 3 -Multistart 3 of 3 |Multistart 3 of 3 |
  1. Perform fuzzy spectral clustering given the adjacency matrix \(\mathbf{W}\), number of clusters k = 3 and the commonly chosen fuzzy parameter m = 1.5. We display the first 5 rows of the membership matrix \(\mathbf{U}\):
res <- FuzzySpec::fuzzy.spectral.clustering(
  W = W, k = 3, m = 1.5, method = "CM"           
)
res$u[1:5,]
#>          Clus 1     Clus 2     Clus 3
#> Obj 1 0.9048457 0.05660900 0.03854527
#> Obj 2 0.9549308 0.02402001 0.02104920
#> Obj 3 0.9092418 0.05372531 0.03703293
#> Obj 4 0.9764813 0.01192352 0.01159519
#> Obj 5 0.9590105 0.02179147 0.01919800
  1. We can compare the hard clustering results to the true class labels:
acc <- FuzzySpec::clustering.accuracy(data$y, res$cluster)
cat("Clustering accuracy:", round(acc, 3), "\n")
#> Clustering accuracy: 0.99
  1. We can compare the membership matrix \(\mathbf{U}\) determined by FVIBES to the true probabilistic cluster memberships with function fari, which computes fuzzy generalizations of the Adjusted Rand Index (FARI) based on Frobenius inner products of membership matrices (Andrews, Brown and Hvingelby, 2022).
far <- FuzzySpec::fari(data$U, res$u)
cat("FARI:", round(far, 3), "\n")
#> FARI: 0.98
  1. Finally, we can visualize the clustering results with observations, where observations are assigned by hard cluster labels and sized by the membership matrix \(\mathbf{U}\):
resDF <- list(
  X = data$X, U = res$u, y = factor(res$cluster), k = 3
)
FuzzySpec::plot.fuzzy(resDF, plotFuzzy = TRUE, colorCluster = TRUE)

Adjacency Construction

See respective help files for each function when needed; here we provide a basic overview of function arguments for make.adjacency(). This function allows for flexible adjacency matrix constructions based on Ghashti et al. (2025). The parameters are as follows:

References