clusterkit 0.1.0.pre.1

data/lib/clusterkit/clustering/hdbscan.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module ClusterKit
+  module Clustering
+    # HDBSCAN clustering algorithm - matching KMeans API pattern
+    class HDBSCAN
+      attr_reader :min_samples, :min_cluster_size, :metric, :labels, :probabilities, 
+                  :outlier_scores, :cluster_persistence
+
+      # Initialize HDBSCAN clusterer (matches KMeans pattern)
+      # @param min_samples [Integer] Min neighborhood size for core points (default: 5)
+      # @param min_cluster_size [Integer] Minimum size of clusters (default: 5)
+      # @param metric [String] Distance metric (default: 'euclidean')
+      def initialize(min_samples: 5, min_cluster_size: 5, metric: 'euclidean')
+        raise ArgumentError, "min_samples must be positive" unless min_samples > 0
+        raise ArgumentError, "min_cluster_size must be positive" unless min_cluster_size > 0
+        
+        valid_metrics = ['euclidean', 'l2', 'manhattan', 'l1', 'cosine']
+        unless valid_metrics.include?(metric)
+          raise ArgumentError, "metric must be one of: #{valid_metrics.join(', ')}"
+        end
+        
+        @min_samples = min_samples
+        @min_cluster_size = min_cluster_size
+        @metric = metric
+        @fitted = false
+      end
+
+      # Fit the HDBSCAN model (matches KMeans.fit)
+      # @param data [Array] 2D array of data points
+      # @return [self] Returns self for method chaining
+      def fit(data)
+        validate_data(data)
+        
+        # Call Rust implementation (hdbscan crate)
+        result = Clustering.hdbscan_rust(data, @min_samples, @min_cluster_size, @metric)
+        
+        @labels = result["labels"]
+        @probabilities = result["probabilities"]
+        @outlier_scores = result["outlier_scores"]
+        @cluster_persistence = result["cluster_persistence"]
+        @fitted = true
+        
+        self
+      end
+
+      # HDBSCAN doesn't support predict for new points (unlike KMeans)
+      # But we keep the method for API consistency
+      # @param data [Array] 2D array of data points
+      # @return [Array] Returns nil or raises
+      def predict(data)
+        raise NotImplementedError, "HDBSCAN does not support prediction on new data. " \
+                                  "Use approximate_predict for approximate membership"
+      end
+
+      # Fit the model and return labels (matches KMeans.fit_predict)
+      # @param data [Array] 2D array of data points
+      # @return [Array] Cluster labels (-1 for noise)
+      def fit_predict(data)
+        fit(data)
+        @labels
+      end
+
+      # Check if model has been fitted (matches KMeans.fitted?)
+      # @return [Boolean] True if fitted
+      def fitted?
+        @fitted
+      end
+
+      # Get number of clusters found (similar to KMeans.k but discovered)
+      # @return [Integer] Number of clusters (excluding noise)
+      def n_clusters
+        return 0 unless fitted?
+        # Count unique labels excluding -1 (noise)
+        unique_labels = @labels.uniq.reject { |l| l == -1 }
+        unique_labels.length
+      end
+
+      # Get noise ratio (HDBSCAN-specific but follows naming pattern)
+      # @return [Float] Fraction of points labeled as noise
+      def noise_ratio
+        return 0.0 unless fitted?
+        @labels.count(-1).to_f / @labels.length
+      end
+
+      # Get the number of noise points
+      # @return [Integer] Number of points labeled as noise
+      def n_noise_points
+        return 0 unless fitted?
+        @labels.count(-1)
+      end
+
+      # Get indices of noise points
+      # @return [Array<Integer>] Indices of points labeled as noise
+      def noise_indices
+        return [] unless fitted?
+        @labels.each_with_index.select { |label, _| label == -1 }.map { |_, idx| idx }
+      end
+
+      # Get indices of points in each cluster
+      # @return [Hash<Integer, Array<Integer>>] Mapping of cluster label to point indices
+      def cluster_indices
+        return {} unless fitted?
+        
+        result = {}
+        @labels.each_with_index do |label, idx|
+          next if label == -1  # Skip noise points
+          result[label] ||= []
+          result[label] << idx
+        end
+        result
+      end
+
+      # Get summary statistics
+      # @return [Hash] Summary of clustering results
+      def summary
+        return {} unless fitted?
+        
+        {
+          n_clusters: n_clusters,
+          n_noise_points: n_noise_points,
+          noise_ratio: noise_ratio,
+          cluster_sizes: cluster_indices.transform_values(&:length),
+          cluster_persistence: @cluster_persistence
+        }
+      end
+
+      private
+
+      def validate_data(data)
+        # Exact same validation as KMeans for consistency
+        raise ArgumentError, "Data must be an array" unless data.is_a?(Array)
+        raise ArgumentError, "Data cannot be empty" if data.empty?
+        raise ArgumentError, "Data must be 2D array" unless data.first.is_a?(Array)
+        
+        row_length = data.first.length
+        unless data.all? { |row| row.is_a?(Array) && row.length == row_length }
+          raise ArgumentError, "All rows must have the same length"
+        end
+        
+        data.each_with_index do |row, i|
+          row.each_with_index do |val, j|
+            unless val.is_a?(Numeric)
+              raise ArgumentError, "Element at position [#{i}, #{j}] is not numeric"
+            end
+          end
+        end
+      end
+    end
+
+    # Module-level convenience methods (matching KMeans pattern)
+    class << self
+      # Perform HDBSCAN clustering (matches Clustering.kmeans signature pattern)
+      # @param data [Array] 2D array of data points
+      # @param min_samples [Integer] Min neighborhood size for core points
+      # @param min_cluster_size [Integer] Minimum size of clusters
+      # @param metric [String] Distance metric
+      # @return [Hash] Result hash with :labels, :probabilities, :outlier_scores
+      def hdbscan(data, min_samples: 5, min_cluster_size: 5, metric: 'euclidean')
+        clusterer = HDBSCAN.new(
+          min_samples: min_samples,
+          min_cluster_size: min_cluster_size,
+          metric: metric
+        )
+        clusterer.fit(data)
+        {
+          labels: clusterer.labels,
+          probabilities: clusterer.probabilities,
+          outlier_scores: clusterer.outlier_scores,
+          n_clusters: clusterer.n_clusters,
+          noise_ratio: clusterer.noise_ratio,
+          cluster_persistence: clusterer.cluster_persistence || {}
+        }
+      end
+    end
+  end
+end

data/lib/clusterkit/clustering.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require_relative 'clusterkit'
+require_relative 'clustering/hdbscan'
+
+module ClusterKit
+  # Module for clustering algorithms
+  module Clustering
+    # K-means clustering algorithm
+    class KMeans
+      attr_reader :k, :max_iter, :centroids, :labels, :inertia
+
+      # Initialize K-means clusterer
+      # @param k [Integer] Number of clusters
+      # @param max_iter [Integer] Maximum iterations (default: 300)
+      # @param random_seed [Integer] Random seed for reproducibility (optional)
+      def initialize(k:, max_iter: 300, random_seed: nil)
+        raise ArgumentError, "k must be positive" unless k > 0
+        @k = k
+        @max_iter = max_iter
+        @random_seed = random_seed
+        @fitted = false
+      end
+
+      # Fit the K-means model
+      # @param data [Array] 2D array of data points
+      # @return [self] Returns self for method chaining
+      def fit(data)
+        validate_data(data)
+        
+        # Set random seed if provided
+        srand(@random_seed) if @random_seed
+        
+        # Call Rust implementation
+        @labels, @centroids, @inertia = Clustering.kmeans_rust(data, @k, @max_iter)
+        @fitted = true
+        
+        self
+      end
+
+      # Predict cluster labels for new data
+      # @param data [Array] 2D array of data points
+      # @return [Array] Cluster labels
+      def predict(data)
+        raise RuntimeError, "Model must be fitted before predict" unless fitted?
+        validate_data(data)
+        
+        Clustering.kmeans_predict_rust(data, @centroids)
+      end
+
+      # Fit the model and return labels
+      # @param data [Array] 2D array of data points
+      # @return [Array] Cluster labels
+      def fit_predict(data)
+        fit(data)
+        @labels
+      end
+
+      # Check if model has been fitted
+      # @return [Boolean] True if fitted
+      def fitted?
+        @fitted
+      end
+
+      # Get cluster centers
+      # @return [Array] 2D array of cluster centers
+      def cluster_centers
+        @centroids
+      end
+
+      # Get the sum of squared distances of samples to their closest cluster center
+      # @return [Float] Inertia value
+      def inertia
+        @inertia
+      end
+
+      # Class methods for K-means specific utilities
+      class << self
+        # Find optimal number of clusters using elbow method
+        # @param data [Array] 2D array of data points
+        # @param k_range [Range] Range of k values to try
+        # @param max_iter [Integer] Maximum iterations per k
+        # @return [Hash] Mapping of k to inertia values
+        def elbow_method(data, k_range: 2..10, max_iter: 300)
+          results = {}
+          
+          k_range.each do |k|
+            kmeans = new(k: k, max_iter: max_iter)
+            kmeans.fit(data)
+            results[k] = kmeans.inertia
+          end
+          
+          results
+        end
+
+        # Detect optimal k from elbow method results
+        # @param elbow_results [Hash] Mapping of k to inertia values (from elbow_method)
+        # @param fallback_k [Integer] Default k to return if detection fails (default: 3)
+        # @return [Integer] Optimal number of clusters
+        def detect_optimal_k(elbow_results, fallback_k: 3)
+          return fallback_k if elbow_results.nil? || elbow_results.empty?
+          
+          k_values = elbow_results.keys.sort
+          return k_values.first if k_values.size == 1
+          
+          # Find the k with the largest drop in inertia
+          max_drop = 0
+          optimal_k = k_values.first
+          
+          k_values.each_cons(2) do |k1, k2|
+            drop = elbow_results[k1] - elbow_results[k2]
+            if drop > max_drop
+              max_drop = drop
+              optimal_k = k2  # Use k after the drop
+            end
+          end
+          
+          optimal_k
+        end
+
+        # Find optimal k and return it
+        # @param data [Array] 2D array of data points
+        # @param k_range [Range] Range of k values to try (default: 2..10)
+        # @param max_iter [Integer] Maximum iterations (default: 300)
+        # @return [Integer] Optimal number of clusters
+        def optimal_k(data, k_range: 2..10, max_iter: 300)
+          elbow_results = elbow_method(data, k_range: k_range, max_iter: max_iter)
+          detect_optimal_k(elbow_results)
+        end
+      end
+
+      private
+
+      def validate_data(data)
+        raise ArgumentError, "Data must be an array" unless data.is_a?(Array)
+        raise ArgumentError, "Data cannot be empty" if data.empty?
+        raise ArgumentError, "Data must be 2D array" unless data.first.is_a?(Array)
+        
+        # Check all rows have same length
+        row_length = data.first.length
+        unless data.all? { |row| row.is_a?(Array) && row.length == row_length }
+          raise ArgumentError, "All rows must have the same length"
+        end
+        
+        # Check all values are numeric
+        data.each_with_index do |row, i|
+          row.each_with_index do |val, j|
+            unless val.is_a?(Numeric)
+              raise ArgumentError, "Element at position [#{i}, #{j}] is not numeric"
+            end
+          end
+        end
+      end
+    end
+
+    # Module-level methods for cross-algorithm functionality
+    class << self
+      # Calculate silhouette score for any clustering result
+      # @param data [Array] 2D array of data points
+      # @param labels [Array] Cluster labels
+      # @return [Float] Mean silhouette coefficient
+      def silhouette_score(data, labels)
+        n_samples = data.size
+        unique_labels = labels.uniq
+        
+        return 0.0 if unique_labels.size == 1
+        
+        silhouette_values = []
+        
+        data.each_with_index do |point, i|
+          cluster_label = labels[i]
+          
+          # Calculate mean intra-cluster distance
+          same_cluster_indices = labels.each_index.select { |j| labels[j] == cluster_label && j != i }
+          if same_cluster_indices.empty?
+            silhouette_values << 0.0
+            next
+          end
+          
+          a = same_cluster_indices.sum { |j| euclidean_distance(point, data[j]) } / same_cluster_indices.size.to_f
+          
+          # Calculate mean nearest-cluster distance
+          b = Float::INFINITY
+          unique_labels.each do |other_label|
+            next if other_label == cluster_label
+            
+            other_cluster_indices = labels.each_index.select { |j| labels[j] == other_label }
+            next if other_cluster_indices.empty?
+            
+            mean_dist = other_cluster_indices.sum { |j| euclidean_distance(point, data[j]) } / other_cluster_indices.size.to_f
+            b = mean_dist if mean_dist < b
+          end
+          
+          # Calculate silhouette value for this point
+          if a == 0.0 && b == 0.0
+            s = 0.0  # When all points are identical
+          else
+            s = (b - a) / [a, b].max
+          end
+          silhouette_values << s
+        end
+        
+        silhouette_values.sum / silhouette_values.size.to_f
+      end
+
+      private
+
+      def euclidean_distance(a, b)
+        Math.sqrt(a.zip(b).sum { |x, y| (x - y) ** 2 })
+      end
+    end
+  end
+end

data/lib/clusterkit/clusterkit.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+begin
+  # Try to load the compiled extension
+  require_relative "clusterkit.bundle"
+rescue LoadError
+  # If that fails, try the .so extension (Linux)
+  require_relative "clusterkit.so"
+end

data/lib/clusterkit/configuration.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module ClusterKit
+  class << self
+    attr_accessor :configuration
+  end
+
+  def self.configure
+    self.configuration ||= Configuration.new
+    yield(configuration) if block_given?
+  end
+
+  class Configuration
+    attr_accessor :verbose
+
+    def initialize
+      # Default to quiet unless explicitly set or debug env var is present
+      @verbose = ENV['CLUSTERKIT_VERBOSE'] == 'true' || ENV['DEBUG'] == 'true'
+    end
+  end
+end
+
+# Initialize default configuration
+ClusterKit.configure

data/lib/clusterkit/dimensionality/pca.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+require_relative '../clusterkit'
+require_relative 'svd'
+
+module ClusterKit
+  module Dimensionality
+    # Principal Component Analysis using SVD
+    # PCA is a linear dimensionality reduction technique that finds
+    # the directions of maximum variance in the data
+    class PCA
+    attr_reader :n_components, :components, :explained_variance, :explained_variance_ratio, :mean
+
+    # Initialize PCA
+    # @param n_components [Integer] Number of principal components to keep
+    def initialize(n_components: 2)
+      @n_components = n_components
+      @fitted = false
+    end
+
+    # Fit the PCA model
+    # @param data [Array] 2D array of data points (n_samples × n_features)
+    # @return [self] Returns self for method chaining
+    def fit(data)
+      validate_data(data)
+      
+      # Center the data (subtract mean from each feature)
+      @mean = calculate_mean(data)
+      centered_data = center_data(data, @mean)
+      
+      # Perform SVD on centered data
+      # U contains the transformed data, S contains singular values, VT contains components
+      u, s, vt = ClusterKit.svd(centered_data, @n_components, n_iter: 5)
+      
+      # Store the principal components (eigenvectors)
+      @components = vt  # Shape: (n_components, n_features)
+      
+      # Store singular values for consistency
+      @singular_values = s
+      
+      # Calculate explained variance (eigenvalues)
+      n_samples = data.size.to_f
+      @explained_variance = s.map { |val| (val ** 2) / (n_samples - 1) }
+      
+      # Calculate explained variance ratio
+      total_variance = calculate_total_variance(centered_data, n_samples)
+      @explained_variance_ratio = @explained_variance.map { |var| var / total_variance }
+      
+      @fitted = true
+      self
+    end
+
+    # Transform data using the fitted PCA model
+    # @param data [Array] 2D array of data points
+    # @return [Array] Transformed data in principal component space
+    def transform(data)
+      raise RuntimeError, "Model must be fitted before transform" unless fitted?
+      validate_data(data)
+      
+      # Center the data using the stored mean
+      centered_data = center_data(data, @mean)
+      
+      # Project onto principal components
+      # Result = centered_data × components.T
+      project_data(centered_data, @components)
+    end
+
+    # Fit the model and transform the data in one step
+    # @param data [Array] 2D array of data points
+    # @return [Array] Transformed data  
+    def fit_transform(data)
+      validate_data(data)
+      
+      # Center the data (subtract mean from each feature)
+      @mean = calculate_mean(data)
+      centered_data = center_data(data, @mean)
+      
+      # Perform SVD on centered data
+      u, s, vt = SVD.randomized_svd(centered_data, @n_components, n_iter: 5)
+      
+      # Store the principal components (eigenvectors)
+      @components = vt
+      
+      # Store singular values for later use
+      @singular_values = s
+      
+      # Calculate explained variance (eigenvalues)
+      n_samples = data.size.to_f
+      @explained_variance = s.map { |val| (val ** 2) / (n_samples - 1) }
+      
+      # Calculate explained variance ratio
+      total_variance = calculate_total_variance(centered_data, n_samples)
+      @explained_variance_ratio = @explained_variance.map { |var| var / total_variance }
+      
+      @fitted = true
+      
+      # For PCA, the transformed data is U * S
+      # Scale U by singular values
+      transformed = []
+      u.each do |row|
+        scaled_row = row.each_with_index.map { |val, i| val * s[i] }
+        transformed << scaled_row
+      end
+      transformed
+    end
+
+    # Inverse transform - reconstruct data from principal components
+    # @param data [Array] Transformed data in PC space
+    # @return [Array] Reconstructed data in original space
+    def inverse_transform(data)
+      raise RuntimeError, "Model must be fitted before inverse_transform" unless fitted?
+      
+      # Reconstruct: data × components + mean
+      reconstructed = []
+      data.each do |sample|
+        reconstructed_sample = Array.new(@mean.size, 0.0)
+        
+        sample.each_with_index do |value, i|
+          @components[i].each_with_index do |comp_val, j|
+            reconstructed_sample[j] += value * comp_val
+          end
+        end
+        
+        # Add back the mean
+        reconstructed_sample = reconstructed_sample.zip(@mean).map { |r, m| r + m }
+        reconstructed << reconstructed_sample
+      end
+      
+      reconstructed
+    end
+
+    # Get the amount of variance explained by each component
+    # @return [Array] Explained variance for each component
+    def explained_variance
+      raise RuntimeError, "Model must be fitted first" unless fitted?
+      @explained_variance
+    end
+
+    # Get the percentage of variance explained by each component
+    # @return [Array] Explained variance ratio for each component
+    def explained_variance_ratio
+      raise RuntimeError, "Model must be fitted first" unless fitted?
+      @explained_variance_ratio
+    end
+
+    # Get cumulative explained variance ratio
+    # @return [Array] Cumulative sum of explained variance ratios
+    def cumulative_explained_variance_ratio
+      raise RuntimeError, "Model must be fitted first" unless fitted?
+      
+      cumsum = []
+      sum = 0.0
+      @explained_variance_ratio.each do |ratio|
+        sum += ratio
+        cumsum << sum
+      end
+      cumsum
+    end
+
+    # Check if model has been fitted
+    # @return [Boolean] True if fitted
+    def fitted?
+      @fitted
+    end
+
+    private
+
+    def validate_data(data)
+      raise ArgumentError, "Data must be an array" unless data.is_a?(Array)
+      raise ArgumentError, "Data cannot be empty" if data.empty?
+      raise ArgumentError, "Data must be 2D array" unless data.first.is_a?(Array)
+      
+      # Check all rows have same length
+      row_length = data.first.length
+      unless data.all? { |row| row.is_a?(Array) && row.length == row_length }
+        raise ArgumentError, "All rows must have the same length"
+      end
+      
+      # Check we have enough samples for n_components
+      if data.size < @n_components
+        raise ArgumentError, "n_components (#{@n_components}) cannot be larger than n_samples (#{data.size})"
+      end
+      
+      if data.first.size < @n_components
+        raise ArgumentError, "n_components (#{@n_components}) cannot be larger than n_features (#{data.first.size})"
+      end
+    end
+
+    def calculate_mean(data)
+      n_features = data.first.size
+      mean = Array.new(n_features, 0.0)
+      
+      data.each do |row|
+        row.each_with_index do |val, i|
+          mean[i] += val
+        end
+      end
+      
+      mean.map { |sum| sum / data.size.to_f }
+    end
+
+    def center_data(data, mean)
+      data.map do |row|
+        row.zip(mean).map { |val, m| val - m }
+      end
+    end
+
+    def calculate_total_variance(centered_data, n_samples)
+      total_var = 0.0
+      
+      centered_data.each do |row|
+        row.each do |val|
+          total_var += val ** 2
+        end
+      end
+      
+      total_var / (n_samples - 1)
+    end
+
+    def project_data(centered_data, components)
+      # Matrix multiplication: centered_data × components.T
+      transformed = []
+      
+      centered_data.each do |sample|
+        projected = Array.new(@n_components, 0.0)
+        
+        components.each_with_index do |component, i|
+          dot_product = 0.0
+          sample.each_with_index do |val, j|
+            dot_product += val * component[j]
+          end
+          projected[i] = dot_product
+        end
+        
+        transformed << projected
+      end
+      
+      transformed
+    end
+  end
+
+  # Module-level convenience method
+  # @param data [Array] 2D array of data points
+  # @param n_components [Integer] Number of components
+  # @return [Array] Transformed data
+  def self.pca(data, n_components: 2)
+    pca = PCA.new(n_components: n_components)
+    pca.fit_transform(data)
+    end
+  end
+end