first commit

app.py

@@ -0,0 +1,323 @@
+
+"""
+Gradio Interface for Unsupervised Learning (Clustering, Dimensionality Reduction, Anomaly Detection)
+
+This script provides a single Gradio-based interface to run three unsupervised tasks:
+1. Clustering
+2. Dimensionality Reduction
+3. Anomaly (Outlier) Detection
+
+Each task is placed in its own Gradio Tab. The user can:
+- Choose a model from the relevant unsupervised directory (clustering/dimred/anomaly).
+- Specify dataset input (upload, local path, or Kaggle).
+- Select columns to drop or keep.
+- Execute the relevant training script (train_clustering_model.py, train_dimred_model.py, or train_anomaly_detection.py).
+- View logs and optional plots.
+
+Project Requirements:
+- Python 3.7+.
+- Gradio, scikit-learn, pandas, etc. in requirements.txt.
+- Properly structured project with:
+  - scripts/train_clustering_model.py
+  - scripts/train_dimred_model.py
+  - scripts/train_anomaly_detection.py
+  - models/unsupervised/<task>/<model>.py
+  - data/datasets/kaggle_data.py (optional for Kaggle usage).
+"""
+
+import gradio as gr
+import pandas as pd
+import os
+import subprocess
+import sys
+import glob
+import re
+
+#####################################
+# Helper Functions
+#####################################
+
+def get_model_modules(task_type):
+    """
+    Dynamically fetch model modules from the unsupervised subdirectories:
+    - clustering
+    - dimred
+    - anomaly
+    """
+    models_dir = os.path.join(project_root, 'models', 'unsupervised', task_type)
+    if not os.path.exists(models_dir):
+        print(f"Directory does not exist: {models_dir}")
+        return []
+    model_files = glob.glob(os.path.join(models_dir, '*.py'))
+    modules = [
+        os.path.splitext(os.path.basename(f))[0]
+        for f in model_files if not f.endswith('__init__.py')
+    ]
+    return modules
+
+def download_kaggle_data(json_path, dataset_name, is_competition):
+    from data.datasets.kaggle_data import get_kaggle_data
+    data_path = get_kaggle_data(json_path=json_path, data_name=dataset_name, is_competition=is_competition)
+    return data_path
+
+def run_subprocess(script_path, script_args):
+    """
+    Run a subprocess call to the given script with the specified arguments.
+    Returns (output_text, plot_image_path_or_None).
+    """
+    try:
+        result = subprocess.run(script_args, capture_output=True, text=True)
+        output = result.stdout
+        errors = result.stderr
+        if result.returncode != 0:
+            return f"Error during training:\n{errors}", None
+        else:
+            # Attempt to parse any 'Visualization saved to ...' line for an image path
+            output = re.sub(r"Figure\(\d+x\d+\)", "", output).strip()
+            image_path = None
+
+            # Look for "Plot saved to ..." or any ".png" reference
+            match_plot = re.search(r"Plot saved to (.+)", output)
+            if match_plot:
+                image_path = match_plot.group(1).strip()
+            else:
+                match_png = re.search(r"(\S+\.png)", output)
+                if match_png:
+                    image_path = match_png.group(1)
+
+            if image_path and os.path.exists(image_path):
+                return f"Completed successfully.\n\n{output}", image_path
+            else:
+                return f"Completed successfully.\n\n{output}", None
+    except Exception as e:
+        return f"An error occurred:\n{str(e)}", None
+
+def get_columns_from_data(data_option, data_file, data_path,
+                          kaggle_json_file, kaggle_competition_name, kaggle_data_name,
+                          is_competition):
+    """
+    Attempt to load the CSV and return columns.
+    """
+    final_path = None
+    if data_option == "Upload Data File":
+        if data_file is None:
+            return []
+        final_path = data_file
+    elif data_option == "Provide Data Path":
+        if os.path.exists(data_path):
+            final_path = data_path
+        else:
+            print("Provided path does not exist.")
+            return []
+    elif data_option == "Download from Kaggle":
+        if kaggle_json_file is None:
+            print("No kaggle.json uploaded.")
+            return []
+        import shutil
+        kaggle_config_dir = os.path.expanduser('~/.kaggle')
+        os.makedirs(kaggle_config_dir, exist_ok=True)
+        kaggle_json_path = os.path.join(kaggle_config_dir, 'kaggle.json')
+        shutil.copy(kaggle_json_file.name, kaggle_json_path)
+        os.chmod(kaggle_json_path, 0o600)
+
+        data_dir = download_kaggle_data(kaggle_json_path, kaggle_competition_name, is_competition)
+        if data_dir is None:
+            print("Failed to download from Kaggle.")
+            return []
+        final_path = os.path.join(data_dir, kaggle_data_name)
+        if not os.path.exists(final_path):
+            print(f"{kaggle_data_name} not found in Kaggle data.")
+            return []
+    else:
+        print("Invalid data option.")
+        return []
+
+    try:
+        df = pd.read_csv(final_path)
+        return df.columns.tolist()
+    except Exception as e:
+        print(f"Error reading {final_path}: {e}")
+        return []
+
+#####################################
+# Creating the Gradio Tab
+#####################################
+
+def create_task_tab(task_name, model_modules, script_path):
+    """
+    Creates a Gradio Tab for a specific unsupervised task (Clustering, DimRed, Anomaly).
+    - model_modules: list of model modules from get_model_modules(task_type)
+    - script_path: e.g. 'scripts/train_clustering_model.py'
+    """
+
+    with gr.Tab(task_name):
+        gr.Markdown(f"## {task_name} Task")
+
+        # Model selection
+        model_select = gr.Dropdown(choices=model_modules, label=f"{task_name} Model Module")
+
+        # Data input approach
+        data_option = gr.Radio(
+            choices=["Upload Data File", "Provide Data Path", "Download from Kaggle"],
+            label="Data Input Option",
+            value="Upload Data File"
+        )
+
+        with gr.Column(visible=True) as upload_data_col:
+            data_file = gr.File(label="Upload CSV Data File", type="filepath")
+
+        with gr.Column(visible=False) as path_data_col:
+            data_path_txt = gr.Textbox(label="Data File Path")
+
+        with gr.Column(visible=False) as kaggle_data_col:
+            kaggle_json = gr.File(label="Upload kaggle.json File", type="filepath")
+            kaggle_competition_name = gr.Textbox(value='', label="Kaggle Competition/Dataset Name")
+            kaggle_data_name = gr.Textbox(value='data.csv', label="Data File Name in Kaggle dataset")
+            kaggle_is_competition = gr.Checkbox(label="Is Kaggle Competition?", value=False)
+
+        # Toggle data input columns
+        def toggle_data_input(choice):
+            if choice == "Upload Data File":
+                return gr.update(visible=True), gr.update(visible=False), gr.update(visible=False)
+            elif choice == "Provide Data Path":
+                return gr.update(visible=False), gr.update(visible=True), gr.update(visible=False)
+            elif choice == "Download from Kaggle":
+                return gr.update(visible=False), gr.update(visible=False), gr.update(visible=True)
+            else:
+                return gr.update(visible=False), gr.update(visible=False), gr.update(visible=False)
+
+        data_option.change(
+            toggle_data_input,
+            inputs=[data_option],
+            outputs=[upload_data_col, path_data_col, kaggle_data_col]
+        )
+
+        # Update columns button
+        update_cols_btn = gr.Button("Update Columns")
+
+        # We remove "Columns in Data (for reference)" as requested
+        drop_cols_chk = gr.CheckboxGroup(choices=[], label="Columns to Drop")
+        select_cols_chk = gr.CheckboxGroup(choices=[], label="Columns to Keep (if empty, keep all)")
+
+        # Visualization param
+        visualize_chk = gr.Checkbox(label="Visualize 2D (using PCA if needed)", value=True)
+
+        # Model / results path with empty default, and label "(optional)"
+        model_path_txt = gr.Textbox(label="Model Save Path (optional)", value="")
+        results_path_txt = gr.Textbox(label="Results Save Path (optional)", value="")
+
+        # The Train button
+        train_btn = gr.Button(f"Train {task_name}")
+
+        # Logs/Output
+        output_box = gr.Textbox(label="Logs / Output")
+        image_display = gr.Image(label="Plot Output", visible=True)
+
+        # Function to update columns
+        def update_columns_fn(dataopt, f, p, kagfile, kcname, kdname, iscomp):
+            cols = get_columns_from_data(dataopt, f, p, kagfile, kcname, kdname, iscomp)
+            # Return updated choices for drop_cols_chk, select_cols_chk
+            if cols:
+                return gr.update(choices=cols), gr.update(choices=cols)
+            else:
+                return gr.update(choices=[]), gr.update(choices=[])
+
+        update_cols_btn.click(
+            fn=update_columns_fn,
+            inputs=[
+                data_option, data_file, data_path_txt,
+                kaggle_json, kaggle_competition_name, kaggle_data_name,
+                kaggle_is_competition
+            ],
+            outputs=[drop_cols_chk, select_cols_chk]
+        )
+
+        def run_task(model_mod, dataopt, f, p, kagfile, kcname, kdname, iscomp,
+                     drop_cols, select_cols, visualize, mpath, rpath):
+            # Build the command for the relevant script
+            script_cmd = [sys.executable, os.path.join(project_root, script_path)]
+            script_cmd.extend(["--model_module", model_mod])
+
+            # Minimal approach for data path logic
+            final_path = None
+            if dataopt == "Upload Data File" and f is not None:
+                final_path = f
+            elif dataopt == "Provide Data Path" and os.path.exists(p):
+                final_path = p
+            else:
+                # For Kaggle or other complexities, skipping for brevity.
+                # Could handle it similarly to get_columns_from_data approach
+                final_path = ""
+
+            if final_path:
+                script_cmd.extend(["--data_path", final_path])
+
+            # drop cols
+            if drop_cols and len(drop_cols) > 0:
+                script_cmd.extend(["--drop_columns", ",".join(drop_cols)])
+            # select cols
+            if select_cols and len(select_cols) > 0:
+                script_cmd.extend(["--select_columns", ",".join(select_cols)])
+            # visualize
+            if visualize:
+                script_cmd.append("--visualize")
+
+            # model_path
+            if mpath.strip():
+                script_cmd.extend(["--model_path", mpath.strip()])
+            # results_path
+            if rpath.strip():
+                script_cmd.extend(["--results_path", rpath.strip()])
+
+            print("Executing command:", " ".join(script_cmd))
+            out_text, plot_path = run_subprocess(script_path, script_cmd)
+            return out_text, plot_path
+
+        # The Train button is above logs, so let's define the click function
+        train_btn.click(
+            fn=run_task,
+            inputs=[
+                model_select, data_option, data_file, data_path_txt,
+                kaggle_json, kaggle_competition_name, kaggle_data_name, kaggle_is_competition,
+                drop_cols_chk, select_cols_chk, visualize_chk,
+                model_path_txt, results_path_txt
+            ],
+            outputs=[output_box, image_display]
+        )
+
+    return  # end create_task_tab
+
+
+#####################################
+# Build the Main Gradio App
+#####################################
+
+with gr.Blocks() as demo:
+    gr.Markdown("# Unsupervised Learning Gradio Interface")
+
+    # 1) Clustering Tab
+    clustering_modules = get_model_modules("clustering")
+    create_task_tab(
+        task_name="Clustering",
+        model_modules=clustering_modules,
+        script_path="scripts/train_clustering_model.py"
+    )
+
+    # 2) Dimensionality Reduction Tab
+    dimred_modules = get_model_modules("dimred")
+    create_task_tab(
+        task_name="Dimensionality Reduction",
+        model_modules=dimred_modules,
+        script_path="scripts/train_dimred_model.py"
+    )
+
+    # 3) Anomaly Detection Tab
+    anomaly_modules = get_model_modules("anomaly")
+    create_task_tab(
+        task_name="Anomaly Detection",
+        model_modules=anomaly_modules,
+        script_path="scripts/train_anomaly_detection.py"
+    )
+
+if __name__ == "__main__":
+    demo.launch()

data/README.md

@@ -0,0 +1 @@
+# data

data/datasets/README.md

@@ -0,0 +1,21 @@
+# Datasets Utilities
+
+This folder contains utility scripts for handling datasets, including downloading data from Kaggle.
+
+## 📄 Scripts
+
+### `kaggle_data.py`
+
+- **Description**: A Python script to download Kaggle datasets or competition data seamlessly, supporting Google Colab, local Linux/Mac, and Windows environments.
+- **Path**: [`data/datasets/kaggle_data.py`](kaggle_data.py)
+- **Key Function**: `get_kaggle_data(json_path, data_name, is_competition=False, output_dir='data/raw')`
+- **Example**:
+
+  ```python
+  from kaggle_data import get_kaggle_data
+
+  # Download a standard Kaggle dataset
+  dataset_path = get_kaggle_data("kaggle.json", "paultimothymooney/chest-xray-pneumonia")
+
+  # Download competition data
+  competition_path = get_kaggle_data("kaggle.json", "house-prices-advanced-regression-techniques", is_competition=True)

data/datasets/kaggle_data.py

@@ -0,0 +1,115 @@
+"""
+This module provides a utility function to download Kaggle datasets or competition data.
+
+The function automatically detects whether it is running in a Google Colab environment, a local Linux/Mac environment, or a Windows environment, and sets up the Kaggle API accordingly.
+
+Requirements:
+    - Kaggle API installed (`pip install kaggle`)
+    - Kaggle API key (`kaggle.json`) with appropriate permissions.
+
+Environment Detection:
+    - Google Colab: Uses `/root/.config/kaggle/kaggle.json`.
+    - Local Linux/Mac: Uses `~/.kaggle/kaggle.json`.
+    - Windows: Uses `C:\\Users\\<Username>\\.kaggle\\kaggle.json`.
+
+Functions:
+    get_kaggle_data(json_path: str, data_name: str, is_competition: bool = False, output_dir: str = "data/raw") -> str
+"""
+
+import os
+import zipfile
+import sys
+import shutil
+import platform
+
+def get_kaggle_data(json_path: str, data_name: str, is_competition: bool = False, output_dir: str = "data/raw") -> str:
+    """
+    Downloads a Kaggle dataset or competition data using the Kaggle API in Google Colab, local Linux/Mac, or Windows environment.
+
+    Parameters:
+        json_path (str): Path to your 'kaggle.json' file.
+        data_name (str): Kaggle dataset or competition name (e.g., 'paultimothymooney/chest-xray-pneumonia' or 'house-prices-advanced-regression-techniques').
+        is_competition (bool): Set to True if downloading competition data. Default is False (for datasets).
+        output_dir (str): Directory to save and extract the data. Default is 'data'.
+
+    Returns:
+        str: Path to the extracted dataset folder.
+
+    Raises:
+        OSError: If 'kaggle.json' is not found or cannot be copied.
+        Exception: If there is an error during download or extraction.
+
+    Example of Usage:
+        # For downloading a standard dataset
+        dataset_path = get_kaggle_data("kaggle.json", "paultimothymooney/chest-xray-pneumonia")
+        print(f"Dataset is available at: {dataset_path}")
+
+        # For downloading competition data
+        competition_path = get_kaggle_data("kaggle.json", "house-prices-advanced-regression-techniques", is_competition=True)
+        print(f"Competition data is available at: {competition_path}")
+    """
+    # Detect environment (Colab, local Linux/Mac, or Windows)
+    is_colab = "google.colab" in sys.modules
+    is_windows = platform.system() == "Windows"
+
+    # Step 1: Setup Kaggle API credentials
+    try:
+        if is_colab:
+            config_dir = "/root/.config/kaggle"
+            os.makedirs(config_dir, exist_ok=True)
+            print("Setting up Kaggle API credentials for Colab environment.")
+            shutil.copy(json_path, os.path.join(config_dir, "kaggle.json"))
+            os.chmod(os.path.join(config_dir, "kaggle.json"), 0o600)
+        else:
+            # For both local Linux/Mac and Windows, use the home directory
+            config_dir = os.path.join(os.path.expanduser("~"), ".kaggle")
+            os.makedirs(config_dir, exist_ok=True)
+            print("Setting up Kaggle API credentials for local environment.")
+            kaggle_json_dest = os.path.join(config_dir, "kaggle.json")
+            if not os.path.exists(kaggle_json_dest):
+                shutil.copy(json_path, kaggle_json_dest)
+                if not is_windows:
+                    os.chmod(kaggle_json_dest, 0o600)
+    except Exception as e:
+        raise OSError(f"Could not set up Kaggle API credentials: {e}")
+
+    # Step 2: Create output directory
+    dataset_dir = os.path.join(output_dir, data_name.split('/')[-1])
+    os.makedirs(dataset_dir, exist_ok=True)
+    original_dir = os.getcwd()
+    os.chdir(dataset_dir)
+
+    # Step 3: Download the dataset or competition data
+    try:
+        if is_competition:
+            print(f"Downloading competition data: {data_name}")
+            cmd = f"kaggle competitions download -c {data_name}"
+        else:
+            print(f"Downloading dataset: {data_name}")
+            cmd = f"kaggle datasets download -d {data_name}"
+        os.system(cmd)
+    except Exception as e:
+        print(f"Error during download: {e}")
+        os.chdir(original_dir)
+        return None
+
+    # Step 4: Unzip all downloaded files
+    zip_files = [f for f in os.listdir() if f.endswith(".zip")]
+    if not zip_files:
+        print("No zip files found. Please check the dataset or competition name.")
+        os.chdir(original_dir)
+        return None
+
+    for zip_file in zip_files:
+        try:
+            with zipfile.ZipFile(zip_file, "r") as zip_ref:
+                zip_ref.extractall()
+            print(f"Extracted: {zip_file}")
+            os.remove(zip_file)
+        except Exception as e:
+            print(f"Error extracting {zip_file}: {e}")
+
+    # Step 5: Navigate back to the original directory
+    os.chdir(original_dir)
+
+    return dataset_dir

data/raw/README.md

@@ -0,0 +1 @@
+# raw

models/unsupervised/anomaly/README.md

@@ -0,0 +1,34 @@
+# Anomaly (Outlier) Detection Models
+
+This directory hosts scripts defining **anomaly detection** estimators (e.g., Isolation Forest, One-Class SVM, etc.) for use with `train_anomaly_detection.py`. Each file specifies a scikit-learn–compatible outlier detector and, if applicable, a parameter grid.
+
+**Key Points**:
+- **Estimator**: Must allow `.fit(X)` and `.predict(X)` or similar. Typically returns +1 / −1 for inliers / outliers (we unify to 0 / 1).
+- **Parameter Grid**: You can define hyperparameters (like `n_estimators`, `contamination`) for potential searching. 
+- **Default Approach**: We do not rely on labeled anomalies (unsupervised). The script will produce a predictions CSV with 0 = normal, 1 = outlier.
+
+**Note**: The main script `train_anomaly_detection.py` handles data loading, label encoding, dropping/selecting columns, the `.fit(X)`, `.predict(X)` steps, saving the outlier predictions, and (optionally) a 2D plot with outliers in red.
+
+## Available Anomaly Detection Models
+
+- [Isolation Forest](isolation_forest.py)  
+- [One-Class SVM](one_class_svm.py)  
+- [Local Outlier Factor (LOF)](local_outlier_factor.py)  
+
+### Usage
+
+For example, to detect outliers with an Isolation Forest:
+
+```bash
+python scripts/train_anomaly_detection.py \
+  --model_module isolation_forest \
+  --data_path data/breast_cancer/data.csv \
+  --drop_columns "id,diagnosis" \
+  --visualize
+```
+
+This:
+1. Loads `isolation_forest.py`, sets up `IsolationForest(...)`.
+2. Fits the model to the data, saves it, then `predict(...)`.
+3. Saves a `predictions.csv` with `OutlierPrediction`.
+4. If `--visualize`, does a 2D PCA scatter, coloring outliers red.

models/unsupervised/anomaly/isolation_forest.py

@@ -0,0 +1,34 @@
+
+"""
+isolation_forest.py
+
+This module defines an Isolation Forest model for anomaly detection. 
+Isolation Forest is an efficient and effective algorithm for identifying 
+outliers in high-dimensional datasets.
+
+Key Features:
+- Utilizes a tree-based approach to isolate anomalies.
+- Efficient for both large datasets and high-dimensional spaces.
+- Automatically determines the expected proportion of anomalies.
+
+Parameters:
+    - n_estimators (int): Number of base estimators in the ensemble.
+        - Default: 100.
+    - contamination (str or float): Expected proportion of outliers in the data.
+        - Default: 'auto' (automatically inferred based on dataset size).
+    - max_samples (int or float): Number of samples to draw for training each estimator.
+        - Default: 'auto' (uses min(256, number of samples)).
+
+Default Configuration:
+    - n_estimators=100: Adequate for most datasets.
+    - contamination='auto': Automatically estimates the proportion of outliers.
+"""
+
+from sklearn.ensemble import IsolationForest
+
+# Define the Isolation Forest estimator
+estimator = IsolationForest(
+    n_estimators=100,       # Default number of trees
+    contamination='auto',   # Automatically estimates the contamination proportion
+    random_state=42         # Ensures reproducibility
+)

models/unsupervised/anomaly/local_outlier_factor.py

@@ -0,0 +1,39 @@
+
+"""
+local_outlier_factor.py
+
+This module defines a Local Outlier Factor (LOF) model for anomaly detection. 
+LOF identifies anomalies by comparing the local density of a sample to the density 
+of its neighbors. Samples with significantly lower density are flagged as outliers.
+
+Key Features:
+- Detects local anomalies in datasets with varying densities.
+- Effective for datasets where the notion of an outlier is context-dependent.
+- Non-parametric method that adapts to the data's structure.
+
+Parameters:
+    - n_neighbors (int): Number of neighbors used to calculate local density.
+        - Default: 20. Higher values smooth out anomalies but may miss local patterns.
+    - contamination (str or float): Proportion of outliers in the data.
+        - 'auto': Automatically estimates the proportion based on the dataset size.
+        - float: Manually set the expected proportion (e.g., 0.1 for 10%).
+    - novelty (bool): If True, allows the model to be applied to new unseen data.
+
+Limitations:
+- LOF directly computes predictions during `fit_predict()` and does not support `predict()` 
+  unless `novelty=True`.
+
+Default Configuration:
+    - n_neighbors=20: Uses 20 neighbors for density comparison.
+    - contamination='auto': Automatically estimates the proportion of outliers.
+    - novelty=True: Enables predictions on unseen data.
+"""
+
+from sklearn.neighbors import LocalOutlierFactor
+
+# Define the Local Outlier Factor estimator
+estimator = LocalOutlierFactor(
+    n_neighbors=20,  # Number of neighbors to calculate density
+    contamination='auto',  # Auto-detect the proportion of outliers
+    novelty=True  # Enables prediction on new data
+)

models/unsupervised/anomaly/one_class_svm.py

@@ -0,0 +1,35 @@
+
+"""
+one_class_svm.py
+
+This module defines a One-Class SVM model for anomaly detection. 
+One-Class SVM identifies a decision boundary that separates normal data points from potential outliers 
+in a high-dimensional feature space.
+
+Key Features:
+- Effective for detecting anomalies in high-dimensional datasets.
+- Flexible kernel options for nonlinear decision boundaries.
+- Suitable for datasets with a small proportion of outliers.
+
+Parameters:
+    - kernel (str): Specifies the kernel type used in the algorithm.
+        - Common options: 'linear', 'poly', 'rbf' (default), and 'sigmoid'.
+    - gamma (str or float): Kernel coefficient. Determines the influence of each sample.
+        - Default: 'scale' (1 / (n_features * X.var())).
+    - nu (float): Approximate fraction of outliers in the dataset.
+        - Must be in the range (0, 1]. Default: 0.05 (5% of data considered outliers).
+
+Default Configuration:
+    - kernel='rbf': Radial Basis Function for nonlinear separation.
+    - gamma='scale': Automatically adjusts kernel influence based on dataset features.
+    - nu=0.05: Assumes approximately 5% of data points are outliers.
+"""
+
+from sklearn.svm import OneClassSVM
+
+# Define the One-Class SVM estimator
+estimator = OneClassSVM(
+    kernel='rbf',  # Radial Basis Function kernel for nonlinear boundaries
+    gamma='scale',  # Adjusts kernel influence based on dataset variance
+    nu=0.05         # Assumes 5% of the data are outliers
+)

models/unsupervised/clustering/README.md

@@ -0,0 +1,37 @@
+# Clustering Models
+
+This directory contains Python scripts defining various **clustering** models and their associated hyperparameter grids. Each model file sets up a scikit-learn–compatible clustering estimator (e.g., `KMeans`, `DBSCAN`, `GaussianMixture`) and defines a param grid for the `train_clustering_model.py` script.
+
+**Key Points**:
+- **Estimator**: Usually supports `.fit(X)` for unsupervised training, and either `.labels_` or `.predict(X)` to retrieve cluster assignments.
+- **Parameter Grid (`param_grid`)**: Used for silhouette-based hyperparameter tuning in `train_clustering_model.py`.
+- **Default Scoring**: Often `'silhouette'`, but can be changed if you adapt your tuning logic.
+
+**Note**: Preprocessing (dropping columns, label encoding) and any hyperparameter loop is handled externally by the script/utility. These model definition files simply define:
+- An **estimator** (like `KMeans(n_clusters=3, random_state=42)`).
+- A **`param_grid`** for silhouette tuning (e.g., `{'model__n_clusters':[2,3,4]}`).
+- Optionally, a **`default_scoring`** set to `'silhouette'`.
+
+## Available Clustering Models
+
+- [KMeans](kmeans.py)  
+- [DBSCAN](dbscan.py)  
+- [Gaussian Mixture](gaussian_mixture.py)  
+- [Agglomerative Clustering (Hierarchical)](hierarchical_clustering.py)  )
+
+### Usage
+
+To train or tune any clustering model, specify the `--model_module` argument with the appropriate model name (e.g., `kmeans`) when running `train_clustering_model.py`, for example:
+
+```bash
+python scripts/train_clustering_model.py \
+  --model_module kmeans \
+  --data_path data/mall_customer/Mall_Customers.csv \
+  --tune \
+  --visualize
+```
+
+This will:
+1. Load the chosen model definition (`kmeans.py`).
+2. Perform optional silhouette-based hyperparameter tuning if `--tune` is used.
+3. Fit the final model, save it, and optionally generate a 2D scatter plot if requested.

models/unsupervised/clustering/dbscan.py

@@ -0,0 +1,29 @@
+
+"""
+dbscan.py
+
+This module defines a DBSCAN clustering model and a parameter grid for hyperparameter tuning.
+
+DBSCAN (Density-Based Spatial Clustering of Applications with Noise) is a density-based clustering algorithm.
+It groups points closely packed together and marks as outliers those points in low-density regions.
+
+Parameters:
+    - eps (float): The maximum distance between two samples for them to be considered as in the same neighborhood.
+    - min_samples (int): The number of samples (or total weight) in a neighborhood for a point to be considered a core point.
+"""
+
+from sklearn.cluster import DBSCAN
+
+# Define the DBSCAN estimator
+estimator = DBSCAN(eps=0.5, min_samples=5)
+
+# Define the hyperparameter grid for tuning
+param_grid = {
+    'model__eps': [0.2, 0.5, 1.0, 1.5, 2.0],  # Explore a wide range of neighborhood radii
+    'model__min_samples': [3, 5, 10, 20]  # Adjust density thresholds for core points
+}
+
+# Default scoring metric
+# Note: Silhouette score works best for convex clusters and may not always be ideal for DBSCAN.
+# For more complex shapes, consider custom evaluation metrics.
+default_scoring = 'silhouette'

models/unsupervised/clustering/gaussian_mixture.py

@@ -0,0 +1,32 @@
+
+"""
+gaussian_mixture.py
+
+This module defines a GaussianMixture model for clustering, along with a parameter grid for hyperparameter tuning.
+
+Gaussian Mixture Models (GMM) assume that data is generated from a mixture of several Gaussian distributions
+with unknown parameters. It's a probabilistic model and can handle clusters of varying sizes and shapes.
+
+Parameters:
+    - n_components (int): Number of mixture components (clusters).
+    - covariance_type (str): Determines the shape of each cluster.
+        - 'full': Each cluster has its own general covariance matrix.
+        - 'tied': All clusters share the same covariance matrix.
+        - 'diag': Each cluster has its own diagonal covariance matrix.
+        - 'spherical': Each cluster has its own single variance.
+"""
+
+from sklearn.mixture import GaussianMixture
+
+# Define the GaussianMixture estimator
+estimator = GaussianMixture(n_components=3, random_state=42)
+
+# Define the hyperparameter grid for tuning
+param_grid = {
+    'model__n_components': [2, 3, 4],  # Experiment with 2 to 4 clusters
+    'model__covariance_type': ['full', 'tied', 'diag', 'spherical']  # Different shapes for cluster covariance
+}
+
+# Default scoring metric
+# Note: Silhouette score works better for convex clusters. For GMMs with non-convex clusters, consider other metrics like BIC or AIC.
+default_scoring = 'silhouette'

models/unsupervised/clustering/hierarchical_clustering.py

@@ -0,0 +1,33 @@
+
+"""
+hierarchical_clustering.py
+
+This module defines an AgglomerativeClustering model for hierarchical clustering, 
+along with a parameter grid for hyperparameter tuning.
+
+Hierarchical clustering creates a tree-like structure (dendrogram) to represent the nested grouping of data points 
+and their similarity levels. Agglomerative clustering starts with each data point as its own cluster and iteratively merges them.
+
+Parameters:
+    - n_clusters (int): The number of clusters to form.
+    - linkage (str): Determines how distances between clusters are computed.
+        - 'ward': Minimizes the variance of clusters (requires Euclidean distance).
+        - 'complete': Maximum linkage, i.e., uses the farthest points between clusters.
+        - 'average': Average linkage, i.e., uses the mean distances between clusters.
+        - 'single': Minimum linkage, i.e., uses the closest points between clusters.
+"""
+
+from sklearn.cluster import AgglomerativeClustering
+
+# Define the AgglomerativeClustering estimator
+estimator = AgglomerativeClustering(n_clusters=3)
+
+# Define the hyperparameter grid for tuning
+param_grid = {
+    'model__n_clusters': [2, 3, 4],  # Experiment with 2 to 4 clusters
+    'model__linkage': ['ward', 'complete', 'average', 'single']  # Different linkage methods for clustering
+}
+
+# Default scoring metric
+# Note: Silhouette score works well for evaluating convex clusters formed by hierarchical clustering.
+default_scoring = 'silhouette'

models/unsupervised/clustering/kmeans.py

@@ -0,0 +1,32 @@
+
+"""
+kmeans.py
+
+This module defines a KMeans clustering model and a parameter grid for hyperparameter tuning.
+
+KMeans is a popular clustering algorithm that partitions data into k clusters. Each cluster is represented by the centroid of its members, and the algorithm iteratively refines the centroids to minimize the within-cluster variance.
+
+Parameters:
+    - n_clusters (int): Number of clusters to form.
+    - init (str): Initialization method for centroids. Common options:
+        - 'k-means++' (default): Optimized centroid initialization.
+        - 'random': Random initialization.
+    - n_init (int): Number of times the algorithm runs with different centroid seeds.
+    - random_state (int): Ensures reproducibility of results.
+"""
+
+from sklearn.cluster import KMeans
+
+# Define the KMeans estimator
+estimator = KMeans(n_clusters=3, random_state=42)
+
+# Define the hyperparameter grid for tuning
+param_grid = {
+    'model__n_clusters': [2, 3, 4, 5],  # Experiment with 2 to 5 clusters
+    'model__init': ['k-means++', 'random'],  # Compare optimized and random initialization
+    'model__n_init': [10, 20, 50]  # Test different numbers of initializations for stability
+}
+
+# Use silhouette score as the default scoring metric
+# Silhouette score evaluates how well clusters are separated and compact
+default_scoring = 'silhouette'

models/unsupervised/dimred/README.md

@@ -0,0 +1,34 @@
+# Dimensionality Reduction Models
+
+This directory contains Python scripts defining **dimensionality reduction** techniques (e.g., PCA, t-SNE, UMAP). Each model file sets up a scikit-learn–compatible estimator or follows a similar interface, making it easy to swap in `train_dimred_model.py`.
+
+**Key Points**:
+- **Estimator**: Typically supports `.fit_transform(X)` for dimension reduction.
+- **Default Settings**: e.g., PCA might default to `n_components=2`; t-SNE might set `n_components=2` and `perplexity=30`; UMAP might define `n_neighbors=15` or `n_components=2`.
+- **No Supervised Tuning**: Usually we pick hyperparameters based on interpretability or domain. A manual approach or specialized metric can be used if needed.
+
+**Note**: The `train_dimred_model.py` script handles dropping columns, label encoding, performing `.fit_transform(X)`, and optionally saving a 2D/3D scatter plot if `--visualize` is used.
+
+## Available Dimensionality Reduction Models
+
+- [PCA](pca.py)  
+- [t-SNE](tsne.py)  
+- [UMAP](umap.py)  
+
+### Usage
+
+To reduce data dimensions:
+
+```bash
+python scripts/train_dimred_model.py \
+  --model_module pca \
+  --data_path data/breast_cancer/data.csv \
+  --select_columns "radius_mean, texture_mean, area_mean, smoothness_mean" \
+  --visualize
+```
+
+This:
+1. Loads `pca.py`, which defines a `PCA(n_components=2)` estimator by default.
+2. Applies `.fit_transform(...)` to produce a 2D embedding.
+3. Saves the model (`dimred_model.pkl`) and the transformed data (`X_transformed.csv`).
+4. If `--visualize` is set and `n_components=2`, it scatter-plots the result.

models/unsupervised/dimred/pca.py

@@ -0,0 +1,28 @@
+
+"""
+pca.py
+
+This module defines a Principal Component Analysis (PCA) model for dimensionality reduction. 
+PCA is a widely used technique to reduce the dimensionality of large datasets by projecting the data 
+onto a lower-dimensional subspace while preserving as much variance as possible.
+
+Key Features:
+- Reduces computational complexity for high-dimensional data.
+- Helps in visualizing data in 2D or 3D space.
+- Useful as a preprocessing step for clustering or classification.
+
+Parameters:
+    - n_components (int, float, or None): Number of principal components to keep.
+        - int: Specifies the exact number of components.
+        - float: Keeps enough components to explain the specified fraction of variance (e.g., 0.95 for 95% variance).
+        - None: Keeps all components (default).
+
+Default:
+    - n_components=2: Projects the data onto 2 dimensions for visualization purposes.
+
+"""
+
+from sklearn.decomposition import PCA
+
+# Define the PCA estimator
+estimator = PCA(n_components=2)  # Default to 2D projection for visualization

models/unsupervised/dimred/tsne.py

@@ -0,0 +1,30 @@
+
+"""
+tsne.py
+
+This module defines a t-Distributed Stochastic Neighbor Embedding (t-SNE) model 
+for dimensionality reduction. t-SNE is primarily used for visualizing high-dimensional 
+data by projecting it into a lower-dimensional space (typically 2D or 3D).
+
+Key Features:
+- Nonlinear dimensionality reduction technique.
+- Preserves local relationships within the data.
+- Useful for exploring clustering structures in high-dimensional datasets.
+
+Parameters:
+    - n_components (int): Number of dimensions for projection (default: 2 for visualization).
+    - perplexity (float): Controls the balance between local and global data structure.
+        - Typical values range between 5 and 50.
+    - learning_rate (float, optional): Learning rate for optimization (default: 'auto').
+    - random_state (int, optional): Ensures reproducibility of the results.
+
+Default:
+    - n_components=2: Projects the data into a 2D space for visualization purposes.
+    - perplexity=30: A good starting point for most datasets.
+
+"""
+
+from sklearn.manifold import TSNE
+
+# Define the t-SNE estimator
+estimator = TSNE(n_components=2, perplexity=30)  # Default to 2D projection with a reasonable perplexity

models/unsupervised/dimred/umap.py

@@ -0,0 +1,35 @@
+
+"""
+umap.py
+
+This module defines a Uniform Manifold Approximation and Projection (UMAP) model 
+for dimensionality reduction. UMAP is a nonlinear dimensionality reduction technique 
+that is efficient for visualizing and analyzing high-dimensional data.
+
+Key Features:
+- Preserves both local and global data structures better than t-SNE in some cases.
+- Scales efficiently to larger datasets compared to t-SNE.
+- Suitable for exploratory data analysis and clustering.
+
+Parameters:
+    - n_components (int): Number of dimensions for projection (default: 2 for visualization).
+    - n_neighbors (int): Determines the size of the local neighborhood to consider for manifold approximation. 
+        - Typical values range between 5 and 50.
+    - min_dist (float): Minimum distance between points in the low-dimensional space.
+        - Smaller values maintain tighter clusters.
+    - metric (str): Distance metric for computing similarity (default: 'euclidean').
+
+Default:
+    - n_components=2: Projects the data into a 2D space for visualization purposes.
+    - n_neighbors=15: Balances local and global structure preservation.
+    - min_dist=0.1: Provides moderate clustering while preserving distances.
+
+Requirements:
+    - umap-learn library must be installed.
+"""
+
+# Import UMAP from the umap-learn library
+import umap.umap_ as umap
+
+# Define the UMAP estimator
+estimator = umap.UMAP(n_components=2, n_neighbors=15, min_dist=0.1)  # Default configuration for 2D projection

requirements.txt

@@ -0,0 +1,13 @@
+pandas==2.2.2
+numpy==1.26.4
+matplotlib==3.8.0
+seaborn==0.13.2
+kaggle==1.6.17
+scikit-learn==1.5.2
+catboost==1.2.7
+dask[dataframe]==2024.10.0
+xgboost==2.1.2
+lightgbm==4.5.0
+joblib==1.4.2
+gradio==5.7.1
+umap-learn==0.5.7

scripts/README.md

@@ -0,0 +1,230 @@
+# Scripts
+
+This directory contains executable scripts for training, testing, and other tasks related to model development and evaluation.
+
+## Contents
+
+Supervised Learning:
+- [train_regression_model.py](#train_regression_modelpy)
+- [train_classification_model.py](#train_classification_modelpy)
+
+Unsupervised Learning:
+- [train_clustering_model.py](#train_clustering_modelpy)
+- [train_dimred_model.py](#train_dimred_modelpy)
+- [train_anomaly_detection.py](#train_anomaly_detectionpy)
+
+---
+
+## `train_regression_model.py`
+
+A script for training supervised learning **regression** models using scikit-learn. It handles data loading, preprocessing, optional log transformation, hyperparameter tuning, model evaluation, and saving of models, metrics, and visualizations.
+
+### Features
+
+- Supports various regression models defined in `models/supervised/regression`.
+- Performs hyperparameter tuning using grid search cross-validation.
+- Saves trained models and evaluation metrics.
+- Generates visualizations if specified.
+
+### Usage
+
+```bash
+python train_regression_model.py --model_module MODEL_MODULE \
+    --data_path DATA_PATH/DATA_NAME.csv \
+    --target_variable TARGET_VARIABLE [OPTIONS]
+```
+
+**Required Arguments**:
+- `model_module`: Name of the regression model module to import (e.g., `linear_regression`).
+- `data_path`: Path to the dataset directory, including the data file name.
+- `target_variable`: Name of the target variable.
+
+**Optional Arguments**:
+- `test_size`: Proportion of the dataset to include in the test split (default: `0.2`).
+- `random_state`: Random seed for reproducibility (default: `42`).
+- `log_transform`: Apply log transformation to the target variable (regression only).
+- `cv_folds`: Number of cross-validation folds (default: `5`).
+- `scoring_metric`: Scoring metric for model evaluation.
+- `model_path`: Path to save the trained model.
+- `results_path`: Path to save results and metrics.
+- `visualize`: Generate and save visualizations (e.g., scatter or actual vs. predicted).
+- `drop_columns`: Comma-separated column names to drop from the dataset.
+
+### Usage Example
+
+```bash
+python train_regression_model.py --model_module linear_regression \
+    --data_path data/house_prices/train.csv \
+    --target_variable SalePrice --drop_columns Id \
+    --log_transform --visualize
+```
+
+---
+
+## `train_classification_model.py`
+
+A script for training supervised learning **classification** models using scikit-learn. It handles data loading, preprocessing, hyperparameter tuning (via grid search CV), model evaluation using classification metrics, and saving of models, metrics, and visualizations.
+
+### Features
+
+- Supports various classification models defined in `models/supervised/classification`.
+- Performs hyperparameter tuning using grid search cross-validation (via `classification_hyperparameter_tuning`).
+- Saves trained models and evaluation metrics (accuracy, precision, recall, F1).
+- If `visualize` is enabled, it generates a metrics bar chart and a confusion matrix plot.
+
+### Usage
+
+```bash
+python train_classification_model.py --model_module MODEL_MODULE \
+    --data_path DATA_PATH/DATA_NAME.csv \
+    --target_variable TARGET_VARIABLE [OPTIONS]
+```
+
+**Required Arguments**:
+- `model_module`: Name of the classification model module to import (e.g., `logistic_regression`).
+- `data_path`: Path to the dataset directory, including the data file name.
+- `target_variable`: Name of the target variable (categorical).
+
+**Optional Arguments**:
+- `test_size`: Proportion of the dataset to include in the test split (default: `0.2`).
+- `random_state`: Random seed for reproducibility (default: `42`).
+- `cv_folds`: Number of cross-validation folds (default: `5`).
+- `scoring_metric`: Scoring metric for model evaluation (e.g., `accuracy`, `f1`, `roc_auc`).
+- `model_path`: Path to save the trained model.
+- `results_path`: Path to save results and metrics.
+- `visualize`: Generate and save visualizations (metrics bar chart, confusion matrix).
+- `drop_columns`: Comma-separated column names to drop from the dataset.
+
+### Usage Example
+
+```bash
+python train_classification_model.py --model_module logistic_regression \
+    --data_path data/adult_income/train.csv \
+    --target_variable income_bracket \
+    --scoring_metric accuracy --visualize
+```
+
+---
+
+## `train_clustering_model.py`
+
+A script for training **clustering** models (K-Means, DBSCAN, Gaussian Mixture, etc.) in an unsupervised manner. It supports data loading, optional drop/select of columns, label encoding for non-numeric features, optional hyperparameter tuning (silhouette-based), saving the final model, and generating a 2D cluster plot if needed.
+
+### Features
+
+- Supports various clustering models defined in `models/unsupervised/clustering`.
+- Optional hyperparameter tuning (silhouette score) via `clustering_hyperparameter_tuning`.
+- Saves the trained clustering model and optional silhouette metrics.
+- Generates a 2D scatter plot if `visualize` is enabled (using PCA if needed).
+
+### Usage
+
+```bash
+python train_clustering_model.py --model_module MODEL_MODULE \
+    --data_path DATA_PATH/DATA_NAME.csv [OPTIONS]
+```
+
+**Key Arguments**:
+- `model_module`: Name of the clustering model module (e.g., `kmeans`, `dbscan`, `gaussian_mixture`).
+- `data_path`: Path to the CSV dataset.
+
+**Optional Arguments**:
+- `drop_columns`: Comma-separated column names to drop.
+- `select_columns`: Comma-separated column names to keep.
+- `tune`: If set, performs silhouette-based hyperparameter tuning.
+- `cv_folds`: Number of folds or times for silhouette-based repeated runs (basic approach).
+- `scoring_metric`: Typically `'silhouette'`.
+- `visualize`: If set, attempts a 2D scatter, using PCA if more than 2 features remain.
+- `model_path`: Path to save the trained model.
+- `results_path`: Path to save results (metrics, plots).
+
+### Usage Example
+
+```bash
+python train_clustering_model.py \
+  --model_module kmeans \
+  --data_path data/mall_customer/Mall_Customers.csv \
+  --drop_columns "Gender" \
+  --select_columns "Annual Income (k$),Spending Score (1-100)" \
+  --visualize
+```
+
+---
+
+## `train_dimred_model.py`
+
+A script for **dimensionality reduction** tasks (e.g., PCA, t-SNE, UMAP). It loads data, optionally drops or selects columns, label-encodes categorical features, fits the chosen dimensionality reduction model, saves the transformed data, and can visualize 2D/3D outputs.
+
+### Features
+
+- Supports various dimension reduction models in `models/unsupervised/dimred`.
+- Saves the fitted model and the transformed data (in CSV).
+- Optionally creates a 2D or 3D scatter plot if the output dimension is 2 or 3.
+
+### Usage
+
+```bash
+python train_dimred_model.py --model_module MODEL_MODULE \
+    --data_path DATA_PATH/DATA_NAME.csv [OPTIONS]
+```
+
+**Key Arguments**:
+- `model_module`: Name of the dimension reduction module (e.g., `pca`, `tsne`, `umap`).
+- `data_path`: Path to the CSV dataset.
+
+**Optional Arguments**:
+- `drop_columns`: Comma-separated column names to drop.
+- `select_columns`: Comma-separated column names to keep.
+- `visualize`: If set, plots the 2D or 3D embedding.
+- `model_path`: Path to save the trained model.
+- `results_path`: Path to save the transformed data and any plots.
+
+### Usage Example
+
+```bash
+python train_dimred_model.py \
+  --model_module pca \
+  --data_path data/breast_cancer/data.csv \
+  --drop_columns "id,diagnosis" \
+  --visualize
+```
+
+---
+
+## `train_anomaly_detection.py`
+
+A script for training **anomaly/outlier detection** models (Isolation Forest, One-Class SVM, etc.). It supports dropping/selecting columns, label-encoding, saving anomaly predictions (0 = normal, 1 = outlier), and optionally visualizing points in 2D with outliers colored differently.
+
+### Features
+
+- Supports various anomaly models in `models/unsupervised/anomaly`.
+- Saves the model and an outlier predictions CSV.
+- If `visualize` is enabled, performs PCA → 2D for plotting normal vs. outliers.
+
+### Usage
+
+```bash
+python train_anomaly_detection.py --model_module MODEL_MODULE \
+    --data_path DATA_PATH/DATA_NAME.csv [OPTIONS]
+```
+
+**Key Arguments**:
+- `model_module`: Name of the anomaly detection module (e.g., `isolation_forest`, `one_class_svm`, `local_outlier_factor`).
+- `data_path`: Path to the CSV dataset.
+
+**Optional Arguments**:
+- `drop_columns`: Comma-separated column names to drop.
+- `select_columns`: Comma-separated column names to keep.
+- `visualize`: If set, attempts a 2D scatter (via PCA) and colors outliers in red.
+- `model_path`: Path to save the anomaly model.
+- `results_path`: Path to save outlier predictions and plots.
+
+### Usage Example
+
+```bash
+python train_anomaly_detection.py \
+  --model_module isolation_forest \
+  --data_path data/breast_cancer/data.csv \
+  --drop_columns "id,diagnosis" \
+  --visualize
+```

scripts/train_anomaly_detection.py

@@ -0,0 +1,163 @@
+
+"""
+train_anomaly_detection.py
+
+Trains an anomaly detection model (Isolation Forest, One-Class SVM, etc.) on a dataset.
+Allows dropping or selecting columns, label-encoding for non-numeric data,
+saves predictions (0 = normal, 1 = outlier) and optionally visualizes in 2D.
+
+Usage Example:
+--------------
+python scripts/train_anomaly_detection.py \
+    --model_module isolation_forest \
+    --data_path data/raw/my_dataset.csv \
+    --drop_columns "unwanted_col" \
+    --select_columns "feat1,feat2,feat3" \
+    --visualize
+"""
+
+import os
+import sys
+import argparse
+import importlib
+import pandas as pd
+import numpy as np
+import joblib
+
+from sklearn.preprocessing import LabelEncoder
+import matplotlib.pyplot as plt
+from timeit import default_timer as timer
+
+def main(args):
+    # Change to the project root if needed
+    project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+    os.chdir(project_root)
+    sys.path.insert(0, project_root)
+
+    # Dynamically import the chosen anomaly model module
+    model_module_path = f"models.unsupervised.anomaly.{args.model_module}"
+    model_module = importlib.import_module(model_module_path)
+
+    # Retrieve the estimator from the model file
+    estimator = model_module.estimator
+
+    # Prepare results directory
+    if args.results_path is None:
+        args.results_path = os.path.join("results", f"{estimator.__class__.__name__}_Anomaly")
+    os.makedirs(args.results_path, exist_ok=True)
+
+    # Load data
+    df = pd.read_csv(args.data_path)
+    print(f"Data loaded from {args.data_path}, initial shape: {df.shape}")
+
+    # Drop empty columns
+    df = df.dropna(axis='columns', how='all')
+    print("After dropping empty columns:", df.shape)
+
+    # Drop specified columns if any
+    if args.drop_columns:
+        drop_cols = [c.strip() for c in args.drop_columns.split(',') if c.strip()]
+        df.drop(columns=drop_cols, inplace=True, errors='ignore')
+        print(f"Dropped columns: {drop_cols} | New shape: {df.shape}")
+
+    # Select specified columns if any
+    if args.select_columns:
+        keep_cols = [c.strip() for c in args.select_columns.split(',') if c.strip()]
+        df = df[keep_cols]
+        print(f"Selected columns: {keep_cols} | New shape: {df.shape}")
+
+    # Label-encode non-numeric columns
+    for col in df.columns:
+        if df[col].dtype == 'object':
+            le = LabelEncoder()
+            df[col] = le.fit_transform(df[col])
+
+    # Convert DataFrame to numpy array
+    X = df.values
+    print(f"Final data shape after dropping/selecting columns and encoding: {X.shape}")
+
+    # Fit the anomaly model
+    start_time = timer()
+    estimator.fit(X)
+    end_time = timer()
+    train_time = end_time - start_time
+    print(f"Anomaly detection training with {args.model_module} completed in {train_time:.2f} seconds.")
+
+    # Save the model
+    model_output_path = os.path.join(args.results_path, "anomaly_model.pkl")
+    os.makedirs(args.model_path, exist_ok=True)
+    joblib.dump(estimator, model_output_path)
+    print(f"Model saved to {model_output_path}")
+
+    # Predict outliers: Typically returns 1 for inliers, -1 for outliers (or vice versa)
+    # We'll unify them to 0 = normal, 1 = outlier
+    raw_preds = estimator.predict(X)
+    # Some anomaly detectors do the opposite: IsolationForest => +1 inlier, -1 outlier
+    # Convert to 0/1:
+    preds_binary = np.where(raw_preds == 1, 0, 1)
+
+    outlier_count = np.sum(preds_binary)
+    inlier_count = len(preds_binary) - outlier_count
+    print(f"Detected {outlier_count} outliers out of {len(X)} samples. ({inlier_count} normal)")
+
+    # Save predictions
+    pred_df = pd.DataFrame({
+        'OutlierPrediction': preds_binary
+    })
+    pred_path = os.path.join(args.results_path, "predictions.csv")
+    pred_df.to_csv(pred_path, index=False)
+    print(f"Predictions saved to {pred_path}")
+
+    # Visualization if 2D or 3D
+    if args.visualize:
+        print("Creating anomaly detection visualization...")
+        # We'll do PCA => 2D if dimension > 2
+        if X.shape[1] > 2:
+            from sklearn.decomposition import PCA
+            pca = PCA(n_components=2)
+            X_2d = pca.fit_transform(X)
+            x_label = "PC1"
+            y_label = "PC2"
+        elif X.shape[1] == 2:
+            X_2d = X
+            x_label = df.columns[0] if df.shape[1] == 2 else "Feature 1"
+            y_label = df.columns[1] if df.shape[1] == 2 else "Feature 2"
+        else:
+            # 1D or 0D => skip
+            print("Only 1 feature or none; can't create 2D scatter. Skipping.")
+            return
+
+        # Plot
+        plt.figure(figsize=(6,5))
+        # color outliers differently
+        colors = np.where(preds_binary == 1, 'r', 'b')
+        plt.scatter(X_2d[:,0], X_2d[:,1], c=colors, s=30, alpha=0.7)
+        plt.title(f"{estimator.__class__.__name__} Anomaly Detection")
+        plt.xlabel(x_label)
+        plt.ylabel(y_label)
+
+        # Save
+        plot_path = os.path.join(args.results_path, "anomaly_plot.png")
+        plt.savefig(plot_path)
+        plt.show()
+        print(f"Anomaly plot saved to {plot_path}")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Train an anomaly detection model.")
+    parser.add_argument('--model_module', type=str, required=True,
+                        help='Name of the anomaly detection model (e.g. isolation_forest, one_class_svm).')
+    parser.add_argument('--data_path', type=str, required=True,
+                        help='Path to the CSV dataset file.')
+    parser.add_argument('--model_path', type=str, default='saved_models/Anomaly',
+                        help='Path to save the trained model.')
+    parser.add_argument('--results_path', type=str, default=None,
+                        help='Directory to save results (predictions, plots).')
+    parser.add_argument('--drop_columns', type=str, default='',
+                        help='Comma-separated column names to drop.')
+    parser.add_argument('--select_columns', type=str, default='',
+                        help='Comma-separated column names to keep (ignore the rest).')
+    parser.add_argument('--visualize', action='store_true',
+                        help='If set, reduce to 2D (via PCA if needed) and color outliers vs. normal points.')
+    args = parser.parse_args()
+    main(args)

scripts/train_clustering_model.py

@@ -0,0 +1,183 @@
+
+"""
+train_clustering_model.py
+
+A script to train clustering models (K-Means, DBSCAN, Gaussian Mixture, etc.).
+It can optionally perform hyperparameter tuning using silhouette score,
+trains the model, saves it, and visualizes clusters if requested.
+"""
+
+import os
+import sys
+import argparse
+import importlib
+import pandas as pd
+import numpy as np
+import joblib
+
+from sklearn import datasets
+from sklearn.metrics import silhouette_score
+from sklearn.preprocessing import LabelEncoder
+import matplotlib.pyplot as plt
+import seaborn as sns
+from timeit import default_timer as timer
+
+def main(args):
+    # Change to the project root if needed
+    project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+    os.chdir(project_root)
+    sys.path.insert(0, project_root)
+
+    # Optional: import the unsupervised hyperparameter tuning function
+    from utils.unsupervised_hyperparameter_tuning import clustering_hyperparameter_tuning
+
+    # Dynamically import the chosen clustering model module
+    model_module_path = f"models.unsupervised.clustering.{args.model_module}"
+    model_module = importlib.import_module(model_module_path)
+
+    # Retrieve the estimator and param grid from the model file
+    estimator = model_module.estimator
+    param_grid = getattr(model_module, 'param_grid', {})
+    default_scoring = getattr(model_module, 'default_scoring', 'silhouette')  # fallback
+
+    # Prepare results directory
+    if args.results_path is None:
+        # e.g., 'results/KMeans_Clustering'
+        args.results_path = os.path.join('results', f"{estimator.__class__.__name__}_Clustering")
+    os.makedirs(args.results_path, exist_ok=True)
+
+    # Load data from CSV
+    df = pd.read_csv(args.data_path)
+    print(f"Data loaded from {args.data_path}, initial shape: {df.shape}")
+
+    # Drop empty columns
+    df = df.dropna(axis='columns', how='all')
+    print("After dropping empty columns:", df.shape)
+
+    # Drop specified columns if any
+    if args.drop_columns:
+        drop_cols = [col.strip() for col in args.drop_columns.split(',') if col.strip()]
+        df = df.drop(columns=drop_cols, errors='ignore')
+        print(f"Dropped columns: {drop_cols} | New shape: {df.shape}")
+
+    # Select specified columns if any
+    if args.select_columns:
+        keep_cols = [col.strip() for col in args.select_columns.split(',') if col.strip()]
+        # Keep only these columns (intersection with what's in df)
+        df = df[keep_cols]
+        print(f"Selected columns: {keep_cols} | New shape: {df.shape}")
+
+    # For each non-numeric column, apply label encoding
+    for col in df.columns:
+        if df[col].dtype == 'object':
+            le = LabelEncoder()
+            df[col] = le.fit_transform(df[col])
+
+    # Convert DataFrame to NumPy array for clustering
+    X = df.values
+    print(f"Final shape after dropping/selecting columns and encoding: {X.shape}")
+
+    # If user wants hyperparam tuning
+    if args.tune:
+        print("Performing hyperparameter tuning...")
+        best_model, best_params = clustering_hyperparameter_tuning(
+            X, estimator, param_grid, scoring=default_scoring, cv=args.cv_folds
+        )
+        estimator = best_model  # the fitted best model
+        print("Best Params:", best_params)
+    else:
+        # Just fit the model directly
+        print("No hyperparameter tuning; fitting model with default parameters...")
+        start_time = timer()
+        estimator.fit(X)
+        end_time = timer()
+        print(f"Training time (no tuning): {end_time - start_time:.2f}s")
+
+    # Ensure the model is fitted at this point
+    model_output_path = os.path.join(args.results_path, "best_model.pkl")
+    os.makedirs(args.model_path, exist_ok=True)  # ensure directory exists
+    joblib.dump(estimator, model_output_path)
+    print(f"Model saved to {model_output_path}")
+
+    # Evaluate using silhouette if possible
+    # Some clusterers use .labels_, others require .predict(X)
+    if hasattr(estimator, 'labels_'):
+        labels = estimator.labels_
+    else:
+        labels = estimator.predict(X)  # e.g. KMeans, GaussianMixture
+
+    unique_labels = set(labels)
+    if len(unique_labels) > 1:
+        sil = silhouette_score(X, labels)
+        print(f"Silhouette Score: {sil:.4f}")
+        pd.DataFrame({"Silhouette": [sil]}).to_csv(
+            os.path.join(args.results_path, "metrics.csv"), index=False
+        )
+    else:
+        print("Only one cluster found; silhouette score not meaningful.")
+
+    # Visualization
+    if args.visualize:
+        print("Creating cluster visualization...")
+
+        # If X has more than 2 dims, do PCA => 2D
+        if X.shape[1] > 2:
+            from sklearn.decomposition import PCA
+            pca = PCA(n_components=2)
+            X_2d = pca.fit_transform(X)
+            var_ratio = pca.explained_variance_ratio_
+            pc1_var = var_ratio[0] * 100
+            pc2_var = var_ratio[1] * 100
+            x_label = f"PC1 ({pc1_var:.2f}% var)"
+            y_label = f"PC2 ({pc2_var:.2f}% var)"
+        elif X.shape[1] == 2:
+            # If we know 'df' and shape matches, label with col names
+            if df.shape[1] == 2:
+                x_label = df.columns[0]
+                y_label = df.columns[1]
+            else:
+                x_label = "Feature 1"
+                y_label = "Feature 2"
+            X_2d = X
+        else:
+            # 1D or 0D => skip
+            if X.shape[1] == 1:
+                print("Only 1 feature available; cannot create a 2D scatter plot.")
+            else:
+                print("No features available for plotting.")
+            return
+
+        plt.figure(figsize=(6, 5))
+        plt.scatter(X_2d[:, 0], X_2d[:, 1], c=labels, cmap='viridis', s=30)
+        plt.title(f"{estimator.__class__.__name__} Clusters")
+        plt.xlabel(x_label)
+        plt.ylabel(y_label)
+
+        # Save the figure
+        plot_path = os.path.join(args.results_path, "clusters.png")
+        plt.savefig(plot_path)
+        plt.show()
+        print(f"Cluster plot saved to {plot_path}")
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Train a clustering model.")
+    parser.add_argument('--model_module', type=str, required=True,
+                        help='Name of the clustering model module (e.g. kmeans, dbscan, etc.).')
+    parser.add_argument('--data_path', type=str, required=True,
+                        help='Path to the CSV dataset.')
+    parser.add_argument('--model_path', type=str, default='saved_models/Clustering',
+                        help='Path to save the trained model.')
+    parser.add_argument('--results_path', type=str, default=None,
+                        help='Directory to save results (metrics, plots).')
+    parser.add_argument('--cv_folds', type=int, default=5,
+                        help='Number of folds for hyperparam tuning.')
+    parser.add_argument('--tune', action='store_true',
+                        help='Perform hyperparameter tuning with silhouette score.')
+    parser.add_argument('--visualize', action='store_true',
+                        help='Generate a 2D visualization of the clusters.')
+    parser.add_argument('--drop_columns', type=str, default='',
+                        help='Comma-separated column names to drop from the dataset.')
+    parser.add_argument('--select_columns', type=str, default='',
+                        help='Comma-separated column names to keep (ignore all others).')
+    args = parser.parse_args()
+    main(args)

scripts/train_dimred_model.py

@@ -0,0 +1,150 @@
+
+"""
+train_dimred_model.py
+
+Trains a dimensionality reduction model (e.g., PCA, t-SNE, UMAP) on a dataset.
+It can drop or select specific columns, perform label encoding on any non-numeric columns,
+and optionally visualize the reduced data (2D or 3D).
+
+Example Usage:
+--------------
+python scripts/train_dimred_model.py \
+    --model_module pca \
+    --data_path data/raw/breast-cancer-wisconsin-data/data.csv \
+    --drop_columns "id" \
+    --select_columns "radius_mean, texture_mean, perimeter_mean, area_mean" \
+    --visualize
+"""
+
+import os
+import sys
+import argparse
+import importlib
+import pandas as pd
+import numpy as np
+import joblib
+
+from sklearn.impute import SimpleImputer
+from sklearn.preprocessing import LabelEncoder
+import matplotlib.pyplot as plt
+
+def main(args):
+    # Move to project root if needed
+    project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+    os.chdir(project_root)
+    sys.path.insert(0, project_root)
+
+    # Dynamically import the chosen model module (pca.py, tsne.py, umap.py, etc.)
+    model_module_path = f"models.unsupervised.dimred.{args.model_module}"
+    model_module = importlib.import_module(model_module_path)
+
+    # Retrieve the estimator from the model file
+    estimator = model_module.estimator
+    default_n_components = getattr(model_module, 'default_n_components', 2)  # fallback
+
+    # Prepare results directory
+    if args.results_path is None:
+        # e.g., 'results/PCA_DimRed'
+        args.results_path = os.path.join('results', f"{estimator.__class__.__name__}_DimRed")
+    os.makedirs(args.results_path, exist_ok=True)
+
+    # Load data from CSV
+    df = pd.read_csv(args.data_path)
+    print(f"Data loaded from {args.data_path}, initial shape: {df.shape}")
+
+    # Drop empty columns
+    df = df.dropna(axis='columns', how='all')
+    print("After dropping empty columns:", df.shape)
+
+    # Drop specified columns if any
+    if args.drop_columns:
+        drop_cols = [col.strip() for col in args.drop_columns.split(',') if col.strip()]
+        df = df.drop(columns=drop_cols, errors='ignore')
+        print(f"Dropped columns: {drop_cols} | New shape: {df.shape}")
+    
+    # Select specified columns if any
+    if args.select_columns:
+        keep_cols = [col.strip() for col in args.select_columns.split(',') if col.strip()]
+        df = df[keep_cols]
+        print(f"Selected columns: {keep_cols} | New shape: {df.shape}")
+
+    # Label-encode non-numeric columns
+    for col in df.columns:
+        if df[col].dtype == 'object':
+            le = LabelEncoder()
+            df[col] = le.fit_transform(df[col])
+
+    # Impute
+    imputer = SimpleImputer(strategy='mean')  # or 'median'
+    df_array = imputer.fit_transform(df)
+    df_imputed = pd.DataFrame(df_array, columns=df.columns)
+    print("After label-encoding and imputation:", df_imputed.shape)
+    
+    # Convert DataFrame to numpy array
+    X = df_imputed.values
+    print(f"Final data shape after dropping/selecting columns and encoding: {X.shape}")
+
+    # Fit-transform the data (typical for dimensionality reduction)
+    X_transformed = estimator.fit_transform(X)
+    print(f"Dimensionality reduction done using {args.model_module}. Output shape: {X_transformed.shape}")
+
+    # Save the model
+    model_output_path = os.path.join(args.results_path, "dimred_model.pkl")
+    os.makedirs(args.model_path, exist_ok=True)  # ensure directory
+    joblib.dump(estimator, model_output_path)
+    print(f"Model saved to {model_output_path}")
+
+    # Save the transformed data
+    transformed_path = os.path.join(args.results_path, "X_transformed.csv")
+    pd.DataFrame(X_transformed).to_csv(transformed_path, index=False)
+    print(f"Transformed data saved to {transformed_path}")
+
+    # Visualization (only if 2D or 3D)
+    if args.visualize:
+        n_dims = X_transformed.shape[1]
+        if n_dims == 2:
+            plt.figure(figsize=(6,5))
+            plt.scatter(X_transformed[:,0], X_transformed[:,1], s=30, alpha=0.7, c='blue')
+            plt.title(f"{estimator.__class__.__name__} 2D Projection")
+            plt.xlabel("Component 1")
+            plt.ylabel("Component 2")
+            plot_path = os.path.join(args.results_path, "dimred_plot_2D.png")
+            plt.savefig(plot_path)
+            plt.show()
+            print(f"2D plot saved to {plot_path}")
+        elif n_dims == 3:
+            from mpl_toolkits.mplot3d import Axes3D
+            fig = plt.figure()
+            ax = fig.add_subplot(111, projection='3d')
+            ax.scatter(X_transformed[:,0], X_transformed[:,1], X_transformed[:,2], s=30, alpha=0.7, c='blue')
+            ax.set_title(f"{estimator.__class__.__name__} 3D Projection")
+            ax.set_xlabel("Component 1")
+            ax.set_ylabel("Component 2")
+            ax.set_zlabel("Component 3")
+            plot_path = os.path.join(args.results_path, "dimred_plot_3D.png")
+            plt.savefig(plot_path)
+            plt.show()
+            print(f"3D plot saved to {plot_path}")
+        else:
+            print(f"Visualization only supported for 2D or 3D outputs. Got {n_dims}D, skipping.")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Train a dimensionality reduction model.")
+    parser.add_argument('--model_module', type=str, required=True,
+                        help='Name of the dimred model module (e.g. pca, tsne, umap).')
+    parser.add_argument('--data_path', type=str, required=True,
+                        help='Path to the CSV dataset file.')
+    parser.add_argument('--model_path', type=str, default='saved_models/DimRed',
+                        help='Where to save the fitted model.')
+    parser.add_argument('--results_path', type=str, default=None,
+                        help='Directory to store results (transformed data, plots).')
+    parser.add_argument('--visualize', action='store_true',
+                        help='Plot the transformed data if 2D or 3D.')
+    parser.add_argument('--drop_columns', type=str, default='',
+                        help='Comma-separated column names to drop from the dataset.')
+    parser.add_argument('--select_columns', type=str, default='',
+                        help='Comma-separated column names to keep (ignore the rest).')
+
+    args = parser.parse_args()
+    main(args)

utils/README.md

@@ -0,0 +1,132 @@
+# Utils
+
+This directory contains utility scripts and helper functions that are used throughout the project. These scripts provide common functionalities such as data preprocessing, hyperparameter tuning, and other support functions that assist in model training and evaluation for **supervised** (regression and classification) as well as **unsupervised** (clustering) tasks.
+
+## Contents
+
+- [supervised_hyperparameter_tuning.py](#supervised_hyperparameter_tuningpy)
+- [unsupervised_hyperparameter_tuning.py](#unsupervised_hyperparameter_tuningpy)
+
+---
+
+## `supervised_hyperparameter_tuning.py`
+
+This script contains functions for performing hyperparameter tuning on **supervised learning** models (both regression and classification) using scikit-learn's `Pipeline` and `GridSearchCV`.
+
+### Functions
+
+#### `regression_hyperparameter_tuning(X, y, estimator, param_grid, cv=5, scoring=None)`
+
+Performs hyperparameter tuning for **regression** models.
+
+- **Parameters**:
+  - `X (pd.DataFrame)`: Feature matrix.
+  - `y (pd.Series)`: Numeric target variable.
+  - `estimator`: A scikit-learn regressor (e.g., `LinearRegression()`).
+  - `param_grid (dict)`: Parameter names and lists of values (e.g. `{'model__fit_intercept': [True, False]}`).
+  - `cv (int)`: Number of cross-validation folds (default 5).
+  - `scoring (str)`: Scoring metric (e.g., `'neg_root_mean_squared_error'`).
+- **Returns**:
+  - `best_model`: The pipeline with the best hyperparameters.
+  - `best_params (dict)`: The dictionary of best hyperparameters.
+
+**Example**:
+
+```python
+from utils.supervised_hyperparameter_tuning import regression_hyperparameter_tuning
+from sklearn.linear_model import LinearRegression
+
+X = ...  # Your regression features
+y = ...  # Your numeric target variable
+param_grid = {
+    'model__fit_intercept': [True, False]
+}
+
+best_model, best_params = regression_hyperparameter_tuning(
+    X, y, LinearRegression(), param_grid, scoring='neg_root_mean_squared_error'
+)
+```
+
+---
+
+#### `classification_hyperparameter_tuning(X, y, estimator, param_grid, cv=5, scoring=None)`
+
+Performs hyperparameter tuning for **classification** models.
+
+- **Parameters**:
+  - `X (pd.DataFrame)`: Feature matrix.
+  - `y (pd.Series)`: Target variable (binary or multi-class).
+  - `estimator`: A scikit-learn classifier (e.g., `LogisticRegression()`, `RandomForestClassifier()`).
+  - `param_grid (dict)`: Parameter names and lists of values (e.g. `{'model__n_estimators': [100, 200]}`).
+  - `cv (int)`: Number of cross-validation folds (default 5).
+  - `scoring (str)`: Scoring metric (e.g., `'accuracy'`, `'f1'`, `'roc_auc'`).
+- **Returns**:
+  - `best_model`: The pipeline with the best hyperparameters.
+  - `best_params (dict)`: The dictionary of best hyperparameters.
+
+**Example**:
+
+```python
+from utils.supervised_hyperparameter_tuning import classification_hyperparameter_tuning
+from sklearn.ensemble import RandomForestClassifier
+
+X = ...  # Your classification features
+y = ...  # Binary or multi-class labels
+param_grid = {
+    'model__n_estimators': [100, 200],
+    'model__max_depth': [None, 10]
+}
+
+best_model, best_params = classification_hyperparameter_tuning(
+    X, y, RandomForestClassifier(), param_grid, scoring='accuracy'
+)
+```
+
+---
+
+## `unsupervised_hyperparameter_tuning.py`
+
+This script provides a function for **hyperparameter tuning of clustering models** using **silhouette score** as the objective metric. Unlike supervised approaches, clustering does not have labeled data, so the silhouette score is used to measure how well-separated the clusters are.
+
+### Functions
+
+#### `clustering_hyperparameter_tuning(X, estimator, param_grid, scoring='silhouette', cv=5)`
+
+A simple manual hyperparameter search for clustering models.
+
+- **Parameters**:
+  - `X (array-like)`: Feature matrix for clustering.
+  - `estimator`: A scikit-learn clustering estimator supporting `.fit(X)` and either `.labels_` or `.predict(X)` (e.g., `KMeans`, `DBSCAN`, `GaussianMixture`).
+  - `param_grid (dict)`: Dictionary of hyperparams (e.g., `{'model__n_clusters': [2,3,4]}`).
+  - `scoring (str)`: Only `'silhouette'` is supported.  
+  - `cv (int)`: Optionally, you could do repeated subsampling or advanced logic for more stable estimates, but the default implementation does a single fit.
+- **Returns**:
+  - `best_estimator`: The fitted estimator with the best silhouette score.
+  - `best_params (dict)`: The dictionary of best hyperparameters found.
+
+**Key Steps**:
+1. **Parameter Loop**: For each combination of parameters in `ParameterGrid(param_grid)`, clone and fit the estimator.
+2. **Retrieve Labels**: If the estimator has `.labels_`, use it; otherwise use `.predict(X)`.
+3. **Compute Silhouette**: If more than one cluster is found, calculate `silhouette_score(X, labels)`.
+4. **Track the Best**: Keep track of the parameter set yielding the highest silhouette score.
+5. **Fallback**: If no valid parameter combos produce more than one cluster, it falls back to the original estimator.
+
+**Example**:
+
+```python
+from utils.unsupervised_hyperparameter_tuning import clustering_hyperparameter_tuning
+from sklearn.cluster import KMeans
+
+X = ...  # Your numeric data for clustering
+param_grid = {
+    'model__n_clusters': [2, 3, 4],
+    'model__init': ['k-means++', 'random']
+}
+
+best_model, best_params = clustering_hyperparameter_tuning(
+    X, KMeans(random_state=42), param_grid, scoring='silhouette'
+)
+print("Best Silhouette Score found:", best_params)
+```
+
+**Note**: This approach is simpler than using `GridSearchCV` for clustering because unsupervised tasks do not have a “true” label. The silhouette score is a common measure, but you could adapt the function for other internal cluster metrics if desired.

utils/unsupervised_hyperparameter_tuning.py

@@ -0,0 +1,86 @@
+
+"""
+unsupervised_hyperparameter_tuning.py
+
+Provides a function for hyperparameter tuning of clustering models
+using silhouette score as an objective.
+"""
+
+import numpy as np
+from sklearn.model_selection import ParameterGrid
+from sklearn.metrics import silhouette_score
+import copy
+
+def clustering_hyperparameter_tuning(X, estimator, param_grid, scoring='silhouette', cv=5):
+    """
+    A simple manual hyperparameter search for clustering models,
+    using silhouette_score for evaluation.
+
+    Args:
+        X (array-like): Feature data for clustering.
+        estimator: An estimator with .fit() and .predict() or .labels_ attribute.
+        param_grid (dict): Dictionary of hyperparams, e.g. {'model__n_clusters': [2,3,4]}.
+        scoring (str): Only 'silhouette' is supported here.
+        cv (int): We can do repeated subsampling or something similar to get stable silhouette.
+
+    Returns:
+        best_estimator: The estimator with best silhouette score.
+        best_params: Dictionary of best parameters found.
+    """
+    if not param_grid:
+        # If param_grid is empty, just fit once
+        estimator.fit(X)
+        return estimator, {}
+
+    best_score = -1  # silhouette ranges -1 to 1
+    best_params = None
+    best_estimator = None
+
+    for params in ParameterGrid(param_grid):
+        # Clone the original estimator
+        from sklearn.base import clone
+        current_estimator = clone(estimator)
+
+        # Apply params
+        for param, val in params.items():
+            # param might look like "model__n_clusters"
+            # We adapt: if param starts with 'model__', we set on current_estimator
+            path = param.split('__')
+            if len(path) > 1:
+                # E.g., path = ['model','n_clusters']
+                # we set current_estimator.n_clusters = val
+                setattr(current_estimator, path[1], val)
+            else:
+                # If there's no 'model__' prefix
+                setattr(current_estimator, param, val)
+
+        # Simple approach to do multiple splits if we want
+        # For now, let's do a single fit to keep it straightforward
+        current_estimator.fit(X)
+
+        # Use the fitted current_estimator here, not 'estimator'
+        if hasattr(current_estimator, 'labels_') and current_estimator.labels_ is not None:
+            labels = current_estimator.labels_
+        elif hasattr(current_estimator, 'predict'):
+            labels = current_estimator.predict(X)
+        else:
+            raise ValueError("No valid way to retrieve cluster labels for this estimator.")
+
+        unique_labels = set(labels)
+        if len(unique_labels) > 1:
+            score = silhouette_score(X, labels)
+        else:
+            score = -999  # invalid scenario if only 1 cluster
+
+        if score > best_score:
+            best_score = score
+            best_params = params
+            best_estimator = current_estimator
+
+    if best_estimator is None:
+        print("No valid parameter combination produced more than 1 cluster. Falling back to original estimator.")
+        estimator.fit(X)
+        return estimator, {}
+    else:
+        print(f"Best silhouette score: {best_score:.4f}")
+        return best_estimator, best_params