skiftet_statistical 0.2.0 → 0.4.0

data/lib/skiftet_statistical/bandit/checks.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require_relative "../numbers"
+require_relative "../inputs"
+
+module SkiftetStatistical
+  class Bandit
+    # The bounds the bandit's modules share, each written once on a number read first by the library's one number
+    # reader (Numbers.read, the input domain), the one reading of a whole number, the one check of an answer, the one
+    # lookup in a caller's Hash by a key and the one reading of one by Symbol names. Private to the bandit: Prior,
+    # Decay, Tallies, Draw, NormalArgmax, Pass and Posteriors ask these, so a bound reads and words alike wherever it
+    # is checked.
+    module Checks
+      # What `lookup` answers inside `holds?` for a key the Hash does not hold.
+      NONE = Object.new.freeze
+      private_constant :NONE
+
+      module_function
+
+      # The value as a Float, by Numbers.read, when it is >= 0; else "<label> must be >= 0 (got <number>)".
+      def nonnegative(given, label)
+        number = Numbers.read(given, label)
+        raise ArgumentError, "#{label} must be >= 0 (got #{number})" if number.negative?
+
+        number
+      end
+
+      # The value as a Float, by Numbers.read, when it lies in [0, 1] (a share of a rule, a uniform, a mixing share, a
+      # mean, a clip bound of a mean); else "<label> must lie in [0, 1], got <number>", the words BetaArgmax's own
+      # [0, 1] bound has used since 0.2.0, so the bound reads alike across the library.
+      def unit(given, label)
+        number = Numbers.read(given, label)
+        raise ArgumentError, "#{label} must lie in [0, 1], got #{number}" unless number.between?(0.0, 1.0)
+
+        number
+      end
+
+      # The value as a Float, by Numbers.read, when it lies above 0 and below 1 (a credible mass); else "<label> must
+      # be a number above 0 and below 1 (got <value>)", a value that is not a number included.
+      def open_unit(given, label)
+        number = Numbers.read(given, label) { nil }
+        return number if number&.positive? && number < 1.0
+
+        raise ArgumentError, "#{label} must be a number above 0 and below 1 (got #{Inputs.shown(given)})"
+      end
+
+      # The value as it is given when it is an Integer that the library's one number reader reads (an Integer beyond
+      # a Float's range is no number, and one beyond Numbers::LARGEST is refused there, in the input domain's words),
+      # at least `minimum` when it is given and below `below` when it is given; else "<label> must be an Integer[ of
+      # at least <minimum>][ and below <below>] within a Float's range (got <value>)". A count of draws, a seed, a top,
+      # a pinned position.
+      def integer(given, label, minimum: nil, below: nil)
+        number = Integer === given ? Numbers.read(given, label) { nil } : nil
+        return given if number && (nil.equal?(minimum) || given >= minimum) && (nil.equal?(below) || given < below)
+
+        bound = nil.equal?(minimum) ? "" : " of at least #{minimum}"
+        bound += "#{nil.equal?(minimum) ? '' : ' and'} below #{below}" unless nil.equal?(below)
+        raise ArgumentError, "#{label} must be an Integer#{bound} within a Float's range (got #{Inputs.shown(given)})"
+      end
+
+      # The value as a Float, by Numbers.read, when it is above 0; else "<label> must be above 0 (got <number>)".
+      def positive(given, label)
+        number = Numbers.read(given, label)
+        raise ArgumentError, "#{label} must be above 0 (got #{number})" unless number.positive?
+
+        number
+      end
+
+      # THE check of an answer, written once, the last guard of every public method of the bandit that answers a
+      # number: `answer` (the numbers themselves unless given), as it is, when every number of `numbers` (the answer's
+      # numbers, a nil among them a figure the answer leaves out) is finite; else "<inputs> overflow a Float's range
+      # (the answer would read <numbers>)", `inputs` naming what was handed in. No sum over fewer than 10**208
+      # in-domain inputs and no product the bandit forms of them overflows (Numbers::LARGEST, whose argument names the
+      # widest term), so what it refuses is a quotient by a small input that left a Float.
+      def finite_answer(numbers, inputs, answer = numbers)
+        return answer if numbers.all? { |number| nil.equal?(number) || number.finite? }
+
+        raise ArgumentError, "#{inputs} overflow a Float's range (the answer would read #{Inputs.shown(numbers)})"
+      end
+
+      # THE lookup in a caller's Hash by a key of the caller's (an opaque key: a mixture's branch or item) or a Symbol
+      # (a pass's leader), written once: the value the Hash holds at `key`, or `missing` (nil) when it holds
+      # none, by Hash's own fetch (Inputs.fetched: a subclass's fetch or [] is never called, and a default the Hash
+      # holds, a value or a block, never read). A key of the caller's has its hash and eql? called by the lookup, one
+      # call into the caller's object, asked by the library's one such call (Inputs.asked), `label` naming the Hash.
+      def lookup(hash, key, label, missing = nil)
+        Inputs.asked(key, "#{label}'s lookup of a key") { Inputs.fetched(hash, key, missing) }
+      end
+
+      # Whether the Hash holds `key` (by `lookup`).
+      def holds?(hash, key, label)
+        !NONE.equal?(lookup(hash, key, label, NONE))
+      end
+
+      # The value the Hash holds at the Symbol key, else at its String, else nil (`named`, for the one key).
+      def fetch(hash, key, label = "a Hash")
+        named(hash, [ key ], label).fetch(key, nil)
+      end
+
+      # THE reading of a caller's Hash by Symbol names, written once (a tally's sums, the given uniforms' parts, an
+      # other's group and own, a level's strength): { key => value } for each of `keys` (Symbols) the Hash names, its
+      # value at the Symbol key, else at the key's String, read from the Hash's pairs (Inputs.pairs, Hash's own to_a,
+      # so a default the Hash holds is never read), a String key by its copy (Inputs.string) and a Symbol key as the
+      # Symbol it is; every other key is not read, and no method of a key is called. Every value is then looked up in
+      # the Hash this builds, never in the caller's by a key of the library's, so a Hash that compares its keys by
+      # identity reads exactly as a plain one. Two String keys of one name (an identity Hash can hold both, as can a
+      # key whose own hash differs from its String's) are an ArgumentError, "<label> names <key> twice".
+      def named(hash, keys, label)
+        symbols = {}
+        strings = {}
+        Inputs.pairs(hash).each do |name, value|
+          if Symbol === name
+            symbols[name] = value if keys.include?(name)
+          elsif String === name
+            copy = Inputs.string(name)
+            key = keys.find { |candidate| candidate.name == copy }
+            next if nil.equal?(key)
+            raise ArgumentError, "#{label} names #{key} twice" if strings.key?(key)
+
+            strings[key] = value
+          end
+        end
+        strings.empty? ? symbols : strings.merge(symbols)
+      end
+    end
+    private_constant :Checks
+  end
+end

data/lib/skiftet_statistical/bandit/decay.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "../numbers"
+require_relative "../inputs"
+require_relative "checks"
+require_relative "tallies"
+
+module SkiftetStatistical
+  class Bandit
+    # How much an old view weighs: one formula, 2 ** (-age / half_life), so a view one half-life old counts half and
+    # a view older than `cap` counts nothing. Age, half-life and cap share one unit of the caller's choosing (hours,
+    # days, passes). Pure: no randomness, no state.
+    #
+    #   SkiftetStatistical::Bandit::Decay.weight(72, half_life: 72, cap: 336)  # => 0.5
+    #   SkiftetStatistical::Bandit::Decay.weight(337, half_life: 72, cap: 336) # => 0.0
+    #
+    # `fold` sums rows that each carry an `age` at that weight: every sum is weighted (views, outcomes and
+    # outcome_squares alike, never views alone), so the folded tally is what a yes/no or an amounts posterior reads.
+    #
+    #   rows = [{ age: 0, views: 10, outcomes: 3 }, { age: 72, views: 20, outcomes: 4 }]
+    #   SkiftetStatistical::Bandit::Decay.fold(rows, half_life: 72, cap: 336)
+    #   # => { views: 20.0, outcomes: 5.0, outcome_squares: 0.0 }
+    #
+    # The fold is linear in the rows, so a caller that sums in a database groups its records by age bucket and folds
+    # the buckets: the answer is the fold of the records one by one, up to rounding.
+    #
+    # Rules: every number is read by the library's one number reader (SkiftetStatistical::Numbers: a finite real
+    # number of magnitude at most Numbers::LARGEST; a NaN, an infinity and a String, a numeric one included, are not
+    # numbers). An age is >= 0 (a negative age is an ArgumentError); the half-life is > 0; the cap is nil (no cap) or
+    # >= 0, and it is inclusive (an age at the cap still weighs by the formula, an age above it weighs 0.0). The rows
+    # are a list, read by the bandit's one list reader (Tallies.list: any Enumerable but a Hash, read once by its each),
+    # each row a tally read by its one tally reader (Tallies.read, Symbol or String keys); its age is required, and a
+    # missing or nil views, outcomes or outcome_squares reads 0. Views and outcome_squares are >= 0; outcomes may be
+    # below 0, a sum of amounts (the tally reader's one list of sums that may be, Tallies::SIGNED_SUMS). Anything else
+    # is an ArgumentError, in a row past the cap too, and every answer passes the bandit's one check of an answer
+    # (Checks.finite_answer).
+    module Decay
+      # The sums `fold` answers, each weighted.
+      SUMS = %i[views outcomes outcome_squares].freeze
+      # What a row holds: its age and its sums.
+      ROW = %i[age views outcomes outcome_squares].freeze
+      private_constant :ROW
+
+      class << self
+        # The weight of a view `age` old: 2 ** (-age / half_life), 0.0 when `cap` is given and age is above it.
+        def weight(age, half_life:, cap: nil)
+          half_life, cap = settings(half_life, cap)
+          Checks.finite_answer([ factor(Checks.nonnegative(age, "an age"), half_life, cap) ],
+                               "the age, half_life and cap").first
+        end
+
+        # { views:, outcomes:, outcome_squares: } summed over `rows`, each row's numbers at its age's weight.
+        def fold(rows, half_life:, cap: nil)
+          half_life, cap = settings(half_life, cap)
+          read = Tallies.list(rows, "rows", "tallies").each_with_index.map do |row, index|
+            Tallies.read(row, "rows[#{index}]", ROW, amounts: true)
+          end
+          weighted = read.each_with_index.map do |row, index|
+            age = row[:age]
+            raise ArgumentError, "rows[#{index}] needs an age" if nil.equal?(age)
+
+            [ factor(age, half_life, cap), row ]
+          end
+          sums = SUMS.to_h { |sum| [ sum, weighted.sum(0.0) { |row_weight, row| row_weight * (row[sum] || 0.0) } ] }
+          Checks.finite_answer(sums.values, "the rows", sums)
+        end
+
+        private
+
+        # The one formula, on a checked age and checked settings.
+        def factor(age, half_life, cap)
+          return 0.0 if cap && age > cap
+
+          2.0**(-age / half_life)
+        end
+
+        def settings(half_life, cap)
+          half_life = Checks.positive(half_life, "half_life")
+          return [ half_life, nil ] if nil.equal?(cap)
+
+          [ half_life, Checks.nonnegative(cap, "cap") ]
+        end
+      end
+    end
+  end
+end

data/lib/skiftet_statistical/bandit/draw.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "../numbers"
+require_relative "../inputs"
+require_relative "checks"
+
+module SkiftetStatistical
+  class Bandit
+    # The randomness helpers, each written once: a text becomes a uniform, a list of parts becomes a uniform or a
+    # seed, and a uniform picks a key by weight. Pure: the same text gives the same uniform in every process, on every
+    # machine, so a caller can key a draw by a visit, a pass or a test and get it back without storing it.
+    #
+    #   SkiftetStatistical::Bandit::Draw.uniform("t")                       # => 0.8895498694938413
+    #   SkiftetStatistical::Bandit::Draw.uniform_for("t", "explore")        # => 0.856909028643178
+    #   SkiftetStatistical::Bandit::Draw.seed_for("t", "explore")           # => 15807181545831752473
+    #   SkiftetStatistical::Bandit::Draw.from_weights({ "a" => 1, "b" => 3 }, 0.5)  # => "b"
+    #   SkiftetStatistical::Bandit::Draw.weighted({ "a" => 1, "b" => 3 }, 0.5)      # => ["b", 0.75]
+    #
+    # A uniform is the first 8 bytes of SHA256 of the text, read as one big-endian unsigned Integer, shifted right by
+    # 11 and divided by 2**53: a Float in [0, 1) on the 2**53 grid. A seed is those same 8 bytes as the Integer, for
+    # Random.new. A list of parts is read as its parts' bytes joined by one NUL byte, nil read as "", a String by its
+    # bytes alone and anything else by its to_s (so 7 and "7" are one part), whose String answer is read the same way
+    # (Inputs.text: never a String's own methods), a to_s that answers no String being an ArgumentError; a part
+    # holding a NUL byte is an ArgumentError, so two different part lists never join to the same text. `uniform` reads
+    # its one text the same way (its bytes, nil as ""), with no NUL rule: it has no parts to keep apart. Both readings
+    # are the bandit's one reading of a keyed draw's parts (`KeyParts`, below), which the order rule also reads a key
+    # by, once, and keeps for a re-pin.
+    #
+    # The draw by weight takes a Hash of key => weight in input order and a uniform in [0, 1]. A weight that is not a
+    # finite number above 0 (0, nil, NaN, an infinity, a negative number, a numeric String) counts 0, and a number
+    # beyond the library's input domain (Numbers::LARGEST either side of 0) is an ArgumentError, as every number the
+    # library reads is; when every weight counts 0, every key counts 1. The arithmetic is the one 0.1's Softmax policy
+    # drew by, step for step: the total is Array#sum of the counted weights (a compensated sum), the target is uniform *
+    # total, and the running sum adds the counted weights one by one in input order; the draw answers the first key that
+    # counts whose running sum is at or above the target, else (the running sum ending below the target, as a uniform
+    # near 1.0 can make it) the last key that counts. A key that counts 0 is never answered, at a uniform of 0.0
+    # included. `weighted` answers that key with its share, its counted weight over the counted total, which is the
+    # probability that a uniform draw answers it; `from_weights` is `weighted`'s key. Keys are any objects and are
+    # answered as given: neither call reads a key, so an app may pass its own records. An empty Hash answers no key
+    # (nil, and [nil, nil] from `weighted`). A uniform that is not a number in [0, 1], and counted weights whose sum is
+    # not a finite number, are an ArgumentError.
+    #
+    # A quantile draw reads its uniform on the open grid (`open_uniform`): clamped to [2**-53, 1 - 2**-53], the
+    # smallest and the largest uniform above 0 that Random#rand answers, so a quantile that is infinite at 0 or 1 (the
+    # Normal's) never reads either end. It is the one such reading, for every quantile draw of the posterior set and
+    # for the tail of its Normal interval; a Beta draw reads its uniform as it is (its position is a comparison key,
+    # and its value at an end is 0 or 1).
+    #
+    #   SkiftetStatistical::Bandit::Draw.open_uniform(0.0)  # => 1.1102230246251565e-16 (2**-53)
+    module Draw
+      # 2**53: the uniform's grid, the most a Float holds without rounding.
+      UNIFORM_SCALE = 9_007_199_254_740_992.0
+      # The open grid's ends: 2**-53 and 1 - 2**-53.
+      OPEN_LOW = 1.0 / UNIFORM_SCALE
+      OPEN_HIGH = 1.0 - OPEN_LOW
+      # The byte between two parts.
+      SEPARATOR = "\x00".b.freeze
+
+      class << self
+        # The uniform of `text`, in [0, 1).
+        def uniform(text)
+          Checks.finite_answer([ (head(KeyParts.bytes(text)) >> 11) / UNIFORM_SCALE ], "the text").first
+        end
+
+        # The uniform of the parts joined by NUL, in [0, 1).
+        def uniform_for(*parts)
+          Checks.finite_answer([ (head(joined(parts)) >> 11) / UNIFORM_SCALE ], "the parts").first
+        end
+
+        # The seed of the parts joined by NUL, an Integer in [0, 2**64), for Random.new.
+        def seed_for(*parts)
+          Checks.finite_answer([ head(joined(parts)) ], "the parts").first
+        end
+
+        # The uniform (a number in [0, 1], read by the bandit's one [0, 1] bound, Checks.unit) clamped to the open
+        # grid [OPEN_LOW, OPEN_HIGH]: the one reading of a uniform a quantile draw takes.
+        def open_uniform(uniform)
+          Checks.finite_answer([ Checks.unit(uniform, "uniform").clamp(OPEN_LOW, OPEN_HIGH) ], "the uniform").first
+        end
+
+        # The key a uniform draws from `weights`: `weighted`'s key.
+        def from_weights(weights, uniform)
+          weighted(weights, uniform).first
+        end
+
+        # [key, share]: the key a uniform draws from `weights`, and its counted weight over the counted total.
+        def weighted(weights, uniform)
+          unless Hash === weights
+            raise ArgumentError, "weights must be a Hash of key => weight (got #{Inputs.class_name(weights)})"
+          end
+
+          target = Checks.unit(uniform, "uniform")
+          entries = Inputs.pairs(weights)
+          keys = entries.map(&:first)
+          counts = entries.map { |_key, weight| counted(weight) }
+          total = counts.sum
+          raise ArgumentError, "the weights must sum to a finite number (got #{total})" unless total.finite?
+
+          if total.zero?
+            counts = Array.new(counts.size, 1.0)
+            total = counts.sum
+          end
+          return [ nil, nil ] if total.zero?
+
+          target *= total
+          running = 0.0
+          last = nil
+          counts.each_with_index do |weight, index|
+            next unless weight.positive?
+
+            running += weight
+            last = index
+            break if running >= target
+          end
+          share = counts[last] / total
+          Checks.finite_answer([ share ], "the weights and the uniform", [ keys[last], share ])
+        end
+
+        private
+
+        # The first 8 bytes of SHA256(text) as one big-endian unsigned Integer.
+        def head(text)
+          Digest::SHA256.digest(text).unpack1("Q>")
+        end
+
+        # The parts as the one reading of a keyed draw's parts reads them (`KeyParts.read`), joined by NUL.
+        def joined(parts)
+          KeyParts.read(*parts).join(SEPARATOR)
+        end
+
+        # A weight as the draw counts it: a number (the library's one number reader, Numbers.read, which refuses one
+        # beyond the input domain) above 0, else 0.0, what is not a number at all included.
+        def counted(weight)
+          value = Numbers.read(weight, "a weight") { 0.0 }
+          value.positive? ? value : 0.0
+        end
+      end
+    end
+
+    # THE reading of a keyed draw's parts, written once: Draw's `uniform` reads its text here, `uniform_for` and
+    # `seed_for` their parts, and the order rule's key source a key's parts, once, keeping what it read for a re-pin
+    # (Order#repin), so a re-pin reads the key as `rank` read it and never asks the caller's parts again. What it
+    # answers is library data, frozen binary Strings, which Draw reads again as their own bytes. Private to the bandit.
+    module KeyParts
+      module_function
+
+      # The parts, in order, each as a keyed draw reads it: its bytes (`bytes`), refused when they hold a NUL byte
+      # (Draw::SEPARATOR, the byte between two parts), each part read once and refused in its turn; a frozen Array of
+      # frozen binary Strings. Taken as a splat, so a caller's Array is read by its elements alone, none of its own
+      # methods called. Draw.uniform_for(*read(*parts), *more) is Draw.uniform_for(*parts, *more), bit for bit: a part
+      # read here reads again as the same bytes.
+      def read(*parts)
+        parts.map do |part|
+          text = bytes(part)
+          if text.include?(Draw::SEPARATOR)
+            raise ArgumentError, "a part must not hold a NUL byte (got the bytes #{text.inspect})"
+          end
+
+          text
+        end.freeze
+      end
+
+      # A part's bytes, a frozen binary String: "" for nil, else the bytes of the library's one reading of a value as
+      # text (Inputs.text: a String read by its bytes and encoding alone, by Inputs.string; anything else by its to_s,
+      # asked by the library's one call into a caller's object, so a to_s that raises is an ArgumentError, and its
+      # String answer read the same way), which must be a String.
+      def bytes(part)
+        return "".b.freeze if nil.equal?(part)
+
+        text = Inputs.text(part, "a part")
+        return text.b.freeze unless nil.equal?(text)
+
+        raise ArgumentError, "a part must answer to_s with a String (got #{Inputs.shown(part)})"
+      end
+    end
+    private_constant :KeyParts
+  end
+end

data/lib/skiftet_statistical/bandit/normal_argmax.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require_relative "../numbers"
+require_relative "../inputs"
+require_relative "../gauss_legendre"
+require_relative "../significance"
+require_relative "../beta_argmax"
+require_relative "checks"
+
+module SkiftetStatistical
+  class Bandit
+    # THE map between two Normals' standardised variables, written once (NormalArgmax's own integrals and panel breaks,
+    # and the order odds' points and distribution functions, probabilities.rb): the point at the standard deviate z of
+    # a Normal (mean, sd), in the standard units of another (onto_mean, onto_sd), ((mean - onto_mean) + sd * z) /
+    # onto_sd, the means' difference formed first, so two near means far from 0 lose no digits to their size, and a
+    # finite numerator over a standard deviation reads a Float, or an infinity where the quotient leaves a Float's
+    # range, never a NaN. Private to the bandit.
+    module Standardised
+      module_function
+
+      def carried(mean, deviation, z, onto_mean, onto_deviation)
+        ((mean - onto_mean) + (deviation * z)) / onto_deviation
+      end
+    end
+    private_constant :Standardised
+
+    # Which of several independent Normal variables is the largest, by BetaArgmax's rule: the probability that each
+    # member is the largest, and the expected value of the largest.
+    #
+    #   P(member i is the largest) = integral of phi(z) * product (j != i) of Phi((mu_i + sigma_i z - mu_j) / sigma_j)
+    #   E[the largest]             = U - integral from L to U of the product of every F_j(x) dx
+    #
+    # (phi and Phi the standard Normal's density and distribution function, F_j member j's distribution function).
+    #
+    # Each member's probability is its own integral, in its own standardised variable z = (x - mu_i) / sigma_i, so its
+    # density is sampled on its own scale however narrow, wide or far from the others it is. The integral runs over z
+    # from the standard quantile at BetaArgmax::TAIL to the one at 1 - TAIL, composite Gauss-Legendre at
+    # BetaArgmax::NODES nodes a panel, the panels broken at the standard quantiles at BetaArgmax::BREAKS and, inside
+    # that range, at the same quantiles of every narrower member, carried into z. On each panel every factor is then
+    # smooth: a narrower member's distribution function lies between two of its own quantiles, and a member at least as
+    # wide moves by at most the panel's width in its own standard units. Another member's argument is formed as
+    # ((mu_i - mu_j) + sigma_i z) / sigma_j, a finite numerator over a standard deviation (the bandit's one map between
+    # two Normals' standardised variables, Standardised.carried), so it reads 0 or 1 where the quotient leaves a
+    # Float, never a NaN.
+    #
+    # The error bound. A member's integral leaves out at most TAIL at each end of its own range, and a factor beyond its
+    # member's extreme quantiles moves by at most TAIL, which a rule of positive weights reads to within 2 TAIL of the
+    # panels' mass; the rest is the Gauss-Legendre error on smooth panels, below SMOOTH_ERROR (1e-12). So each member's
+    # integral lies within 2 k TAIL + 1e-12 of its exact probability (k the number of members), and their sum within k
+    # times that of 1: a sum further from 1 is refused, as beyond what the rule can integrate. The answers are the
+    # integrals over their sum, each within 2 k (k + 1) TAIL + 2e-12 of the exact probability (at most 8.4e-8 for 20
+    # members, 1.2e-9 for two), then mixed with epsilon / k, as BetaArgmax's are. A standard deviation below Float::MIN,
+    # where a Float holds fewer digits and sigma_i z rounds coarsely, is beyond what the rule can integrate, for both
+    # answers alike.
+    #
+    # E[the largest] reads no density: [L, U] is the members' joint range, from the lowest of their quantiles at TAIL to
+    # the highest at 1 - TAIL, the panels broken at every member's quantiles at BREAKS, on x less the largest mean (so a
+    # mean near 10**6 loses no digits to its own size). Its integrand is a product of distribution functions, at most 1,
+    # and a narrow member's step sits on its own quantile points however close they round, so no member's mass goes
+    # unsampled. Leaving out what lies beyond the joint range costs at most 1.4e-11 standard deviations a member at each
+    # end (below L the product is at most the lowest member's F, and above U one minus it is at most the sum of the
+    # members' upper tails); the rest is a rounding of the members' means relative to the largest.
+    #
+    #   SkiftetStatistical::Bandit::NormalArgmax.probabilities([ [ 0.0, 1.0 ], [ 0.0, 1.0 ] ])     # => [0.5, 0.5]
+    #   SkiftetStatistical::Bandit::NormalArgmax.expected_maximum([ [ 0.0, 1.0 ], [ 0.0, 1.0 ] ])  # => 1 / sqrt(pi)
+    #
+    # Members are given as [[mean, standard_deviation], ...], 1 to BetaArgmax::MAX_MEMBERS of them, each pair read by
+    # the library's one reading of a pair (Numbers.pair, its numbers in the input domain, Numbers::LARGEST), the
+    # standard deviation above 0. Every answer is in the members' order and passes the bandit's one check of an answer
+    # (Checks.finite_answer).
+    module NormalArgmax
+      ROOT_TWO_PI = Math.sqrt(2.0 * Math::PI)
+      # The names of a member's two numbers.
+      PAIR = [ "mean", "standard deviation" ].freeze
+      # The standard Normal's quantiles at BetaArgmax::BREAKS: a member's own panel breaks in its own variable z, the
+      # first and the last its range; on the joint range of E[the largest], every member's breaks.
+      SCORES = BetaArgmax::BREAKS.map { |level| Significance.normal_quantile(level) }.freeze
+      # What the Gauss-Legendre rule may add to a member's integral on smooth panels, beyond the 2 k TAIL above.
+      SMOOTH_ERROR = 1e-12
+      private_constant :PAIR, :SCORES, :SMOOTH_ERROR
+
+      class << self
+        # P(member i is the largest), mixed with epsilon / k, for every member in order; [1.0] for one member.
+        # epsilon lies in [0, 1], read by the bandit's one [0, 1] bound (Checks.unit). The answers lie in [0, 1] and sum
+        # to 1.
+        def probabilities(params, epsilon: 0.0)
+          members = members(params)
+          epsilon = Checks.unit(epsilon, "epsilon")
+          return [ 1.0 ] if members.size == 1
+
+          integrals, total = integrable(members, params)
+          k = members.size
+          Checks.finite_answer(integrals.map { |integral| (epsilon / k) + ((1.0 - epsilon) * integral / total) },
+                               "the members' parameters")
+        end
+
+        # E[the largest member]; one member's mean exactly. Members `probabilities` cannot integrate are refused alike
+        # (the one guard, `integrable`), and an answer beyond a Float's range by the bandit's one check of an answer
+        # (Checks.finite_answer).
+        def expected_maximum(params)
+          members = members(params)
+          return Checks.finite_answer([ members.first.first ], "the members' parameters").first if members.size == 1
+
+          integrable(members, params)
+          origin = members.map(&:first).max
+          normals = members.map { |mean, deviation| [ mean - origin, deviation ] }
+          points = joint_points(normals)
+          integral = 0.0
+          panels(points) do |x, weight|
+            product = 1.0
+            normals.each { |mean, deviation| product *= distribution((x - mean) / deviation) }
+            integral += weight * product
+          end
+          Checks.finite_answer([ origin + (points.last - integral) ], "the members' parameters").first
+        end
+
+        private
+
+        # THE guard of both answers, written once: [each member's own integral, their total] when every standard
+        # deviation is at least Float::MIN and the integrals sum to 1 within k (2 k TAIL + SMOOTH_ERROR); else an
+        # ArgumentError.
+        def integrable(members, params)
+          if members.all? { |_mean, deviation| deviation >= Float::MIN }
+            integrals = members.each_index.map { |member| own_integral(members, member) }
+            total = integrals.sum
+            k = members.size
+            return [ integrals, total ] if (total - 1.0).abs <= k * ((2 * k * BetaArgmax::TAIL) + SMOOTH_ERROR)
+          end
+
+          raise ArgumentError, "the members' parameters are beyond what the rule can integrate, got #{Inputs.shown(params)}"
+        end
+
+        # The member's own integral of phi(z) * the product of the others' Phi(((mu_i - mu_j) + sigma_i z) / sigma_j)
+        # (z carried into each other's standard units by Standardised.carried) over its own range in z; at a node where
+        # the product reaches 0, the rest of it is not read.
+        def own_integral(members, member)
+          mean, deviation = members[member]
+          others = members.each_with_index.filter_map { |pair, other| pair unless other == member }
+          sum = 0.0
+          panels(own_points(members, member)) do |z, weight|
+            product = Math.exp(-0.5 * z * z) / ROOT_TWO_PI
+            others.each do |other_mean, other_deviation|
+              product *= distribution(Standardised.carried(mean, deviation, z, other_mean, other_deviation))
+              break if product.zero?
+            end
+            sum += weight * product
+          end
+          sum
+        end
+
+        # The member's own breaks in z (SCORES), and every narrower member's quantiles at BREAKS carried into z,
+        # ((mu_j - mu_i) + sigma_j * score) / sigma_i (Standardised.carried), where they lie inside its range; sorted,
+        # each once.
+        def own_points(members, member)
+          mean, deviation = members[member]
+          low = SCORES.first
+          high = SCORES.last
+          points = SCORES.dup
+          members.each_with_index do |(other_mean, other_deviation), other|
+            next if other == member || other_deviation >= deviation
+
+            SCORES.each do |score|
+              z = Standardised.carried(other_mean, other_deviation, score, mean, deviation)
+              points << z if z > low && z < high
+            end
+          end
+          points.sort.uniq
+        end
+
+        # Every member's quantiles at BetaArgmax::BREAKS, sorted, each once: the first is L and the last U.
+        def joint_points(normals)
+          normals.flat_map { |mean, deviation| SCORES.map { |score| mean + (deviation * score) } }.sort.uniq
+        end
+
+        # Yields each node of the composite rule and its weight, the panel's half width folded in.
+        def panels(points)
+          rule = GaussLegendre.nodes(BetaArgmax::NODES)
+          points.each_cons(2) do |left, right|
+            half_width = (right - left) / 2.0
+            middle = (left + right) / 2.0
+            rule.each { |node, weight| yield middle + (half_width * node), weight * half_width }
+          end
+        end
+
+        def distribution(score)
+          Significance.normal_cdf(score)
+        end
+
+        # The members, read by Array's own to_a (Inputs.elements) and each pair by Numbers.pair.
+        def members(params)
+          given = Array === params ? Inputs.elements(params) : []
+          if given.empty?
+            raise ArgumentError, "params must be a non-empty Array of [mean, standard_deviation] pairs, got " \
+                                 "#{Inputs.shown(params)}"
+          end
+          if given.size > BetaArgmax::MAX_MEMBERS
+            raise ArgumentError, "params may hold at most #{BetaArgmax::MAX_MEMBERS} members, got #{given.size}"
+          end
+
+          given.each_with_index.map do |pair, i|
+            Numbers.pair(pair, "member #{i}", PAIR) do |number, name, index|
+              index == 1 ? Checks.positive(number, name) : number
+            end
+          end
+        end
+      end
+    end
+  end
+end