irt_ruby 0.1.0 → 0.3.0

data/benchmarks/performance_benchmark.rb

@@ -0,0 +1,153 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "irt_ruby"
+require "benchmark/ips"
+require "memory_profiler"
+
+# Generate test data of different sizes
+def generate_data(num_people, num_items, missing_rate: 0.0)
+  Array.new(num_people) do
+    Array.new(num_items) do
+      if rand < missing_rate
+        nil
+      else
+        rand < 0.6 ? 1 : 0 # 60% probability of correct response
+      end
+    end
+  end
+end
+
+# Dataset configurations
+DATASET_CONFIGS = [
+  { people: 10, items: 5, label: "Tiny (10x5)" },
+  { people: 50, items: 20, label: "Small (50x20)" },
+  { people: 100, items: 50, label: "Medium (100x50)" },
+  { people: 200, items: 100, label: "Large (200x100)" },
+  { people: 500, items: 200, label: "XLarge (500x200)" }
+].freeze
+
+puts "=" * 60
+puts "IRT Ruby Performance Benchmarks"
+puts "=" * 60
+puts
+
+# Benchmark each model type across different dataset sizes
+DATASET_CONFIGS.each do |config|
+  puts "Dataset: #{config[:label]}"
+  puts "-" * 40
+
+  data = generate_data(config[:people], config[:items])
+
+  Benchmark.ips do |x|
+    x.config(time: 5, warmup: 2)
+
+    x.report("Rasch Model") do
+      model = IrtRuby::RaschModel.new(data, max_iter: 100)
+      model.fit
+    end
+
+    x.report("2PL Model") do
+      model = IrtRuby::TwoParameterModel.new(data, max_iter: 100)
+      model.fit
+    end
+
+    x.report("3PL Model") do
+      model = IrtRuby::ThreeParameterModel.new(data, max_iter: 100)
+      model.fit
+    end
+
+    x.compare!
+  end
+
+  puts
+end
+
+# Memory usage analysis for medium dataset
+puts "=" * 60
+puts "Memory Usage Analysis (Medium Dataset: 100x50)"
+puts "=" * 60
+
+data = generate_data(100, 50)
+
+%i[RaschModel TwoParameterModel ThreeParameterModel].each do |model_class|
+  puts "\n#{model_class}:"
+  puts "-" * 20
+
+  report = MemoryProfiler.report do
+    model = IrtRuby.const_get(model_class).new(data, max_iter: 100)
+    model.fit
+  end
+
+  puts "Total allocated: #{report.total_allocated_memsize} bytes"
+  puts "Total retained:  #{report.total_retained_memsize} bytes"
+  puts "Objects allocated: #{report.total_allocated}"
+  puts "Objects retained:  #{report.total_retained}"
+end
+
+# Scaling analysis - how performance changes with dataset size
+puts "\n#{"=" * 60}"
+puts "Scaling Analysis - Rasch Model Only"
+puts "=" * 60
+
+scaling_results = {}
+
+DATASET_CONFIGS.each do |config|
+  data = generate_data(config[:people], config[:items])
+
+  times = []
+  5.times do
+    start_time = Time.now
+    model = IrtRuby::RaschModel.new(data, max_iter: 100)
+    model.fit
+    end_time = Time.now
+    times << (end_time - start_time)
+  end
+
+  avg_time = times.sum / times.size
+  scaling_results[config[:label]] = {
+    size: config[:people] * config[:items],
+    avg_time: avg_time,
+    people: config[:people],
+    items: config[:items]
+  }
+
+  puts "#{config[:label]}: #{avg_time.round(4)}s (#{config[:people] * config[:items]} data points)"
+end
+
+# Calculate scaling coefficient
+puts "\nScaling Analysis:"
+puts "-" * 20
+scaling_results.each_cons(2) do |(label1, data1), (label2, data2)|
+  size_ratio = data2[:size].to_f / data1[:size]
+  time_ratio = data2[:avg_time] / data1[:avg_time]
+  scaling_factor = Math.log(time_ratio) / Math.log(size_ratio)
+
+  puts "#{label1} -> #{label2}: #{size_ratio.round(2)}x size, #{time_ratio.round(2)}x time (O(n^#{scaling_factor.round(2)}))"
+end
+
+# Missing data performance impact
+puts "\n#{"=" * 60}"
+puts "Missing Data Strategy Performance Impact"
+puts "=" * 60
+
+data_with_missing = generate_data(100, 50, missing_rate: 0.2)
+
+%i[ignore treat_as_incorrect treat_as_correct].each do |strategy|
+  puts "\nMissing Strategy: #{strategy}"
+  puts "-" * 30
+
+  Benchmark.ips do |x|
+    x.config(time: 3, warmup: 1)
+
+    x.report("Rasch") do
+      model = IrtRuby::RaschModel.new(data_with_missing, max_iter: 50, missing_strategy: strategy)
+      model.fit
+    end
+  end
+end
+
+puts "\n#{"=" * 60}"
+puts "Benchmark Complete!"
+puts "=" * 60

data/lib/irt_ruby/rasch_model.rb

@@ -1,58 +1,148 @@
 # frozen_string_literal: true
 
-require "matrix"
-
 module IrtRuby
-  # A class representing the Rasch model for Item Response Theory.
+  # A class representing the Rasch model for Item Response Theory (ability - difficulty).
+  # Incorporates:
+  # - Adaptive learning rate
+  # - Missing data handling (skip nil)
+  # - Multiple convergence checks (log-likelihood + parameter updates)
   class RaschModel
-    def initialize(data, max_iter: 1000, tolerance: 1e-6, learning_rate: 0.01)
+    MISSING_STRATEGIES = %i[ignore treat_as_incorrect treat_as_correct].freeze
+
+    def initialize(data,
+                   max_iter: 1000,
+                   tolerance: 1e-6,
+                   param_tolerance: 1e-6,
+                   learning_rate: 0.01,
+                   decay_factor: 0.5,
+                   missing_strategy: :ignore)
+      # data: A Matrix or array-of-arrays of responses (0/1 or nil for missing).
+      # missing_strategy: :ignore (skip), :treat_as_incorrect, :treat_as_correct
+
       @data = data
-      @abilities = Array.new(data.row_count) { rand }
-      @difficulties = Array.new(data.column_count) { rand }
-      @max_iter = max_iter
-      @tolerance = tolerance
-      @learning_rate = learning_rate
+      @data_array = data.to_a
+      num_rows = @data_array.size
+      num_cols = @data_array.first.size
+
+      raise ArgumentError, "missing_strategy must be one of #{MISSING_STRATEGIES}" unless MISSING_STRATEGIES.include?(missing_strategy)
+
+      @missing_strategy = missing_strategy
+
+      # Initialize parameters near zero
+      @abilities    = Array.new(num_rows)  { rand(-0.25..0.25) }
+      @difficulties = Array.new(num_cols)  { rand(-0.25..0.25) }
+
+      @max_iter        = max_iter
+      @tolerance       = tolerance
+      @param_tolerance = param_tolerance
+      @learning_rate   = learning_rate
+      @decay_factor    = decay_factor
     end
 
-    # Sigmoid function to calculate probability
     def sigmoid(x)
       1.0 / (1.0 + Math.exp(-x))
     end
 
-    # Calculate the log-likelihood of the data given the current parameters
-    def likelihood
-      likelihood = 0
-      @data.row_vectors.each_with_index do |row, i|
-        row.to_a.each_with_index do |response, j|
+    def resolve_missing(resp)
+      return [resp, false] unless resp.nil?
+
+      case @missing_strategy
+      when :ignore
+        [nil, true]
+      when :treat_as_incorrect
+        [0, false]
+      when :treat_as_correct
+        [1, false]
+      end
+    end
+
+    def log_likelihood
+      total_ll = 0.0
+      @data_array.each_with_index do |row, i|
+        row.each_with_index do |resp, j|
+          value, skip = resolve_missing(resp)
+          next if skip
+
           prob = sigmoid(@abilities[i] - @difficulties[j])
-          likelihood += response == 1 ? Math.log(prob) : Math.log(1 - prob)
+          total_ll += if value == 1
+                        Math.log(prob + 1e-15)
+                      else
+                        Math.log((1 - prob) + 1e-15)
+                      end
         end
       end
-      likelihood
+      total_ll
     end
 
-    # Update parameters using gradient ascent
-    def update_parameters
-      last_likelihood = likelihood
-      @max_iter.times do |_iter|
-        @data.row_vectors.each_with_index do |row, i|
-          row.to_a.each_with_index do |response, j|
-            prob = sigmoid(@abilities[i] - @difficulties[j])
-            error = response - prob
-            @abilities[i] += @learning_rate * error
-            @difficulties[j] -= @learning_rate * error
-          end
+    def compute_gradient
+      grad_abilities    = Array.new(@abilities.size, 0.0)
+      grad_difficulties = Array.new(@difficulties.size, 0.0)
+
+      @data_array.each_with_index do |row, i|
+        row.each_with_index do |resp, j|
+          value, skip = resolve_missing(resp)
+          next if skip
+
+          prob = sigmoid(@abilities[i] - @difficulties[j])
+          error = value - prob
+
+          grad_abilities[i]    += error
+          grad_difficulties[j] -= error
         end
-        current_likelihood = likelihood
-        break if (last_likelihood - current_likelihood).abs < @tolerance
+      end
 
-        last_likelihood = current_likelihood
+      [grad_abilities, grad_difficulties]
+    end
+
+    def apply_gradient_update(grad_abilities, grad_difficulties)
+      old_abilities    = @abilities.dup
+      old_difficulties = @difficulties.dup
+
+      @abilities.each_index do |i|
+        @abilities[i] += @learning_rate * grad_abilities[i]
+      end
+
+      @difficulties.each_index do |j|
+        @difficulties[j] += @learning_rate * grad_difficulties[j]
+      end
+
+      [old_abilities, old_difficulties]
+    end
+
+    def average_param_update(old_abilities, old_difficulties)
+      deltas = []
+      @abilities.each_with_index do |a, i|
+        deltas << (a - old_abilities[i]).abs
+      end
+      @difficulties.each_with_index do |d, j|
+        deltas << (d - old_difficulties[j]).abs
       end
+      deltas.sum / deltas.size
     end
 
-    # Fit the model to the data
     def fit
-      update_parameters
+      prev_ll = log_likelihood
+
+      @max_iter.times do
+        grad_abilities, grad_difficulties = compute_gradient
+
+        old_a, old_d = apply_gradient_update(grad_abilities, grad_difficulties)
+
+        current_ll  = log_likelihood
+        param_delta = average_param_update(old_a, old_d)
+
+        if current_ll < prev_ll
+          @abilities    = old_a
+          @difficulties = old_d
+          @learning_rate *= @decay_factor
+        else
+          ll_diff = (current_ll - prev_ll).abs
+          break if ll_diff < @tolerance && param_delta < @param_tolerance
+
+          prev_ll = current_ll
+        end
+      end
+
       { abilities: @abilities, difficulties: @difficulties }
     end
   end

data/lib/irt_ruby/three_parameter_model.rb

@@ -1,68 +1,181 @@
 # frozen_string_literal: true
 
-require "matrix"
-
 module IrtRuby
-  # A class representing the Three-Parameter model for Item Response Theory.
+  # A class representing the Three-Parameter model (3PL) for Item Response Theory.
+  # Incorporates:
+  # - Adaptive learning rate
+  # - Missing data handling
+  # - Parameter clamping for discrimination, guessing
+  # - Multiple convergence checks
+  # - Separate gradient calculation & updates
   class ThreeParameterModel
-    def initialize(data, max_iter: 1000, tolerance: 1e-6, learning_rate: 0.01)
+    MISSING_STRATEGIES = %i[ignore treat_as_incorrect treat_as_correct].freeze
+
+    def initialize(data,
+                   max_iter: 1000,
+                   tolerance: 1e-6,
+                   param_tolerance: 1e-6,
+                   learning_rate: 0.01,
+                   decay_factor: 0.5,
+                   missing_strategy: :ignore)
       @data = data
-      @abilities = Array.new(data.row_count) { rand }
-      @difficulties = Array.new(data.column_count) { rand }
-      @discriminations = Array.new(data.column_count) { rand }
-      @guessings = Array.new(data.column_count) { rand * 0.3 }
-      @max_iter = max_iter
-      @tolerance = tolerance
-      @learning_rate = learning_rate
+      @data_array = data.to_a
+      num_rows = @data_array.size
+      num_cols = @data_array.first.size
+
+      raise ArgumentError, "missing_strategy must be one of #{MISSING_STRATEGIES}" unless MISSING_STRATEGIES.include?(missing_strategy)
+
+      @missing_strategy = missing_strategy
+
+      # Initialize parameters
+      @abilities       = Array.new(num_rows)  { rand(-0.25..0.25) }
+      @difficulties    = Array.new(num_cols)  { rand(-0.25..0.25) }
+      @discriminations = Array.new(num_cols)  { rand(0.5..1.5) }
+      @guessings       = Array.new(num_cols)  { rand(0.0..0.3) }
+
+      @max_iter        = max_iter
+      @tolerance       = tolerance
+      @param_tolerance = param_tolerance
+      @learning_rate   = learning_rate
+      @decay_factor    = decay_factor
     end
 
-    # Sigmoid function to calculate probability
     def sigmoid(x)
       1.0 / (1.0 + Math.exp(-x))
     end
 
-    # Probability function for the 3PL model
+    # Probability for the 3PL model: c + (1-c)*sigmoid(a*(θ - b))
     def probability(theta, a, b, c)
-      c + (1 - c) * sigmoid(a * (theta - b))
+      c + ((1.0 - c) * sigmoid(a * (theta - b)))
+    end
+
+    def resolve_missing(resp)
+      return [resp, false] unless resp.nil?
+
+      case @missing_strategy
+      when :ignore
+        [nil, true]
+      when :treat_as_incorrect
+        [0, false]
+      when :treat_as_correct
+        [1, false]
+      end
     end
 
-    # Calculate the log-likelihood of the data given the current parameters
-    def likelihood
-      likelihood = 0
-      @data.row_vectors.each_with_index do |row, i|
-        row.to_a.each_with_index do |response, j|
-          prob = probability(@abilities[i], @discriminations[j], @difficulties[j], @guessings[j])
-          likelihood += response == 1 ? Math.log(prob) : Math.log(1 - prob)
+    def log_likelihood
+      ll = 0.0
+      @data_array.each_with_index do |row, i|
+        row.each_with_index do |resp, j|
+          value, skip = resolve_missing(resp)
+          next if skip
+
+          prob = probability(@abilities[i],
+                             @discriminations[j],
+                             @difficulties[j],
+                             @guessings[j])
+
+          ll += if value == 1
+                  Math.log(prob + 1e-15)
+                else
+                  Math.log((1 - prob) + 1e-15)
+                end
         end
       end
-      likelihood
+      ll
     end
 
-    # Update parameters using gradient ascent
-    def update_parameters
-      last_likelihood = likelihood
-      @max_iter.times do |_iter|
-        @data.row_vectors.each_with_index do |row, i|
-          row.to_a.each_with_index do |response, j|
-            prob = probability(@abilities[i], @discriminations[j], @difficulties[j], @guessings[j])
-            error = response - prob
-            @abilities[i] += @learning_rate * error * @discriminations[j]
-            @difficulties[j] -= @learning_rate * error * @discriminations[j]
-            @discriminations[j] += @learning_rate * error * (@abilities[i] - @difficulties[j])
-            @guessings[j] += @learning_rate * error * (1 - prob)
-            @guessings[j] = [[@guessings[j], 0].max, 1].min # Keep guessings within [0, 1]
-          end
+    def compute_gradient
+      grad_abilities       = Array.new(@abilities.size, 0.0)
+      grad_difficulties    = Array.new(@difficulties.size, 0.0)
+      grad_discriminations = Array.new(@discriminations.size, 0.0)
+      grad_guessings       = Array.new(@guessings.size, 0.0)
+
+      @data_array.each_with_index do |row, i|
+        row.each_with_index do |resp, j|
+          value, skip = resolve_missing(resp)
+          next if skip
+
+          theta = @abilities[i]
+          a     = @discriminations[j]
+          b     = @difficulties[j]
+          c     = @guessings[j]
+
+          prob  = probability(theta, a, b, c)
+          error = value - prob
+
+          grad_abilities[i]       += error * a * (1 - c)
+          grad_difficulties[j]    -= error * a * (1 - c)
+          grad_discriminations[j] += error * (theta - b) * (1 - c)
+
+          grad_guessings[j]       += error * 1.0
         end
-        current_likelihood = likelihood
-        break if (last_likelihood - current_likelihood).abs < @tolerance
+      end
 
-        last_likelihood = current_likelihood
+      [grad_abilities, grad_difficulties, grad_discriminations, grad_guessings]
+    end
+
+    def apply_gradient_update(ga, gd, gdisc, gc)
+      old_a    = @abilities.dup
+      old_d    = @difficulties.dup
+      old_disc = @discriminations.dup
+      old_c    = @guessings.dup
+
+      @abilities.each_index do |i|
+        @abilities[i] += @learning_rate * ga[i]
       end
+
+      @difficulties.each_index do |j|
+        @difficulties[j] += @learning_rate * gd[j]
+      end
+
+      @discriminations.each_index do |j|
+        @discriminations[j] += @learning_rate * gdisc[j]
+        @discriminations[j] = 0.01 if @discriminations[j] < 0.01
+        @discriminations[j] = 5.0  if @discriminations[j] > 5.0
+      end
+
+      @guessings.each_index do |j|
+        @guessings[j] += @learning_rate * gc[j]
+        @guessings[j] = 0.0  if @guessings[j] < 0.0
+        @guessings[j] = 0.35 if @guessings[j] > 0.35
+      end
+
+      [old_a, old_d, old_disc, old_c]
+    end
+
+    def average_param_update(old_a, old_d, old_disc, old_c)
+      deltas = []
+      @abilities.each_with_index       { |x, i| deltas << (x - old_a[i]).abs }
+      @difficulties.each_with_index    { |x, j| deltas << (x - old_d[j]).abs }
+      @discriminations.each_with_index { |x, j| deltas << (x - old_disc[j]).abs }
+      @guessings.each_with_index       { |x, j| deltas << (x - old_c[j]).abs }
+      deltas.sum / deltas.size
     end
 
-    # Fit the model to the data
     def fit
-      update_parameters
+      prev_ll = log_likelihood
+
+      @max_iter.times do
+        ga, gd, gdisc, gc = compute_gradient
+        old_a, old_d, old_disc, old_c = apply_gradient_update(ga, gd, gdisc, gc)
+
+        curr_ll     = log_likelihood
+        param_delta = average_param_update(old_a, old_d, old_disc, old_c)
+
+        if curr_ll < prev_ll
+          @abilities       = old_a
+          @difficulties    = old_d
+          @discriminations = old_disc
+          @guessings       = old_c
+          @learning_rate  *= @decay_factor
+        else
+          ll_diff = (curr_ll - prev_ll).abs
+          break if ll_diff < @tolerance && param_delta < @param_tolerance
+
+          prev_ll = curr_ll
+        end
+      end
+
       {
         abilities: @abilities,
         difficulties: @difficulties,