irt_ruby 0.3.0 → 0.4.0

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