docs: clarify response data validation contract

Author: kholdrex

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project are documented in this file.
 
+## [Unreleased]
+
+### Changed
+- Clarified that response data must be a `Matrix` or array of arrays containing only integer `0`, integer `1`, or `nil`; floats, strings, booleans, and other values are rejected.
+
+---
+
 ## [0.3.0] - 2025-01-14
 
 ### Changed

README.md

@@ -47,6 +47,12 @@ result = model.fit
 puts "Abilities:    #{result[:abilities]}"
 puts "Difficulties: #{result[:difficulties]}"
 ```
+
+Response data passed to model constructors must be either a `Matrix` or an
+array of arrays. Each response value must be the integer `0`, the integer `1`,
+or `nil` for missing data; floats such as `0.0`/`1.0`, strings, booleans, and
+other values are rejected.
+
 ### Using 2PL and 3PL Models
 ```ruby
 two_pl_model = IrtRuby::TwoParameterModel.new(data)

lib/irt_ruby/response_data_validator.rb

@@ -2,6 +2,7 @@
 
 module IrtRuby
   # Validates response data accepted by IRT model constructors.
+  # @api private
   module ResponseDataValidator
     module_function
 
@@ -10,7 +11,7 @@ def validate!(data)
 
       data_array = data.to_a
 
-      raise ArgumentError, "response data must have at least one row" unless data_array.is_a?(Array) && data_array.any?
+      raise ArgumentError, "response data must have at least one row" unless data_array.any?
 
       validate_rows!(data_array)
       validate_values!(data_array)
@@ -27,11 +28,12 @@ def validate_rows!(data_array)
       raise ArgumentError, "response data must have at least one column" if expected_columns.zero?
 
       data_array.each_with_index do |row, index|
-        raise ArgumentError, "response data row #{index} must be an Array" unless row.is_a?(Array)
+        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 #{index} has #{row.size} columns, expected #{expected_columns}"
+        raise ArgumentError, "response data must be rectangular; row #{row_number} has #{row.size} columns, expected #{expected_columns}"
       end
     end
 

spec/spec_helper.rb

@@ -12,7 +12,7 @@
   end
 
   it "rejects ragged rows" do
-    expect { described_class.new([[1, 0], [1]]) }.to raise_error(ArgumentError, /rectangular/)
+    expect { described_class.new([[1, 0], [1]]) }.to raise_error(ArgumentError, /rectangular; row 2/)
   end
 
   it "rejects invalid response values" do
@@ -24,8 +24,16 @@
     expect { described_class.new([[1.0]]) }.to raise_error(ArgumentError, /invalid value 1\.0/)
   end
 
-  it "rejects non-numeric truthy, falsey, and string responses" do
-    expect { described_class.new([[1, "1"], [false, nil]]) }.to raise_error(ArgumentError, /invalid value/)
+  it "rejects string response values" do
+    expect { described_class.new([["1"]]) }.to raise_error(ArgumentError, /invalid value "1"/)
+  end
+
+  it "rejects false response values" do
+    expect { described_class.new([[false]]) }.to raise_error(ArgumentError, /invalid value false/)
+  end
+
+  it "rejects true response values" do
+    expect { described_class.new([[true]]) }.to raise_error(ArgumentError, /invalid value true/)
   end
 
   it "rejects hash input even when it can be converted to an array" do