66 feature visualize clusters method

README.md

@@ -714,12 +714,45 @@ from ds_utils.unsupervised import plot_loss_vs_cluster_number
 data = pd.read_csv(path / to / dataset)
 
 plot_loss_vs_cluster_number(data, 3, 20, euclidean)
-
 plt.show()
 ```
 
 ![Optimum Number of Clusters](https://raw.githubusercontent.com/idanmoradarthas/DataScienceUtils/master/tests/baseline_images/test_unsupervised/test_plot_loss_vs_cluster_number.png)
 
+### Plot Clusters
+
+This method creates a 2D scatter plot of clustering results. Each cluster is shown
+in a distinct color. For high-dimensional data (more than 2 features),
+dimensionality reduction is applied automatically. Supports PCA (default), t-SNE,
+and UMAP. Cluster centroids can optionally be displayed.
+
+Available in both matplotlib and Plotly backends.
+
+> **Note:** UMAP requires the optional ``umap`` extras: ``pip install data-science-utils[umap]``
+
+**Matplotlib:**
+```python
+from ds_utils.unsupervised import plot_clusters
+from sklearn.cluster import KMeans
+from matplotlib import pyplot as plt
+
+estimator = KMeans(n_clusters=8, random_state=42)
+estimator.fit(data)
+
+plot_clusters(data.values, estimator.labels_, estimator.cluster_centers_)
+plt.show()
+```
+
+**Plotly (interactive):**
+```python
+from ds_utils.unsupervised import plot_clusters_plotly
+
+fig = plot_clusters_plotly(data.values, estimator.labels_, estimator.cluster_centers_)
+fig.show()
+```
+
+![Plot Clusters](https://raw.githubusercontent.com/idanmoradarthas/DataScienceUtils/master/tests/baseline_images/test_unsupervised/test_plot_clusters_pca_with_centroids.png)
+
 ## XAI (Explainable AI)
 
 ## Plot Feature Importance
@@ -921,6 +954,12 @@ For NLP features (``SentenceEmbeddingTransformer``), install with the optional `
 pip install data-science-utils[nlp]
 ```
 
+For UMAP-based cluster visualization (``plot_clusters(..., reduction_method="umap")``), install with the optional ``umap`` extras:
+
+```bash
+pip install data-science-utils[umap]
+```
+
 
 ## Staying Updated
 

docs/source/installation.rst

@@ -34,6 +34,7 @@ installer |pypi_version|::
 To install with optional dependencies (like NLP features that require ``sentence-transformers``), use the extras syntax::
 
     pip install "data-science-utils[nlp]"
+    pip install "data-science-utils[umap]"
 
 To upgrade Data Science Utils to the latest version, use::
 
@@ -51,6 +52,7 @@ If you prefer to install from source, you can clone the repository and install |
 To include optional dependencies when installing from source, use::
 
     pip install ".[nlp]"
+    pip install ".[umap]"
 
 Alternatively, you can install directly from GitHub using pip::
 
@@ -73,7 +75,7 @@ Note on Dependencies
 Data Science Utils has several core dependencies, including numpy, pandas, matplotlib, plotly and scikit-learn. These will be
 automatically installed when you install the package using the methods above. 
 
-Optional features (such as ``SentenceEmbeddingTransformer``) require additional dependencies (``sentence-transformers``) which must be installed explicitly using the ``[nlp]`` extra or separately via conda.
+Optional features require extra dependencies: ``SentenceEmbeddingTransformer`` needs ``sentence-transformers`` (``[nlp]`` extra), and UMAP cluster visualization needs ``umap-learn`` (``[umap]`` extra).
 
 Staying Updated
 ===============

docs/source/metrics/regression.rst

@@ -4,7 +4,7 @@ Regression Metrics
 Regression Error Characteristic (REC) curves provide a powerful framework for evaluating and comparing regression models, generalizing the Receiver Operating Characteristic (ROC) curve used in classification.
 
 Background and Theory
--------------------
+---------------------
 
 The REC curve was introduced by **Bi & Bennett (2003)** in *"Regression error characteristic curves"* (Proceedings of the Twentieth International Conference on Machine Learning, pp. 43-50) as a method to visualize the cumulative distribution of errors in regression modeling. 
 

docs/source/unsupervised.rst

@@ -123,4 +123,51 @@ And the following image will be shown:
 
 .. image:: ../../tests/baseline_images/test_unsupervised/test_plot_loss_vs_cluster_number.png
     :align: center
-    :alt: Optimum Number of Clusters
+    :alt: Loss vs Number of Clusters
+
+*****************************
+Plot Clusters (Matplotlib)
+*****************************
+
+The plot_clusters function creates a 2D scatter plot of clustering results.
+For data with more than 2 features, dimensionality reduction is applied
+automatically. Supports PCA (default), t-SNE, and UMAP (requires the optional
+``umap`` extra: ``pip install data-science-utils[umap]``).
+
+.. autofunction:: ds_utils.unsupervised.plot_clusters
+
+Example::
+
+    from matplotlib import pyplot as plt
+    from sklearn.cluster import KMeans
+    from ds_utils.unsupervised import plot_clusters
+
+    estimator = KMeans(n_clusters=8, random_state=42)
+    estimator.fit(X)
+
+    plot_clusters(X, estimator.labels_, estimator.cluster_centers_)
+    plt.show()
+
+.. image:: ../../tests/baseline_images/test_unsupervised/test_plot_clusters_pca_with_centroids.png
+    :align: center
+    :alt: Plot Clusters with PCA
+
+*****************************
+Plot Clusters (Plotly)
+*****************************
+
+The plot_clusters_plotly function provides an interactive Plotly scatter plot
+with hover information showing coordinates and cluster labels.
+
+.. autofunction:: ds_utils.unsupervised.plot_clusters_plotly
+
+Example::
+
+    from ds_utils.unsupervised import plot_clusters_plotly
+
+    fig = plot_clusters_plotly(X, estimator.labels_, estimator.cluster_centers_)
+    fig.show()
+
+.. image:: ../../tests/baseline_images/test_unsupervised/test_plot_clusters_plotly_pca_with_centroids.png
+    :align: center
+    :alt: Plot Clusters Plotly

ds_utils/__init__.py

@@ -1,3 +1,3 @@
 """Data Science Utilities package."""
 
-__version__ = "1.10.0rc13"
+__version__ = "1.10.0rc14"