Title:	Statistical Evaluation of UMAP Dimensionality Reductions
Version:	1.4
Description:	A metric expressing the quality of a UMAP layout. This is a package that contains the Saturn_coefficient() function that reads an input matrix, its dimensionality reduction produced by UMAP, and evaluates the quality of this dimensionality reduction by producing a real value in the [0; 1] interval. We call this real value Saturn coefficient. A higher value means better dimensionality reduction; a lower value means worse dimensionality reduction. Reference: Davide Chicco et al. "The Saturn coefficient for evaluating the quality of UMAP dimensionality reduction results" (2025, in preparation).
License:	GPL-3
URL:	https://github.com/davidechicco/SaturnCoefficient_R_package
BugReports:	https://github.com/davidechicco/SaturnCoefficient_R_package/issues
Depends:	R (≥ 4.0.0)
Imports:	MatrixCorrelation, ProjectionBasedClustering, stats, umap
Suggests:	knitr, rmarkdown, testthat (≥ 3.0.0)
VignetteBuilder:	knitr
Config/testthat/edition:	3
Encoding:	UTF-8
RoxygenNote:	7.3.2
NeedsCompilation:	no
Packaged:	2025-02-14 14:40:35 UTC; davide
Author:	Davide Chicco [aut, cre]
Maintainer:	Davide Chicco <davidechicco@davidechicco.it>
Repository:	CRAN
Date/Publication:	2025-02-14 15:20:01 UTC

Function that calculates the Saturn coefficient to quantify the quality of a UMAP dimensionality reduction

Description

Function that calculates the Saturn coefficient to quantify the quality of a UMAP dimensionality reduction

Usage

Saturn_coefficient(original_matrix, umap_output_layout, VERBOSE)

Arguments

Value

a real value containing the Saturn coefficient

Examples

this_nrows <- 200
this_ncols <- 100
this_min <- 0
this_max <- 10000
noise_random_matrix <- matrix(runif(n = this_nrows * this_ncols,
     min = this_min, max = this_max), nrow = this_nrows)
input_matrix <- as.matrix(noise_random_matrix)
these_nearest_neighbors <- 15
this_min_dist <- 0.05

library("umap")
custom.settings <- umap::umap.defaults
custom.settings$"n_neighbors" <- these_nearest_neighbors
custom.settings$"min_dist" <- this_min_dist

x_umap <- umap::umap(input_matrix, config=custom.settings)

this_verbose <- FALSE
thisSaturn <- Saturn_coefficient(input_matrix, x_umap$"layout",  this_verbose)
cat("Saturn coefficient = ", thisSaturn, "\n", sep="")

Function that calculates the Saturn coefficient, trustworthiness score, and the continuity score of a UMAP dimensionality reduction

Description

Function that calculates the Saturn coefficient, trustworthiness score, and the continuity score of a UMAP dimensionality reduction

Usage

calculatesSaturnContinuityTrustworthiness(
  original_matrix,
  umap_output_layout,
  VERBOSE
)

Arguments

Value

a dataframe containing the Saturn coefficient, the trustworthiness score, and the continuity score

Examples

this_nrows <- 200
this_ncols <- 100
this_min <- 0
this_max <- 10000
noise_random_matrix <- matrix(runif(n = this_nrows * this_ncols,
     min = this_min, max = this_max), nrow = this_nrows)
input_matrix <- as.matrix(noise_random_matrix)
these_nearest_neighbors <- 15
this_min_dist <- 0.05

library("umap")
custom.settings <- umap::umap.defaults
custom.settings$"n_neighbors" <- these_nearest_neighbors
custom.settings$"min_dist" <- this_min_dist

x_umap <- umap::umap(input_matrix, config=custom.settings)

this_verbose <- FALSE
theseThreeMetrics <- calculatesSaturnContinuityTrustworthiness(input_matrix,
     x_umap$"layout",  this_verbose)
print(theseThreeMetrics)

Function that calculates the continuity score of a UMAP dimensionality reduction

Description

Function that calculates the continuity score of a UMAP dimensionality reduction

Usage

continuity_score(original_matrix, umap_output_layout, VERBOSE)

Arguments

Value

a real value containing the continuity score

Examples

this_nrows <- 200
this_ncols <- 100
this_min <- 0
this_max <- 10000
noise_random_matrix <- matrix(runif(n = this_nrows * this_ncols,
     min = this_min, max = this_max), nrow = this_nrows)
input_matrix <- as.matrix(noise_random_matrix)
these_nearest_neighbors <- 15
this_min_dist <- 0.05

library("umap")
custom.settings <- umap::umap.defaults
custom.settings$"n_neighbors" <- these_nearest_neighbors
custom.settings$"min_dist" <- this_min_dist

x_umap <- umap::umap(input_matrix, config=custom.settings)

this_verbose <- FALSE
thisCon <- continuity_score(input_matrix, x_umap$"layout",  this_verbose)
cat("continuity = ", thisCon, "\n", sep="")

Function that calculates the trustworthiness score of a UMAP dimensionality reduction

Description

Function that calculates the trustworthiness score of a UMAP dimensionality reduction

Usage

trustworthiness_score(original_matrix, umap_output_layout, VERBOSE)

Arguments

Value

a real value containing the trustworthiness score

Examples

this_nrows <- 200
this_ncols <- 100
this_min <- 0
this_max <- 10000
noise_random_matrix <- matrix(runif(n = this_nrows * this_ncols,
     min = this_min, max = this_max), nrow = this_nrows)
input_matrix <- as.matrix(noise_random_matrix)
these_nearest_neighbors <- 15
this_min_dist <- 0.05

library("umap")
custom.settings <- umap::umap.defaults
custom.settings$"n_neighbors" <- these_nearest_neighbors
custom.settings$"min_dist" <- this_min_dist

x_umap <- umap(input_matrix, config=custom.settings)

this_verbose <- FALSE
thisTW <- trustworthiness_score(input_matrix, x_umap$"layout",  this_verbose)
cat("trustworthiness = ", thisTW, "\n", sep="")