imageatlas 0.1.0__py3-none-any.whl

imageatlas/__init__.py

@@ -0,0 +1,42 @@
+"""
+ImageAtlas: A toolkit for organizing, cleaning and analysing your image datasets.
+"""
+
+__version__ = '0.1.0'
+
+
+# 1. High level API (The everything tool)
+from .core.clusterer import ImageClusterer
+from .core.results import ClusteringResults
+
+# 2. Modular APIs (For specific tasks)
+
+# Feature extraction tools
+from .features.pipeline import FeaturePipeline
+from .features.extractors.factory import create_feature_extractor
+
+# ImageLoader, BatchProcessing later
+
+# Dimensionality Reduction Tools
+from .reduction.factory import create_reducer
+from .reduction.pca import PCAReducer
+from .reduction.umap_reducer import UMAPReducer
+
+# Clustering Tools
+from .clustering.factory import create_clustering_algorithm
+
+# Visualization Tools
+from .visualization.grids import GridVisualizer, create_cluster_grids
+
+__all__ = [
+    'ImageClusterer',
+    'ClusteringResults',
+    'FeaturePipeline',
+    'create_feature_extractor',
+    'create_reducer',
+    'PCAReducer',
+    'UMAPReducer',
+    'create_clustering_algorithm',
+    'GridVisualizer',
+    'create_cluster_grids',
+]

imageatlas/clustering/__init__.py

@@ -0,0 +1,14 @@
+from .base import ClusteringResult, ClusteringAlgorithm
+from .kmeans import KMeansClustering
+from .hdbscan_clustering import HDBSCANClustering
+from .gmm import GMMClustering
+
+
+
+__all__ = [
+    'ClusteringAlgorithm',
+    'ClusteringResult',
+    'KMeansClustering',
+    'HDBSCANClustering',
+    'GMMClustering',
+]

imageatlas/clustering/base.py

@@ -0,0 +1,129 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Any
+import numpy as np
+
+
+@dataclass
+class ClusteringResult:
+    """
+    Container for clustering Results.
+    """
+    cluster_labels: np.ndarray
+    cluster_dict: Dict[int, List[int]]
+    n_clusters: int
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def get_cluster_sizes(self) -> Dict[int, int]:
+        """Get the size of each cluster."""
+        return {cluster_id: len(indices) for cluster_id, indices in self.cluster_dict.items()}
+    
+    def get_cluster(self, cluster_id: int) -> List[int]:
+        """Get indices belonging to a specific cluster."""
+        return self.cluster_dict.get(cluster_id, [])
+    
+    def get_outliers(self) -> Optional[List[int]]:
+        """Get outlier indices (cluster_id = -1) if any exist."""
+        return self.cluster_dict.get(-1, None)
+    
+    def summary(self) -> str:
+        """Get a summary string of clustering results."""
+
+        summary_lines = [
+            f"Clustering Results Summary:",
+            f"   Total Samples: {len(self.clustering_labels)}",
+            f"   Number of Clusters: {self.n_clusters}",
+            f"   Cluster Sizes: {self.get_cluster_sizes()}",
+        ]
+
+        outliers = self.get_outliers()
+
+        if outliers:
+            summary_lines.append(f"   Outliers: {len(outliers)}")
+        
+        if self.metadata:
+            summary_lines.append(f"   Metadata: {list(self.metadata.keys())}")
+        
+        return "\n".join(summary_lines)
+
+class ClusteringAlgorithm(ABC):
+    """
+    Abstract base class for all clustering algorithms.
+    """
+
+    def __init__(self, random_state=42, **kwargs):
+        """
+        Initialize the clustering algorithm.
+        """
+        self.random_state = random_state
+        self.params = kwargs
+        self.is_fitted = False
+        self._model = None
+
+    @abstractmethod
+    def fit_predict(self, features) -> ClusteringResult:
+        """
+        Fit the clustering algorithms and predict cluster labels.
+        """
+        pass
+    
+    @abstractmethod
+    def get_algorithm_name(self):
+        """
+        Return the name of the clustering algorithm.
+        """
+        pass
+    
+    def _validate_features(self, features:np.ndarray) -> None:
+        """
+        Validate the input feature matrix.
+        """
+        if not isinstance(features, np.ndarray):
+            raise ValueError(f"Feature must be a numpy array, got {type(features)}")
+        
+        if features.ndim != 2:
+            raise ValueError(f"Features must be 2D array, got shape: {features.shape}")
+        
+        if features.shape[0] == 0:
+            raise ValueError("Feature matrix is empty.")
+        
+        if np.any(np.isnan(features)) or np.any(np.isinf(features)):
+            raise ValueError("Features contain NaN or Inf values")
+    
+    def _create_cluster_dict(self, cluster_labels, filenames=None):
+        """
+        Createa dictionary mapping cluster IDs to indices or filenames
+        """
+
+        cluster_dict = {}
+
+        for idx, cluster_id in enumerate(cluster_labels):
+            cluster_id = int(cluster_id)
+
+            if cluster_id not in cluster_dict:
+                cluster_dict[cluster_id] = []
+            
+            item = filenames[idx] if filenames else idx
+            cluster_dict[cluster_id].append(item)
+        
+        return cluster_dict
+    
+    def get_params(self):
+        """
+        Get parameters of the clustering algorithms.
+        """
+        return {
+            'random_state': self.random_state,
+            **self.params,
+        }
+    
+    def __repr__(self):
+        """
+        String representation of the clustering algorithm.
+        """
+        params_str = ", ".join(f"{key}={value}" for key, value in self.get_params().items())
+        return f"{self.get_algorithm_name()}({params_str})"
+    
+
+
+

imageatlas/clustering/factory.py

@@ -0,0 +1,43 @@
+"""
+Factory function for creating clustering algorithms.
+"""
+
+
+from .base import ClusteringAlgorithm
+from .kmeans import KMeansClustering
+from .hdbscan_clustering import HDBSCANClustering
+from .gmm import GMMClustering
+
+
+# Registry of available clustering algorithms.
+CLUSTERING_ALGORITHMS = {
+    'kmeans': KMeansClustering,
+    'hdbscan': HDBSCANClustering,
+    'gmm': GMMClustering,
+}
+
+def create_clustering_algorithm(
+    method:str,
+    **kwargs,
+) -> ClusteringAlgorithm:
+    """
+    Factory function to create clustering algorithms.
+    """
+
+    method = method.lower()
+
+    if method not in CLUSTERING_ALGORITHMS:
+        available = ", ".join(sorted(CLUSTERING_ALGORITHMS.keys()))
+        raise ValueError(
+            f"Unknown clustering Method: '{method}'.",
+            f"Available methods: {available}"
+        )
+    
+    algorithm_class = CLUSTERING_ALGORITHMS[method]
+    return algorithm_class(**kwargs)
+
+def get_available_algorithms():
+    """
+    Get a list of available clustering algorithms.
+    """
+    return sorted(CLUSTERING_ALGORITHMS.keys())

imageatlas/clustering/gmm.py

@@ -0,0 +1,165 @@
+"""
+Gaussian Mixture Model (GMM) clustering implementation.
+"""
+
+import numpy as np
+from typing import Optional, List
+from sklearn.mixture import GaussianMixture
+from .base import ClusteringAlgorithm, ClusteringResult
+
+class GMMClustering(ClusteringAlgorithm):
+    """
+    Gaussian Mixture Model clustering algorithm.
+    """
+
+    def __init__(
+        self,
+        n_components = 5,
+        covariance_type = 'diag',
+        max_iter = 100,
+        n_init = 10,
+        reg_covar = 1e-6,
+        random_state = 42,
+        **kwargs,
+    ):
+
+        super().__init__(random_state, **kwargs)
+
+        if n_components < 2:
+            raise ValueError("n_components must be atleast 2")
+        
+        valid_covariance_types = ['full', 'tied', 'diag', 'spherical']
+        if covariance_type not in valid_covariance_types:
+            raise ValueError(f"covariance_type must be one of {valid_covariance_types}")
+        
+        self.n_components = n_components
+        self.covariance_type = covariance_type
+        self.max_iter = max_iter
+        self.n_init = n_init
+        self.reg_covar = reg_covar
+    
+    def fit_predict(
+        self,
+        features,
+        filenames = None,
+    ) -> ClusteringResult:
+
+        """
+        Fit GMM and predict cluster labels.
+        """
+
+        self._validate_features(features)
+        print('fshape: ', features.shape)
+
+        n_samples = features.shape[0]
+
+        # Adjust n-components if needed
+        actual_n_components = min(self.n_components, n_samples)
+
+        if actual_n_components < self.n_components:
+            print(f"Warning: Requested {self.n_components} components only "
+                f"{n_samples} samples. Using {actual_n_components} components.")
+        
+        features_float64 = features.astype(np.float64)
+
+        
+        # Create and fit GMM
+        self._model = GaussianMixture(
+            n_components=actual_n_components,
+            covariance_type=self.covariance_type,
+            max_iter=self.max_iter,
+            n_init=self.n_init,
+            reg_covar=self.reg_covar,
+            random_state=self.random_state,
+            verbose=0
+        )
+
+        # Fit and predict
+        cluster_labels = self._model.fit_predict(features_float64)
+
+        # Get probability scores
+        probabilities = self._model.predict_proba(features_float64)
+
+        # Create cluster dictionary
+        cluster_dict =self._create_cluster_dict(cluster_labels, filenames)
+
+
+        # Prepare metadata
+        metadata = {
+            'algorithm': 'gmm',
+            'converged': bool(self._model.converged_),
+            'n_iter': int(self._model.n_iter_),
+            'bic': float(self._model.bic(features_float64)),
+            'aic': float(self._model.aic(features_float64)),
+            'lower_bound': float(self._model.lower_bound_),
+            'covariance_type': self.covariance_type,
+            'probabilities': probabilities,
+            'means': self._model.means_,
+            'covariance': self._model.covariances_,
+        }
+
+        self.is_fitted = True
+
+        return ClusteringResult(
+            cluster_labels = cluster_labels,
+            cluster_dict = cluster_dict,
+            n_clusters = actual_n_components,
+            metadata = metadata
+        )
+    
+    def predict(self, features):
+        """
+        Predict cluster label for new samples.
+        """
+
+        if not self.is_fitted or self._model is None:
+            raise RuntimeError("Model must be fitted before prediction. Call fit_predict first.")
+        
+        self._validate_features(features)
+        return self._model.predict(features)
+    
+    def predict_proba(self, features):
+        """
+        Predict probability of each cluster for new samples.
+        """
+
+        if not self.is_fitted or self._model is None:
+            raise RuntimeError("Model must be fitted before prediction. Call fit_predict first.")
+        
+        self._validate_features(features)
+        return self._model.predict_proba(features)
+    
+    def get_cluster_means(self):
+        """
+        Get cluster means (centers) if model is fitted.
+        """
+
+        if self.is_fitted and self._model is not None:
+            return self._model.means_
+        
+        return None
+    
+    def score(self, features):
+        """
+        Compute the log-likelihood of the data under the model.
+        """
+
+        if not self.is_fitted or self._model is None:
+            raise RuntimeError("Model must be fitted before scoring.")
+        
+        return self._model.score(features)
+    
+    def get_algorithm_name(self):
+        """Return the name of the clustering algorithm."""
+        return "GaussianMixtureModel (GMM)"
+    
+    def get_params(self):
+        """Get parameters of the clustering algorithm."""
+        return {
+            'n_components': self.n_components,
+            'covariance_type': self.covariance_type,
+            'max_iter': self.max_iter,
+            'n_init': self.n_init,
+            'random_state': self.random_state,
+            'reg_covar': self.reg_covar
+        }

imageatlas/clustering/hdbscan_clustering.py

@@ -0,0 +1,175 @@
+"""HDBSCAN clustering Implementation."""
+
+
+import numpy as np
+from typing import Optional, List
+from .base import ClusteringAlgorithm, ClusteringResult
+
+class HDBSCANClustering(ClusteringAlgorithm):
+    """
+    HDBSCAN algorithm.
+    """
+
+    def __init__(
+        self,
+        min_cluster_size = None,
+        min_samples = None,
+        metric = 'euclidean',
+        cluster_selection_method = 'eom',
+        auto_params = True,
+        random_state = 42,
+        **kwargs,
+    ):
+
+        super().__init__(random_state=random_state, **kwargs)
+
+        self.min_cluster_size = min_cluster_size
+        self.min_samples = min_samples
+        self.metric = metric
+        self.cluster_selection_method = cluster_selection_method
+        self.auto_params = auto_params
+
+        # Validate parameters
+        if cluster_selection_method not in ['eom', 'leaf']:
+            raise ValueError("cluster_selection_method must be 'eom' or 'leaf'")
+        
+    
+    def _auto_select_params(self, n_samples):
+        """
+        Automatically select HDBSCAN parameters based on dataset size.
+        """
+
+        if n_samples < 100:
+            min_cluster_size = max(5, n_samples // 20)
+            min_samples = 1
+        elif n_samples < 2000:
+            min_cluster_size = 10
+            min_samples = 1
+        elif n_samples < 10000:
+            min_cluster_size = 20
+            min_samples = 3
+        else:
+            min_cluster_size = 30
+            min_samples = 5
+        
+        return min_cluster_size, min_samples
+    
+    def fit_predict(
+        self,
+        features,
+        filenames,
+    ) -> ClusteringResult:
+
+        """
+        Fit HDBSCAN and predict cluster labels.
+        """
+
+        try:
+            import hdbscan
+        except ImportError:
+            raise ImportError(
+                "hdbscan is not installed. Install it with: pip install hdbscan"
+                )
+        
+        self._validate_features(features)
+
+        n_samples = features.shape[0]
+
+        # Auto-select parameters if needed.
+        if self.auto_params:
+            auto_min_cluster_size, auto_min_samples = self._auto_select_params(n_samples)
+            min_cluster_size = self.min_cluster_size or auto_min_cluster_size
+            min_samples = self.min_samples or auto_min_samples
+        else:
+            min_cluster_size = self.min_cluster_size or 10
+            min_samples = self.min_samples or 1
+        
+        # Ensure parameters are valid.
+        min_cluster_size = min(min_cluster_size, n_samples)
+        min_samples = min(min_samples, min_cluster_size)
+
+        # Create and fit HDBSCAN
+        self._model = hdbscan.HDBSCAN(
+            min_cluster_size = min_cluster_size,
+            min_samples = min_samples,
+            metric = self.metric,
+            cluster_selection_method = self.cluster_selection_method,
+            core_dist_n_jobs=-1 # Use all cores
+        )
+
+        # Fit and predict
+        cluster_labels = self._model.fit_predict(features)
+
+        # Create cluster dictionary
+        cluster_dict = self._create_cluster_dict(cluster_labels, filenames)
+
+        # Count actual clusters
+        unique_labels = np.unique(cluster_labels)
+        n_clusters = len(unique_labels[unique_labels >= 0])
+        n_noise = np.sum(cluster_labels == -1)
+
+        # Prepare metadata
+        metadata = {
+            'algorithm': 'hdbscan',
+            'n_clusters_found': n_clusters,
+            'n_noise_points': int(n_noise),
+            'min_cluster_size': min_cluster_size,
+            'min_samples' : min_samples,
+            'metric': self.metric,
+            'cluster_selection_method': self.cluster_selection_method,
+            'probabilities': self._model.probabilities_,
+            'outlier_scores': self._model.outlier_scores_,
+        }
+
+        # Add exemplars if available (representative points for each cluster)
+        if hasattr(self._model, 'exemplars_'):
+            metadata['exemplars'] = self._model.exemplars_
+        
+        self.is_fitted = True
+
+        return ClusteringResult(
+            cluster_labels=cluster_labels,
+            cluster_dict=cluster_dict,
+            n_clusters=n_clusters,
+            metadata=metadata
+        )
+    
+    def get_outlier_score(self):
+        """
+        Get outlier score for each sample.
+        """
+
+        if self.is_fitted and self._model is not None:
+            return self._model.outlier_scores_
+        
+        return None
+    
+    def get_condensed_tree(self):
+        """
+        Get condensed cluster hierarchy tree.
+        """
+
+        if self.is_fitted and self._model is not None:
+            return self._model.condensed_tree_
+        
+        return None
+    
+    def get_algorithm_name(self):
+        """
+        Return the name of the clustering algorithm.
+        """
+        return "HDBSCAN"
+    
+    def get_params(self):
+        """
+        Get parameters of the clustering algorithm.
+        """
+        return {
+            'min_cluster_size': self.min_cluster_size,
+            'min_samples': self.min_samples,
+            'metric': self.metric,
+            'cluster_selection_method': self.cluster_selection_method,
+            'auto_params': self.auto_params,
+            'random_state': self.random_state
+        }
+