saturnscore 1.2.5

Saturn coefficient to assess the results of an UMAP dimensionality reduction

Saturn score

Article

More information about this package can be found in the following article:

Davide Chicco, Simone Melzi, Francesca Gasparini and Giuseppe Jurman, "The advantages of our proposed Saturn coefficient over continuity and trustworthiness for UMAP dimensionality reduction evaluation", PeerJ Computer Science 12:e3424, pages 1-34 (2026). https://doi.org/10.7717/peerj-cs.3424

Summary

A Python package that computes the Saturn coefficient of a matrix to assess the quality of its UMAP dimensionality reduction.

Please notice that I developed the Saturn coefficient package originally in R, which is programming language I know better and is also where I was able to make more tests. I then ported this software package from R to Python, and here you can find the outcome. If you find anything that should be improved, please let me know.

Installation and example execution

You can run the following Python code to test your package installation. It will first install the needed packages and then apply the Saturn coefficient calculation:

import subprocess
import sys

bash_command = sys.executable +" -m pip install --upgrade pip"
# Execute the bash command
print("bash_command:\n", bash_command)
result = subprocess.run(bash_command, shell=True, capture_output=True, text=True)

# List of libraries to check/install
libraries = ["numpy", "pandas", "scipy", "umap-learn", "scikit-learn", "saturnscore"]

for lib in libraries:
    try:
        __import__(lib)
        print(f"{lib} is already installed.")
    except ImportError:
        print(f"{lib} not found. Installing...")
        subprocess.check_call([sys.executable, "-m", "pip", "install", lib])

# Print the output and errors (if any)
print("output:\t", result.stdout)
error = result.stderr
if(error):
    print("errors:\t", error)

import numpy as np
import pandas as pd
import scipy
import umap.umap_ as umap
from saturnscore import Saturn_coefficient
from sklearn.preprocessing import StandardScaler

base = 120
height = 200
this_random_seed = 0
np.random.seed(this_random_seed)  # Set random seed for reproducibility
input_data = np.random.randn(base, height)  # Generate random matrix

these_n_neighbors = 20
this_min_dist = 0.01
these_n_components = 2
this_metric = 'euclidean'
this_random_state = 42
this_n_jobs = 1
this_n_epochs = 200

print("these_n_neighbors = ", these_n_neighbors, sep="")
print("this_min_dist = ", this_min_dist, sep="")
print("these_n_components = ", these_n_components, sep="")
print("this_metric = ", this_metric, sep="")

umap_verbose = False
fit = umap.UMAP(n_neighbors=these_n_neighbors,
min_dist=this_min_dist,
n_components=these_n_components,
metric=this_metric,
n_jobs=this_n_jobs,
random_state=this_random_state,
n_epochs = this_n_epochs,
verbose=umap_verbose)

umap_output_layout = fit.fit_transform(input_data)

result = Saturn_coefficient.SaturnCoefficient(input_data, umap_output_layout)
print(f"Saturn coefficient =  ", result, " in the [0,1] interval (the higher, the better)", sep="")

The final command should print something like Saturn coefficient = 0.1029461972317906 (this value might be slightly different because of the random component of UMAP).

Contact

The SaturnScore package was developed by Davide Chicco. Questions should be addressed to davidechicco(AT)davidechicco.it