README

sclValid is an R package for clustering and validating single-cell RNA sequencing data. It provides a unified workflow for applying built-in or user-defined clustering methods, calculating internal, external, and stability-based validation measures, scaling validation results, and aggregating them into an overall ranking of clustering solutions.

sclValid is conceptually related to the clValid package. Both packages use clustering validation measures to assess and compare clustering solutions, but they differ in the type of perturbation used for stability assessment. In clValid, stability is evaluated by perturbing the features used to define the clustering. In sclValid, the samples being clustered are perturbed instead. For single-cell RNA sequencing data, this corresponds to removing cells and evaluating how stable the resulting clustering is relative to the clustering obtained from the full dataset.

The package is built around SingleCellExperiment objects. Expression data are stored in the "data" assay, clustering assignments are stored in colData, and validation and ranking results are stored in metadata.

Installation

install.packages("remotes")
remotes::install_github("owenvisser/sclValid")

library(sclValid)

Basic workflow

sce <- make_sce(
  example_data,
  example_labels
)

The package includes a small example dataset derived from the single-cell RNA-seq data of Biase et al. The example contains 1,000 sampled features and 49 cells.

Clustering

Several clustering procedures are available directly through sclValid. User-defined clustering functions can also be incorporated into the same validation workflow with run_custom_clustering().

Custom clustering functions

Custom clustering functions should take the expression matrix as input and return a vector of cluster assignments, with one assignment for each cell. Additional arguments can be passed through run_custom_clustering().

custom_kmeans <- function(data, k) {
  stats::kmeans(
    t(data),
    centers = k
  )$cluster
}

sce <- run_custom_clustering(
  sce,
  fun = custom_kmeans,
  name = "CustomKmeans_cs3",
  k = 3
)

The resulting clustering is stored in colData and can be used by the validation framework in the same way as clustering solutions produced by the built-in methods:

sce <- run_validation(
  sce,
  clusterings = "CustomKmeans_cs3"
)

This allows clustering procedures from other packages, or entirely user-defined methods, to be evaluated using the same validation and ranking framework provided by sclValid.

pcaReduce

sce <- run_pcareduce(
  sce,
  cluster_sizes = 2:4,
  method = "M"
)

sce <- run_pcareduce(
  sce,
  cluster_sizes = 2:4,
  method = "S"
)

RaceID

sce <- run_raceid(
  sce,
  cluster_sizes = 2:4
)

PCA- and t-SNE-based clustering

sce <- run_reduction_clustering(
  sce,
  reductions = c("PCA", "TSNE"),
  methods = c(
    "kmeans",
    "hierarchical",
    "louvain",
    "leiden"
  ),
  cluster_sizes = 2:4,
  knn = c(5, 10),
  resolution = c(0.5, 1)
)

SummarizedExperiment::colData(sce)

Validation

sce <- run_validation(
  sce,
  measures = c(
    "AD",
    "ADM",
    "APN",
    "ARI",
    "BHI",
    "BSI",
    "CN",
    "DI",
    "IGP",
    "SW"
  )
)

ARI, BHI, and BSI require known labels. AD, ADM, APN, and BSI use perturbed datasets and repeated reclustering to evaluate stability.

By default, stability-based validation displays a progress bar while suppressing detailed clustering output.

S4Vectors::metadata(sce)$validation

Scaling validation measures

Validation measures have different ranges and directions. They can be transformed to a common scale with:

sce <- scale_validation(sce)

After scaling, larger values consistently indicate better clustering performance.

S4Vectors::metadata(sce)$validation_scaled

Rank aggregation

The scaled validation measures can be combined into an overall ranking of clustering solutions:

sce <- run_rank_aggregation(sce)

Rank aggregation is performed in two stages. Clustering solutions are first compared within each cluster size, and the highest-ranked solution for each size is retained. These selected solutions are then aggregated to produce the final ranking.

S4Vectors::metadata(sce)$ranking

Complete example

library(sclValid)

sce <- make_sce(
  example_data,
  example_labels
)

sce <- run_pcareduce(
  sce,
  cluster_sizes = 2:4,
  method = "M"
)

sce <- run_pcareduce(
  sce,
  cluster_sizes = 2:4,
  method = "S"
)

sce <- run_raceid(
  sce,
  cluster_sizes = 2:4
)

sce <- run_reduction_clustering(
  sce,
  reductions = c("PCA", "TSNE"),
  methods = c(
    "kmeans",
    "hierarchical",
    "louvain",
    "leiden"
  ),
  cluster_sizes = 2:4,
  knn = c(5, 10),
  resolution = c(0.5, 1)
)

sce <- run_validation(sce)

sce <- scale_validation(sce)

sce <- run_rank_aggregation(sce)

S4Vectors::metadata(sce)$ranking

Methodology

The overall framework implemented in sclValid follows the methodology introduced by Visser and Datta (2025). Multiple clustering procedures are evaluated using a diverse set of validation measures representing different aspects of clustering performance. These measures are standardized to a common direction and then combined using weighted rank aggregation to identify clustering solutions that perform consistently across validation criteria.

Several stability-based validation measures in the package are adaptations of earlier clustering validation methods. Full methodological references are provided in the documentation for the corresponding functions.

Citation

Visser O, Datta S. Integrating Multiple Clustering Techniques and Performance Measures via Ranking for scRNA-Seq Data. Statistics in Medicine. 2025;44(28-30):e70331. https://doi.org/10.1002/sim.70331

References

The package includes implementations or adaptations of established clustering validation measures, including methods based on work by Dunn, Rousseeuw, Hubert and Arabie, Datta and Datta, Kapp and Tibshirani, and Pihur and colleagues.

The clustering procedures implemented or supported in the package include pcaReduce, RaceID, K-means, hierarchical clustering, Louvain clustering, and Leiden clustering.

sclValid