irt_ruby 0.1.0 → 0.3.0

data/lib/irt_ruby/two_parameter_model.rb

@@ -1,65 +1,156 @@
 # frozen_string_literal: true
 
-require "matrix"
-
 module IrtRuby
-  # A class representing the Two-Parameter model for Item Response Theory.
+  # A class representing the Two-Parameter model (2PL) for IRT.
+  # Incorporates:
+  # - Adaptive learning rate
+  # - Missing data handling
+  # - Parameter clamping for discrimination
+  # - Multiple convergence checks
+  # - Separate gradient calculation & parameter update
   class TwoParameterModel
-    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 }
-      @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
+      # Typically: ability ~ 0, difficulty ~ 0, discrimination ~ 1
+      @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) }
+
+      @max_iter         = max_iter
+      @tolerance        = tolerance
+      @param_tolerance  = param_tolerance
+      @learning_rate    = learning_rate
+      @decay_factor     = decay_factor
     end
 
-    # Sigmoid function
     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
+      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(@discriminations[j] * (@abilities[i] - @difficulties[j]))
-          if response == 1
-            likelihood += Math.log(prob)
-          elsif response.zero?
-            likelihood += Math.log(1 - prob)
-          end
+          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 = sigmoid(@discriminations[j] * (@abilities[i] - @difficulties[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])
-          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)
+
+      @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(@discriminations[j] * (@abilities[i] - @difficulties[j]))
+          error = value - prob
+
+          grad_abilities[i]       += error * @discriminations[j]
+          grad_difficulties[j]    -= error * @discriminations[j]
+          grad_discriminations[j] += error * (@abilities[i] - @difficulties[j])
         end
-        current_likelihood = likelihood
-        break if (last_likelihood - current_likelihood).abs < @tolerance
+      end
+
+      [grad_abilities, grad_difficulties, grad_discriminations]
+    end
+
+    def apply_gradient_update(ga, gd, gdisc)
+      old_a    = @abilities.dup
+      old_d    = @difficulties.dup
+      old_disc = @discriminations.dup
+
+      @abilities.each_index do |i|
+        @abilities[i] += @learning_rate * ga[i]
+      end
 
-        last_likelihood = current_likelihood
+      @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
+
+      [old_a, old_d, old_disc]
+    end
+
+    def average_param_update(old_a, old_d, old_disc)
+      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 }
+      deltas.sum / deltas.size
     end
 
-    # Fit the model to the data
     def fit
-      update_parameters
-      { abilities: @abilities, difficulties: @difficulties, discriminations: @discriminations }
+      prev_ll = log_likelihood
+
+      @max_iter.times do
+        ga, gd, gdisc = compute_gradient
+        old_a, old_d, old_disc = apply_gradient_update(ga, gd, gdisc)
+
+        curr_ll     = log_likelihood
+        param_delta = average_param_update(old_a, old_d, old_disc)
+
+        if curr_ll < prev_ll
+          @abilities       = old_a
+          @difficulties    = old_d
+          @discriminations = old_disc
+          @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,
+        discriminations: @discriminations
+      }
     end
   end
 end

data/lib/irt_ruby/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module IrtRuby
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/irt_ruby.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "irt_ruby/version"
+require "matrix"
 require "irt_ruby/rasch_model"
 require "irt_ruby/two_parameter_model"
 require "irt_ruby/three_parameter_model"

metadata

@@ -1,15 +1,43 @@
 --- !ruby/object:Gem::Specification
 name: irt_ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Alex Kholodniak
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-06-09 00:00:00.000000000 Z
+date: 2025-06-13 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: matrix
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.2
+- !ruby/object:Gem::Dependency
+  name: benchmark-ips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -24,6 +52,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: memory_profiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -52,16 +94,30 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
-description: IrtRuby is a Ruby gem that provides implementations of the Rasch model,
-  Two-Parameter model, and Three-Parameter model for Item Response Theory (IRT). It
-  allows you to estimate the abilities of individuals and the difficulties, discriminations,
-  and guessing parameters of items based on their responses to a set of items.
+description: "IrtRuby is a comprehensive Ruby library for Item Response Theory (IRT)
+  analysis, \ncommonly used in educational assessment, psychological testing, and
+  survey research.\n\nFeatures three core IRT models:\n• Rasch Model (1PL) - Simple
+  difficulty-only model\n• Two-Parameter Model (2PL) - Adds item discrimination\n•
+  Three-Parameter Model (3PL) - Includes guessing parameter\n\nKey capabilities:\n•
+  Robust gradient ascent optimization with adaptive learning rates\n• Flexible missing
+  data strategies (ignore, treat as incorrect/correct)\n• Comprehensive performance
+  benchmarking suite\n• Memory-efficient implementation with excellent scaling\n•
+  Production-ready with extensive test coverage\n\nPerfect for researchers, data scientists,
+  and developers working with \neducational assessments, psychological measurements,
+  or any binary response data\nwhere item and person parameters need to be estimated
+  simultaneously.\n"
 email:
 - alexandrkholodniak@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- benchmarks/README.md
+- benchmarks/convergence_benchmark.rb
+- benchmarks/performance_benchmark.rb
 - lib/irt_ruby.rb
 - lib/irt_ruby/rasch_model.rb
 - lib/irt_ruby/three_parameter_model.rb
@@ -73,7 +129,10 @@ licenses:
 metadata:
   homepage_uri: https://github.com/SyntaxSpirits/irt_ruby
   source_code_uri: https://github.com/SyntaxSpirits/irt_ruby
-  changelog_uri: https://github.com/SyntaxSpirits/irt_ruby/CHANGELOG.md
+  changelog_uri: https://github.com/SyntaxSpirits/irt_ruby/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/SyntaxSpirits/irt_ruby#readme
+  bug_tracker_uri: https://github.com/SyntaxSpirits/irt_ruby/issues
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -89,9 +148,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.16
+rubygems_version: 3.5.9
 signing_key:
 specification_version: 4
-summary: A Ruby gem that provides implementations of Rasch, Two-Parameter, and Three-Parameter
-  models for Item Response Theory (IRT).
+summary: Production-ready Item Response Theory (IRT) models with comprehensive performance
+  benchmarking and adaptive optimization.
 test_files: []