kot 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3d7be21381f93bf3481b87a3167afeb00bc85101113fb55031d25d169434d56
-  data.tar.gz: 57e6c62c8bf39ff09f63db2c9c70a4f3c3727ade7e216ea1cc26d7a8a42dd67f
+  metadata.gz: 4df58ff0365bfa26e18adba52d56d07b2ba6e1648a7672e30e36074086a59b86
+  data.tar.gz: 277e71849654efe4c68d6e0994195c03bfcc4758d5e768fcca3a363e56c54c01
 SHA512:
-  metadata.gz: dfade4c0dda38f2ad2d8182abacecb4686088c6323a6a0c044507ba921aebe8fb552b3b92eb8c7a0f24a0d62d21762ce623de852d30a38b069c0cd0b42a9354e
-  data.tar.gz: a59fbf2efccc4843e456c8a5093e263030411250d100f42163425f4b22a6b3ce778acf94a69c1d67e066f95c8dd5b0e5ec75a2db4eadd7d3eae0e32c65d2cfa8
+  metadata.gz: 782b27fe171ca5ed98fde2c0f83115bfc94e3272c25132779edff79f0955bff817238f53b4079bb122b563274054cd00d7399b967783abe2ad533ce8ea026642
+  data.tar.gz: 24ab8c8ae3af9e2bbf3bf02de19e2fbcdcbdcf552f840bb835c1bbe91cd3f4bbe27adfba0d26a0542f12c6e56245dac8e40d9171a71815d014bc8882b3015bab

data/lib/kot.rb

@@ -1,4 +1,5 @@
 require('kot/item_response_theory')
+require('kot/item4pl')
 require('kot/hill_climbing_estimator')
 require('kot/randomesque_selector')
-require('kot/test')
+require('kot/test')

data/lib/kot/hill_climbing_estimator.rb

@@ -1,54 +1,53 @@
 module Kot
-
   class HillClimbingEstimator
 
-
-
+    # Estimates theta when all responses are true or all are false, based on Dodd, 1990.
     # "The variable stepsize changed the 0 estimate by half the distance to the appropriate ... value in the item pool."
-    def dodd(est_theta:0.0, items:[], last_response:[])
+    def dodd(est_theta: 0.0, items: [], last_response: [])
       max_b = items.map(&:b).max
       min_b = items.map(&:b).min
 
       last_response ? est_theta + ((max_b - est_theta) / 2.0) : est_theta - ((est_theta - min_b) / 2.0)
     end
 
-
+    # Performs a single iteration of the hill climb, starting from one bound towards the other.
     def estimate_iteration(best_theta, max_ll, lower_bound, upper_bound, responses, items)
-        step_size = (upper_bound - lower_bound) /  10
-
-        case step_size <=> 0
-        when 1
-          intervals = (lower_bound..upper_bound).step(step_size).each
-        when -1
-          intervals = (upper_bound..lower_bound).step(step_size.abs).reverse_each
-        when 0
-          intervals = []
-        end
-
-        intervals.each do |ii|
+      step_size = (upper_bound - lower_bound) / 10
+
+      case step_size <=> 0
+      when 1
+        intervals = (lower_bound..upper_bound).step(step_size).each
+      when -1
+        intervals = (upper_bound..lower_bound).step(step_size.abs).reverse_each
+      when 0
+        intervals = []
+      end
 
-          ll = ItemResponseTheory.log_likelihood(ii, responses, items)
+      intervals.each do |ii|
 
-          if ll > max_ll
-            max_ll = ll
+        ll = ItemResponseTheory.log_likelihood(ii, responses, items)
 
-            #TODO - precision-based early exit
-            best_theta = ii
-          else
-            lower_bound = best_theta - step_size.abs
-            upper_bound = ii
-            break
-          end
+        if ll > max_ll
+          max_ll = ll
 
+          #TODO: precision-based early exit
+          best_theta = ii
+        else
+          lower_bound = best_theta - step_size.abs
+          upper_bound = ii
+          break
         end
 
-        return best_theta, max_ll, lower_bound, upper_bound
+      end
+
+      [best_theta, max_ll, lower_bound, upper_bound]
     end
 
-    def estimate(responses:[], items:[], all_items:[], est_theta:0.0)
+    # Estimate theta using multiple iterations of a hill climb, falling back to {#dodd} if all responses are true or false.
+    def estimate(responses: [], items: [], all_items: [], est_theta: 0.0)
       if responses.uniq.count == 1
-        raise ArgumentError.new("Responses are all #{responses.first} but missing all_items argument") if all_items.empty?
-        return dodd(est_theta:est_theta, items:all_items, last_response:responses.last)
+        raise ArgumentError, "Responses are all #{responses.first} but missing all_items argument" if all_items.empty?
+        return dodd(est_theta: est_theta, items: all_items, last_response: responses.last)
       end
 
       lower_bound = items.map(&:b).min
@@ -59,8 +58,6 @@ module Kot
       best_theta = - Float::INFINITY
       max_ll = - Float::INFINITY
 
-      old_best_theta = best_theta
-
       10.times do
         best_theta, max_ll, lower_bound, upper_bound = 
           estimate_iteration(best_theta, max_ll, lower_bound, upper_bound, responses, items)
@@ -68,9 +65,9 @@ module Kot
         break if lower_bound == upper_bound
       end
 
-      return best_theta
+      best_theta
     end
 
   end
 
-end
+end

data/lib/kot/item4pl.rb

@@ -0,0 +1,93 @@
+module Kot
+
+  # An example of an Item class. You probably don't want to inherit from this, 
+  # but instead to include {ItemResponseTheory} in a class of your own that 
+  # provides {#a}, {#b}, {#c} and {#d}. See those attribute definitions for
+  # more information about what each parameter means in the context of
+  # correct/incorrect tests of ability.
+  #
+  # This class is useful for simulating different CAT setups and is used
+  # for some of the specification tests of this library.
+  class Item4PL
+    include Kot::ItemResponseTheory
+
+    attr_reader :a, :b, :c, :d
+
+    # @!attribute [r] a
+    #   Discrimination ability of the item.
+    #   This describe the maximum slope of the item's ICC, at the point given by {#b},
+    #   and so how sharply the item distinguishes between those with ability below and above that point.
+    #
+    #   An item with an _a_ of zero would have an entirely flat ICC (and so be completely useless),
+    #   while an item with an infinitely high _a_ would perfectly discriminate such that anyone with an ability
+    #   of *less* *than* _b_ would have _c_ probability of getting the answer right and anyone with an ability
+    #   *greater* *than* _b_ would have _d_ probability of getting the answer right.
+    #
+    #   Usually set to 1.0 for 1PL models.
+    #   @return [Float] Discrimination
+
+    # @!attribute [r] b
+    #   Difficulty of the item.
+    #   This describes the midpoint of the item's ICC, where P(_b_)=0.5, 
+    #   and so the point at which half of those with a _theta_ equal to _b_ will answer
+    #   the item correctly and half will answer it incorrectly.
+    #
+    #   _b_ is the parameter required by any model, and across the bank of items usually
+    #    will range over the distribution of test-takers' ability.
+    #   (Often the distribution of ability is conceived as N(0,1).)
+    #
+    #   @return [Float] Difficulty
+
+    # @!attribute [r] c
+    #   Likelihood of guesing the item.
+    #   This describes the lower asymptote of the item's ICC,
+    #   and so the lowest probability of answering correctly regardless of ability.
+    #
+    #   For example, a multiple choice test item with 5 possible answers,
+    #   one of which is correct, might have a _c_ of 1/5 or 0.2 .
+    #
+    #   Usually set to 0.0 for 1-2PL models.
+    #   @return [Float] Guessing
+
+    # @!attribute [r] d
+    #   Maximum likelihood of answering correctly.
+    #   This describes the upper asymptote of the item's ICC,
+    #   and so the highest probability of answering correctly regardless of ability.
+    #
+    #   This parameter is more common in contexts outside of testing ability
+    #   such as cognitive and clinical measures.
+    #
+    #   Usually set to 1.0 for 1-3PL models.
+    #   @return [Float] Insurmountable difficulty
+
+    def self.[](*arr)
+      arr.map { |a| Item4PL.new(a) }
+    end
+
+    # @see https://stackoverflow.com/questions/5825680/code-to-generate-gaussian-normally-distributed-random-numbers-in-ruby
+    def self.gaussian(mean = 0.0, stddev = 1.0, rand = lambda{ Kernel.rand } )
+      theta = 2 * Math::PI * rand.call
+      rho = Math.sqrt(-2 * Math.log(1 - rand.call))
+      scale = stddev * rho
+      mean + scale * Math.cos(theta)
+    end
+
+    # @return [Item4PL] a 1PL Item4PL with a {#b} chosen randomly from N(0,1)
+    # @return [Array] an array of 1PL Item4PLs with {#b}s chosen randomly from N(0,1)
+    def self.generate(n = nil)
+      return Item4PL.new(b:gaussian()) if n.nil?
+      Array.new(n) { generate }
+    end
+
+    def initialize(a: 1.0, b: 0.0, c: 0.0, d: 1.0)
+      @a = a
+      @b = b
+      @c = c
+      @d = d
+    end
+
+    def to_s
+      "<Item4PL a:#{a} b:#{b} c:#{c} d#{d} >"
+    end
+  end
+end

data/lib/kot/item_response_theory.rb

@@ -1,53 +1,61 @@
 module Kot
 
-  # Requires a, b, c, d
+  # Include this module into a class to give various IRT statistics for individual items.
+  # Including classes are expected to respond to #a, #b, #c and #d ; see the example {Item4PL} class for more information.
+  #
+  # Class methods for this module provide IRT statistics for a set of items,
+  # given an individual's estimated theta (and sometimes their responses to those items).
   module ItemResponseTheory
 
-    #
-    # Module methods for statistics based on estimated theta, items and responses
-    #
-
+    # @param est_theta [Float] an estimate of an individual's ability
+    # @param responses [Array<TrueClass, FalseClass>] the responses given by an individual to _items_
+    # @param items [Array<ItemResponseTheory>] items that an individual has responded to
+    # @return [Float]
     def self.log_likelihood(est_theta, responses, items)
-      ps = items.map {|i| i.icc(est_theta) }
-      ls = ps.each_with_index.map {|e,i| responses[i] ? Math.log(e) : Math.log(1.0 - e)} #TODO: Polychotomous
+      ps = items.map { |i| i.icc(est_theta) }
+      ls = ps.each_with_index.map { |e, i| responses[i] ? Math.log(e) : Math.log(1.0 - e) } 
+      # TODO: Polychotomous
       ls.inject(:+)
     end
 
+    # @param est_theta [Float] an estimate of an individual's ability
+    # @param items [Array<ItemResponseTheory>] items that an individual has responded to
+    # @return [Float]
     def self.test_info(est_theta, items)
-      items.map {|i| i.inf(est_theta) }.inject(:+)
+      items.map { |i| i.inf(est_theta) }.inject(:+)
     end
 
+    # @param est_theta [Float] an estimate of an individual's ability
+    # @param items [Array<ItemResponseTheory>] items that an individual has responded to
+    # @return [Float]
     def self.var(est_theta, items)
-      1.0/test_info(est_theta, items)
+      1.0 / test_info(est_theta, items)
     end
 
+    # @param est_theta [Float] an estimate of an individual's ability
+    # @param items [Array<ItemResponseTheory>] items that an individual has responded to
+    # @return [Float] standard error of estimation
     def self.see(est_theta, items)
       Math.sqrt(var(est_theta, items))
     end
 
-
-    #
-    # Methods intended for inclusion into Item-classes
-    #
-
-    def icc_component(theta)
-      Math.exp(-a * (theta - b))
-    end
-
     # Item characteristic curve
+    # @return [Float] the probability of someone with ability _theta_ of answering this item correctly
     def icc(theta)
-      c + ((d - c) / (1.0 + icc_component(theta)))
+      icc_component = Math.exp(-a * (theta - b))
+      c + ((d - c) / (1.0 + icc_component))
     end
 
-    # Information value of an item
+    # Item information function
+    # @return [Float] a measure of the information that would be provided by a response to this item given a prior _theta_
     def inf(theta)
       vp = icc(theta)
 
       top = (a ** 2) * ((vp - c) ** 2) * ((d - vp) ** 2)
       bottom = ((d - c) ** 2) * vp * (1.0 - vp)
 
-      top/bottom
+      top / bottom
     end
 
   end
-end
+end

data/lib/kot/randomesque_selector.rb

@@ -7,9 +7,9 @@ module Kot
     end
 
     def select(est_theta, possible_items)
-
-      possible_items.sort_by {|i| - i.inf(est_theta)}.slice(0, @bin_size).sample
+      possible_items.sort_by { |i| - i.inf(est_theta) }.
+        slice(0, @bin_size).sample
     end
 
   end
-end
+end

data/lib/kot/test.rb

@@ -1,6 +1,5 @@
 module Kot
 
-
   class Test
 
     attr_reader :est_theta
@@ -15,21 +14,24 @@ module Kot
       @asked_items = []
     end
 
-
+    # Get the standard error of estimation for the test so far.
     def see
       return Float::INFINITY if @asked_items.empty?
       ItemResponseTheory.see(@est_theta, @asked_items)
     end
 
+    # Update the estimated theta for the test so far.
     def update_est_theta
-      @est_theta = @estimator.estimate(est_theta: @est_theta, responses:@responses, items:@asked_items, all_items:@item_bank)
+      @est_theta = @estimator.estimate(est_theta: @est_theta, responses: @responses, items: @asked_items, all_items: @item_bank)
     end
 
+    # Ask the selector for a new item from the item bank.
     def next_item
       possible_items = @item_bank - @asked_items
       @selector.select(@est_theta, possible_items)
     end
 
+    # Add a response for a given item.
     def respond(response, item)
       @responses << response
       @asked_items << item
@@ -38,4 +40,4 @@ module Kot
 
   end
 
-end
+end

data/lib/kot/version.rb

@@ -1,3 +1,3 @@
 module Kot
-  VERSION = '0.0.2'.freeze
+  VERSION = '0.0.3'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kot
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Adam Watkins
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-08-25 00:00:00.000000000 Z
+date: 2018-10-03 00:00:00.000000000 Z
 dependencies: []
 description: "  Kot is a basic toolkit for getting started with computerised adaptive
   testing (CAT). It includes a module to calculate item response theory (IRT) statistics
@@ -22,6 +22,7 @@ extra_rdoc_files: []
 files:
 - lib/kot.rb
 - lib/kot/hill_climbing_estimator.rb
+- lib/kot/item4pl.rb
 - lib/kot/item_response_theory.rb
 - lib/kot/randomesque_selector.rb
 - lib/kot/test.rb