skiftet_statistical 0.2.0 → 0.4.0

data/lib/skiftet_statistical/bandit/summary.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require_relative "../numbers"
+require_relative "../inputs"
+require_relative "../beta_function"
+require_relative "../beta_argmax"
+require_relative "../significance"
+require_relative "checks"
+require_relative "draw"
+require_relative "normal_argmax"
+require_relative "posteriors"
+
+module SkiftetStatistical
+  class Bandit
+    # A posterior set's summary: per item, the figures a pass reads, taken from the set itself, so the figures a caller
+    # shows and the allocation it hands them to read one posterior set. The answer is Allocator.from_summary's
+    # `summary:` as it is (String keys and all), so a pass on exact figures is one call more.
+    #
+    #   set = SkiftetStatistical::Bandit::Posteriors.beta({ "a" => [ 2.0, 8.0 ], "b" => [ 3.0, 7.0 ] },
+    #                                                     views: { "a" => 120.0, "b" => 340.0 })
+    #   summary = set.summary(credible_mass: 0.95)
+    #   # => { "a" => { views: 120.0, mean: 0.2, lower: 0.0281..., upper: 0.4825..., p_best: 0.2882...,
+    #   #               expected_loss: 0.1335... },
+    #   #      "b" => { views: 340.0, mean: 0.3, lower: 0.0748..., upper: 0.6000..., p_best: 0.7117...,
+    #   #               expected_loss: 0.0335... } }
+    #   SkiftetStatistical::Bandit::Allocator.from_summary(arms: %w[a b], summary: summary,
+    #                                                      exposures: { "a" => 120, "b" => 340 }, status: "running",
+    #                                                      winner_arm: nil, hold_satisfied: false)
+    #
+    # Every item, in item order, gets:
+    # - views: the set's views of the item;
+    # - mean, lower and upper: the posterior mean and the equal-tailed `credible_mass` interval, read on the pair as
+    #   given, so the interval is the posterior's own, never the scaled pair's, a Beta pair above LARGEST_TOTAL
+    #   included. For a Beta the bounds are BetaFunction.quantile (0.2.0's, kept as it is) at (1 - credible_mass) / 2
+    #   and at 1 less that, accurate to about 2e-10 up to totals (alpha + beta) near 10**8. Its continued fraction
+    #   stops at a fixed number of steps, so beyond a total of about 3 * 10**8 one bound can fall on or past the mean
+    #   (measured, at a mean of 1/2: the lower bound lies 0.0025 standard deviations above the mean at 4 * 10**8 and
+    #   0.013 at 10**9; at 10**15 the interval spans +1.71 to +3.03 standard deviations from a mean of 1/2 and -3.48 to
+    #   +3.48 from a mean of 1/10, where -1.96 to +1.96 is right; at 10**20 both bounds sit 963 to 980 standard
+    #   deviations above the mean). For a Normal they are the mean less and plus its standard deviation times the
+    #   Normal's quantile at 1 less that tail (Significance.normal_quantile), the same distance on each side, the tail
+    #   read on the open grid as every quantile draw reads its uniform (Draw.open_uniform: at least 2**-53, which
+    #   moves only the credible mass 1 - 2**-53, whose tail is 2**-54);
+    # - p_best and expected_loss, for an item `among` names: P(the item is the largest) and E[the largest] less the
+    #   item's mean (the mean answered, on the pair as given), among the items named only, the largest read on the
+    #   scaled pairs (`parameters`) by BetaArgmax.probabilities and BetaArgmax.expected_maximum, or NormalArgmax's,
+    #   through the set's one P(largest) by kind, which the exact odds call too. A loss that rounds below
+    #   0 (a leader far ahead, whose exact loss is below a rounding of its mean) is answered as 0, so
+    #   Allocator.from_summary, which refuses a loss below 0, takes every answer. nil for an item `among` does not name.
+    #
+    # `among`: nil names every item; [] names none, a means-only summary, which computes no P(best) and no loss, for a
+    # set of any size; otherwise a list of items, read as the items it names (a name given twice counts once), at most
+    # EXACT_PICK_MAX of them. P(best) and the loss are computed in item order, whatever the list's order.
+    #
+    # Refused, as an ArgumentError before anything is computed: a credible_mass that is not a number above 0 and below
+    # 1; an `among` that is not a list, or names something that is not an item; more than EXACT_PICK_MAX items named
+    # (nil names every item, so a larger set passes [] or names its items); and, by the set's one refusal, a Beta
+    # parameter below BetaArgmax::SMALLEST_PARAMETER on the pairs each computation reads: on the pair as given, of any
+    # item, on every path, the means-only summary included, for the interval (BetaFunction.quantile cannot read such a
+    # pair: Beta(1e-300, 1) answered both bounds 4.1e-25 around a mean of 1e-300); and in `parameters`, of any item
+    # whenever `among` names one, for P(best) and the loss. A pair above LARGEST_TOTAL can be taken by the one and
+    # refused by the other: [1, 2 * 10**12] scales to about [5e-7, 10**6], so its means-only summary answers the
+    # interval BetaFunction.quantile gives on the pair as given, and a summary naming any item refuses it. A set with
+    # no items answers {}. Every figure of the answer passes the bandit's one check of an answer (Checks.finite_answer).
+    #
+    # `means` answers the mean alone, { item => mean }, as summary answers it (`set.means # => { "a" => 0.2, "b" =>
+    # 0.3 }`), with no interval and no quantile (below).
+    class Posteriors
+      # What each of summary's computations reads, in the words of GB6's refusal.
+      SUMMARY_INTERVAL = "the interval, BetaFunction.quantile on the pair as given"
+      SUMMARY_BEST = "P(best) and the expected loss on the scaled pairs"
+      private_constant :SUMMARY_INTERVAL, :SUMMARY_BEST
+
+      # { item => { views:, mean:, lower:, upper:, p_best:, expected_loss: } }, every item in item order; p_best and
+      # expected_loss nil for an item `among` does not name (see above).
+      def summary(credible_mass: 0.95, among: nil)
+        tail = summary_tail(credible_mass)
+        named = summary_named(among)
+        refuse_below_smallest_parameter(pairs: given_parameters, computing: SUMMARY_INTERVAL)
+        refuse_below_smallest_parameter(computing: SUMMARY_BEST) unless named.empty?
+
+        best = summary_best(named)
+        answer = summary_intervals(tail).to_h do |item, (lower, upper)|
+          p_best, expected_loss = best[item]
+          [ item, { views: @views.fetch(item), mean: mean_as_given(item), lower: lower, upper: upper, p_best: p_best,
+                    expected_loss: expected_loss } ]
+        end
+        Checks.finite_answer(answer.values.flat_map(&:values), "the parameters and the credible mass", answer)
+      end
+
+      # { item => mean }, every item in item order, frozen: the posterior mean `summary` answers as :mean, read by
+      # summary's own reader on the pair as given (`mean_as_given`), never a second formula, so the two agree bit for
+      # bit, a Beta pair above LARGEST_TOTAL included. The means-only reader: it works out no interval, no P(best) and
+      # no loss, and draws nothing, so it calls no quantile (BetaFunction.quantile, Significance.normal_quantile),
+      # reads no key, uniform or RNG and holds no randomness, for a set of any size; a caller that needs only the means
+      # pays for no interval (summary(among: []) works out two quantile bisections an item). Its refusals are
+      # summary's for the mean: the bandit's one check of an answer (Checks.finite_answer), which every set as built
+      # passes (a Beta mean lies in [0, 1], a Normal's in the input domain). The refusal of a parameter below
+      # BetaArgmax::SMALLEST_PARAMETER is the interval's, not the mean's, so such a pair is read here, its mean the
+      # pair's own (Beta(1e-300, 1): 1e-300). A set with no items answers {}.
+      def means
+        answer = @items.to_h { |item| [ item, mean_as_given(item) ] }.freeze
+        Checks.finite_answer(answer.values, "the parameters", answer)
+      end
+
+      private
+
+      # (1 - credible_mass) / 2, the probability the interval leaves out at each end; credible_mass lies above 0 and
+      # below 1 (the bandit's one such bound, Checks.open_unit).
+      def summary_tail(credible_mass)
+        (1.0 - Checks.open_unit(credible_mass, "credible_mass")) / 2.0
+      end
+
+      # The items `among` names, in item order (the set's one list reading): every item for nil, none for a list naming
+      # none. At most EXACT_PICK_MAX.
+      def summary_named(among)
+        named = nil.equal?(among) ? @items : listed_items(among, "among", @items, []).first
+        return named if named.size <= EXACT_PICK_MAX
+
+        raise ArgumentError, "summary computes P(best) and the loss exactly among at most #{EXACT_PICK_MAX} items " \
+                             "(#{named.size} named); name them in among, or pass among: [] for means and intervals only"
+      end
+
+      # { item => [p_best, expected_loss] } among `named`, on the scaled pairs (the set's one P(largest) by kind), the
+      # loss E[max] less the mean as given, never below 0; {} for none.
+      def summary_best(named)
+        return {} if named.empty?
+
+        largest, maximum = largest_draw(named, maximum: true)
+        named.each_with_index.to_h do |item, index|
+          loss = maximum - mean_as_given(item)
+          [ item, [ largest[index], loss.positive? ? loss : 0.0 ] ]
+        end
+      end
+
+      # { item => [lower, upper] } in item order: the equal-tailed interval leaving `tail` out at each end, on the
+      # pair as given.
+      def summary_intervals(tail)
+        if @kind == :beta
+          return given_parameters.transform_values do |alpha, beta|
+            [ BetaFunction.quantile(tail, alpha, beta), BetaFunction.quantile(1.0 - tail, alpha, beta) ]
+          end
+        end
+
+        score = -Significance.normal_quantile(Draw.open_uniform(tail))
+        given_parameters.transform_values do |mean, deviation|
+          [ mean - (score * deviation), mean + (score * deviation) ]
+        end
+      end
+    end
+  end
+end

data/lib/skiftet_statistical/bandit/tallies.rb

@@ -0,0 +1,297 @@
+# frozen_string_literal: true
+
+require_relative "../numbers"
+require_relative "../inputs"
+require_relative "checks"
+
+module SkiftetStatistical
+  class Bandit
+    # How one tally is read and how it becomes one posterior pair, a rule per kind, each written once. Private to the
+    # bandit: the posterior set, Prior and Decay read every tally here (the posterior set an amounts prior), every list
+    # is read here (Decay's rows, Prior's others and levels, the posterior set's lists of names), the posterior set and
+    # Prior.pooled_new add yes/no evidence to a prior here, Prior.pooled_amount and the amounts rule take the moments
+    # here, and Prior and the amounts rule shrink a mean here, so each is the same arithmetic on every path. The
+    # moments, the amounts rule's gap and the shrunk mean are formed exactly from the Floats they are given (`exact`,
+    # `exact_sum`) and rounded once (`rounded`), so no cancellation and no underflow on the way changes an answer; the
+    # posterior set's Normal draws are compared by the same exact arithmetic, never rounded (`exact_key`).
+    # Which weighted sums count, the yes/no rule and the effective views are 0.3.0's WeightedPosterior.count,
+    # WeightedPosterior.beta and WeightedPosterior.effective_exposures, called on the tally's checked Floats, never
+    # written again here. The rules check nothing and bound no pair: the posterior set bounds a pair above its
+    # LARGEST_TOTAL once it is built (never here).
+    module Tallies
+      # THE sums that may be below 0, declared once: in a tally of amounts the plain and the weighted sum of the
+      # amounts (`outcomes`, `weighted_outcomes`); every other sum, and every sum of a yes/no tally, is >= 0. Every
+      # reader of a tally asks `read` with `amounts:`, never a list of its own.
+      SIGNED_SUMS = %i[outcomes weighted_outcomes].freeze
+      # A Float's significant bits (53), and the power of 2 of the smallest Float above 0 (2**-1074, a subnormal).
+      MANTISSA_BITS = Float::MANT_DIG
+      SMALLEST_POWER = Float::MIN_EXP - Float::MANT_DIG
+      # The exact numbers 0 and 1, as `exact` answers them.
+      ZERO = [ 0, 0 ].freeze
+      ONE = [ 1, 0 ].freeze
+      # The smallest power of 2 `exact` answers for a product of at most two finite Floats, and so `exact_sum` for two
+      # such terms: each factor's mantissa is read as an Integer of MANTISSA_BITS bits, so the smallest Float above 0,
+      # 2**-1074, reads 2**52 * 2**-1126, and two factors read at least 2**-2252.
+      PAIR_FLOOR = 2 * (SMALLEST_POWER - MANTISSA_BITS + 1)
+
+      module_function
+
+      # A tally's sums by `keys` (Symbol or String keys; a nil tally holds none), read by the bandit's one reading of a
+      # caller's Hash by Symbol names (Checks.named: from its pairs, so a default the Hash holds is never read and a Hash
+      # that compares its keys by identity reads as a plain one), each by the library's one number reader
+      # (Numbers.read, the input domain), nil when absent or nil. Every sum is >= 0, save, with `amounts: true`, those
+      # in SIGNED_SUMS, which may be any number in the domain. `label` names the tally in the error words.
+      def read(tally, label, keys, amounts: false)
+        tally = {} if nil.equal?(tally)
+        raise ArgumentError, "#{label} must be a Hash or nil (got #{Inputs.class_name(tally)})" unless Hash === tally
+
+        named = Checks.named(tally, keys, label)
+        keys.to_h do |key|
+          found = named.fetch(key, nil)
+          name = "#{label}'s #{key}"
+          sum =
+            if nil.equal?(found) then nil
+            elsif amounts && SIGNED_SUMS.include?(key) then Numbers.read(found, name)
+            else Checks.nonnegative(found, name)
+            end
+          [ key, sum ]
+        end
+      end
+
+      # THE reading of a list, written once for every list the bandit reads (Decay's rows, Prior.pooled_new's others,
+      # Prior.chain's levels, and the posterior set's lists of item names: `may_lead`, `pinned`'s names, `among`): a
+      # list is any Enumerable but a Hash (an Array, a Set, an Enumerator, a lazy list), read once, by one pass of its
+      # each into a frozen Array (one call into the caller's object, Inputs.asked), so what its map, its to_a or a
+      # second pass would answer is never read. Anything else, a Hash or an object that answers each but is no
+      # Enumerable included, is an ArgumentError, "<label> must be a list of <what> (got <value>)".
+      def list(given, label, what)
+        unless Enumerable === given && !(Hash === given)
+          raise ArgumentError, "#{label} must be a list of #{what} (got #{Inputs.shown(given)})"
+        end
+
+        read = []
+        Inputs.asked(given, "#{label}'s each") { given.each { |element| read << element } }
+        read.freeze
+      end
+
+      # An amounts prior as the amounts rule reads it: a Prior::Amount, its three numbers (asked by the library's one
+      # call into a caller's object, Inputs.asked, as a subclass may answer them) read again by the Amount's own checks
+      # (Prior.amount), so an Amount that never ran them (made by allocate, or by a subclass that skips them) is
+      # refused as any number that is not one is. Anything else is an ArgumentError naming `label`.
+      def amount_prior(given, label)
+        unless Prior::Amount === given
+          raise ArgumentError, "#{label} must be a Prior::Amount (there is no scale-free amounts prior; got " \
+                               "#{Inputs.shown(given)})"
+        end
+
+        mean, variance, strength = Inputs.asked(given, "#{label}'s numbers") do
+          [ given.mean, given.variance, given.strength ]
+        end
+        Prior.amount(mean: mean, variance: variance, strength: strength)
+      end
+
+      # Which weighted sums a tally counts, as [weighted, squared]: weighted when weighted_views is above 0 and every
+      # weighted sum in `sums` is given (else the plain sums are judged); the squared sum only beside them, and only
+      # above 0. WeightedPosterior.count, 0.3.0's rule, judges it on these sums (its weighted conversions given when
+      # every sum in `sums` is), never written again here.
+      def counted(weighted_views, sums, weighted_views_squared)
+        count = WeightedPosterior.count(
+          { weighted_exposures: weighted_views, weighted_conversions: sums.none?(&:nil?) ? 0.0 : nil,
+            weighted_exposures_squared: weighted_views_squared }
+        )
+        [ !count[:weighted_exposures].nil?, !count[:weighted_exposures_squared].nil? ]
+      end
+
+      # The views a posterior is built on: with a squared sum, the Kish size (sum w)^2 / sum w^2, never above the views;
+      # without one, the views as given. WeightedPosterior.effective_exposures, 0.3.0's rule, on these sums.
+      def effective_views(views, weighted_views, weighted_views_squared)
+        WeightedPosterior.effective_exposures(
+          { exposures: views, weighted_exposures: weighted_views, weighted_exposures_squared: weighted_views_squared }
+        )
+      end
+
+      # THE yes/no rule: [prior alpha + c, prior beta + n - c], n the effective views and c the outcomes clamped to
+      # [0, n], or, when weighted_views is given, the weighted outcomes rescaled to n (weighted_outcomes * n /
+      # weighted_views) and clamped to [0, n]. A weighted sum the tally does not count is passed as nil (the default).
+      # WeightedPosterior.beta, 0.3.0's rule, on these sums and this prior.
+      def yes_no(views:, outcomes:, prior:, weighted_views: nil, weighted_outcomes: nil, weighted_views_squared: nil)
+        prior_alpha, prior_beta = prior
+        WeightedPosterior.beta(
+          { exposures: views, conversions: outcomes, weighted_exposures: weighted_views,
+            weighted_conversions: weighted_outcomes, weighted_exposures_squared: weighted_views_squared },
+          prior_alpha: prior_alpha, prior_beta: prior_beta
+        )
+      end
+
+      # THE amounts rule: the mean per view is Normal(mu_n, sd_n) under a prior of k views at mean mu0 and per-view
+      # variance v0, with n the effective views, m the mean amount a view and s^2 its variance (from the weighted sums
+      # when weighted_views is given, else the plain ones, `moments`; at n = 0, m and s^2 read 0):
+      # mu_n = (k mu0 + n m) / (k + n), the one shrunk mean (`shrunk`), and
+      # sd_n^2 = [k v0 + n s^2 + k n (m - mu0)^2 / (k + n)] / (k + n)^2, its root taken by `spread`, which forms no
+      # product of numbers of the input domain's size at all (Numbers::LARGEST). With m = sum / base (base the views
+      # the moments divide by), n m is n sum / base, so mu_n is (k mu0 base + n sum) / ((k + n) base) and the gap
+      # m - mu0 is (sum - mu0 base) / base: each formed exactly from the Floats and rounded once, as s^2 is.
+      def amounts(views:, outcomes:, outcome_squares:, weighted_views:, weighted_outcomes:, weighted_outcome_squares:,
+                  weighted_views_squared:, prior:)
+        n = effective_views(views, weighted_views, weighted_views_squared)
+        strength = prior.strength
+        if n.zero?
+          return [ shrunk(exact(strength, prior.mean), exact(strength), ZERO, ZERO),
+                   spread(strength, prior.variance, n, 0.0, 0.0) ]
+        end
+
+        sum, squares, base =
+          if weighted_views then [ weighted_outcomes, weighted_outcome_squares, weighted_views ]
+          else [ outcomes, outcome_squares, views ]
+          end
+        _mean, variance = moments(sum, squares, base)
+        gap = rounded(exact_sum(exact(sum), exact(-prior.mean, base)), exact(base))
+        [ shrunk(exact(strength, prior.mean, base), exact(strength, base), exact(n, sum), exact(n, base)),
+          spread(strength, prior.variance, n, variance, gap) ]
+      end
+
+      # THE amounts rule's standard deviation, sd_n = sqrt(a + b + c) with T = k + n and gap = m - mu0:
+      # a = k v0 / T^2, b = n s^2 / T^2 and c = k n gap gap / T^3 (the rule's three terms, each over (k + n)^2).
+      # Each term is a product of numbers of the domain's size divided by T two or three times, which, formed as it
+      # reads, could leave a Float either way: k n gap gap reaches 4 * 10**400 (k = n = 10**100, gap = 2 * 10**100),
+      # and a share such as k / T underflows when k is far below n (k = 10**-300 at n = 10**100 reads 0, though c
+      # there is 10**-200 * gap gap), as does n / T when n is far below k, and k v0 / T^2 itself when the answer is
+      # small (k = 10**100 at n = 0 and v0 = 10**-300: the term is 10**-400, the answer 10**-200). So no term is formed
+      # as a Float at all: `scaled` splits every factor and the divisor by Math.frexp into a mantissa in [0.5, 1) and a
+      # power of 2, multiplies and divides the mantissas only (a's and b's in (1/4, 4), c's in (1/16, 8): no mantissa
+      # product leaves a Float either way) and adds the powers as Integers. The terms are then added on the largest
+      # power, made even (each term below 8, their sum in [1/32, 24)), and the root is the root of that sum times 2 to
+      # half that power. The answer is the one number rounded into a Float's range: below the smallest Float (k = v0 =
+      # 5 * 10**-324 at n = 10**100, an exact sd near 10**-424) it reads 0, which the set refuses as a standard
+      # deviation that is not above 0; above the largest it reads Infinity, which only a mean amount or a variance that
+      # left a Float (a quotient by a small input) can make and the check of the answer refuses; a finite sd beyond
+      # the input domain (k = n = 5 * 10**-324 at v0 = 10**100: about 10**211) is refused by the set's reading of its
+      # pair.
+      # Every other in-domain tally reads its exact sd (the rule on the Floats it is given, s^2 and the gap exact)
+      # within 1e-15 relative: s^2 and the gap are each formed exactly and rounded once (`moments`, `amounts`), T
+      # rounds once, and the mantissa arithmetic of a term rounds once a step, so a term is within 5 (a), 6 (b) and 11
+      # (c) roundings of its exact value; the terms are >= 0, so their sum (2 roundings more) cancels nothing, and the
+      # root halves that and rounds once: within 7.5 roundings, 2**-53 each, 8.4e-16. An sd below the smallest normal
+      # Float (2**-1022, about 2.2 * 10**-308) reads on the subnormal grid as well, within half its spacing (2**-1075)
+      # more. An infinity in s^2 or the gap (a quotient by a small input that left a Float) rides through to the
+      # answer, as it is.
+      def spread(strength, prior_variance, views, variance, gap)
+        total = strength + views
+        terms = [ scaled([ strength, prior_variance ], total, 2), scaled([ views, variance ], total, 2),
+                  scaled([ strength, views, gap, gap ], total, 3) ].compact
+        power = terms.map(&:last).max
+        power += 1 if power.odd?
+        sum = terms.sum { |mantissa, own| Math.ldexp(mantissa, own - power) }
+        Math.ldexp(Math.sqrt(sum), power / 2)
+      end
+
+      # [mantissa, power], the product of `factors` divided `times` times by `divisor` (above 0) as mantissa * 2**power,
+      # every number split by Math.frexp into a mantissa in [0.5, 1) and a power of 2, the mantissas multiplied and
+      # divided and the powers added as Integers, so no step leaves a Float's range; nil when a factor is 0 (the term
+      # is 0).
+      def scaled(factors, divisor, times)
+        mantissa = 1.0
+        power = 0
+        factors.each do |factor|
+          return nil if factor.zero?
+
+          fraction, exponent = Math.frexp(factor)
+          mantissa *= fraction
+          power += exponent
+        end
+        fraction, exponent = Math.frexp(divisor)
+        times.times do
+          mantissa /= fraction
+          power -= exponent
+        end
+        [ mantissa, power ]
+      end
+
+      # THE shrunk mean, written once (Prior's pooled means and the amounts rule's posterior mean): (prior outcomes +
+      # outcomes) / (prior views + views), its four numbers exact (`exact`: a strength times a mean is passed as the
+      # exact product), the prior views and views summing above 0, else an ArgumentError. The sums and the quotient are
+      # formed exactly and rounded once (`rounded`), so no step underflows a mean a Float can hold, and when both views
+      # are above 0 the answer, a convex combination of the two means it weighs, is held between them as they round
+      # (prior outcomes / prior views and outcomes / views, each rounded once): it never rounds past either.
+      def shrunk(prior_outcomes, prior_views, outcomes, views)
+        total = exact_sum(prior_views, views)
+        unless total.first.positive?
+          raise ArgumentError, "strength + views must be above 0 (got #{rounded(total, ONE)})"
+        end
+
+        mean = rounded(exact_sum(prior_outcomes, outcomes), total)
+        return mean unless prior_views.first.positive? && views.first.positive?
+
+        mean.clamp(*[ rounded(prior_outcomes, prior_views), rounded(outcomes, views) ].minmax)
+      end
+
+      # THE moments of amounts: [m, s^2] = [sum / views, (squares views - sum sum) / views^2], views above 0: m one
+      # Float quotient (one rounding), s^2 formed exactly from the Floats (`exact`, `exact_sum`) and rounded once
+      # (`rounded`), so no cancellation between squares / views and m^2 changes it; a residual below 0 (squares that
+      # no amounts could sum to) reads 0.
+      def moments(sum, squares, views)
+        residual = exact_sum(exact(squares, views), exact(-sum, sum))
+        [ sum / views, residual.first.negative? ? 0.0 : rounded(residual, exact(views, views)) ]
+      end
+
+      # The product of finite Floats, exactly, as [integer, power], the number integer * 2**power: each factor split by
+      # Math.frexp into a mantissa in [0.5, 1), scaled to an Integer of at most 53 bits, and a power of 2, the Integers
+      # multiplied and the powers added, so no step rounds, over- or underflows. One factor is the Float itself.
+      def exact(*factors)
+        integer = 1
+        power = 0
+        factors.each do |factor|
+          fraction, exponent = Math.frexp(factor)
+          integer *= Math.ldexp(fraction, MANTISSA_BITS).to_i
+          power += exponent - MANTISSA_BITS
+        end
+        [ integer, power ]
+      end
+
+      # The sum of two exact numbers (`exact`), exactly: the Integer of the larger power shifted onto the smaller power,
+      # and added (a term that is 0 is the other).
+      def exact_sum(first, second)
+        return second if first.first.zero?
+        return first if second.first.zero?
+
+        (left, left_power), (right, right_power) = first, second
+        return [ left + (right << (right_power - left_power)), left_power ] if left_power < right_power
+
+        [ (left << (left_power - right_power)) + right, right_power ]
+      end
+
+      # An exact number (`exact`, `exact_sum`) of terms of at most two Floats each, as one Integer: the number times
+      # 2**-PAIR_FLOOR, so any two such numbers compare exactly as their Integers (Integer#<=>), with no rounding and
+      # no fraction to reduce (the posterior set's Normal draw keys).
+      def exact_key(number)
+        integer, power = number
+        integer << (power - PAIR_FLOOR)
+      end
+
+      # The quotient of two exact numbers (`exact`; the denominator above 0) rounded once to the nearest Float, ties
+      # to the even one, as a Float's own division rounds: its leading bit found by one comparison, its 53 leading bits
+      # (fewer below the smallest normal Float, on the subnormal grid down to 2**-1074) taken by one Integer division
+      # and rounded by its remainder; a quotient beyond the largest Float reads an infinity (Math.ldexp). (Ruby's own
+      # Rational#to_f does not round so: it can miss the nearest Float by one.)
+      def rounded(numerator, denominator)
+        top, top_power = numerator
+        return 0.0 if top.zero?
+
+        bottom, bottom_power = denominator
+        size = top.abs
+        power = top_power - bottom_power
+        # size / bottom lies in [2**(lead - 1), 2**(lead + 1)), and in [2**lead, 2**(lead + 1)) once lead is lowered
+        # where it lies below 2**lead.
+        lead = size.bit_length - bottom.bit_length
+        lead -= 1 if (lead.negative? ? size << -lead : size) < (lead.negative? ? bottom : bottom << lead)
+        shift = [ lead + 1 - MANTISSA_BITS, SMALLEST_POWER - power ].max
+        divisor = shift.negative? ? bottom : bottom << shift
+        quotient, remainder = (shift.negative? ? size << -shift : size).divmod(divisor)
+        half = (remainder << 1) <=> divisor
+        quotient += 1 if half.positive? || (half.zero? && quotient.odd?)
+        Math.ldexp(top.negative? ? -quotient.to_f : quotient.to_f, shift + power)
+      end
+    end
+    private_constant :Tallies
+  end
+end

data/lib/skiftet_statistical/bandit.rb

@@ -6,11 +6,11 @@ module SkiftetStatistical
   # in the arms, so a bandit serialises to a plain Hash and back for persistence.
   #
   #   bandit = SkiftetStatistical::Bandit.new(
-  #     arms: %w[facebook whatsapp x],
+  #     arms: %w[a b c],
   #     policy: SkiftetStatistical::Policies::ThompsonSampling.new,
   #   )
-  #   choice = bandit.select          # => "whatsapp"
-  #   bandit.record("whatsapp", 1)    # a conversion
+  #   choice = bandit.select          # => "b"
+  #   bandit.record("b", 1)           # an outcome of 1
   #   bandit.best_arm                 # => highest empirical mean
   class Bandit
     attr_reader :policy