sclValid is now available on CRAN
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 methodology implemented in this package is based on:
O. Visser and S. Datta, “Integrating Multiple Clustering Techniques and Performance Measures via Ranking for scRNA-Seq Data,” Statistics in Medicine 44, no. 28-30 (2025): e70331. https://doi.org/10.1002/sim.70331
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.
The development version can be installed from GitHub with:
install.packages("remotes")
remotes::install_github("owenvisser/sclValid")Then load the package:
library(sclValid)sclValid expects a numeric matrix with features in rows and cells in columns.
A SingleCellExperiment object can be created with:
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.
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 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().
For example, a simple custom K-means function can be defined as:
custom_kmeans <- function(data, k) {
stats::kmeans(
t(data),
centers = k
)$cluster
}The function can then be applied to the SingleCellExperiment object with:
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.
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)
)Clustering assignments are added as columns in:
SummarizedExperiment::colData(sce)Validation measures can be calculated with:
sce <- run_validation(
sce,
measures = c(
"AD",
"ADM",
"APN",
"ARI",
"BHI",
"BSI",
"CN",
"DI",
"IGP",
"SW"
)
)The available measures are:
- AD: Average Distance
- ADM: Average Distance Between Means
- APN: Average Proportion of Non-Overlap
- ARI: Adjusted Rand Index
- BHI: Biological Homogeneity Index
- BSI: Biological Stability Index
- CN: Connectivity
- DI: Dunn Index
- IGP: In-Group Proportion
- SW: Silhouette Width
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.
Raw validation results are stored in:
S4Vectors::metadata(sce)$validationValidation 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.
Scaled results are stored separately from the raw validation measures:
S4Vectors::metadata(sce)$validation_scaledThe 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.
The final ranking is stored in:
S4Vectors::metadata(sce)$rankinglibrary(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)$rankingThe 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.
If you use sclValid in your research, please cite:
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
A package-specific citation entry may also be added in a future release.
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.
See the individual function documentation for complete references.
License information is provided in the package DESCRIPTION file.
Owen Visser, Somnath Datta