Metadata-Version: 2.1
Name: saturnscore
Version: 1.2.5
Summary: Saturn coefficient to assess the results of an UMAP dimensionality reduction
Author-Email: Davide Chicco <davidechicco@davidechicco.it>
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Project-URL: Homepage, https://github.com/davidechicco/SaturnCoefficient_Python_package
Project-URL: Issues, https://github.com/davidechicco/SaturnCoefficient_Python_package/issues
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# 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"](https://doi.org/10.7717/peerj-cs.3424), _PeerJ Computer Science_ 12:e3424, pages 1-34 (2026). [https://doi.org/10.7717/peerj-cs.3424](https://doi.org/10.7717/peerj-cs.3424)

[<img src="https://github.com/davidechicco/SaturnCoefficient_Python_package/raw/main/paper_screenshot_rounded.png" alt="Article on PeerJ Computer Science" title="Article on PeerJ Computer Science" width="600"/>](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](https://doi.org/10.32614/CRAN.package.SaturnCoefficient), 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](https://www.DavideChicco.it). Questions should be addressed to davidechicco(AT)davidechicco.it
