skiftet_statistical 0.2.0 → 0.4.0

data/lib/skiftet_statistical/hierarchical_rates.rb

@@ -0,0 +1,450 @@
+# frozen_string_literal: true
+
+module SkiftetStatistical
+  # Hierarchical Poisson rates: how far a node's rate stands from its parent's, from the node's count s and the count E
+  # its parent leads us to expect there. The node's ratio theta = rate / expected rate has a Gamma prior with mean 1 and
+  # strength k (Clayton and Kaldor 1987), so its posterior is Gamma(k + s, k + E). Under a two-groups prior (Efron 2008)
+  # the node is null with probability 1 - h (its count Poisson(E), its ratio 1) and else drawn from that Gamma slab, so
+  # its count is negative binomial NB(s; k, k / (k + E)). Beside the node rule: the leave-one-out share that sets E, the
+  # level fit of k (and h) by grid marginal maximum likelihood, the leaf fit that estimates each parent's null rate
+  # jointly with k and h, the smoothing of a fitted value across runs, Marshall's (1991) moment estimate and the
+  # boundary likelihood-ratio test (Self and Liang 1987).
+  #
+  # Counts are real numbers >= 0 throughout, so a caller may count by share: a node that stands in its parent only by a
+  # share w has w multiplied into its count and total by the caller (there is no weight keyword). The probability mass
+  # functions are taken in logs and through log-gamma, s! being Gamma(s + 1), with no rounding.
+  #
+  #   SkiftetStatistical::HierarchicalRates.node(count: 6.0, expected: 2.5, strength: 8.0, threshold: 1.25,
+  #                                            parent_tail: 0.0, parent_ratio: 1.0)
+  #   # => { ratio: 1.3333333333333333 (14 / 10.5), hot: 1.0, tail: 0.5593048238168208 (Q(14, 13.125)) }
+  #
+  # The arithmetic and its order are part of the contract: an app pins these outputs at 1e-9 relative (they go through
+  # Math.lgamma), so a reordered formula is a breaking change even when it is "the same".
+  module HierarchicalRates
+    # The strengths a level is fitted on: 2**-2 to 2**12 in quarter powers of 2, 57 points.
+    GRID = Array.new(57) { |i| 2.0**(-2 + (i / 4.0)) }.freeze
+    # A strength's log-likelihood within this of the maximum lies in the 95 % profile interval: half the 95 % point
+    # of chi-squared(1).
+    PROFILE_DROP = 1.92
+    # A pair whose parent has fewer children with data than this carries nothing about its level: the fit and both
+    # checks leave it out.
+    MINIMUM_SIBLINGS = 2
+    # The leaf fit takes at most this many steps on a parent's null rate ...
+    LEAF_STEPS = 50
+    # ... and stops at the first step that moves the rate by at most this share of itself.
+    LEAF_CHANGE = 1e-10
+
+    class << self
+      # The parent's share with the node's own count and total taken out, smoothed toward a prior share:
+      # (parent_count - node_count + prior_strength * prior_share) / (parent_total - node_total + prior_strength).
+      def leave_one_out_share(parent_count:, parent_total:, node_count:, node_total:, prior_share:, prior_strength:)
+        parent_count = nonnegative(parent_count, "parent_count")
+        parent_total = nonnegative(parent_total, "parent_total")
+        node_count = nonnegative(node_count, "node_count")
+        node_total = nonnegative(node_total, "node_total")
+        prior_share = share(prior_share, "prior_share")
+        prior_strength = nonnegative(prior_strength, "prior_strength")
+
+        denominator = parent_total - node_total + prior_strength
+        unless denominator.positive?
+          raise ArgumentError, "parent_total - node_total + prior_strength must be > 0, got #{denominator}"
+        end
+
+        (parent_count - node_count + (prior_strength * prior_share)) / denominator
+      end
+
+      # One node: count s, expected count E, strength k, hot share h, a threshold L on the ratio to the reference
+      # (theta = parent_ratio * node ratio), and the parent's own P(theta > L) and ratio.
+      #   hot   = h * NB(s; k, k / (k + E)) / [h * NB + (1 - h) * Poisson(s; E)], 1.0 at h = 1
+      #   ratio = (1 - hot) + hot * (k + s) / (k + E)
+      #   tail  = (1 - hot) * parent_tail + hot * Q(k + s, (k + E) * L / parent_ratio), Q = Gamma.regularized_upper
+      # A node with nothing expected (E = 0) may only have a count of 0, and then answers its prior.
+      def node(count:, expected:, strength:, hot_share: 1.0, threshold:, parent_tail:, parent_ratio:)
+        s = nonnegative(count, "count")
+        e = nonnegative(expected, "expected")
+        k = positive(strength, "strength")
+        h = share(hot_share, "hot_share")
+        limit = nonnegative(threshold, "threshold")
+        parent_tail = share(parent_tail, "parent_tail")
+        parent_ratio = positive(parent_ratio, "parent_ratio")
+        observable(s, e)
+
+        hot = hot_probability(s, e, k, h)
+        ratio = (1.0 - hot) + (hot * (k + s) / (k + e))
+        tail = ((1.0 - hot) * parent_tail) + (hot * Gamma.regularized_upper(k + s, (k + e) * limit / parent_ratio))
+        { ratio: ratio, hot: hot, tail: tail }
+      end
+
+      # The level fit: the marginal log-likelihood sum log[h * NB(s; k, k / (k + E)) + (1 - h) * Poisson(s; E)] over
+      # pairs [{ count:, expected:, siblings: }] (siblings: the children of the pair's parent that hold data, the pair's
+      # own node included), maximised over GRID and over hot_grid (h = 1 without one). A tie goes to the larger
+      # strength (the nodes then differ less), then to the hot share listed first. interval holds the grid strengths
+      # within PROFILE_DROP of the maximum at the fitted h; profile is [strength, log-likelihood] at every grid point
+      # at the fitted h. at_upper_bound: the strength is GRID's top, so the level's nodes inherit their parent.
+      def fit_strength(pairs:, hot_grid: nil)
+        level = level_terms(pairs)
+        hots = hot_grid.nil? ? [ 1.0 ] : hot_shares(hot_grid)
+
+        profiles = hots.map { [] }
+        GRID.each do |k|
+          terms = slab_terms(level, k)
+          hots.each_with_index { |h, j| profiles[j] << log_likelihood(terms, h) }
+        end
+
+        best_ll, best_k, best_j = best_point(profiles)
+        profile = profiles[best_j]
+        inside = GRID.each_index.select { |i| profile[i] >= best_ll - PROFILE_DROP }
+        {
+          strength: GRID[best_k],
+          hot_share: hots[best_j],
+          log_likelihood: best_ll,
+          at_upper_bound: best_k == GRID.size - 1,
+          interval: [ GRID[inside.min], GRID[inside.max] ],
+          profile: GRID.each_with_index.map { |k, i| [ k, profile[i] ] }
+        }
+      end
+
+      # The leaf level's two-groups fit, each parent's NULL rate estimated jointly with k and h instead of read from a
+      # leave-one-out share. With few leaves to a parent (about five), a hot leaf lifts its siblings' leave-one-out
+      # share, so they read as cold, and a fit on those expected counts reads the hot share several times too high.
+      #
+      # parents: [[{ count:, total: }]], each parent's leaves, count a real number >= 0 and total the leaf's exposure,
+      # > 0; a leaf expects total * rate, rate its parent's null rate. At a strength k (grid: rising strengths, GRID
+      # by default) and a hot share h (hot_shares: each in [0, 1), since the rate is read from the leaves that may be
+      # null), every parent's rate starts at its pooled rate, sum count / sum total, and each step makes it
+      #   rate = sum w * count / sum w * total, w = the leaf's posterior probability of being null at the rate before,
+      # the null part of the mixture whose slab part is a node's hot. A parent stops at the first step that moves its
+      # rate by at most LEAF_CHANGE of itself (converged) or after LEAF_STEPS steps; parents share only k and h, so
+      # each is stepped on its own. A step whose sums give no rate, or a rate of 0 beside a count above 0 (which no
+      # rate of 0 explains), is not taken: the parent keeps its rate, not converged.
+      #
+      # The fit maximises fit_strength's marginal log-likelihood, over the leaves at their parents' rates, on grid
+      # times hot_shares; a tie goes to the larger strength, then to the hot share listed first. A parent with fewer
+      # than MINIMUM_SIBLINGS leaves is its own leaf's rate and carries nothing about the level: it is left out of
+      # the fit and answered at the fitted k and h. The answer, converged, rates and hot in the order given:
+      #   { strength:, hot_share:, log_likelihood:, at_upper_bound: (the strength is grid's last), converged: [whether
+      #     the parent's rate settled at the fitted point], rates: [rate], hot: [[posterior probability that the leaf
+      #     is hot]] }
+      # A leaf's hot is node's hot at count: count, expected: total * rate, strength: and hot_share:, bit for bit. A
+      # parent whose one leaf is near the line between null and hot can take hundreds of steps to settle: it answers
+      # its rate after LEAF_STEPS steps, and converged says so.
+      def fit_leaves(parents:, hot_shares:, grid: GRID)
+        groups = leaf_groups(parents)
+        strengths = strength_grid(grid)
+        hots = leaf_hot_shares(hot_shares)
+        kept = groups.select { |leaves| leaves.size >= MINIMUM_SIBLINGS }
+        raise ArgumentError, "no parent with #{MINIMUM_SIBLINGS} or more leaves" if kept.empty?
+
+        profiles = hots.map { [] }
+        strengths.each do |k|
+          level = with_strength(kept, k)
+          hots.each_with_index { |h, j| profiles[j] << leaf_level(level, k, h)[:log_likelihood] }
+        end
+
+        best_ll, best_k, best_j = best_point(profiles)
+        k = strengths[best_k]
+        h = hots[best_j]
+        fitted = leaf_level(with_strength(groups, k), k, h)
+        {
+          strength: k,
+          hot_share: h,
+          log_likelihood: best_ll,
+          at_upper_bound: best_k == strengths.size - 1,
+          converged: fitted[:converged],
+          rates: fitted[:rates],
+          hot: groups.zip(fitted[:rates]).map do |leaves, rate|
+            leaves.map { |s, t| hot_probability(s, t * rate, k, h) }
+          end
+        }
+      end
+
+      # exp((1 - weight) * log previous + weight * log fitted), a moving average in logs; fitted when there is no
+      # previous value.
+      def smooth_strength(previous:, fitted:, weight: 0.2)
+        fitted = positive(fitted, "fitted")
+        return fitted if previous.nil?
+
+        previous = positive(previous, "previous")
+        weight = share(weight, "weight")
+        Math.exp(((1.0 - weight) * Math.log(previous)) + (weight * Math.log(fitted)))
+      end
+
+      # Marshall's moment estimate of the ratios' variance over the fit's pairs: A = sum E * (s / E - m)**2 / sum E -
+      # m / mean(E), m = sum s / sum E, floored at 0; strength 1 / A, infinite at 0.
+      def marshall(pairs:)
+        level = kept_pairs(pairs)
+        total = level.sum { |_s, e| e }
+        m = level.sum { |s, _e| s } / total
+        spread = level.sum { |s, e| e * (((s / e) - m)**2) } / total
+        variance = spread - (m / (total / level.size))
+        variance = 0.0 unless variance.positive?
+        { variance: variance, strength: variance.zero? ? Float::INFINITY : 1.0 / variance }
+      end
+
+      # Does the level matter at all? LR = 2 * (l(k, h) - l(infinite)), l the fit's log-likelihood on the fit's
+      # pairs and l(infinite) the all-Poisson one; p = 0.5 * chi_squared_survival(LR, 1) on the boundary, 1.0 at
+      # LR <= 0. The statistic is answered as computed, negative included.
+      def boundary_test(pairs:, strength:, hot_share: 1.0)
+        level = level_terms(pairs)
+        k = positive(strength, "strength")
+        h = share(hot_share, "hot_share")
+
+        statistic = 2.0 * (log_likelihood(slab_terms(level, k), h) - level.sum { |term| term[3] })
+        p_value = statistic > 0.0 ? 0.5 * Significance.chi_squared_survival(statistic, 1) : 1.0
+        { statistic: statistic, p_value: p_value }
+      end
+
+      private
+
+      # The posterior probability that the node is drawn from the slab: the slab's part of the same two-part mixture
+      # whose log is a pair's term in the level's likelihood (log_likelihood).
+      def hot_probability(s, e, k, h)
+        return 1.0 if h == 1.0
+        return 0.0 if h.zero?
+
+        log_hot, log_rest = log_weights(h)
+        log_factorial = Math.lgamma(s + 1.0)[0]
+        slab = log_hot + log_slab(s, e, k, Math.lgamma(k)[0], log_factorial)
+        null = log_rest + log_null(s, e, log_factorial)
+        1.0 / (1.0 + Math.exp(null - slab))
+      end
+
+      # sum over pairs of log[h * NB + (1 - h) * Poisson], each term mixed in logs.
+      def log_likelihood(terms, h)
+        return terms.sum { |slab, _null| slab } if h == 1.0
+        return terms.sum { |_slab, null| null } if h.zero?
+
+        log_hot, log_rest = log_weights(h)
+        terms.sum { |slab, null| log_sum(log_hot + slab, log_rest + null) }
+      end
+
+      # [log h, log(1 - h)] for 0 < h < 1: the two parts' weights.
+      def log_weights(h)
+        [ Math.log(h), Math.log(1.0 - h) ]
+      end
+
+      # log(e**a + e**b), from the larger.
+      def log_sum(a, b)
+        if a > b
+          a + Math.log(1.0 + Math.exp(b - a))
+        else
+          b + Math.log(1.0 + Math.exp(a - b))
+        end
+      end
+
+      # log NB(s; k, k / (k + E)) = lgamma(s + k) - lgamma(k) - lgamma(s + 1) + k log(k / (k + E)) + s log(E / (k + E)).
+      def log_slab(s, e, k, log_gamma_k, log_factorial)
+        log_slab_from(Math.lgamma(s + k)[0], s, e, k, log_gamma_k, log_factorial)
+      end
+
+      # log_slab with lgamma(s + k) given, in the same order.
+      def log_slab_from(log_gamma_sk, s, e, k, log_gamma_k, log_factorial)
+        log_gamma_sk - log_gamma_k - log_factorial + (k * Math.log(k / (k + e))) + x_log_y(s, e / (k + e))
+      end
+
+      # log Poisson(s; E) = s log E - E - lgamma(s + 1).
+      def log_null(s, e, log_factorial)
+        x_log_y(s, e) - e - log_factorial
+      end
+
+      # x log y, 0 at x = 0 (a count of 0 against nothing expected).
+      def x_log_y(x, y)
+        x.zero? ? 0.0 : x * Math.log(y)
+      end
+
+      # [log NB, log Poisson] of every pair at strength k.
+      def slab_terms(level, k)
+        log_gamma_k = Math.lgamma(k)[0]
+        level.map { |s, e, log_factorial, null| [ log_slab(s, e, k, log_gamma_k, log_factorial), null ] }
+      end
+
+      # The kept pairs with what does not depend on k: [s, E, lgamma(s + 1), log Poisson(s; E)].
+      def level_terms(pairs)
+        kept_pairs(pairs).map do |s, e|
+          log_factorial = Math.lgamma(s + 1.0)[0]
+          [ s, e, log_factorial, log_null(s, e, log_factorial) ]
+        end
+      end
+
+      # Every pair checked, the lone ones (fewer than MINIMUM_SIBLINGS children with data) left out: [[s, E]].
+      def kept_pairs(pairs)
+        kept = pairs.filter_map do |pair|
+          siblings = pair.fetch(:siblings) { raise ArgumentError, "each pair needs siblings:, got #{pair.inspect}" }
+          unless siblings.is_a?(Integer) && siblings >= 0
+            raise ArgumentError, "siblings must be an Integer >= 0, got #{siblings.inspect}"
+          end
+
+          s = nonnegative(pair.fetch(:count) { raise ArgumentError, "each pair needs count:" }, "count")
+          e = positive(pair.fetch(:expected) { raise ArgumentError, "each pair needs expected:" }, "expected")
+          [ s, e ] if siblings >= MINIMUM_SIBLINGS
+        end
+        raise ArgumentError, "no pair whose parent has #{MINIMUM_SIBLINGS} or more children with data" if kept.empty?
+
+        kept
+      end
+
+      # The largest log-likelihood, ties to the larger strength, then to the hot share listed first:
+      # [log-likelihood, grid index, hot index].
+      def best_point(profiles)
+        best = nil
+        profiles.each_with_index do |profile, j|
+          profile.each_with_index do |ll, i|
+            best = [ ll, i, j ] if best.nil? || ll > best[0] || (ll == best[0] && i > best[1])
+          end
+        end
+        best
+      end
+
+      def hot_shares(hot_grid, name = "hot_grid")
+        hots = hot_grid.map { |h| share(h, "each #{name} value") }
+        raise ArgumentError, "#{name} must hold at least one hot share" if hots.empty?
+
+        hots
+      end
+
+      # The leaf fit's hot shares, each below 1: the null rate is read from the leaves that may be null.
+      def leaf_hot_shares(values)
+        raise ArgumentError, "hot_shares must be an Array, got #{values.inspect}" unless values.is_a?(Array)
+
+        hots = hot_shares(values, "hot_shares")
+        raise ArgumentError, "each hot_shares value must be below 1, got #{values.inspect}" if hots.include?(1.0)
+
+        hots
+      end
+
+      def strength_grid(grid)
+        unless grid.is_a?(Array) && !grid.empty?
+          raise ArgumentError, "grid must be an Array of at least one strength, got #{grid.inspect}"
+        end
+
+        strengths = grid.map { |k| positive(k, "each grid strength") }
+        raise ArgumentError, "grid must rise strictly, got #{grid.inspect}" unless strengths.each_cons(2).all? { |a, b| a < b }
+
+        strengths
+      end
+
+      # Every parent's leaves checked: [[[s, t, lgamma(s + 1)]]].
+      def leaf_groups(parents)
+        raise ArgumentError, "parents must be an Array of parents, got #{parents.inspect}" unless parents.is_a?(Array)
+
+        parents.map do |leaves|
+          unless leaves.is_a?(Array) && !leaves.empty?
+            raise ArgumentError, "each parent must be an Array of at least one leaf, got #{leaves.inspect}"
+          end
+
+          leaves.map do |leaf|
+            raise ArgumentError, "each leaf must be a Hash of count: and total:, got #{leaf.inspect}" unless leaf.is_a?(Hash)
+
+            s = nonnegative(leaf.fetch(:count) { raise ArgumentError, "each leaf needs count:" }, "count")
+            t = positive(leaf.fetch(:total) { raise ArgumentError, "each leaf needs total:" }, "total")
+            [ s, t, Math.lgamma(s + 1.0)[0] ]
+          end
+        end
+      end
+
+      # The parents at strength k, each [pooled rate, any count above 0, leaves], a leaf [s, t, lgamma(s + 1),
+      # lgamma(s + k), lgamma(s + k) - lgamma(k) + k log k].
+      def with_strength(groups, k)
+        base = (k * Math.log(k)) - Math.lgamma(k)[0]
+        groups.map do |leaves|
+          parent = leaves.map do |s, t, log_factorial|
+            log_gamma_sk = Math.lgamma(s + k)[0]
+            [ s, t, log_factorial, log_gamma_sk, log_gamma_sk + base ]
+          end
+          [ pooled_rate(leaves), leaves.any? { |s, _t| s.positive? }, parent ]
+        end
+      end
+
+      # Every parent's null rate at strength k and hot share h, whether it settled, and the log-likelihood of their
+      # leaves at those rates (fit_strength's terms, in the same order).
+      def leaf_level(level, k, h)
+        log_gamma_k = Math.lgamma(k)[0]
+        odds = h.zero? ? nil : Math.log(h) - Math.log(1.0 - h)
+        converged = []
+        terms = []
+        rates = level.map do |pooled, counted, leaves|
+          rate, settled = odds.nil? || !counted || leaves.size == 1 ? [ pooled, true ] : null_rate(pooled, leaves, k, odds)
+          converged << settled
+          leaves.each do |s, t, log_factorial, log_gamma_sk|
+            e = t * rate
+            terms << [ log_slab_from(log_gamma_sk, s, e, k, log_gamma_k, log_factorial), log_null(s, e, log_factorial) ]
+          end
+          rate
+        end
+        { rates: rates, converged: converged, log_likelihood: log_likelihood(terms, h) }
+      end
+
+      # One parent's null rate (fit_leaves) from its pooled rate, at log odds log(h / (1 - h)) with 0 < h < 1 and a
+      # count above 0: [rate, converged]. A leaf's weight is its posterior probability of being null, 1 / (1 +
+      # exp(d)), d the log odds of slab to null, log(h / (1 - h)) + lgamma(s + k) - lgamma(k) + k log k + E - (k + s)
+      # log(k + E), the two parts' lgamma(s + 1) and s log E cancelling. (At h = 0 every weight is 1, with no count
+      # every rate is 0, and a lone leaf's weight cancels, so in each case the pooled rate is its own next step.)
+      def null_rate(rate, leaves, k, odds)
+        LEAF_STEPS.times do
+          count = 0.0
+          total = 0.0
+          leaves.each do |s, t, _log_factorial, _log_gamma_sk, base|
+            e = t * rate
+            w = 1.0 / (1.0 + Math.exp(odds + base + e - ((k + s) * Math.log(k + e))))
+            count += w * s
+            total += w * t
+          end
+          following = count / total
+          return [ rate, false ] unless following.finite? && following.positive?
+
+          settled = (following - rate).abs <= LEAF_CHANGE * rate
+          rate = following
+          return [ rate, true ] if settled
+        end
+        [ rate, false ]
+      end
+
+      # sum s / sum t over a parent's leaves, summed in order: every weight 1.
+      def pooled_rate(leaves)
+        count = 0.0
+        total = 0.0
+        leaves.each do |s, t|
+          count += s
+          total += t
+        end
+        count / total
+      end
+
+      def observable(s, e)
+        return unless e.zero? && s.positive?
+
+        raise ArgumentError, "a count above 0 needs an expected count above 0, got count #{s} and expected 0"
+      end
+
+      # A finite real number, as the other modules read one (a Complex is not real, whatever its imaginary part), and
+      # finite as a Float too (an Integer or Rational beyond a Float's range is not).
+      def real(value, name)
+        number = value.to_f if value.is_a?(Numeric) && value.real? && value.finite?
+        return number if number&.finite?
+
+        raise ArgumentError, "#{name} must be a finite number, got #{value.inspect}"
+      end
+
+      def nonnegative(value, name)
+        value = real(value, name)
+        raise ArgumentError, "#{name} must be >= 0, got #{value}" if value.negative?
+
+        value
+      end
+
+      def positive(value, name)
+        value = real(value, name)
+        raise ArgumentError, "#{name} must be > 0, got #{value}" unless value.positive?
+
+        value
+      end
+
+      def share(value, name)
+        value = real(value, name)
+        raise ArgumentError, "#{name} must lie in [0, 1], got #{value}" unless value.between?(0.0, 1.0)
+
+        value
+      end
+    end
+  end
+end

data/lib/skiftet_statistical/inputs.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+module SkiftetStatistical
+  # The library's one reading of what a caller hands in besides a number (SkiftetStatistical::Numbers reads those):
+  # a random number generator and the values it answers, and a name, each written once, each refusing with an
+  # ArgumentError, the one call into a caller's object (`asked`), the one reading of a caller's String (`string`) and
+  # the one way a value and a class are shown in a refusal (`shown`, `class_name`). Private to the library: the code
+  # new in 0.4.0 asks these; every 0.3.0 module keeps its own readings, as 0.3.0 wrote them.
+  #
+  # The caller-object contract. Every method the new code calls on a caller's object goes through `asked`: a key
+  # part's to_s, a name's hash and eql? (a lookup by it), a list's each, a number's real?, finite? and to_f
+  # (Numbers.read), an rng's rand, a status's to_s, an Amount's numbers, Kernel#respond_to? (which asks
+  # respond_to_missing?), and, to word a refusal, a value's inspect and an error's message. A StandardError such a
+  # call raises, or a NotImplementedError (the error an unfinished method raises), is an ArgumentError naming the
+  # input, as an answer of the wrong kind is (or, for the readings that word a refusal, the answer they fall back on).
+  # The core values the new code reads from a caller are read by core methods bound to them, never by their own: a
+  # String by `string` (String's own b and encoding), a number by Numbers.read, a class's name by Module's own name
+  # (`class_name`), a Hash or an Array by Hash's and Array's own methods (`pairs`, `elements`, `fetched`,
+  # `with_values`, `merged`), so a subclass's methods, a singleton method or an overridden == are never called, nor a
+  # default the Hash holds read. Whatever a caller's object answers is then judged by these one readers. The
+  # callables a caller hands in to do its own work (a pass's block, a hold's satisfied_for?) are its own code: what
+  # they raise reaches it as raised.
+  #
+  # An rng is any object that answers rand (asked by Kernel#respond_to?, so an object that answers it only through
+  # method_missing, or a BasicObject, is not one); its rand must answer a Float in [0, 1) and its rand(n) an Integer in
+  # [0, n). A name is any object that answers hash, eql? and inspect, its hash an Integer, so a Hash can look it up.
+  # Each is checked where it is read, before any draw; an answer of rand, which cannot be checked before it is drawn,
+  # at the draw that read it (`checked` wraps an rng so that a reader written for a plain rng, such as 0.3.0's
+  # Sampler, has each answer checked as it draws it).
+  module Inputs
+    # Kernel's own methods, bound to the value, so that an object that answers neither (a BasicObject) is read too.
+    RESPONDS = Kernel.instance_method(:respond_to?)
+    CLASS_OF = Kernel.instance_method(:class)
+    # Module's own name, bound to a class, so that a class whose name or to_s is its own is named by Ruby's record.
+    MODULE_NAME = Module.instance_method(:name)
+    # String's own b and encoding, bound to a caller's String: the one reading of it (`string`).
+    STRING_BYTES = String.instance_method(:b)
+    STRING_ENCODING = String.instance_method(:encoding)
+    # Hash's and Array's own readers, bound to a caller's Hash or Array, so that a subclass's overrides are never
+    # called.
+    HASH_PAIRS = Hash.instance_method(:to_a)
+    HASH_FETCH = Hash.instance_method(:fetch)
+    HASH_VALUES = Hash.instance_method(:transform_values)
+    HASH_MERGE = Hash.instance_method(:merge)
+    ARRAY_ELEMENTS = Array.instance_method(:to_a)
+    # What `asked` is told by default to do when the call raises: refuse.
+    REFUSE = Object.new.freeze
+    private_constant :RESPONDS, :CLASS_OF, :MODULE_NAME, :STRING_BYTES, :STRING_ENCODING, :HASH_PAIRS, :HASH_FETCH,
+                     :HASH_VALUES, :HASH_MERGE, :ARRAY_ELEMENTS, :REFUSE
+
+    module_function
+
+    # THE call into a caller's object, written once: the block's answer, the block calling a method of `value` (`label`
+    # names the call: "a part's to_s", "may_lead: a name's lookup"). A StandardError or a NotImplementedError the call
+    # raises is an ArgumentError, "<label> raised <its class's name>: <its message> (got <value>)", that error its
+    # cause; or, when `otherwise` is given, `otherwise` is answered instead (the readings that word a refusal, and
+    # Numbers.read, which reads such a call as no number).
+    def asked(value, label, otherwise: REFUSE)
+      yield
+    rescue StandardError, NotImplementedError => e
+      return otherwise unless REFUSE.equal?(otherwise)
+
+      raise ArgumentError, "#{label} raised #{class_name(e)}#{described(e)} (got #{shown(value)})"
+    end
+
+    # ": <the error's message>", or "" when its message (asked by `asked`) answers no String or raises; the message read
+    # by `string` and worded by `words`.
+    def described(error)
+      text = string(asked(error, "an error's message", otherwise: nil) { error.message })
+      nil.equal?(text) ? "" : ": #{words(text)}"
+    end
+
+    # The value as a refusal shows it, the one reading that never refuses, since it words the refusals: a String by
+    # its copy's inspect (`string`, so none of its own methods is called); any other value by its inspect (asked by
+    # `asked`), read by `string`; for a value that answers none (a BasicObject), whose inspect raises or answers no
+    # String, "an object of <its class's name>" (`class_name`). Worded by `words`.
+    def shown(value)
+      copy = string(value)
+      return words(copy.inspect) unless nil.equal?(copy)
+
+      text = string(asked(value, "an inspect", otherwise: nil) { value.inspect })
+      nil.equal?(text) ? "an object of #{class_name(value)}" : words(text)
+    end
+
+    # The name of the value's class, as a refusal words it: read by Kernel#class and Module#name, both bound (never
+    # the class's own name or to_s, so building a refusal never calls a caller's method), "an anonymous class" for a
+    # class without one; worded by `words`.
+    def class_name(value)
+      name = MODULE_NAME.bind_call(CLASS_OF.bind_call(value))
+      nil.equal?(name) ? "an anonymous class" : words(string(name))
+    end
+
+    # THE reading of a caller's String, written once (a key part or its to_s answer, an item name, a status or its
+    # to_s answer, a name in a list, and the words of a refusal): a plain, frozen String of the same bytes in the same encoding,
+    # copied by String's own b and encoding bound to it, so a subclass's methods, a singleton method (a frozen String
+    # keeps those) or an overridden == are never called; nil for a value that is not a String. What the new code reads
+    # of the String (==, include?, inspect, its encoding, its bytes) it then reads of the copy, whose methods are
+    # String's own.
+    def string(value)
+      return nil unless String === value
+
+      STRING_BYTES.bind_call(value).force_encoding(STRING_ENCODING.bind_call(value)).freeze
+    end
+
+    # THE reading of a value as text, written once (a key part, a status): a String by `string`, so none of its own
+    # methods is called, its to_s included; any other value by its to_s (Kernel#respond_to? and the call asked by
+    # `asked`, `label` naming the value, so a to_s that raises is an ArgumentError), its answer read by `string`; nil
+    # when the value answers no to_s or its to_s answers no String.
+    def text(value, label)
+      copy = string(value)
+      return copy unless nil.equal?(copy)
+      return nil unless responds?(value, :to_s, label)
+
+      string(asked(value, "#{label}'s to_s") { value.to_s })
+    end
+
+    # A copy (`string`) as a refusal sets it among its words: as it is when its bytes are ASCII in an ASCII-compatible
+    # encoding, or valid in the encoding String#inspect answers in (the default internal encoding, else the default
+    # external, US-ASCII when that is not ASCII-compatible); else its inspect, its characters escaped in that encoding.
+    # So the words of one refusal never meet in incompatible encodings, and building it never raises.
+    def words(text)
+      return text if text.ascii_only?
+
+      encoding = Encoding.default_internal || Encoding.default_external
+      encoding = Encoding::US_ASCII unless encoding.ascii_compatible?
+      text.encoding == encoding && text.valid_encoding? ? text : text.inspect
+    end
+
+    # A caller's Hash's [key, value] pairs, in its order, by Hash's own to_a: a new Array.
+    def pairs(hash)
+      HASH_PAIRS.bind_call(hash)
+    end
+
+    # A caller's Hash's value at `key`, or `missing` when it holds none, by Hash's own fetch (a default the Hash holds
+    # is never read). Looking a caller's key up calls its hash and eql?: the caller asks this through `asked`.
+    def fetched(hash, key, missing)
+      HASH_FETCH.bind_call(hash, key, missing)
+    end
+
+    # A caller's Hash with each value replaced by the block's answer for it, by Hash's own transform_values: a new
+    # Hash of its keys as given, never hashed again.
+    def with_values(hash, &)
+      HASH_VALUES.bind_call(hash, &)
+    end
+
+    # A caller's Hash merged with `other`, by Hash's own merge.
+    def merged(hash, other)
+      HASH_MERGE.bind_call(hash, other)
+    end
+
+    # A caller's Array's elements, by Array's own to_a: the Array itself, or for a subclass's, a new plain Array.
+    def elements(array)
+      ARRAY_ELEMENTS.bind_call(array)
+    end
+
+    # Whether the value answers the method, by Kernel#respond_to? (a BasicObject answers nothing), asked by `asked`
+    # (respond_to? asks the value's respond_to_missing?), `label` naming the value.
+    def responds?(value, method, label = "a value")
+      asked(value, "#{label}'s respond_to?(:#{method})") { RESPONDS.bind_call(value, method) }
+    end
+
+    # The rng, when it answers rand; else an ArgumentError naming `label`.
+    def rng(value, label = "rng")
+      return value if responds?(value, :rand, label)
+
+      raise ArgumentError, "#{label} must answer rand (got #{shown(value)})"
+    end
+
+    # The rng's next rand (asked by `asked`), when it is a Float in [0, 1); else an ArgumentError.
+    def uniform(rng)
+      value = asked(rng, "rng.rand") { rng.rand }
+      return value if Float === value && value >= 0.0 && value < 1.0
+
+      raise ArgumentError, "rng.rand must answer a Float in [0, 1) (got #{shown(value)})"
+    end
+
+    # The rng's next rand(size) (asked by `asked`), when it is an Integer in [0, size); else an ArgumentError.
+    def index(rng, size)
+      value = asked(rng, "rng.rand(#{size})") { rng.rand(size) }
+      return value if Integer === value && value >= 0 && value < size
+
+      raise ArgumentError, "rng.rand(#{size}) must answer an Integer in [0, #{size}) (got #{shown(value)})"
+    end
+
+    # The rng (by `rng`), wrapped so that each of its answers is checked when it is drawn: rand by `uniform`, rand(n)
+    # by `index`. The wrapper answers the rng's own stream, one rand of the rng a rand of its own; an rng already
+    # wrapped is answered as it is.
+    def checked(value, label = "rng")
+      Checked === value ? value : Checked.new(rng(value, label))
+    end
+
+    # Whether the value can name something a Hash looks up: it answers hash, eql? and inspect, and its hash answers
+    # an Integer (a Hash raises TypeError on any other hash, and calls eql? on a name whose hash matches a key's). Its
+    # hash is asked by `asked`, `label` naming where the name was given: a hash that raises is an ArgumentError.
+    def name?(value, label = "a name")
+      responds?(value, :hash, label) && responds?(value, :eql?, label) && responds?(value, :inspect, label) &&
+        Integer === asked(value, "#{label}: a name's hash") { value.hash }
+    end
+
+    # An rng whose answers are checked as they are drawn (`checked`).
+    class Checked
+      def initialize(rng)
+        @rng = rng
+      end
+
+      # The rng's rand, checked by `uniform`; with a size, its rand(size), checked by `index`.
+      def rand(size = nil)
+        nil.equal?(size) ? Inputs.uniform(@rng) : Inputs.index(@rng, size)
+      end
+    end
+    private_constant :Checked
+  end
+  private_constant :Inputs
+end