irt_ruby 0.3.0 → 0.4.0

data/lib/irt_ruby/three_parameter_model.rb

@@ -1,5 +1,10 @@
 # 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 Three-Parameter model (3PL) for Item Response Theory.
   # Incorporates:
@@ -8,42 +13,72 @@ module IrtRuby
   # - Parameter clamping for discrimination, guessing
   # - Multiple convergence checks
   # - Separate gradient calculation & updates
+  # - Exclusion of extreme response patterns, which have no finite estimates
+  # - Identification by reporting abilities standardized to mean 0 and SD 1
   class ThreeParameterModel
     MISSING_STRATEGIES = %i[ignore treat_as_incorrect treat_as_correct].freeze
+    DISCRIMINATION_BOUNDS = [0.01, 5.0].freeze
+    GUESSING_BOUNDS = [0.0, 0.35].freeze
+    # A correct response contributes (1 - s) / P to the guessing gradient (exp(-z) at
+    # c = 0), which overflows when P is tiny; capping each term keeps the sum finite
+    # so that backtracking can still shrink the step.
+    MAX_GUESSING_GRADIENT_TERM = 1e12
 
     def initialize(data,
                    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)
-      @data = data
-      @data_array = data.to_a
-      num_rows = @data_array.size
-      num_cols = @data_array.first.size
+                   missing_strategy: :ignore,
+                   seed: nil)
+      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)
+      @floor_items = floor_items
+      @guessing_counts = @item_counts.dup
+      @floor_items.each { |j| @guessing_counts[j] += 1 }
 
       # 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
+      @abilities       = Array.new(num_rows)  { random_between(-0.25..0.25) }
+      @difficulties    = Array.new(num_cols)  { random_between(-0.25..0.25) }
+      @discriminations = Array.new(num_cols)  { random_between(0.5..1.5) }
+      @guessings       = Array.new(num_cols)  { random_between(0.0..0.3) }
+
+      @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
+
     # Probability for the 3PL model: c + (1-c)*sigmoid(a*(θ - b))
     def probability(theta, a, b, c)
       c + ((1.0 - c) * sigmoid(a * (theta - b)))
@@ -64,23 +99,17 @@ module IrtRuby
 
     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
+      Estimation.each_response(@responses, @active_persons, @active_items) do |i, j, value|
+        z = @discriminations[j] * (@abilities[i] - @difficulties[j])
+        c = @guessings[j]
+
+        ll += if value == 1
+                c.zero? ? Estimation.log_sigmoid(z) : Math.log(c + ((1.0 - c) * sigmoid(z)))
+              else
+                Math.log(1.0 - c) + Estimation.log_sigmoid(-z)
+              end
       end
+      @floor_items.each { |j| ll += Math.log(1.0 - @guessings[j]) }
       ll
     end
 
@@ -90,29 +119,45 @@ module IrtRuby
       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]
+      Estimation.each_response(@responses, @active_persons, @active_items) do |i, j, value|
+        theta = @abilities[i]
+        a     = @discriminations[j]
+        b     = @difficulties[j]
+        c     = @guessings[j]
+
+        # With P = c + (1 - c) * s and s = sigmoid(z), z = a * (theta - b):
+        # dLL/dz = (u - P) * s / P, and dLL/dc = (1 - s) / P if u = 1, -1 / (1 - c) if u = 0.
+        z     = a * (theta - b)
+        s     = sigmoid(z)
+        prob  = c + ((1.0 - c) * s)
+        dz    = c.zero? ? value - s : (value - prob) * s / prob
+
+        grad_abilities[i]       += dz * a
+        grad_difficulties[j]    -= dz * a
+        grad_discriminations[j] += dz * (theta - b)
+        grad_guessings[j]       += if value.zero?
+                                     -1.0 / (1.0 - c)
+                                   else
+                                     [c.zero? ? Math.exp(-z) : (1.0 - s) / prob, MAX_GUESSING_GRADIENT_TERM].min
+                                   end
+      end
+      @floor_items.each { |j| grad_guessings[j] -= 1.0 / (1.0 - @guessings[j]) }
 
-          prob  = probability(theta, a, b, c)
-          error = value - prob
+      [grad_abilities, grad_difficulties, grad_discriminations, grad_guessings]
+    end
 
-          grad_abilities[i]       += error * a * (1 - c)
-          grad_difficulties[j]    -= error * a * (1 - c)
-          grad_discriminations[j] += error * (theta - b) * (1 - c)
+    # Excluded respondents who answered every estimable item incorrectly have ability
+    # tending to -infinity, where P = c, so each of those responses still contributes
+    # log(1 - c) to the likelihood of its item's guessing parameter.
+    def floor_items
+      @responses.each_index.flat_map do |i|
+        next [] if @active_persons[i]
 
-          grad_guessings[j]       += error * 1.0
-        end
+        items = @responses[i].each_index.select { |j| @active_items[j] && !@responses[i][j].nil? }
+        items.all? { |j| @responses[i][j].zero? } ? items : []
       end
-
-      [grad_abilities, grad_difficulties, grad_discriminations, grad_guessings]
     end
+    private :floor_items
 
     def apply_gradient_update(ga, gd, gdisc, gc)
       old_a    = @abilities.dup
@@ -129,59 +174,84 @@ module IrtRuby
       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
+        @discriminations[j] = (@discriminations[j] + (@learning_rate * gdisc[j])).clamp(*DISCRIMINATION_BOUNDS)
       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
+        @guessings[j] = (@guessings[j] + (@learning_rate * gc[j])).clamp(*GUESSING_BOUNDS)
       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 = Estimation.changes(@abilities, old_a, @active_persons) +
+               Estimation.changes(@difficulties, old_d, @active_items) +
+               Estimation.changes(@discriminations, old_disc, @active_items) +
+               Estimation.changes(@guessings, old_c, @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
-        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
+      converged = false
+      iterations = 0
+
+      if @active_persons.any?
+        prev_ll = log_likelihood
+
+        @max_iter.times do
+          iterations += 1
+          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
+            if ll_diff < @tolerance && param_delta < @param_tolerance
+              converged = stationary?
+              break
+            end
+
+            prev_ll = curr_ll
+            @learning_rate *= Estimation::LEARNING_RATE_GROWTH
+          end
         end
+
       end
 
+      mean, sd = Estimation.scale(@abilities, @active_persons)
       {
-        abilities: @abilities,
-        difficulties: @difficulties,
-        discriminations: @discriminations,
-        guessings: @guessings
+        abilities: Estimation.estimates(@abilities.map { |theta| (theta - mean) / sd }, @active_persons),
+        difficulties: Estimation.estimates(@difficulties.map { |b| (b - mean) / sd }, @active_items),
+        discriminations: Estimation.estimates(@discriminations.map { |a| a * sd }, @active_items),
+        guessings: Estimation.estimates(@guessings, @active_items),
+        converged: converged,
+        iterations: iterations
       }
     end
+
+    # Gradients are compared on the reported scale (theta' = (theta - m) / sd,
+    # b' = (b - m) / sd, a' = a * sd), where they scale by sd, sd and 1 / sd.
+    def stationary?
+      ga, gd, gdisc, gc = compute_gradient
+      gdisc = Estimation.project(gdisc, @discriminations, *DISCRIMINATION_BOUNDS)
+      gc = Estimation.project(gc, @guessings, *GUESSING_BOUNDS)
+      _, sd = Estimation.scale(@abilities, @active_persons)
+      Estimation.stationary?(ga.map { |g| g * sd },
+                             [gd.map { |g| g * sd }, gdisc.map { |g| g / sd }],
+                             @person_counts, @item_counts, @gradient_tolerance) &&
+        Estimation.small_residuals?(gc, @guessing_counts, @gradient_tolerance)
+    end
+    private :stationary?
   end
 end

data/lib/irt_ruby/two_parameter_model.rb

@@ -1,5 +1,10 @@
 # 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 Two-Parameter model (2PL) for IRT.
   # Incorporates:
@@ -8,38 +13,59 @@ module IrtRuby
   # - Parameter clamping for discrimination
   # - Multiple convergence checks
   # - Separate gradient calculation & parameter update
+  # - Exclusion of extreme response patterns, which have no finite estimates
+  # - Identification by reporting abilities standardized to mean 0 and SD 1
   class TwoParameterModel
     MISSING_STRATEGIES = %i[ignore treat_as_incorrect treat_as_correct].freeze
+    DISCRIMINATION_BOUNDS = [0.01, 5.0].freeze
 
     def initialize(data, 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)
-      @data = data
-      @data_array = data.to_a
-      num_rows = @data_array.size
-      num_cols = @data_array.first.size
+                   missing_strategy: :ignore, seed: nil)
+      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
       # 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
+      @abilities       = Array.new(num_rows)  { random_between(-0.25..0.25) }
+      @difficulties    = Array.new(num_cols)  { random_between(-0.25..0.25) }
+      @discriminations = Array.new(num_cols)  { random_between(0.5..1.5) }
+
+      @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?
 
@@ -55,18 +81,9 @@ module IrtRuby
 
     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]))
-          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 = @discriminations[j] * (@abilities[i] - @difficulties[j])
+        ll += Estimation.log_sigmoid(value == 1 ? z : -z)
       end
       ll
     end
@@ -76,18 +93,13 @@ module IrtRuby
       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
+      Estimation.each_response(@responses, @active_persons, @active_items) do |i, j, value|
+        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
+        grad_abilities[i]       += error * @discriminations[j]
+        grad_difficulties[j]    -= error * @discriminations[j]
+        grad_discriminations[j] += error * (@abilities[i] - @difficulties[j])
       end
 
       [grad_abilities, grad_difficulties, grad_discriminations]
@@ -107,50 +119,75 @@ module IrtRuby
       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
+        @discriminations[j] = (@discriminations[j] + (@learning_rate * gdisc[j])).clamp(*DISCRIMINATION_BOUNDS)
       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 = Estimation.changes(@abilities, old_a, @active_persons) +
+               Estimation.changes(@difficulties, old_d, @active_items) +
+               Estimation.changes(@discriminations, old_disc, @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
-        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
+      converged = false
+      iterations = 0
+
+      if @active_persons.any?
+        prev_ll = log_likelihood
+
+        @max_iter.times do
+          iterations += 1
+          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
+            if ll_diff < @tolerance && param_delta < @param_tolerance
+              converged = stationary?
+              break
+            end
+
+            prev_ll = curr_ll
+            @learning_rate *= Estimation::LEARNING_RATE_GROWTH
+          end
         end
+
       end
 
+      mean, sd = Estimation.scale(@abilities, @active_persons)
       {
-        abilities: @abilities,
-        difficulties: @difficulties,
-        discriminations: @discriminations
+        abilities: Estimation.estimates(@abilities.map { |theta| (theta - mean) / sd }, @active_persons),
+        difficulties: Estimation.estimates(@difficulties.map { |b| (b - mean) / sd }, @active_items),
+        discriminations: Estimation.estimates(@discriminations.map { |a| a * sd }, @active_items),
+        converged: converged,
+        iterations: iterations
       }
     end
+
+    # Gradients are compared on the reported scale (theta' = (theta - m) / sd,
+    # b' = (b - m) / sd, a' = a * sd), where they scale by sd, sd and 1 / sd.
+    def stationary?
+      ga, gd, gdisc = compute_gradient
+      gdisc = Estimation.project(gdisc, @discriminations, *DISCRIMINATION_BOUNDS)
+      _, sd = Estimation.scale(@abilities, @active_persons)
+      Estimation.stationary?(ga.map { |g| g * sd },
+                             [gd.map { |g| g * sd }, gdisc.map { |g| g / sd }],
+                             @person_counts, @item_counts, @gradient_tolerance)
+    end
+    private :stationary?
   end
 end

data/lib/irt_ruby/version.rb

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

data/lib/irt_ruby.rb

@@ -2,6 +2,10 @@
 
 require "irt_ruby/version"
 require "matrix"
+require "irt_ruby/model_options_validator"
+require "irt_ruby/response_data_validator"
+require "irt_ruby/estimation"
+require "irt_ruby/response_graph"
 require "irt_ruby/rasch_model"
 require "irt_ruby/two_parameter_model"
 require "irt_ruby/three_parameter_model"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: irt_ruby
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Alex Kholodniak
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-06-13 00:00:00.000000000 Z
+date: 2026-10-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: matrix
@@ -94,18 +94,17 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
-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"
+description: "IrtRuby is a 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• Joint maximum likelihood by gradient
+  ascent with an adaptive learning rate\n• Convergence reporting, scale identification,
+  and exclusion of extreme response patterns\n• Missing data strategies (ignore, treat
+  as incorrect/correct)\n• Performance and convergence benchmark scripts\n\nIntended
+  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: []
@@ -119,7 +118,11 @@ files:
 - benchmarks/convergence_benchmark.rb
 - benchmarks/performance_benchmark.rb
 - lib/irt_ruby.rb
+- lib/irt_ruby/estimation.rb
+- lib/irt_ruby/model_options_validator.rb
 - lib/irt_ruby/rasch_model.rb
+- lib/irt_ruby/response_data_validator.rb
+- lib/irt_ruby/response_graph.rb
 - lib/irt_ruby/three_parameter_model.rb
 - lib/irt_ruby/two_parameter_model.rb
 - lib/irt_ruby/version.rb
@@ -151,6 +154,6 @@ requirements: []
 rubygems_version: 3.5.9
 signing_key:
 specification_version: 4
-summary: Production-ready Item Response Theory (IRT) models with comprehensive performance
-  benchmarking and adaptive optimization.
+summary: Rasch, 2PL, and 3PL Item Response Theory (IRT) models estimated by joint
+  maximum likelihood.
 test_files: []