build: add project dependencies to pyproject.toml for clustering analysis package

Add click, pandas, scikit-learn, seaborn, matplotlib, and pyyaml dependencies with minimum version requirements for CLI, data processing, clustering, and visualization

Author: artemisTurintech

clustering_toolkit/__init__.py

@@ -0,0 +1,20 @@
+"""
+Clustering Toolkit Package
+
+A modular package for data clustering analysis, providing functionality for:
+- Data loading and validation
+- Data preprocessing and transformation
+- Clustering algorithm implementations
+- Cluster evaluation metrics
+- Visualization and reporting
+"""
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "data_loader",
+    "preprocessor",
+    "clustering",
+    "evaluation",
+    "visualization",
+]

clustering_toolkit/clustering.py

@@ -0,0 +1,141 @@
+"""
+Clustering Module
+
+This module provides implementations and wrappers for various clustering
+algorithms. It supports multiple clustering approaches:
+
+- K-Means clustering
+- Hierarchical clustering (Agglomerative, Divisive)
+- DBSCAN (Density-Based Spatial Clustering)
+- Gaussian Mixture Models (GMM)
+- Spectral clustering
+- Mean Shift clustering
+
+The module provides a unified interface for applying different clustering
+algorithms and comparing their results.
+
+Typical usage:
+    from clustering_toolkit.clustering import KMeansClustering, DBSCANClustering
+    
+    kmeans = KMeansClustering(n_clusters=3)
+    labels = kmeans.fit_predict(data)
+    
+    dbscan = DBSCANClustering(eps=0.5, min_samples=5)
+    labels = dbscan.fit_predict(data)
+"""
+
+import pandas as pd
+import numpy as np
+from sklearn.cluster import KMeans, DBSCAN, AgglomerativeClustering, SpectralClustering
+from sklearn.mixture import GaussianMixture
+from typing import Optional, Union, Literal
+from abc import ABC, abstractmethod
+
+
+class ClusteringAlgorithm(ABC):
+    """Base class for clustering algorithms."""
+    
+    def __init__(self):
+        self.labels_ = None
+        self.model = None
+    
+    @abstractmethod
+    def fit(self, data: Union[pd.DataFrame, np.ndarray]):
+        """Fit the clustering model to the data."""
+        pass
+    
+    @abstractmethod
+    def predict(self, data: Union[pd.DataFrame, np.ndarray]) -> np.ndarray:
+        """Predict cluster labels for the data."""
+        pass
+    
+    def fit_predict(self, data: Union[pd.DataFrame, np.ndarray]) -> np.ndarray:
+        """Fit the model and return cluster labels."""
+        self.fit(data)
+        return self.predict(data)
+
+
+class KMeansClustering(ClusteringAlgorithm):
+    """K-Means clustering implementation."""
+    
+    def __init__(self, n_clusters: int = 3, random_state: Optional[int] = 42, **kwargs):
+        super().__init__()
+        self.n_clusters = n_clusters
+        self.random_state = random_state
+        self.model = KMeans(n_clusters=n_clusters, random_state=random_state, **kwargs)
+    
+    def fit(self, data: Union[pd.DataFrame, np.ndarray]):
+        """Fit K-Means model to the data."""
+        self.model.fit(data)
+        self.labels_ = self.model.labels_
+        return self
+    
+    def predict(self, data: Union[pd.DataFrame, np.ndarray]) -> np.ndarray:
+        """Predict cluster labels."""
+        return self.model.predict(data)
+
+
+class DBSCANClustering(ClusteringAlgorithm):
+    """DBSCAN clustering implementation."""
+    
+    def __init__(self, eps: float = 0.5, min_samples: int = 5, **kwargs):
+        super().__init__()
+        self.eps = eps
+        self.min_samples = min_samples
+        self.model = DBSCAN(eps=eps, min_samples=min_samples, **kwargs)
+    
+    def fit(self, data: Union[pd.DataFrame, np.ndarray]):
+        """Fit DBSCAN model to the data."""
+        self.labels_ = self.model.fit_predict(data)
+        return self
+    
+    def predict(self, data: Union[pd.DataFrame, np.ndarray]) -> np.ndarray:
+        """Return cluster labels (DBSCAN doesn't support prediction on new data)."""
+        return self.labels_
+
+
+class HierarchicalClustering(ClusteringAlgorithm):
+    """Hierarchical (Agglomerative) clustering implementation."""
+    
+    def __init__(self, n_clusters: int = 3, linkage: str = 'ward', **kwargs):
+        super().__init__()
+        self.n_clusters = n_clusters
+        self.linkage = linkage
+        self.model = AgglomerativeClustering(n_clusters=n_clusters, linkage=linkage, **kwargs)
+    
+    def fit(self, data: Union[pd.DataFrame, np.ndarray]):
+        """Fit hierarchical clustering model to the data."""
+        self.labels_ = self.model.fit_predict(data)
+        return self
+    
+    def predict(self, data: Union[pd.DataFrame, np.ndarray]) -> np.ndarray:
+        """Return cluster labels (Hierarchical clustering doesn't support prediction)."""
+        return self.labels_
+
+
+def cluster_data(
+    data: Union[pd.DataFrame, np.ndarray],
+    algorithm: Literal['kmeans', 'dbscan', 'hierarchical'] = 'kmeans',
+    **kwargs
+) -> np.ndarray:
+    """
+    Cluster data using the specified algorithm.
+    
+    Args:
+        data: Data to cluster
+        algorithm: Clustering algorithm to use
+        **kwargs: Algorithm-specific parameters
+    
+    Returns:
+        Array of cluster labels
+    """
+    if algorithm == 'kmeans':
+        clusterer = KMeansClustering(**kwargs)
+    elif algorithm == 'dbscan':
+        clusterer = DBSCANClustering(**kwargs)
+    elif algorithm == 'hierarchical':
+        clusterer = HierarchicalClustering(**kwargs)
+    else:
+        raise ValueError(f"Unknown algorithm: {algorithm}")
+    
+    return clusterer.fit_predict(data)

clustering_toolkit/data_loader.py

@@ -0,0 +1,65 @@
+"""
+Data Loader Module
+
+This module provides functionality for loading and validating CSV data files
+for clustering analysis. It handles:
+
+- CSV file reading with proper encoding and delimiter detection
+- Data validation (checking for required columns, data types, etc.)
+- Basic data quality checks (missing values, duplicates, etc.)
+- Data integrity verification before processing
+- Error handling for malformed or incompatible data files
+
+Typical usage:
+    from clustering_toolkit.data_loader import load_data, validate_data
+    
+    data = load_data('path/to/data.csv')
+    is_valid, errors = validate_data(data)
+"""
+
+import pandas as pd
+from pathlib import Path
+from typing import Optional, Tuple, List
+
+
+def load_data(file_path: str, **kwargs) -> pd.DataFrame:
+    """
+    Load data from a CSV file.
+    
+    Args:
+        file_path: Path to the CSV file
+        **kwargs: Additional arguments to pass to pandas.read_csv()
+    
+    Returns:
+        DataFrame containing the loaded data
+    
+    Raises:
+        FileNotFoundError: If the file doesn't exist
+        pd.errors.ParserError: If the file cannot be parsed
+    """
+    path = Path(file_path)
+    if not path.exists():
+        raise FileNotFoundError(f"File not found: {file_path}")
+    
+    return pd.read_csv(file_path, **kwargs)
+
+
+def validate_data(data: pd.DataFrame) -> Tuple[bool, List[str]]:
+    """
+    Validate the loaded data for clustering analysis.
+    
+    Args:
+        data: DataFrame to validate
+    
+    Returns:
+        Tuple of (is_valid, error_messages)
+    """
+    errors = []
+    
+    if data.empty:
+        errors.append("Data is empty")
+    
+    if len(data.columns) == 0:
+        errors.append("No columns found in data")
+    
+    return len(errors) == 0, errors