bitbullet 0.1.0__py3-none-any.whl

bitbullet/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

bitbullet/cluster/__init__.py

@@ -0,0 +1,34 @@
+"""
+BitBullet Cluster - Production-grade clustering engine for mixed data types.
+
+This package provides a comprehensive clustering solution with:
+- Support for mixed numerical and categorical data
+- Multiple clustering algorithms (K-Modes, K-Prototypes, K-Means, DBSCAN, GMM)
+- Data-driven feature weighting
+- Memory-efficient distance computation
+- Production-ready serialization
+- Comprehensive evaluation metrics
+- Beautiful visualizations
+"""
+
+from bitbullet.cluster.core.base import BaseClusterer, ClusterConfig, ClusterState
+from bitbullet.cluster.weights.categorical_weights import CategoricalWeights
+from bitbullet.cluster.weights.gamma_estimation import GammaEstimator
+from bitbullet.cluster.utils.sample_size import (
+    SampleSizeEstimator,
+    SampleSizeEstimate,
+    estimate_sample_size,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BaseClusterer",
+    "ClusterConfig",
+    "ClusterState",
+    "CategoricalWeights",
+    "GammaEstimator",
+    "SampleSizeEstimator",
+    "SampleSizeEstimate",
+    "estimate_sample_size",
+]

bitbullet/cluster/algorithms/density/dbscan.py

@@ -0,0 +1,252 @@
+"""
+DBSCAN density-based clustering algorithm.
+
+Finds arbitrarily-shaped clusters and identifies outliers.
+"""
+
+from typing import Optional
+
+import numpy as np
+import pandas as pd
+from sklearn.cluster import DBSCAN as SKLearnDBSCAN
+
+from bitbullet.cluster.core.base import BaseClusterer
+
+
+class DBSCANClusterer(BaseClusterer):
+    """DBSCAN clustering for arbitrary-shaped clusters.
+
+    Features:
+    - Density-based clustering (no need to specify n_clusters)
+    - Automatic outlier detection (noise points labeled as -1)
+    - Works with arbitrary cluster shapes
+    - Supports custom distance metrics
+
+    Note:
+        DBSCAN does not support prediction on new data. Use fit_predict
+        on all data at once, or use a classifier trained on DBSCAN labels.
+    """
+
+    def _validate_config(self) -> None:
+        """Validate DBSCAN specific configuration."""
+        # DBSCAN doesn't require n_clusters (it's determined automatically)
+        # So we don't validate n_clusters
+
+        # Must have eps and min_samples
+        eps = self._config.params.get("eps")
+        min_samples = self._config.params.get("min_samples")
+
+        if eps is None:
+            raise ValueError("DBSCAN requires 'eps' parameter in config.params")
+
+        if min_samples is None:
+            raise ValueError("DBSCAN requires 'min_samples' parameter in config.params")
+
+        if eps <= 0:
+            raise ValueError(f"eps must be positive, got {eps}")
+
+        if min_samples < 1:
+            raise ValueError(f"min_samples must be >= 1, got {min_samples}")
+
+    def _fit(self, data: pd.DataFrame, verbose: bool = False) -> None:
+        """Fit DBSCAN to data.
+
+        Args:
+            data: Input data
+            verbose: Print progress messages
+        """
+        # Extract parameters
+        eps = self._config.params.get("eps", 0.5)
+        min_samples = self._config.params.get("min_samples", 5)
+        metric = self._config.params.get("metric", "euclidean")
+        algorithm = self._config.params.get("algorithm", "auto")
+        leaf_size = self._config.params.get("leaf_size", 30)
+
+        if verbose:
+            print(f"Fitting DBSCAN (eps={eps}, min_samples={min_samples}, metric={metric})...")
+
+        # ── Mixed-distance path ───────────────────────────────────────────────
+        # When metric == 'mixed', DBSCAN consumes a precomputed pairwise
+        # distance matrix built from the same k-prototypes hybrid distance
+        # formula (numerical Euclidean + γ · weighted-matching) — the same
+        # math the Clusterability Diagnostic γ slider previews. This is how
+        # DBSCAN supports mixed numerical+categorical data without dragging
+        # in Gower as an external dep.
+        if metric == "mixed":
+            from bitbullet.cluster.distance import compute_mixed_distance_matrix
+            from bitbullet.cluster.weights.categorical_weights import CategoricalWeights
+            from bitbullet.cluster.weights.gamma_estimation import GammaEstimator
+
+            numerical_cols = self._config.numerical_columns or []
+            categorical_cols = self._config.categorical_columns or []
+            if not numerical_cols and not categorical_cols:
+                raise ValueError(
+                    "DBSCAN with metric='mixed' requires at least one numerical "
+                    "or categorical feature selection."
+                )
+
+            num_df = data[numerical_cols] if numerical_cols else None
+            cat_df = data[categorical_cols] if categorical_cols else None
+
+            # Resolve γ: heuristic string ('huang' / 'variance_matching') or
+            # a concrete float (manual). Mirrors k-prototypes' contract so a
+            # user toggling between the two algorithms sees identical γ
+            # semantics.
+            gamma_raw = self._config.params.get("gamma", "huang")
+            gamma_mode = "fixed"
+            if isinstance(gamma_raw, str):
+                gamma_mode = gamma_raw
+                gamma_value = GammaEstimator.calculate(
+                    data, numerical_cols, categorical_cols, method=gamma_raw
+                ) if numerical_cols and categorical_cols else 1.0
+            else:
+                gamma_value = float(gamma_raw)
+
+            # Categorical weights — same factory k-prototypes uses.
+            cat_weights_raw = self._config.params.get("categorical_weights", "relevance")
+            cat_weights_method = "manual"
+            if isinstance(cat_weights_raw, str):
+                cat_weights_method = cat_weights_raw
+                if categorical_cols:
+                    cat_weights = CategoricalWeights.calculate(
+                        data, method=cat_weights_raw, categorical_columns=categorical_cols
+                    )
+                else:
+                    cat_weights = None
+            elif cat_weights_raw is None:
+                cat_weights = None
+                cat_weights_method = "none"
+            else:
+                cat_weights = CategoricalWeights.validate_manual_weights(
+                    cat_weights_raw, categorical_cols
+                )
+
+            distance_matrix = compute_mixed_distance_matrix(
+                num_df=num_df,
+                cat_df=cat_df,
+                gamma=float(gamma_value),
+                cat_weights=cat_weights,
+            )
+
+            sklearn_metric = "precomputed"
+            sklearn_input = distance_matrix
+            mixed_metadata = {
+                "gamma_value": float(gamma_value),
+                "gamma_mode": gamma_mode,
+                "categorical_weighting_method": cat_weights_method,
+                "categorical_weights": cat_weights,
+            }
+        else:
+            sklearn_metric = metric
+            sklearn_input = data
+            mixed_metadata = None
+
+        # Create DBSCAN instance
+        clusterer = SKLearnDBSCAN(
+            eps=eps,
+            min_samples=min_samples,
+            metric=sklearn_metric,
+            algorithm=algorithm,
+            leaf_size=leaf_size,
+            n_jobs=-1,
+        )
+
+        # Fit the model
+        labels = clusterer.fit_predict(sklearn_input)
+
+        # Count clusters (excluding noise points labeled -1)
+        n_clusters = len(set(labels)) - (1 if -1 in labels else 0)
+        n_noise = np.sum(labels == -1)
+
+        # Store results
+        self._state.labels = labels
+        self._state.n_clusters_actual = n_clusters
+
+        # DBSCAN doesn't have explicit centroids, but we can calculate them
+        # as the mean of points in each cluster (excluding noise). Categorical
+        # columns get the mode; only numerical columns get a true mean.
+        centroids = []
+        numerical_only = data.select_dtypes(include="number")
+        for cluster_id in range(n_clusters):
+            mask = labels == cluster_id
+            if np.any(mask) and not numerical_only.empty:
+                centroid = numerical_only[mask].mean(axis=0).values
+                centroids.append(centroid)
+
+        if centroids:
+            self._state.cluster_centers = np.array(centroids)
+        else:
+            self._state.cluster_centers = None
+
+        # Store fitted parameters
+        self._state.fitted_params = {
+            "eps": eps,
+            "min_samples": min_samples,
+            "metric": metric,
+            "n_noise_points": int(n_noise),
+            "n_clusters_found": n_clusters,
+            "core_sample_indices": clusterer.core_sample_indices_.tolist() if len(clusterer.core_sample_indices_) > 0 else [],
+            **({"mixed_distance": mixed_metadata} if mixed_metadata else {}),
+        }
+
+        if verbose:
+            print(f"Found {n_clusters} clusters and {n_noise} noise points")
+
+    def _predict(self, data: pd.DataFrame) -> np.ndarray:
+        """DBSCAN does not support prediction on new data.
+
+        Args:
+            data: New data
+
+        Raises:
+            NotImplementedError: DBSCAN does not support prediction
+        """
+        raise NotImplementedError(
+            "DBSCAN does not support prediction on new data. "
+            "Either:\n"
+            "1. Include all data in fit_predict()\n"
+            "2. Train a classifier (e.g., KNN) on DBSCAN labels to predict new data\n"
+            "3. Use a different algorithm that supports prediction (e.g., K-Means)"
+        )
+
+    def get_noise_points(self) -> np.ndarray:
+        """Get indices of points classified as noise.
+
+        Returns:
+            Array of indices where labels == -1
+
+        Raises:
+            RuntimeError: If not fitted
+        """
+        if not self.is_fitted:
+            raise RuntimeError("Must fit before getting noise points")
+
+        return np.where(self._state.labels == -1)[0]
+
+    def get_core_points(self) -> np.ndarray:
+        """Get indices of core points (points with >= min_samples neighbors).
+
+        Returns:
+            Array of core point indices
+
+        Raises:
+            RuntimeError: If not fitted
+        """
+        if not self.is_fitted:
+            raise RuntimeError("Must fit before getting core points")
+
+        return np.array(self._state.fitted_params["core_sample_indices"])
+
+    def get_n_clusters(self) -> int:
+        """Get number of clusters found (excluding noise).
+
+        Returns:
+            Number of clusters
+
+        Raises:
+            RuntimeError: If not fitted
+        """
+        if not self.is_fitted:
+            raise RuntimeError("Must fit before getting n_clusters")
+
+        return self._state.n_clusters_actual

bitbullet/cluster/algorithms/model_based/gmm.py

@@ -0,0 +1,283 @@
+"""
+Gaussian Mixture Model (GMM) clustering algorithm.
+
+Probabilistic soft clustering assuming Gaussian distributions.
+"""
+
+from typing import Optional
+
+import numpy as np
+import pandas as pd
+from sklearn.mixture import GaussianMixture
+
+from bitbullet.cluster.core.base import BaseClusterer
+
+
+class GMMClusterer(BaseClusterer):
+    """Gaussian Mixture Model for probabilistic clustering.
+
+    Features:
+    - Soft clustering (probabilities for each cluster)
+    - Models overlapping clusters
+    - Multiple covariance types (full, tied, diag, spherical)
+    - Supports convergence diagnostics
+
+    Note:
+        GMM only works with numerical features. For mixed data,
+        use K-Prototypes instead.
+    """
+
+    def _validate_config(self) -> None:
+        """Validate GMM specific configuration."""
+        if self._config.n_clusters is None or self._config.n_clusters < 1:
+            raise ValueError(
+                f"n_clusters must be >= 1 for GMM, got {self._config.n_clusters}"
+            )
+
+        # GMM doesn't support categorical columns
+        if self._config.categorical_columns:
+            raise ValueError(
+                "GMM does not support categorical columns. "
+                "Use K-Prototypes for mixed data types."
+            )
+
+    def _fit(self, data: pd.DataFrame, verbose: bool = False) -> None:
+        """Fit GMM to numerical data.
+
+        Args:
+            data: Input data with only numerical features
+            verbose: Print progress messages
+        """
+        # Extract parameters
+        covariance_type = self._config.params.get("covariance_type", "full")
+        n_init = self._config.params.get("n_init", 1)
+        max_iter = self._config.params.get("max_iter", 100)
+        tol = self._config.params.get("tol", 1e-3)
+        reg_covar = self._config.params.get("reg_covar", 1e-6)
+        init_params = self._config.params.get("init_params", "kmeans")
+
+        if verbose:
+            print(f"Fitting GMM (n_components={self._config.n_clusters}, "
+                  f"covariance_type={covariance_type})...")
+
+        # Create GMM instance
+        gmm = GaussianMixture(
+            n_components=self._config.n_clusters,
+            covariance_type=covariance_type,
+            n_init=n_init,
+            max_iter=max_iter,
+            tol=tol,
+            reg_covar=reg_covar,
+            init_params=init_params,
+            random_state=self._config.random_state,
+            verbose=int(verbose),
+            verbose_interval=10,
+        )
+
+        # Fit the model
+        gmm.fit(data)
+        labels = gmm.predict(data)
+
+        # Store results
+        self._state.labels = labels
+        self._state.n_clusters_actual = self._config.n_clusters
+        self._state.cluster_centers = gmm.means_
+
+        # Store fitted parameters (needed for prediction)
+        self._state.fitted_params = {
+            "converged": bool(gmm.converged_),
+            "n_iter": int(gmm.n_iter_),
+            "lower_bound": float(gmm.lower_bound_),
+            "covariances": gmm.covariances_.tolist(),
+            "weights": gmm.weights_.tolist(),
+            "precisions_cholesky": gmm.precisions_cholesky_.tolist(),
+            "covariance_type": covariance_type,
+        }
+
+        if verbose:
+            converged = "converged" if gmm.converged_ else "did NOT converge"
+            print(f"GMM {converged} after {gmm.n_iter_} iterations. "
+                  f"Log-likelihood: {gmm.lower_bound_:.2f}")
+
+    def _predict(self, data: pd.DataFrame) -> np.ndarray:
+        """Assign new data to clusters using hard assignment.
+
+        Args:
+            data: New data to assign to clusters
+
+        Returns:
+            Cluster labels (hard assignment)
+        """
+        # Recreate GMM from fitted parameters
+        gmm = GaussianMixture(n_components=self._config.n_clusters)
+        gmm.means_ = self._state.cluster_centers
+        gmm.covariances_ = np.array(self._state.fitted_params["covariances"])
+        gmm.weights_ = np.array(self._state.fitted_params["weights"])
+        gmm.precisions_cholesky_ = np.array(self._state.fitted_params["precisions_cholesky"])
+        gmm.covariance_type = self._state.fitted_params["covariance_type"]
+
+        # Predict
+        labels = gmm.predict(data)
+
+        return labels
+
+    def predict_proba(self, data: pd.DataFrame) -> np.ndarray:
+        """Get probability of each cluster for each data point.
+
+        Args:
+            data: Data to get probabilities for
+
+        Returns:
+            Array of shape (n_samples, n_clusters) with probabilities
+
+        Raises:
+            RuntimeError: If not fitted
+        """
+        if not self.is_fitted:
+            raise RuntimeError("Must fit before prediction")
+
+        # Recreate GMM from fitted parameters
+        gmm = GaussianMixture(n_components=self._config.n_clusters)
+        gmm.means_ = self._state.cluster_centers
+        gmm.covariances_ = np.array(self._state.fitted_params["covariances"])
+        gmm.weights_ = np.array(self._state.fitted_params["weights"])
+        gmm.precisions_cholesky_ = np.array(self._state.fitted_params["precisions_cholesky"])
+        gmm.covariance_type = self._state.fitted_params["covariance_type"]
+
+        # Get probabilities
+        probas = gmm.predict_proba(data)
+
+        return probas
+
+    def get_centroids(self) -> pd.DataFrame:
+        """Get cluster centroids (means) as DataFrame.
+
+        Returns:
+            DataFrame with centroids
+
+        Raises:
+            RuntimeError: If not fitted
+        """
+        if not self.is_fitted:
+            raise RuntimeError("Must fit before getting centroids")
+
+        centroids_df = pd.DataFrame(
+            self._state.cluster_centers,
+            columns=self._state.feature_names,
+            index=[f"cluster_{i}" for i in range(self._state.n_clusters_actual)]
+        )
+
+        return centroids_df
+
+    def get_covariances(self) -> np.ndarray:
+        """Get covariance matrices for each cluster.
+
+        Returns:
+            Covariance matrices (shape depends on covariance_type)
+
+        Raises:
+            RuntimeError: If not fitted
+        """
+        if not self.is_fitted:
+            raise RuntimeError("Must fit before getting covariances")
+
+        return np.array(self._state.fitted_params["covariances"])
+
+    def get_weights(self) -> np.ndarray:
+        """Get mixture weights (prior probabilities of each cluster).
+
+        Returns:
+            Array of weights summing to 1.0
+
+        Raises:
+            RuntimeError: If not fitted
+        """
+        if not self.is_fitted:
+            raise RuntimeError("Must fit before getting weights")
+
+        return np.array(self._state.fitted_params["weights"])
+
+    def score(self, data: pd.DataFrame) -> float:
+        """Compute log-likelihood of data under the model.
+
+        Args:
+            data: Data to score
+
+        Returns:
+            Log-likelihood score (higher is better)
+
+        Raises:
+            RuntimeError: If not fitted
+        """
+        if not self.is_fitted:
+            raise RuntimeError("Must fit before scoring")
+
+        # Recreate GMM from fitted parameters
+        gmm = GaussianMixture(n_components=self._config.n_clusters)
+        gmm.means_ = self._state.cluster_centers
+        gmm.covariances_ = np.array(self._state.fitted_params["covariances"])
+        gmm.weights_ = np.array(self._state.fitted_params["weights"])
+        gmm.precisions_cholesky_ = np.array(self._state.fitted_params["precisions_cholesky"])
+        gmm.covariance_type = self._state.fitted_params["covariance_type"]
+
+        return gmm.score(data)
+
+    def get_bic(self, data: pd.DataFrame) -> float:
+        """Compute Bayesian Information Criterion (BIC) for model selection.
+
+        BIC balances model fit with complexity. Lower is better.
+        Use this for elbow-like plots when selecting optimal number of clusters.
+
+        BIC = -2 * log_likelihood + n_params * log(n_samples)
+
+        Args:
+            data: Data used for fitting (same data used in fit())
+
+        Returns:
+            BIC score (lower is better)
+
+        Raises:
+            RuntimeError: If not fitted
+        """
+        if not self.is_fitted:
+            raise RuntimeError("Must fit before computing BIC")
+
+        # Recreate GMM from fitted parameters
+        gmm = GaussianMixture(n_components=self._config.n_clusters)
+        gmm.means_ = self._state.cluster_centers
+        gmm.covariances_ = np.array(self._state.fitted_params["covariances"])
+        gmm.weights_ = np.array(self._state.fitted_params["weights"])
+        gmm.precisions_cholesky_ = np.array(self._state.fitted_params["precisions_cholesky"])
+        gmm.covariance_type = self._state.fitted_params["covariance_type"]
+
+        return gmm.bic(data)
+
+    def get_aic(self, data: pd.DataFrame) -> float:
+        """Compute Akaike Information Criterion (AIC) for model selection.
+
+        AIC is similar to BIC but with less penalty for model complexity.
+        Lower is better.
+
+        AIC = -2 * log_likelihood + 2 * n_params
+
+        Args:
+            data: Data used for fitting (same data used in fit())
+
+        Returns:
+            AIC score (lower is better)
+
+        Raises:
+            RuntimeError: If not fitted
+        """
+        if not self.is_fitted:
+            raise RuntimeError("Must fit before computing AIC")
+
+        # Recreate GMM from fitted parameters
+        gmm = GaussianMixture(n_components=self._config.n_clusters)
+        gmm.means_ = self._state.cluster_centers
+        gmm.covariances_ = np.array(self._state.fitted_params["covariances"])
+        gmm.weights_ = np.array(self._state.fitted_params["weights"])
+        gmm.precisions_cholesky_ = np.array(self._state.fitted_params["precisions_cholesky"])
+        gmm.covariance_type = self._state.fitted_params["covariance_type"]
+
+        return gmm.aic(data)

bitbullet/cluster/algorithms/partitional/__init__.py

@@ -0,0 +1,19 @@
+"""Partitional clustering algorithms."""
+
+__all__ = ["KMeansClusterer", "KModesClusterer", "KPrototypesClusterer"]
+
+
+def __getattr__(name: str):
+    if name == "KMeansClusterer":
+        from bitbullet.cluster.algorithms.partitional.kmeans import KMeansClusterer
+
+        return KMeansClusterer
+    if name == "KModesClusterer":
+        from bitbullet.cluster.algorithms.partitional.kmodes import KModesClusterer
+
+        return KModesClusterer
+    if name == "KPrototypesClusterer":
+        from bitbullet.cluster.algorithms.partitional.kprototypes import KPrototypesClusterer
+
+        return KPrototypesClusterer
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")