skiftet_statistical 0.2.0 → 0.4.0

data/lib/skiftet_statistical/linear_value.rb

@@ -0,0 +1,364 @@
+# frozen_string_literal: true
+
+require_relative "sampler"
+require_relative "descriptive"
+require_relative "cholesky"
+
+module SkiftetStatistical
+  # The value of each arm as a linear sum of several rates, V_a = sum over parts p of w_p * r_(a, p), when both the
+  # rates and the weights are uncertain. The rates are one joint normal over every (arm, part) pair (each arm's part
+  # means and one covariance over all pairs, so arms that share their evidence stay correlated); the weights come from
+  # named parameters drawn afresh in every joint draw. Because each draw takes its weights and its rates together,
+  # P(best) and the expected loss hedge every uncertain weight at once instead of judging the arms at one assumed
+  # weight.
+  #
+  #   SkiftetStatistical::LinearValue.summary(
+  #     arms: %i[a b], parts: %i[p q],
+  #     means: { a: [ 0.12, 0.031 ], b: [ 0.105, 0.044 ] },
+  #     covariance: [ [ 4e-4, 6e-5, 2e-4, 1e-5 ], [ 6e-5, 1e-4, 2e-5, 4e-5 ],     # arm-major:
+  #                   [ 2e-4, 2e-5, 5e-4, -5e-5 ], [ 1e-5, 4e-5, -5e-5, 1.2e-4 ] ], # (a, p), (a, q), (b, p), (b, q)
+  #     parameters: { base: { fixed: 1.5 }, worth: { uniform: [ 2.0, 6.0 ] },
+  #                   lift: { normal: [ 0.5, 0.2 ], clip: [ 0.0, 1.0 ] } },
+  #     weights: ->(drawn) { { p: drawn.fetch(:base), q: drawn.fetch(:worth) * drawn.fetch(:lift) } },
+  #     draws: 20_000, rng: Random.new(7))
+  #   # => { a: { point: 0.242, mean: 0.2423..., lower: 0.1516..., upper: 0.3587..., p_best: 0.47715,
+  #   #           expected_loss: 0.0188... },
+  #   #      b: { point: 0.2455, mean: 0.2461..., lower: 0.1460..., upper: 0.3736..., p_best: 0.52285,
+  #   #           expected_loss: 0.0150... } }
+  #
+  # THE DRAW ORDER IS THE CONTRACT (as JointBeta's). Per draw:
+  # 1. each parameter in the order given: `fixed: x` takes nothing; `uniform: [lo, hi]` one `rng.rand` u, giving
+  #    lo + (hi - lo) * u; `normal: [mean, sd]` one Sampler#gaussian g, giving mean + sd * g; then its `clip: [lo, hi]`
+  #    when it has one (any kind may; a clip bound may be infinite);
+  # 2. the part weights, `weights.call(drawn)` with the drawn values under the parameters' own names;
+  # 3. one joint normal draw of every (arm, part) rate, z = means + L * n: n is K * P Sampler#gaussian values in
+  #    arm-major order, L the Cholesky factor of the covariance (Cholesky.factor, once per call);
+  # 4. each arm's value V_a = sum over parts p of w_p * z_(a, p).
+  # A part with no variance is drawn at its mean and still takes its normal, so the numbers taken never depend on the
+  # data. A seeded caller gets the same rows only while this order holds, never with a draw added, dropped or moved.
+  #
+  # Where Cholesky.factor refuses the covariance, L is Cholesky.root's square root S of it, read the same way with the
+  # same K * P normals: the draw order holds and the joint normal is the same one, but S is not triangular, so its rows
+  # are not the rows the factor would give. That is a covariance of lower rank whose rounding the given order cannot
+  # carry. `rounding:` (a finite number of at least 0, 0.0 by default) is the largest rounding bound of the covariance's
+  # entries, read only there: a caller with SharedCredit's estimate hands `estimate.rounding`, so a covariance summed
+  # from rows is never refused for its own rounding. An entry cleared to 0 under its bound may be that bound and its own
+  # rounding from the exact one, so Cholesky.root is given twice `rounding`. A covariance that neither takes raises.
+  #
+  # Everything is checked before the first random number (ArgumentError): 1 to 7 arms and 1 to 12 parts, each named
+  # once by a Symbol or a String (a part shared by one weight is summed into one by the caller); `means` an Array of
+  # P finite numbers per arm; `covariance` (K * P) rows of K * P, symmetric and positive semidefinite (Cholesky);
+  # each parameter one kind of finite numbers (uniform lo <= hi, normal sd >= 0, clip lo <= hi); `weights` callable,
+  # answering a Hash with a finite number for every part (read by Symbol or String; a key for no part is left out).
+  # A finite number is a real Numeric that stays finite as a Float (an Integer or Rational beyond a Float's range, a
+  # Complex, a NaN and an infinity are refused alike), the one number check the library's modules share.
+  # The weights are first read at the parameters' centres, so a callable that leaves out a part is refused before any
+  # draw; a draw whose weights leave one out raises too.
+  module LinearValue
+    MAX_ARMS = 7
+    MAX_PARTS = 12
+    # How many times its rounding bound an entry of a covariance may be from the exact one: cleared to 0 under the
+    # bound, it may have been a bound and a half away. Cholesky.root is given this much.
+    ENTRY_ROUNDING = 2.0
+
+    class << self
+      # Per arm (the arms as given): `point` the value at every parameter's centre (the fixed value, the uniform's
+      # midpoint, the normal's mean, each clipped) and the part means; over the `draws` joint draws, `mean` the mean of
+      # the drawn values, `lower` and `upper` their equal-tailed `credible_mass` interval (Descriptive.percentile),
+      # `p_best` the share of draws the arm is best in (a tie split equally) and `expected_loss` the mean of the draw's
+      # best value minus the arm's. Built on the rows each_draw yields: the same seed gives the same rows.
+      def summary(arms:, parts:, means:, covariance:, parameters:, weights:, draws:, rng:, credible_mass: 0.95, rounding: 0.0)
+        model = Model.new(arms: arms, parts: parts, means: means, covariance: covariance, parameters: parameters,
+                          weights: weights, rounding: rounding)
+        draws = draw_count(draws)
+        raise ArgumentError, "summary needs at least one draw" if draws.zero?
+
+        tail = (1.0 - mass(credible_mass)) / 2.0
+        size = model.arms.size
+        samples = Array.new(size) { Array.new(draws) }
+        wins = Array.new(size, 0.0)
+        losses = Array.new(size, 0.0)
+
+        draw = 0
+        model.each_row(draws, rng) do |row|
+          best = row.max
+          leaders = 0
+          row.each_with_index do |value, index|
+            samples[index][draw] = value
+            losses[index] += best - value
+            leaders += 1 if value == best
+          end
+          share = 1.0 / leaders
+          row.each_with_index { |value, index| wins[index] += share if value == best }
+          draw += 1
+        end
+
+        model.arms.each_with_index.to_h do |arm, index|
+          values = samples[index]
+          [ arm, {
+            point: model.point[index],
+            mean: values.sum / draws,
+            lower: Descriptive.percentile(values, tail * 100.0),
+            upper: Descriptive.percentile(values, (1.0 - tail) * 100.0),
+            p_best: wins[index] / draws,
+            expected_loss: losses[index] / draws
+          } ]
+        end
+      end
+
+      # Yields one Array per draw, each arm's value V in `arms` order, and returns nil. Without a block the rows are
+      # drawn at once and an Enumerator over them is answered, so reading it again gives the same rows and the RNG is
+      # left where the block form leaves it.
+      def each_draw(arms:, parts:, means:, covariance:, parameters:, weights:, draws:, rng:, rounding: 0.0, &block)
+        model = Model.new(arms: arms, parts: parts, means: means, covariance: covariance, parameters: parameters,
+                          weights: weights, rounding: rounding)
+        draws = draw_count(draws)
+        unless block
+          rows = []
+          model.each_row(draws, rng) { |row| rows << row }
+          return rows.each
+        end
+
+        model.each_row(draws, rng, &block)
+        nil
+      end
+
+      private
+
+      def draw_count(draws)
+        raise ArgumentError, "draws must be an Integer >= 0, got #{draws.inspect}" unless draws.is_a?(Integer) && draws >= 0
+
+        draws
+      end
+
+      def mass(credible_mass)
+        unless credible_mass.is_a?(Numeric) && credible_mass.real? && credible_mass > 0 && credible_mass < 1
+          raise ArgumentError, "credible_mass must be a number above 0 and below 1, got #{credible_mass.inspect}"
+        end
+
+        credible_mass.to_f
+      end
+    end
+
+    # One call's checked inputs: the factor (taken once), the flat arm-major means, the parameters and the value at
+    # their centres. Its #each_row is the one draw order both public methods read.
+    class Model
+      KINDS = %i[fixed uniform normal].freeze
+      KEYS = (KINDS + %i[clip]).freeze
+
+      attr_reader :arms, :point
+
+      def initialize(arms:, parts:, means:, covariance:, parameters:, weights:, rounding:)
+        @arms = names(arms, "arms", MAX_ARMS)
+        @parts = names(parts, "parts", MAX_PARTS)
+        @size = @arms.size * @parts.size
+        @means = flat_means(means)
+        @parameters = read_parameters(parameters)
+        raise ArgumentError, "weights must respond to #call, got #{weights.class}" unless weights.respond_to?(:call)
+
+        @weights = weights
+        @lower, @bands = factor_bands(covariance, read_rounding(rounding))
+        @point = values(part_weights(centres), @means)
+      end
+
+      def each_row(draws, rng)
+        sampler = Sampler.new(rng)
+        draws.times do
+          weight = part_weights(draw_parameters(rng, sampler))
+          normals = Array.new(@size) { sampler.gaussian }
+          yield values(weight, rates(normals))
+        end
+      end
+
+      private
+
+      def names(list, label, most)
+        raise ArgumentError, "#{label} must be an Array, got #{list.class}" unless list.is_a?(Array)
+        raise ArgumentError, "#{label} must name 1 to #{most}, got #{list.size}" unless list.size.between?(1, most)
+
+        list.each do |name|
+          raise ArgumentError, "#{label} must be Symbols or Strings, got #{name.inspect}" unless name.is_a?(Symbol) || name.is_a?(String)
+        end
+        raise ArgumentError, "#{label} must each be named once" unless list.map(&:to_s).uniq.size == list.size
+
+        list.dup.freeze
+      end
+
+      def flat_means(means)
+        raise ArgumentError, "means must be a Hash of arm => [one mean per part], got #{means.class}" unless means.is_a?(Hash)
+
+        @arms.flat_map do |arm|
+          row = lookup(means, arm) { raise ArgumentError, "means has no row for arm #{arm.inspect}" }
+          unless row.is_a?(Array) && row.size == @parts.size
+            raise ArgumentError, "means of arm #{arm.inspect} must be #{@parts.size} numbers, one per part"
+          end
+
+          row.map { |value| finite(value, "a mean of arm #{arm.inspect}") }
+        end
+      end
+
+      # [name, kind, first, second, clip] per parameter, in the order given.
+      def read_parameters(parameters)
+        raise ArgumentError, "parameters must be a Hash of name => distribution, got #{parameters.class}" unless parameters.is_a?(Hash)
+
+        parameters.map { |name, spec| read_parameter(name, spec) }
+      end
+
+      def read_parameter(name, spec)
+        raise ArgumentError, "parameter #{name.inspect} must be a Hash, got #{spec.inspect}" unless spec.is_a?(Hash)
+
+        spec = spec.to_h { |key, value| [ key.respond_to?(:to_sym) ? key.to_sym : key, value ] }
+        unknown = spec.keys - KEYS
+        raise ArgumentError, "parameter #{name.inspect} has unknown key(s) #{unknown.inspect}" unless unknown.empty?
+
+        kinds = spec.keys & KINDS
+        raise ArgumentError, "parameter #{name.inspect} must have one of #{KINDS.inspect}" unless kinds.size == 1
+
+        kind = kinds.first
+        label = "parameter #{name.inspect}"
+        first, second =
+          if kind == :fixed
+            [ finite(spec.fetch(:fixed), label), nil ]
+          else
+            pair(spec.fetch(kind), "#{label} #{kind}")
+          end
+        raise ArgumentError, "#{label}: uniform needs lo <= hi" if kind == :uniform && first > second
+        raise ArgumentError, "#{label}: normal needs sd >= 0" if kind == :normal && second.negative?
+
+        [ name, kind, first, second, spec.key?(:clip) ? clip(spec.fetch(:clip), label) : nil ]
+      end
+
+      def pair(value, label)
+        raise ArgumentError, "#{label} must be two numbers, got #{value.inspect}" unless value.is_a?(Array) && value.size == 2
+
+        value.map { |number| finite(number, label) }
+      end
+
+      def clip(value, label)
+        unless value.is_a?(Array) && value.size == 2 && value.all? { |bound| clip_bound?(bound) }
+          raise ArgumentError, "#{label} clip must be two numbers [lo, hi], got #{value.inspect}"
+        end
+
+        bounds = value.map(&:to_f)
+        raise ArgumentError, "#{label} clip needs lo <= hi" if bounds[0] > bounds[1]
+
+        bounds
+      end
+
+      # A real number, an infinity allowed only as an infinity: one no Float holds is not read as one.
+      def clip_bound?(bound)
+        number?(bound) && !bound.to_f.nan? && (bound.to_f.finite? || !bound.finite?)
+      end
+
+      def read_rounding(value)
+        number = finite(value, "rounding")
+        raise ArgumentError, "rounding must be at least 0, got #{value.inspect}" if number.negative?
+
+        number
+      end
+
+      # The factor's rows and, per row, the band [first, last] of its nonzero columns (first > last for a row of
+      # zeros), so a row skips the zero blocks of independent arms; a zero inside the band adds a zero to its sum.
+      def factor_bands(covariance, rounding)
+        unless covariance.is_a?(Array) && covariance.size == @size
+          raise ArgumentError, "covariance must be #{@size} rows of #{@size} (arms x parts, arm-major)"
+        end
+
+        lower = square_root(covariance, rounding).map(&:freeze).freeze
+        bands = lower.map do |row|
+          nonzero = row.each_index.reject { |column| row[column].zero? }
+          nonzero.empty? ? [ 0, -1 ].freeze : [ nonzero.first, nonzero.last ].freeze
+        end
+        [ lower, bands.freeze ]
+      end
+
+      # The factor where it takes the covariance, so a covariance it takes draws its rows; the root where it refuses.
+      def square_root(covariance, rounding)
+        Cholesky.factor(covariance)
+      rescue ArgumentError
+        Cholesky.root(covariance, rounding: ENTRY_ROUNDING * rounding)
+      end
+
+      # z = means + L * n, each row summed left to right over its band.
+      def rates(normals)
+        Array.new(@size) do |index|
+          row = @lower[index]
+          column, last = @bands[index]
+          total = 0.0
+          while column <= last
+            total += row[column] * normals[column]
+            column += 1
+          end
+          @means[index] + total
+        end
+      end
+
+      def centres
+        @parameters.to_h do |name, kind, first, second, bounds|
+          centre = kind == :uniform ? (first + second) / 2.0 : first
+          [ name, bounds ? centre.clamp(*bounds) : centre ]
+        end
+      end
+
+      def draw_parameters(rng, sampler)
+        @parameters.to_h do |name, kind, first, second, bounds|
+          value =
+            case kind
+            when :fixed then first
+            when :uniform then first + ((second - first) * rng.rand)
+            else first + (second * sampler.gaussian)
+            end
+          [ name, bounds ? value.clamp(*bounds) : value ]
+        end
+      end
+
+      def part_weights(drawn)
+        given = @weights.call(drawn)
+        raise ArgumentError, "the weights callable must answer a Hash of part => weight, got #{given.class}" unless given.is_a?(Hash)
+
+        @parts.map do |part|
+          weight = lookup(given, part) { raise ArgumentError, "the weights callable left out part #{part.inspect}" }
+          finite(weight, "the weight of part #{part.inspect}")
+        end
+      end
+
+      # V_a = sum over parts p of w_p * rate_(a, p), the rates arm-major, summed left to right over the parts.
+      def values(weight, rates)
+        parts = weight.size
+        Array.new(@arms.size) do |arm|
+          offset = arm * parts
+          total = 0.0
+          part = 0
+          while part < parts
+            total += weight[part] * rates[offset + part]
+            part += 1
+          end
+          total
+        end
+      end
+
+      def lookup(hash, name)
+        return hash[name] if hash.key?(name)
+
+        other = name.is_a?(Symbol) ? name.to_s : name.to_sym
+        return hash[other] if hash.key?(other)
+
+        yield
+      end
+
+      def number?(value)
+        value.is_a?(Numeric) && value.real?
+      end
+
+      # A finite real number, finite as a Float too (an Integer or Rational beyond a Float's range is not), as a Float:
+      # the library's one number check.
+      def finite(value, label)
+        number = value.to_f if number?(value) && value.finite?
+        return number if number&.finite?
+
+        raise ArgumentError, "#{label} must be a finite number, got #{value.inspect}"
+      end
+    end
+    private_constant :Model
+  end
+end

data/lib/skiftet_statistical/numbers.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative "inputs"
+
+module SkiftetStatistical
+  # The library's one number reader, written once: every module new in 0.4.0 reads every number its caller hands it
+  # here (a parameter, a sum of a tally, a share, a probability, a prior, a strength, an age, a cap, a uniform, a
+  # weight), then checks its own bounds on the Float it gets back.
+  #
+  # The input domain: a number is a real Numeric (an Integer, a Float, a Rational, a BigDecimal) whose to_f answers a
+  # finite Float of magnitude at most LARGEST. Refused alike, as an ArgumentError: a NaN, an infinity, a Complex
+  # (whatever its imaginary part), nil, a String (a numeric one included: "0.5" and "0x14" are not numbers here), any
+  # other object (one that answers no method at all, a BasicObject, included), a Numeric that answers no to_f or whose
+  # to_f answers anything but a finite Float or raises, and a number beyond LARGEST either side of 0.
+  #
+  #   SkiftetStatistical::Numbers.read(3, "a count")             # => 3.0
+  #   SkiftetStatistical::Numbers.read("0.25", "a share")        # ArgumentError: a share must be a finite number, ...
+  #   SkiftetStatistical::Numbers.read(1e200, "a share")         # ArgumentError: a share must lie within the input ...
+  #   SkiftetStatistical::Numbers.read(nil, "a weight") { 0.0 }  # => 0.0, the block's answer for what is not a number
+  #   SkiftetStatistical::Numbers.pair([ 2, 3 ], "a prior", %w[alpha beta])  # => [2.0, 3.0]
+  module Numbers
+    # The largest magnitude the library reads: 10**100. Every sum, product and square the new code forms from its inputs
+    # then stays inside a Float (whose largest is about 1.8 * 10**308), because no product it forms multiplies more than
+    # two numbers of the domain's size: every other factor beside them is a share, a weight or a probability in [0, 1]
+    # (a Decay weight, a uniform, a mixing share) or a standard Normal score (at most about 8.3). The products, by the
+    # factors of the domain's size in each:
+    # - two: a share times a probability (Posteriors.mixture), the weighted outcomes times the views
+    #   (WeightedPosterior.beta) and the weighted views squared (its Kish size), each at most 10**200;
+    # - one: a standard deviation times a score, a weight times a sum, a mean held at a weight, at most 10**101;
+    # - none: the moments of amounts, the amounts rule's mean and gap and every shrunk mean (Bandit's Tallies.moments,
+    #   Tallies.amounts, Tallies.shrunk), whose products (a strength times a mean, the views times a sum, a sum
+    #   squared, the squares times the views) are formed exactly, as Integers and powers of 2 (Tallies.exact), and
+    #   rounded once (Tallies.rounded); and the amounts rule's standard deviation (Tallies.spread), whose three terms
+    #   multiply up to four such numbers (k, n and the difference of two means twice) and divide by k + n up to three
+    #   times, formed by Math.frexp's mantissas and powers of 2 apart. So no step of either leaves a Float either way,
+    #   and only an answer rounds into a Float's range.
+    # A sum over n such terms is at most n * 10**200, which leaves a Float only past n = 10**108 terms, no list a
+    # computer holds (a sum of n inputs, past 10**208). A quotient by a small input (a sum over views of 10**-300, say)
+    # can still leave a Float, but only to an infinity: a clamp or a minimum then reads it as it reads the exact
+    # quotient (which is larger than any bound it is clamped to), or it reaches the answer, where the bandit's one check
+    # of an answer refuses it. So no sum or product of inputs overflows on its way to an answer, and no answer reads a
+    # wrong finite number because one did.
+    LARGEST = 1e100
+
+    class << self
+      # The value as a Float in [-LARGEST, LARGEST]. A value that is not a number by the rule above is an ArgumentError,
+      # "<label> must be a finite number, got <the value inspected>" (Inputs.shown: a value that answers no inspect is
+      # named by its class), unless a block is given, whose answer (given the value) is answered instead: a reader
+      # with a rule of its own for what is not a number (a weight that counts 0, a bound with its own words). A number
+      # beyond LARGEST is always an ArgumentError, "<label> must lie within the input domain, at most <LARGEST> either
+      # side of 0 (got <the value inspected>)"; no block waives the domain.
+      def read(value, label)
+        number = float(value)
+        if nil.equal?(number)
+          return yield(value) if block_given?
+
+          raise ArgumentError, "#{label} must be a finite number, got #{Inputs.shown(value)}"
+        end
+        return number if number.abs <= LARGEST
+
+        raise ArgumentError, "#{label} must lie within the input domain, at most #{LARGEST} either side of 0 (got " \
+                             "#{Inputs.shown(value)})"
+      end
+
+      # THE reading of a pair [first, second], written once for every reader of one (a Beta pair, a Normal pair, a
+      # prior, a clip, a member): an Array of exactly two values (read by Array's own to_a, Inputs.elements, never a
+      # subclass's methods), else "<label> must be a pair [<names>] (got
+      # <value>)"; each value read by `read` as "<label>'s <name>", then, when a block is given, handed to it with
+      # that label and its index (0 or 1), and the block's answer kept: the reader's own bound. Answers two Floats.
+      def pair(given, label, names)
+        elements = Array === given ? Inputs.elements(given) : nil
+        unless elements&.size == 2
+          raise ArgumentError, "#{label} must be a pair [#{names.join(', ')}] (got #{Inputs.shown(given)})"
+        end
+
+        elements.each_with_index.map do |value, index|
+          name = "#{label}'s #{names[index]}"
+          number = read(value, name)
+          block_given? ? yield(number, name, index) : number
+        end
+      end
+
+      private
+
+      # The value as a finite Float when it is a real Numeric whose to_f answers one, whatever its magnitude; nil for
+      # anything else. Its respond_to?, real?, finite? and to_f are calls into the caller's object, asked by the
+      # library's one such call (Inputs.asked), told to answer nil when one raises: no number.
+      def float(value)
+        return nil unless Numeric === value
+
+        number = Inputs.asked(value, "a number's real?, finite? and to_f", otherwise: nil) do
+          value.to_f if Inputs.responds?(value, :to_f) && value.real? && value.finite?
+        end
+        Float === number && number.finite? ? number : nil
+      end
+    end
+  end
+end

data/lib/skiftet_statistical/prequential.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require_relative "significance"
+
+module SkiftetStatistical
+  # The prequential log score (Dawid 1984): how many bits an outcome cost a predictor that gave it probability p,
+  # -log2 p, scored on outcomes it had not seen. Several depths of one predictor, each deeper than the one before, are
+  # compared on the same events, and the gain of a depth is the bits per event it saves over the depth before it.
+  #
+  #   rows = [ { cluster: 1, log_probs: { shallow: Math.log(0.25), deep: Math.log(0.5) } },
+  #            { cluster: 1, log_probs: { shallow: Math.log(0.5),  deep: Math.log(0.5) } },
+  #            { cluster: 2, log_probs: { shallow: Math.log(0.5),  deep: Math.log(0.25) } },
+  #            { cluster: 3, log_probs: { shallow: Math.log(0.125), deep: Math.log(0.5) } } ]
+  #   SkiftetStatistical::Prequential.score(rows, depth: :deep)  # => 1.25
+  #   SkiftetStatistical::Prequential.gains(rows, depths: %i[shallow deep])
+  #   # => { deep: { bits: 0.5, se: 0.6495, events: 4, clusters: 3 } }
+  #
+  # Events of one cluster move together, so the standard error comes from the spread between clusters and not between
+  # events (Liang and Zeger 1986). With s_g and n_g a cluster's total and count, and G clusters,
+  #
+  #   mean = sum s_g / sum n_g
+  #   se   = sqrt(G / (G - 1) * sum (s_g - mean * n_g)^2) / sum n_g
+  #
+  # the residuals taken about the pooled mean, so a cluster weighs by its events. `clustered_mean` answers that mean with
+  # its normal interval for a caller that stores per-cluster totals and no events; `gains` adds its rows up to the same
+  # totals and goes through the same arithmetic, so the two cannot differ. Under 2 clusters there is no spread to read:
+  # the mean stands, its standard error and bounds are nil. With no event at all the mean is nil too.
+  #
+  # A log probability is a number at most 0. A probability of 0 has no finite log: such an outcome costs a predictor
+  # infinitely many bits, so the caller smooths it first and -Infinity is refused like any other non-finite number. A
+  # value above 0 is refused too (it is no log of a probability, and it is what a flipped sign looks like). Depths are
+  # named by Symbols or Strings, each once, and answered as given; a row's fields and depths are read by either spelling
+  # and each must be there once, a depth nobody asked for is not read. A cluster is any Hash key but nil. Every
+  # number is a finite real number, finite as a Float too (a NaN, an infinity, a Complex, an Integer beyond a Float's
+  # range and a non-number are refused alike), a count is above 0, and a total a Float cannot hold is refused rather
+  # than answered as NaN or infinity. Every refusal is an ArgumentError.
+  module Prequential
+    LOG2 = Math.log(2.0)
+
+    class << self
+      # The mean of -log2 p at one depth over `rows`, any Enumerable of `{ log_probs: { depth => Float } }`, read once;
+      # nil with no rows.
+      def score(rows, depth:)
+        names = read_names([ depth ])
+        # The rows are read once into their log probabilities and counted by that list's size, never by a counter
+        # inside sum's block: Ruby 3.4.12's Array#sum may call its block more than once for an element.
+        logs = read_rows(rows).map { |row| read_log_probs(row, names).first }.to_a
+        return nil if logs.empty?
+
+        finite((0.0 - (logs.sum(0.0) / logs.size)) / LOG2)
+      end
+
+      # Per depth after the first, its gain over the depth before it in the order given: `{ depth => { bits:, se:,
+      # events:, clusters: } }`, bits the mean gain per event and se its cluster-robust standard error. `rows` is any
+      # Enumerable of `{ cluster:, log_probs: { depth => Float } }`, read once.
+      def gains(rows, depths:)
+        names = read_names(depths)
+        after = names.drop(1)
+        counts = Hash.new(0)
+        totals = after.map { Hash.new(0.0) }
+
+        read_rows(rows).each do |row|
+          logs = read_log_probs(row, names)
+          cluster = read_cluster(row)
+          counts[cluster] += 1
+          totals.each_with_index { |total, i| total[cluster] += (logs[i + 1] - logs[i]) / LOG2 }
+        end
+
+        after.zip(totals).to_h do |depth, total|
+          pooled = moments(total, counts)
+          [ depth, { bits: pooled[:mean], se: pooled[:se], events: pooled[:n], clusters: pooled[:clusters] } ]
+        end
+      end
+
+      # The mean of per-cluster totals `sums` over per-cluster `counts`, on one key set, with its cluster-robust normal
+      # interval at `level`: `{ mean:, lower:, upper:, n:, clusters: }`, n the summed counts as given.
+      def clustered_mean(sums:, counts:, level: 0.95)
+        level = read_level(level)
+        pooled = moments(*read_clusters(sums, counts))
+        lower, upper = bounds(pooled[:mean], pooled[:se], level)
+        { mean: pooled[:mean], lower: lower, upper: upper, n: pooled[:n], clusters: pooled[:clusters] }
+      end
+
+      private
+
+      # The one arithmetic: `totals` and `counts` hold the same keys, the totals Floats. A cluster's total and count
+      # meet by key, never by position.
+      def moments(totals, counts)
+        size = totals.size
+        n = counts.values.sum
+        return { mean: nil, se: nil, n: n, clusters: size } if size.zero?
+
+        events = number(n, "the summed counts")
+        mean = finite(totals.values.sum / events)
+        { mean: mean, se: standard_error(totals, counts, mean, events), n: n, clusters: size }
+      end
+
+      def standard_error(totals, counts, mean, events)
+        size = totals.size
+        return nil if size < 2
+
+        squares = totals.sum do |cluster, total|
+          residual = total - (mean * counts.fetch(cluster).to_f)
+          residual * residual
+        end
+        finite(Math.sqrt(size.to_f / (size - 1) * squares) / events)
+      end
+
+      # The lower tail's quantile, so that a level just under 1 still reads a finite z: its upper tail rounds to 1.
+      def bounds(mean, se, level)
+        return [ nil, nil ] if se.nil?
+
+        half_width = finite(-Significance.normal_quantile((1.0 - level) / 2.0) * se)
+        [ finite(mean - half_width), finite(mean + half_width) ]
+      end
+
+      def read_level(value)
+        level = number(value, "level")
+        raise ArgumentError, "level must be strictly between 0 and 1, got #{value.inspect}" unless level > 0.0 && level < 1.0
+
+        level
+      end
+
+      # [totals as Floats, counts as given], checked.
+      def read_clusters(sums, counts)
+        raise ArgumentError, "sums must be a Hash of cluster => total, got #{sums.class}" unless sums.is_a?(Hash)
+        raise ArgumentError, "counts must be a Hash of cluster => count, got #{counts.class}" unless counts.is_a?(Hash)
+        unless sums.size == counts.size && sums.each_key.all? { |cluster| counts.key?(cluster) }
+          raise ArgumentError, "sums and counts must name the same clusters"
+        end
+
+        sums.each_key { |cluster| cluster_key(cluster) }
+        counts.each do |cluster, count|
+          label = "the count of cluster #{cluster.inspect}"
+          raise ArgumentError, "#{label} must be above 0, got #{count.inspect}" unless number(count, label).positive?
+        end
+        [ sums.to_h { |cluster, total| [ cluster, number(total, "the total of cluster #{cluster.inspect}") ] }, counts ]
+      end
+
+      def read_rows(rows)
+        return rows if rows.is_a?(Enumerable)
+
+        raise ArgumentError, "rows must be an Enumerable of rows, got #{rows.class}"
+      end
+
+      # The names as given, checked: an Array of one or more Symbols or Strings, each named once.
+      def read_names(list)
+        raise ArgumentError, "depths must be an Array of names, got #{list.class}" unless list.is_a?(Array)
+        raise ArgumentError, "depths must name at least one" if list.empty?
+
+        list.each do |name|
+          raise ArgumentError, "a depth must be a Symbol or a String, got #{name.inspect}" unless name.is_a?(Symbol) || name.is_a?(String)
+        end
+        raise ArgumentError, "depths must each be named once, got #{list.inspect}" unless list.map(&:to_s).uniq.size == list.size
+
+        list
+      end
+
+      # One rule for both doors: a cluster is any Hash key but nil, which reads as a key nobody filled in.
+      def cluster_key(cluster)
+        raise ArgumentError, "a cluster must not be nil" if cluster.nil?
+
+        cluster
+      end
+
+      def read_cluster(row)
+        cluster_key(entry(row, :cluster, "a row"))
+      end
+
+      # The row's log probabilities at `names`, as Floats, in that order.
+      def read_log_probs(row, names)
+        logs = entry(row, :log_probs, "a row")
+        names.map do |name|
+          log_prob = number(entry(logs, name, "a row's log_probs"), "the log probability at #{name.inspect}")
+          raise ArgumentError, "the log probability at #{name.inspect} must be at most 0, got #{log_prob}" if log_prob.positive?
+
+          log_prob
+        end
+      end
+
+      # The one entry of `hash` that `name` spells, by Symbol or String.
+      def entry(hash, name, label)
+        raise ArgumentError, "#{label} must be a Hash, got #{hash.class}" unless hash.is_a?(Hash)
+
+        found = [ name.to_sym, name.to_s ].select { |key| hash.key?(key) }
+        raise ArgumentError, "#{label} must hold #{name.inspect} once" unless found.size == 1
+
+        hash[found.first]
+      end
+
+      # A finite real number, finite as a Float too (an Integer or Rational beyond a Float's range is not), as a Float.
+      def number(value, label)
+        number = value.to_f if value.is_a?(Numeric) && value.real? && value.finite?
+        return number if number&.finite?
+
+        raise ArgumentError, "#{label} must be a finite number, got #{value.inspect}"
+      end
+
+      def finite(value)
+        return value if value.finite?
+
+        raise ArgumentError, "the totals are beyond a Float's range"
+      end
+    end
+  end
+end