irt_ruby 0.2.0 → 0.4.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/estimation.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module IrtRuby
+  # Numerical helpers shared by IRT model implementations.
+  # @api private
+  module Estimation
+    # Learning-rate multiplier after an accepted step, so the rate can recover from earlier decays.
+    LEARNING_RATE_GROWTH = 1.1
+
+    module_function
+
+    def log_sigmoid(x)
+      x >= 0 ? -Math.log(1.0 + Math.exp(-x)) : x - Math.log(1.0 + Math.exp(x))
+    end
+
+    def each_response(responses, persons, items)
+      responses.each_with_index do |row, i|
+        next unless persons[i]
+
+        row.each_with_index do |value, j|
+          next if value.nil? || !items[j]
+
+          yield i, j, value
+        end
+      end
+    end
+
+    def response_counts(responses, persons, items)
+      person_counts = Array.new(responses.size, 0)
+      item_counts = Array.new(responses.first.size, 0)
+      each_response(responses, persons, items) do |i, j, _value|
+        person_counts[i] += 1
+        item_counts[j] += 1
+      end
+      [person_counts, item_counts]
+    end
+
+    # True when every gradient component, averaged over the responses it sums, is below tolerance.
+    def stationary?(person_gradient, item_gradients, person_counts, item_counts, tolerance)
+      small_residuals?(person_gradient, person_counts, tolerance) &&
+        item_gradients.all? { |gradient| small_residuals?(gradient, item_counts, tolerance) }
+    end
+
+    def small_residuals?(gradient, counts, tolerance)
+      gradient.each_index.all? { |k| counts[k].zero? || (gradient[k] / counts[k]).abs < tolerance }
+    end
+
+    # Drops gradient components that push a parameter further past the bound it sits on.
+    def project(gradient, values, min, max)
+      gradient.each_index.map do |k|
+        blocked = (values[k] <= min && gradient[k].negative?) || (values[k] >= max && gradient[k].positive?)
+        blocked ? 0.0 : gradient[k]
+      end
+    end
+
+    # Location and scale of the estimable abilities, used to report parameters on a fixed scale.
+    def scale(abilities, active)
+      values = abilities.select.with_index { |_, i| active[i] }
+      return [0.0, 1.0] if values.empty?
+
+      mean, sd = mean_and_sd(values)
+      [mean, sd.zero? ? 1.0 : sd]
+    end
+
+    def mean_and_sd(values)
+      mean = values.sum / values.size
+      [mean, Math.sqrt(values.sum { |v| (v - mean)**2 } / values.size)]
+    end
+
+    def changes(current, previous, active)
+      current.each_index.select { |k| active[k] }.map { |k| (current[k] - previous[k]).abs }
+    end
+
+    def estimates(values, active)
+      values.each_index.map { |k| active[k] ? values[k] : nil }
+    end
+  end
+end

data/lib/irt_ruby/model_options_validator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module IrtRuby
+  # Validates optimization hyperparameters shared by IRT model implementations.
+  module ModelOptionsValidator
+    module_function
+
+    def validate!(max_iter:, tolerance:, param_tolerance:, gradient_tolerance:, learning_rate:, decay_factor:)
+      validate_positive_integer!(:max_iter, max_iter)
+      validate_positive_finite_numeric!(:tolerance, tolerance)
+      validate_positive_finite_numeric!(:param_tolerance, param_tolerance)
+      validate_positive_finite_numeric!(:gradient_tolerance, gradient_tolerance)
+      validate_positive_finite_numeric!(:learning_rate, learning_rate)
+      validate_decay_factor!(decay_factor)
+    end
+
+    def validate_positive_integer!(name, value)
+      return if value.is_a?(Integer) && value.positive?
+
+      raise ArgumentError, "#{name} must be a positive Integer"
+    end
+
+    def validate_positive_finite_numeric!(name, value)
+      return if finite_numeric?(value) && value.positive?
+
+      raise ArgumentError, "#{name} must be a positive finite Numeric"
+    end
+
+    def validate_decay_factor!(value)
+      return if finite_numeric?(value) && value.positive? && value < 1
+
+      raise ArgumentError, "decay_factor must be a finite Numeric strictly between 0 and 1"
+    end
+
+    def finite_numeric?(value)
+      value.is_a?(Numeric) && !value.is_a?(Complex) && value.finite?
+    end
+  end
+end

data/lib/irt_ruby/rasch_model.rb

@@ -1,11 +1,18 @@
 # frozen_string_literal: true
 
+require "irt_ruby/estimation"
+require "irt_ruby/model_options_validator"
+require "irt_ruby/response_data_validator"
+require "irt_ruby/response_graph"
+
 module IrtRuby
   # 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)
+  # - Exclusion of extreme response patterns, which have no finite estimates
+  # - Identification by reporting abilities centered at zero
   class RaschModel
     MISSING_STRATEGIES = %i[ignore treat_as_incorrect treat_as_correct].freeze
 
@@ -13,36 +20,55 @@ module IrtRuby
                    max_iter: 1000,
                    tolerance: 1e-6,
                    param_tolerance: 1e-6,
+                   gradient_tolerance: 1e-3,
                    learning_rate: 0.01,
                    decay_factor: 0.5,
-                   missing_strategy: :ignore)
+                   missing_strategy: :ignore,
+                   seed: nil)
       # 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
-      @data_array = data.to_a
-      num_rows = @data_array.size
-      num_cols = @data_array.first.size
+      ModelOptionsValidator.validate!(max_iter: max_iter,
+                                      tolerance: tolerance,
+                                      param_tolerance: param_tolerance,
+                                      gradient_tolerance: gradient_tolerance,
+                                      learning_rate: learning_rate,
+                                      decay_factor: decay_factor)
+
+      data_array = ResponseDataValidator.validate!(data)
+      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
+      @random = seed.nil? ? nil : Random.new(seed)
+
+      @responses = data_array.map { |row| row.map { |resp| resolve_missing(resp).first } }
+      @active_persons, @active_items = ResponseGraph.estimable(@responses)
+      @person_counts, @item_counts = Estimation.response_counts(@responses, @active_persons, @active_items)
 
       # 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
+      @abilities    = Array.new(num_rows)  { random_between(-0.25..0.25) }
+      @difficulties = Array.new(num_cols)  { random_between(-0.25..0.25) }
+
+      @max_iter           = max_iter
+      @tolerance          = tolerance
+      @param_tolerance    = param_tolerance
+      @gradient_tolerance = gradient_tolerance
+      @learning_rate      = learning_rate
+      @decay_factor       = decay_factor
     end
 
     def sigmoid(x)
       1.0 / (1.0 + Math.exp(-x))
     end
 
+    def random_between(range)
+      @random ? @random.rand(range) : rand(range)
+    end
+    private :random_between
+
     def resolve_missing(resp)
       return [resp, false] unless resp.nil?
 
@@ -58,18 +84,9 @@ module IrtRuby
 
     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])
-          total_ll += if value == 1
-                        Math.log(prob + 1e-15)
-                      else
-                        Math.log((1 - prob) + 1e-15)
-                      end
-        end
+      Estimation.each_response(@responses, @active_persons, @active_items) do |i, j, value|
+        z = @abilities[i] - @difficulties[j]
+        total_ll += Estimation.log_sigmoid(value == 1 ? z : -z)
       end
       total_ll
     end
@@ -78,17 +95,11 @@ module IrtRuby
       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
+      Estimation.each_response(@responses, @active_persons, @active_items) do |i, j, value|
+        error = value - sigmoid(@abilities[i] - @difficulties[j])
 
-          grad_abilities[i]    += error
-          grad_difficulties[j] -= error
-        end
+        grad_abilities[i]    += error
+        grad_difficulties[j] -= error
       end
 
       [grad_abilities, grad_difficulties]
@@ -110,40 +121,60 @@ module IrtRuby
     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 = Estimation.changes(@abilities, old_abilities, @active_persons) +
+               Estimation.changes(@difficulties, old_difficulties, @active_items)
       deltas.sum / deltas.size
     end
 
+    # Returns estimates on the identified scale, with nil for persons and items that
+    # have no finite estimate on it, plus whether the convergence criteria were met.
     def fit
-      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
+      converged = false
+      iterations = 0
+
+      if @active_persons.any?
+        prev_ll = log_likelihood
+
+        @max_iter.times do
+          iterations += 1
+          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
+            if ll_diff < @tolerance && param_delta < @param_tolerance
+              converged = stationary?
+              break
+            end
+
+            prev_ll = current_ll
+            @learning_rate *= Estimation::LEARNING_RATE_GROWTH
+          end
         end
+
       end
 
-      { abilities: @abilities, difficulties: @difficulties }
+      mean, = Estimation.scale(@abilities, @active_persons)
+      {
+        abilities: Estimation.estimates(@abilities.map { |theta| theta - mean }, @active_persons),
+        difficulties: Estimation.estimates(@difficulties.map { |b| b - mean }, @active_items),
+        converged: converged,
+        iterations: iterations
+      }
+    end
+
+    def stationary?
+      grad_abilities, grad_difficulties = compute_gradient
+      Estimation.stationary?(grad_abilities, [grad_difficulties], @person_counts, @item_counts, @gradient_tolerance)
     end
+    private :stationary?
   end
 end

data/lib/irt_ruby/response_data_validator.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module IrtRuby
+  # Validates response data accepted by IRT model constructors.
+  # @api private
+  module ResponseDataValidator
+    module_function
+
+    def validate!(data)
+      raise ArgumentError, "response data must be a Matrix or array of arrays" unless valid_data_container?(data)
+
+      data_array = data.to_a
+
+      raise ArgumentError, "response data must have at least one row" unless data_array.any?
+
+      validate_rows!(data_array)
+      validate_values!(data_array)
+
+      data_array
+    end
+
+    def validate_rows!(data_array)
+      first_row = data_array.first
+
+      raise ArgumentError, "response data must be a Matrix or array of arrays" unless first_row.is_a?(Array)
+
+      expected_columns = first_row.size
+      raise ArgumentError, "response data must have at least one column" if expected_columns.zero?
+
+      data_array.each_with_index do |row, index|
+        row_number = index + 1
+        raise ArgumentError, "response data row #{row_number} must be an Array" unless row.is_a?(Array)
+
+        next if row.size == expected_columns
+
+        raise ArgumentError, "response data must be rectangular; row #{row_number} has #{row.size} columns, expected #{expected_columns}"
+      end
+    end
+
+    def validate_values!(data_array)
+      data_array.each_with_index do |row, row_index|
+        row.each_with_index do |value, column_index|
+          next if valid_response?(value)
+
+          raise ArgumentError,
+                "response data contains invalid value #{value.inspect} at row #{row_index + 1}, column #{column_index + 1}; allowed values are 0, 1, and nil"
+        end
+      end
+    end
+
+    def valid_response?(value)
+      value.nil? || value.eql?(0) || value.eql?(1)
+    end
+
+    def valid_data_container?(data)
+      data.is_a?(Array) || (defined?(::Matrix) && data.is_a?(::Matrix))
+    end
+  end
+end

data/lib/irt_ruby/response_graph.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module IrtRuby
+  # Finds the persons and items whose parameters are jointly estimable.
+  # @api private
+  module ResponseGraph
+    module_function
+
+    # Returns [persons, items] flags marking the parameters that have finite joint
+    # maximum-likelihood estimates on a common scale. In the response graph a correct
+    # answer links item -> person and an incorrect one person -> item; estimates exist
+    # within a strongly connected component, so the largest one is kept. All-correct,
+    # all-incorrect and unobserved rows or columns, perfectly separated subsets, and
+    # subsets sharing no responses all fall outside it. This suffices for the Rasch
+    # model and for 2PL with bounded discriminations; for 3PL it is necessary but not
+    # sufficient.
+    def estimable(responses)
+      num_persons = responses.size
+      num_items = responses.first.size
+      forward = Array.new(num_persons + num_items) { [] }
+      backward = Array.new(num_persons + num_items) { [] }
+      responses.each_with_index do |row, i|
+        row.each_with_index do |value, j|
+          next if value.nil?
+
+          from, to = value == 1 ? [num_persons + j, i] : [i, num_persons + j]
+          forward[from] << to
+          backward[to] << from
+        end
+      end
+
+      component = strongly_connected_components(forward, backward)
+      sizes = Hash.new(0)
+      component.each { |c| sizes[c] += 1 }
+      largest, size = sizes.max_by { |c, n| [n, -c] }
+      return [Array.new(num_persons, false), Array.new(num_items, false)] if size < 2
+
+      [Array.new(num_persons) { |i| component[i] == largest },
+       Array.new(num_items) { |j| component[num_persons + j] == largest }]
+    end
+
+    # Iterative Kosaraju: returns the component index of every node.
+    def strongly_connected_components(forward, backward)
+      order = []
+      visited = Array.new(forward.size, false)
+      forward.each_index do |start|
+        next if visited[start]
+
+        visited[start] = true
+        stack = [[start, 0]]
+        until stack.empty?
+          node, edge = stack.last
+          if edge < forward[node].size
+            stack.last[1] += 1
+            target = forward[node][edge]
+            next if visited[target]
+
+            visited[target] = true
+            stack << [target, 0]
+          else
+            order << node
+            stack.pop
+          end
+        end
+      end
+
+      component = Array.new(forward.size)
+      count = 0
+      order.reverse_each do |start|
+        next if component[start]
+
+        component[start] = count
+        stack = [start]
+        until stack.empty?
+          backward[stack.pop].each do |source|
+            next if component[source]
+
+            component[source] = count
+            stack << source
+          end
+        end
+        count += 1
+      end
+      component
+    end
+  end
+end