clusterkit 0.1.0.pre.1

data/lib/clusterkit/preprocessing.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+# Pure Ruby implementation of preprocessing functions
+
+module ClusterKit
+  # Data preprocessing utilities
+  module Preprocessing
+    class << self
+      # Normalize data using specified method
+      # @param data [Array] Input data (2D array)
+      # @param method [Symbol] Normalization method (:standard, :minmax, :l2)
+      # @return [Array] Normalized data
+      def normalize(data, method: :standard)
+        raise ArgumentError, "Unsupported data type: #{data.class}" unless data.is_a?(Array)
+        
+        case method
+        when :standard
+          standard_normalize(data)
+        when :minmax
+          minmax_normalize(data)
+        when :l2
+          l2_normalize(data)
+        else
+          raise ArgumentError, "Unknown normalization method: #{method}"
+        end
+      end
+
+      # Reduce dimensionality using PCA before embedding
+      # @param data [Array] Input data
+      # @param n_components [Integer] Number of PCA components
+      # @return [Array] Reduced data
+      def pca_reduce(data, n_components)
+        # Note: This would require SVD implementation in pure Ruby
+        # For now, raise an error suggesting to use the Rust-based SVD module
+        raise NotImplementedError, "PCA reduction requires the SVD module which needs to be called directly"
+      end
+
+      private
+
+      def standard_normalize(data)
+        # Pure Ruby implementation of standard normalization
+        return data if data.empty?
+        
+        # Calculate mean and std for each column
+        n_rows = data.size
+        n_cols = data.first.size
+        
+        means = Array.new(n_cols, 0.0)
+        stds = Array.new(n_cols, 0.0)
+        
+        # Calculate means
+        data.each do |row|
+          row.each_with_index { |val, j| means[j] += val }
+        end
+        means.map! { |m| m / n_rows }
+        
+        # Calculate standard deviations
+        data.each do |row|
+          row.each_with_index { |val, j| stds[j] += (val - means[j]) ** 2 }
+        end
+        stds.map! { |s| Math.sqrt(s / n_rows) }
+        stds.map! { |s| s == 0 ? 1.0 : s } # Avoid division by zero
+        
+        # Normalize
+        data.map do |row|
+          row.map.with_index { |val, j| (val - means[j]) / stds[j] }
+        end
+      end
+
+      def minmax_normalize(data)
+        # Pure Ruby implementation of min-max normalization
+        return data if data.empty?
+        
+        n_cols = data.first.size
+        mins = Array.new(n_cols) { Float::INFINITY }
+        maxs = Array.new(n_cols) { -Float::INFINITY }
+        
+        # Find min and max for each column
+        data.each do |row|
+          row.each_with_index do |val, j|
+            mins[j] = val if val < mins[j]
+            maxs[j] = val if val > maxs[j]
+          end
+        end
+        
+        # Calculate ranges
+        ranges = mins.zip(maxs).map { |min, max| max - min }
+        ranges.map! { |r| r == 0 ? 1.0 : r } # Avoid division by zero
+        
+        # Normalize
+        data.map do |row|
+          row.map.with_index { |val, j| (val - mins[j]) / ranges[j] }
+        end
+      end
+
+      def l2_normalize(data)
+        # Pure Ruby implementation of L2 normalization
+        data.map do |row|
+          norm = Math.sqrt(row.sum { |val| val ** 2 })
+          norm = 1.0 if norm == 0 # Avoid division by zero
+          row.map { |val| val / norm }
+        end
+      end
+    end
+  end
+end

data/lib/clusterkit/silence.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module ClusterKit
+  # Module to suppress stdout output from the Rust library
+  # Following the pattern used by Rails/ActiveSupport and other popular gems
+  module Silence
+    # Temporarily silence stdout and stderr
+    # This is the most idiomatic Ruby way to suppress output from C/Rust extensions
+    # 
+    # @example
+    #   ClusterKit::Silence.silence_stream(STDOUT) do
+    #     # code that produces unwanted output
+    #   end
+    def self.silence_stream(stream)
+      old_stream = stream.dup
+      stream.reopen(File::NULL)
+      stream.sync = true
+      yield
+    ensure
+      stream.reopen(old_stream)
+      old_stream.close
+    end
+
+    # Silence both stdout and stderr
+    def self.silence_output
+      silence_stream(STDOUT) do
+        silence_stream(STDERR) do
+          yield
+        end
+      end
+    end
+
+    # Conditionally silence based on configuration
+    def self.maybe_silence
+      if ClusterKit.configuration.verbose
+        yield
+      else
+        silence_output { yield }
+      end
+    end
+  end
+end

data/lib/clusterkit/utils.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# Pure Ruby utility functions
+
+module ClusterKit
+  # Utility functions for data analysis
+  module Utils
+    class << self
+      # Estimate the intrinsic dimension of data
+      # @param data [Array, Numo::NArray] Input data
+      # @param k_neighbors [Integer] Number of neighbors to consider
+      # @return [Float] Estimated intrinsic dimension
+      def estimate_intrinsic_dimension(data, k_neighbors: 10)
+        raise ArgumentError, "Unsupported data type: #{data.class}" unless data.is_a?(Array)
+        
+        estimate_intrinsic_dimension_rust(data, k_neighbors)
+      end
+
+      # Estimate hubness in the data
+      # @param data [Array, Numo::NArray] Input data
+      # @return [Hash] Hubness statistics
+      def estimate_hubness(data)
+        raise ArgumentError, "Unsupported data type: #{data.class}" unless data.is_a?(Array)
+        
+        result = estimate_hubness_rust(data)
+        symbolize_keys(result)
+      end
+
+      # Measure neighborhood stability through embedding
+      # @param original_data [Array, Numo::NArray] Original high-dimensional data
+      # @param embedded_data [Array, Numo::NArray] Embedded low-dimensional data
+      # @param k [Integer] Number of neighbors to check
+      # @return [Float] Stability score (0-1, higher is better)
+      def neighborhood_stability(original_data, embedded_data, k: 15)
+        raise ArgumentError, "Unsupported data type: #{original_data.class}" unless original_data.is_a?(Array)
+        raise ArgumentError, "Unsupported data type: #{embedded_data.class}" unless embedded_data.is_a?(Array)
+        
+        # TODO: Implement neighborhood stability calculation
+        raise NotImplementedError, "Neighborhood stability not implemented yet"
+      end
+
+      private
+
+      def symbolize_keys(hash)
+        return hash unless hash.is_a?(Hash)
+        
+        hash.transform_keys { |key| key.to_s.to_sym }
+      end
+    end
+  end
+end

data/lib/clusterkit/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ClusterKit
+  VERSION = "0.1.0.pre.1"
+end

data/lib/clusterkit.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative "clusterkit/version"
+require_relative "clusterkit/clusterkit"
+require_relative "clusterkit/configuration"
+
+# Main module for ClusterKit gem
+# Provides high-performance dimensionality reduction algorithms
+module ClusterKit
+  class Error < StandardError; end
+
+
+  # Core error classes
+  class DimensionError < Error; end
+  class ConvergenceError < Error; end
+  class InvalidParameterError < Error; end
+  
+  # Data-related errors
+  class DataError < Error; end
+  class IsolatedPointError < DataError; end
+  class DisconnectedGraphError < DataError; end
+  class InsufficientDataError < DataError; end
+
+  # Load modules - can't use autoload with require_relative path issues
+  require_relative "clusterkit/dimensionality"
+  require_relative "clusterkit/clustering"
+  
+  # Autoload utilities
+  autoload :Utils, "clusterkit/utils"
+  autoload :Preprocessing, "clusterkit/preprocessing"
+  autoload :Silence, "clusterkit/silence"
+  
+  # Load the extension first
+  require_relative "clusterkit/clusterkit"
+  
+  # Now load the modules that depend on the extension
+  require_relative "clusterkit/clustering"
+
+  class << self
+    # Quick UMAP embedding
+    # @param data [Array] Input data
+    # @param n_components [Integer] Number of dimensions in output
+    # @return [Array] Embedded data
+    def umap(data, n_components: 2, **options)
+      umap = Dimensionality::UMAP.new(n_components: n_components, **options)
+      umap.fit_transform(data)
+    end
+    
+    # Quick PCA
+    # @param data [Array] Input data
+    # @param n_components [Integer] Number of dimensions in output
+    # @return [Array] Transformed data
+    def pca(data, n_components: 2)
+      pca = Dimensionality::PCA.new(n_components: n_components)
+      pca.fit_transform(data)
+    end
+
+    # t-SNE is not yet implemented
+    # @deprecated Not implemented - use UMAP instead
+    def tsne(data, n_components: 2, **options)
+      raise NotImplementedError, "t-SNE is not yet implemented. Please use UMAP instead, which provides similar dimensionality reduction capabilities."
+    end
+
+    # Estimate intrinsic dimension of data
+    # @param data [Array, Numo::NArray] Input data
+    # @param k [Integer] Number of neighbors to consider
+    # @return [Float] Estimated intrinsic dimension
+    def estimate_dimension(data, k: 10)
+      Utils.estimate_intrinsic_dimension(data, k_neighbors: k)
+    end
+
+    # Perform SVD
+    # @param matrix [Array] Input matrix
+    # @param k [Integer] Number of components
+    # @param n_iter [Integer] Number of iterations for randomized algorithm
+    # @return [Array] U, S, V matrices
+    def svd(matrix, k, n_iter: 2)
+      svd = Dimensionality::SVD.new(n_components: k, n_iter: n_iter)
+      svd.fit_transform(matrix)
+    end
+    
+    # Quick K-means with automatic k detection
+    # @param data [Array] Input data
+    # @param k [Integer, nil] Number of clusters (auto-detect if nil)
+    # @param k_range [Range] Range for auto-detection
+    # @return [Array] Cluster labels
+    def kmeans(data, k: nil, k_range: 2..10, **options)
+      k ||= Clustering::KMeans.optimal_k(data, k_range: k_range)
+      kmeans = Clustering::KMeans.new(k: k, **options)
+      kmeans.fit_predict(data)
+    end
+  end
+end