skiftet_statistical 0.4.0 → 0.5.0

data/lib/skiftet_statistical/bandit/allocator.rb

@@ -107,6 +107,11 @@ module SkiftetStatistical
       class FixedAllocation < ArgumentError; end
 
       # The allocator's settings, each a finite number. The defaults are the values its A/B tests run with.
+      #
+      # Takes any of the DEFAULTS' names by keyword. Answers a frozen value (`to_h`, `==` and `hash` by its settings).
+      # Guarantees: every setting is read by the decision it names, at every call that is handed this Config (the
+      # allocator never reads a setting from anywhere else); a setting left out is its DEFAULTS value. Refuses, as an
+      # ArgumentError: a name that is not a setting, a value that is not a finite number, a floor outside (0, 1].
       class Config
         DEFAULTS = {
           warmup_exposures: 300, floor: 0.10, max_step: 0.15, win_p_best: 0.95, win_loss: 0.0025, won_share: 0.95,
@@ -344,6 +349,11 @@ module SkiftetStatistical
 
       # The won split: the winner `won_share`, the other arms `won_rest` shared equally; a single arm gets
       # everything. The keys are `arms` as given (Symbols or Strings).
+      #
+      # Takes a list of arms, the winner (compared with ==, so give it as the arms are given) and a Config, whose
+      # won_share and won_rest are the ones read. Pure arithmetic: the same arms and Config answer the same split.
+      # Refuses nothing of its own: a winner that is not one of the arms is not checked (every arm then gets its
+      # won_rest share), and a config that is not a Config raises NoMethodError at its first setting.
       def self.won_weights(arms, winner, config: Config.new)
         return { winner => 1.0 } if arms.size == 1
 
@@ -372,6 +382,19 @@ module SkiftetStatistical
         Shares.new(arms, fixed_shares: nil, arm_floors: nil, config: config).lift(target)
       end
 
+      # The decision for one pass (the class comment's rule): { weights:, phase:, stats:, winner:, result_changed:,
+      # leader: }, arms as Symbols.
+      #
+      # Takes: `arms` (1 to Config#max_arms, Symbols or Strings), `tallies` ({ arm => { exposures:, conversions: } },
+      # optionally the weighted sums and guardrails), `status` ("running", "paused" or "won"), `winner_arm`, `rng`
+      # (answering rand), `draws` (a whole number of joint draws, at least 1), `previous_weights`, `hold_satisfied`,
+      # `config` (a Config, whose every setting is read), `fixed_shares` and `arm_floors`.
+      # Guarantees: pure, no clock and no state; the same inputs and the same RNG stream answer the same result, the
+      # joint draws taken arm by arm in the given order (JointBeta), so the stream's use is fixed by the arms and
+      # `draws`; the inputs are not changed; `hold_satisfied` moves only the crown (the weights, the phase and the
+      # winner), never `stats`. Refuses, as an ArgumentError before any draw: a config that is not a Config, no arms or
+      # more than Config#max_arms, `draws` below 1 once read by Integer() (whose own error a value it cannot read
+      # raises), the per-arm share checks, and `allocation: :fixed` (FixedAllocation, an ArgumentError).
       def self.call(arms:, tallies:, status:, winner_arm:, rng:, previous_weights: nil, draws:, hold_satisfied: true,
                     allocation: :adaptive, config: Config.new, fixed_shares: nil, arm_floors: nil)
         new(arms: arms, tallies: tallies, status: status, winner_arm: winner_arm, rng: rng,

data/lib/skiftet_statistical/bandit/decay.rb

@@ -34,6 +34,9 @@ module SkiftetStatistical
     # 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).
+    #
+    # Guarantees: no randomness and no clock (the caller gives every age), so the same rows answer the same sums;
+    # a weight is 1.0 at age 0, 0.5 at one half-life, and 0.0 past the cap.
     module Decay
       # The sums `fold` answers, each weighted.
       SUMS = %i[views outcomes outcome_squares].freeze

data/lib/skiftet_statistical/bandit/draw.rb

@@ -9,7 +9,10 @@ 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.
+    # machine and on every Ruby version (SHA256 and Integer arithmetic only, no Float function and no Ruby hash seed),
+    # so a caller can key a draw by a visit, a pass or a test and get it back without storing it. A uniform or a seed
+    # moves only with the bytes of its parts: a release that changes one for the same parts changes a public answer
+    # (README, "Stability").
     #
     #   SkiftetStatistical::Bandit::Draw.uniform("t")                       # => 0.8895498694938413
     #   SkiftetStatistical::Bandit::Draw.uniform_for("t", "explore")        # => 0.856909028643178
@@ -63,12 +66,16 @@ module SkiftetStatistical
           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).
+        # The uniform of the parts joined by NUL, in [0, 1): the seed's top 53 bits over 2**53, identical everywhere.
+        # Refuses, as an ArgumentError: a part holding a NUL byte, and a part whose to_s answers no String.
         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.
+        # The seed of the parts joined by NUL, an Integer in [0, 2**64), for Random.new: identical in every process,
+        # on every machine and Ruby version, unlike String#hash, which Ruby seeds per process. nil reads as "", and a
+        # number by its to_s (7 and "7" are one part). Refuses, as an ArgumentError: a part holding a NUL byte, and a
+        # part whose to_s answers no String.
         def seed_for(*parts)
           Checks.finite_answer([ head(joined(parts)) ], "the parts").first
         end
@@ -79,7 +86,12 @@ module SkiftetStatistical
           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.
+        # The key a uniform draws from `weights`: `weighted`'s key. Takes a Hash of key => weight (keys any objects,
+        # answered as given and never read) and a uniform in [0, 1]. A uniform drawn uniformly answers a key with
+        # probability its counted weight over the counted total; a key that counts 0 is never answered; no positive
+        # weight counts every key as 1; an empty Hash answers nil. Pure: the same weights and uniform answer the same
+        # key. Refuses, as an ArgumentError: weights that are not a Hash, a uniform outside [0, 1], a weight beyond the
+        # input domain, and counted weights whose sum is not finite.
         def from_weights(weights, uniform)
           weighted(weights, uniform).first
         end

data/lib/skiftet_statistical/bandit/posteriors.rb

@@ -157,8 +157,26 @@ module SkiftetStatistical
       # LARGEST_TOTAL scaled to it; views: { item => Float }. All frozen.
       attr_reader :items, :kind, :parameters, :views
 
+      # THE CONTRACT OF A SET, whichever builder made it (README, "Interface contract"; each guarantee's examples are
+      # indexed in spec/interface_contract_spec.rb):
+      # - A set is a value: `items`, `kind`, `parameters` and `views` are frozen, and no reader (`rank`, `pick`,
+      #   `Order#repin`, `summary`, `means`, `values`, `greedy`) writes to the set, so one set may be built once and read
+      #   from many requests and threads. (The order and position odds keep a memo on a set its caller has not frozen;
+      #   a frozen set computes them each time.)
+      # - An item's pair is its own tally's and prior's (or its own given pair) alone: no other item moves it.
+      # - The pairs are plain arithmetic, formed as stated and rounded once where the class comment says so, so the same
+      #   inputs build the same pairs bit for bit in every process, on every machine and Ruby version.
       class << self
         # Beta posteriors from yes/no tallies, { item => tally }, under `priors` (nil, one pair, or { item => pair }).
+        #
+        # Takes: `items`, a Hash of item name (a non-blank String, in the tie order) => tally ({ views:, outcomes: },
+        # Symbol or String keys, numbers >= 0 and at most Numbers::LARGEST, fractional allowed, optionally the weighted
+        # sums); `priors` nil (Beta(1, 1)), one pair [alpha, beta] (each >= 0) or { item => pair } naming every item.
+        # Answers: a :beta set whose `parameters` are { item => [alpha + c, beta + n - c] }, c the outcomes clamped to
+        # [0, views] (or the weighted outcomes rescaled to the Kish size), a pair above LARGEST_TOTAL scaled to it.
+        # Refuses, as an ArgumentError when the set is built: what the class comment lists (a name that is not a
+        # usable String, a count below 0 or not a number, a Hash of priors naming a name that is not an item or leaving
+        # one out, a pair that is not above 0 once the tally is added).
         def yes_no(items, priors: nil)
           entries = named_entries(items, "items")
           prior_of = prior_per_item(nil.equal?(priors) ? Prior.flat : priors, entries, "priors") do |given, label|
@@ -183,6 +201,11 @@ module SkiftetStatistical
 
         # Normal posteriors for the mean per view from amount tallies, { item => tally }, under `priors` (one
         # Prior::Amount, or { item => Prior::Amount }).
+        #
+        # Takes: tallies { views:, outcomes:, outcome_squares: } (views and outcome_squares >= 0, outcomes the sum of
+        # amounts, any sign), optionally the weighted sums. Answers: a :normal set whose `parameters` are { item =>
+        # [mean, standard deviation] } of the mean per view. Refuses, as an ArgumentError: as `yes_no` does, and a prior
+        # that is not a Prior::Amount (there is no flat amounts prior, so nil and a pair are refused).
         def amounts(items, priors:)
           entries = named_entries(items, "items")
           prior_of = prior_per_item(priors, entries, "priors") { |given, label| Tallies.amount_prior(given, label) }
@@ -206,6 +229,12 @@ module SkiftetStatistical
         end
 
         # Beta posteriors given as pairs, { item => [alpha, beta] }, with views { item => Float } when given.
+        #
+        # Takes: `pairs`, a Hash of item name => [alpha, beta], each a finite number above 0 within the input domain;
+        # `views` nil (every item 0) or a Hash of item name => views >= 0 (an item it leaves out reads 0). Answers: a
+        # :beta set holding the pairs as given (`summary` reads them so), scaled in `parameters` only above
+        # LARGEST_TOTAL. Refuses, as an ArgumentError: the names `yes_no` refuses, a parameter that is not a number
+        # above 0, and views that name a name that is not an item or are below 0.
         def beta(pairs, views: nil)
           from_pairs(:beta, pairs, views)
         end

data/lib/skiftet_statistical/bandit/prior.rb

@@ -67,7 +67,7 @@ module SkiftetStatistical
       private_constant :YES_NO, :AMOUNTS
 
       class << self
-        # Beta(1, 1), the frozen FLAT pair.
+        # Beta(1, 1), the frozen FLAT pair: the same frozen Array on every call.
         def flat = FLAT
 
         # A mean in [0, 1] (the bandit's one [0, 1] bound, Checks.unit) held at a strength >= 0: [strength * mean,
@@ -85,6 +85,11 @@ module SkiftetStatistical
 
         # THE leave-one-out rule: { views:, outcomes: }, the group less the item's own (own nil takes out nothing),
         # views at least 0 and outcomes within [0, views].
+        #
+        # Takes two yes/no tallies (nil reads as no evidence). Answers Floats. Guarantees: the one rule `pooled` and
+        # `pooled_new` borrow by, so a caller never nets an item out by hand; an own tally larger than its group
+        # borrows nothing rather than a negative count. Refuses, as an ArgumentError: a tally that is not a Hash or
+        # nil, a count below 0, a count that is not a number (a String included) or beyond the input domain.
         def borrowed(group:, own: nil)
           taken = left_out(tally(group, "group"), tally(own, "own"))
           answer = { views: taken[:views], outcomes: taken[:outcomes].clamp(0.0, taken[:views]) }
@@ -96,6 +101,12 @@ module SkiftetStatistical
         # min(strength, n). With nothing borrowed it is `base`; while n is at most the strength it is the group's
         # posterior from `base`; above it the borrowed mean stays and its weight stops growing, so a large group never
         # outweighs the item's own evidence for long.
+        #
+        # Takes: `group` and `own` yes/no tallies (as `borrowed`), `strength` a number >= 0 (views), `base` a pair
+        # above 0. Answers [alpha, beta], plain arithmetic, the mean formed exactly and rounded once, so the same
+        # inputs answer the same pair bit for bit everywhere. Refuses, as an ArgumentError: a `base` that is not a pair
+        # above 0, then a `strength` below 0 or not a number ("strength must be >= 0 (got -1.0)"), whatever the tallies
+        # hold, a nil group included; then whatever `borrowed` refuses.
         def pooled(group:, own: nil, strength:, base: FLAT)
           base_alpha, base_beta = pair(base, "base")
           strength = Checks.nonnegative(strength, "strength")
@@ -113,6 +124,10 @@ module SkiftetStatistical
         # evidence (`group` less `own`; a nil group adds nothing), added by the bandit's one yes/no rule. With no
         # others and no group it is Beta(1, 1) at the default weight of 2. `others` is a list, read by the bandit's one
         # list reader (Tallies.list), each a Hash of group: and own:.
+        #
+        # Answers [alpha, beta], plain arithmetic, the pooled rate formed exactly and rounded once. Refuses, as an
+        # ArgumentError: a `weight` below 0 or not a number, `others` that is not a list of Hashes, and whatever
+        # `borrowed` refuses of any tally.
         def pooled_new(others:, group: nil, own: nil, weight: 2.0)
           weight = Checks.nonnegative(weight, "weight")
           others = Tallies.list(others, "others", "Hashes of group: and own:")

data/lib/skiftet_statistical/bandit/ranking.rb

@@ -112,6 +112,28 @@ module SkiftetStatistical
       private_constant :RANK_QUANTILE_DRAW
 
       # The posterior set's items in the order the rule draws: an Order.
+      #
+      # Takes (the class comment's rule): exactly one of `key:` (a String, or an Array of parts: nil, a String, or
+      # anything whose to_s answers a String, none holding a NUL byte), `uniforms:` or `rng:` (answering rand with
+      # Floats in [0, 1)); `shuffle` and `explore` in [0, 1] summing to at most 1; `may_lead` nil or a list of item
+      # names; `min_views` a number in the input domain (one below 0 asks for none, as 0 does); `pinned` a Hash of
+      # Integer position (0-based) => item name; `top` nil or an Integer of at least 1.
+      # Answers: a frozen Order (`items`, `leader`, `branch`, `draws`), and writes nothing to the set.
+      # Guarantees:
+      # - A key draws the same Order from the same set in every process: its uniforms are Draw.uniform_for of the
+      #   key's parts (SHA256, identical on every machine and Ruby version), and its draws their Beta or Normal
+      #   quantiles on `parameters`, whose last bits rest on the math library's lgamma (the pins compare a draw at
+      #   1e-9 relative, and an order, a leader and a branch exactly).
+      # - An item's uniforms are the key's and its own name's alone: with no pin, an added item never changes the
+      #   others' relative order, and an added item that `may_lead` does not name changes neither the others' order,
+      #   the leader nor the branch. `may_lead`, `min_views`, `shuffle` and `explore` choose the head, the branch and
+      #   the leader; the items after the head follow by draw (by priority on the shuffled branch) whatever they are.
+      # - An RNG gives the same Order for the same stream: the rule takes from it exactly one branch value (when
+      #   shuffle + explore is above 0), one priority per free item on the shuffled or explored branch, then one
+      #   Sampler draw per free item where the branch draws, in item order, and nothing else.
+      # - Every source draws exactly from the posteriors, so the order and pick odds describe each of them.
+      # Refuses: the class comment's list, each an ArgumentError before any draw and before anything is taken from an
+      # RNG; an RNG's answer that is not a Float in [0, 1), or a raise from its rand, is an ArgumentError at that answer.
       def rank(key: nil, uniforms: nil, rng: nil, shuffle: 0.0, explore: 0.0, may_lead: nil, min_views: 0.0,
                pinned: {}, top: nil)
         rule = rank_rule(shuffle: shuffle, explore: explore, may_lead: may_lead, min_views: min_views, pinned: pinned,
@@ -120,6 +142,11 @@ module SkiftetStatistical
       end
 
       # The head of the order rule (`rank` with top 1 and no pins): a Choice.
+      #
+      # Takes `rank`'s source and rule, without `pinned` and `top`. Answers a frozen Choice: `item` (the leader: the
+      # head when it has at least `min_views` views, else nil), `head`, `branch` and `draws` (every free item's draw,
+      # none on the shuffled branch). Guarantees `rank`'s: under every source it is the head of the Order `rank`
+      # answers there, an RNG giving up exactly the values `rank` takes. Refuses what `rank` refuses.
       def pick(key: nil, uniforms: nil, rng: nil, shuffle: 0.0, explore: 0.0, may_lead: nil, min_views: 0.0)
         rule = rank_rule(shuffle: shuffle, explore: explore, may_lead: may_lead, min_views: min_views, pinned: {},
                          top: nil)
@@ -535,6 +562,11 @@ module SkiftetStatistical
       # key>, pinned: pinned, top: <its top>)`, or the same with its given uniforms, bit for bit, computed on the draws
       # this order made (an item it did not draw is drawn now). An ArgumentError for an order drawn from an RNG, one no
       # posterior set made, and whatever `rank` refuses there.
+      #
+      # Guarantees: the answer is `rank`'s on the same set, source and pins, `==` and every draw; an item this order
+      # drew keeps its draw and is not drawn again, so re-pinning an order's own head first draws nothing at all; the
+      # source is the one `rank` read (each key part's bytes, each given number), so a caller's object changed after
+      # `rank` moves no re-pin. Neither the order nor its set is changed.
       def repin(pinned)
         unless Posteriors === @posteriors && Hash === @rule
           raise ArgumentError, "a #{Inputs.class_name(self)} is re-pinned only when a posterior set made it (it " \

data/lib/skiftet_statistical/bandit/summary.rb

@@ -73,6 +73,17 @@ module SkiftetStatistical
 
       # { 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).
+      #
+      # Takes: `credible_mass` a number above 0 and below 1; `among` nil (every item), [] (none: means and intervals
+      # only, for a set of any size) or a list of at most EXACT_PICK_MAX item names. Guarantees:
+      # - Exact, never drawn: no key, uniform or RNG is read, so the same set answers the same summary bit for bit on
+      #   every call, whatever the process's random state.
+      # - An item's views, mean and interval are its own pair's alone (the pair as given), so the item answers them
+      #   alike in any set that holds it, a set of its own included; P(best) and the loss read the items `among` names
+      #   and no other.
+      # - The interval's ends are BetaFunction.quantile's (that function's stated accuracy), or the Normal's mean -+ z
+      #   sd; P(best) is BetaArgmax.probabilities' (or NormalArgmax's) quadrature, and the loss is never below 0.
+      # Refuses the list above, each an ArgumentError before anything is computed.
       def summary(credible_mass: 0.95, among: nil)
         tail = summary_tail(credible_mass)
         named = summary_named(among)

data/lib/skiftet_statistical/bandit/weighted_posterior.rb

@@ -14,6 +14,13 @@ module SkiftetStatistical
     # under a small share holds no more evidence than it has. n is the Kish effective sample size
     # (sum w)^2 / sum w^2 when the squared sum is present, never more than the raw count; else the raw exposure
     # count. Without the weighted sums the raw counts are judged.
+    #
+    # Guarantees: plain arithmetic, no randomness, so the same tally answers the same pair bit for bit everywhere;
+    # Bandit::Posteriors.yes_no reads a tally by the same rule (one rule, held equal by its specs). This is 0.2.0's
+    # reading, kept as it was: the counts by Kernel#Integer (a Float truncates toward 0, a numeric String reads as its
+    # number), the weighted sums by to_f. Refuses: what Integer() cannot read raises Integer()'s own error (an
+    # ArgumentError for a String that is no number, a TypeError for an Array or another object, a FloatDomainError for
+    # NaN or an infinity); `beta` refuses a negative exposure count as an ArgumentError.
     module WeightedPosterior
       module_function
 

data/lib/skiftet_statistical/bandit/win_hold.rb

@@ -25,6 +25,15 @@ module SkiftetStatistical
     # A blank leading arm (nil, false, an empty or whitespace-only String, an empty Symbol) reads as none; any other
     # arm is kept as a String. This is ActiveSupport's `blank?`, in every encoding: a String that is not
     # ASCII-compatible (UTF-16, UTF-32) is matched with the pattern in its own encoding.
+    #
+    # Takes: `leading_arm` (any arm, or a blank one), `leading_since`, `now` and `last_pass_at` (Times, numbers of
+    # seconds, or any values whose difference compares with a number of seconds; leading_since and last_pass_at may be
+    # nil), `hold_seconds` and `max_gap_seconds` (numbers of seconds, or any values a difference compares with).
+    # Guarantees: pure, no clock of its own and no state; the two lengths given are the two read (the defaults,
+    # HOLD_SECONDS and MAX_GAP_SECONDS, only when they are left out); both bounds are inclusive: satisfied from exactly
+    # hold_seconds after leading_since, and a gap of exactly max_gap_seconds still unbroken. Refuses nothing of its
+    # own: leaving out a required keyword is Ruby's ArgumentError, and a clock value that cannot be subtracted raises
+    # its own error (NoMethodError or TypeError) when the hold is first asked.
     class WinHold
       HOLD_SECONDS = 86_400
       MAX_GAP_SECONDS = 1_200

data/lib/skiftet_statistical/beta_function.rb

@@ -4,14 +4,30 @@ module SkiftetStatistical
   # The regularized incomplete beta function I_x(alpha, beta), which is the Beta(alpha, beta) distribution
   # function, and its inverse, the Beta quantile. An exact credible interval on a conversion rate is two quantiles
   # of its Beta posterior; computed this way it does not move when a Monte Carlo seed does. Beside them, the log of
-  # the Beta density.
+  # the Beta density, the shortest interval holding a given mass (the highest-density interval, which holds the
+  # mode), and the intervals of means of non-negative values read as shares of their visits.
   #
   #   SkiftetStatistical::BetaFunction.regularized(0.5, 2.0, 2.0)   # => 0.5
   #   SkiftetStatistical::BetaFunction.quantile(0.975, 41.0, 361.0) # => the 97.5 % bound of Beta(41, 361)
   #   SkiftetStatistical::BetaFunction.log_density(0.25, 2.0, 3.0)  # => 0.5232481437645479 (log 27/16)
+  #   SkiftetStatistical::BetaFunction.shortest_interval(0.95, 1.0, 2.0) # => [0.0, 0.776393202250...] (1 - sqrt(0.05))
+  #   SkiftetStatistical::BetaFunction.mean_intervals({ "a" => { visits: 300, mean: 0.02, standard_error: 0.008 },
+  #                                                     "b" => { visits: 300, mean: 0.0, standard_error: 0.0 } },
+  #                                                   mass: 0.95)
+  #   # => { "a" => [lower, upper] around 0.02, "b" => [0.0, upper] }
   #
   # The arithmetic and its order are part of the contract: with parameters in the hundreds or more the lgamma
   # terms of the front factor reach 1e3-1e5, so a reordered sum can move the result by 1e-12 to 1e-10.
+  #
+  # Accuracy (spec/beta_function_spec.rb): for parameters up to a few hundred, `regularized` is within 5e-12
+  # relative of an exact reference (measured worst 2.4e-13). For parameters from 1 000 to 50 000 each, with n = alpha
+  # + beta, the front factor's lgamma terms reach about n log n, whose roundings bound the answer to 4 n log n machine
+  # epsilons, relative (about 1e-9 at n = 100 000; measured worst 0.9 of it against an exact binomial reference), and
+  # the identities I_x(a, b) + I_(1-x)(b, a) = 1 and I_(1/2)(a, a) = 1/2 hold within that bound. `quantile` bisects to
+  # a Float's spacing, so regularized(quantile(p)) is p within the same bound, and its 2.5 % and 97.5 % quantiles lie
+  # within 0.001 sd of the normal approximation with its first skewness term. Past a total of about 3 * 10**8 the
+  # continued fraction's fixed bound binds (Bandit::Posteriors#summary states what that does to an interval). The same
+  # inputs answer the same Float on one platform; another math library's lgamma can move the last bits.
   module BetaFunction
     # Lentz's floor for a denominator that would otherwise be zero.
     TINY = 1.0e-30
@@ -23,15 +39,21 @@ module SkiftetStatistical
     MAX_ITERATIONS = 300
     # Halvings of [0, 1] in the quantile: 80 take the bracket below a Float's spacing anywhere in (0, 1).
     QUANTILE_STEPS = 80
+    # Halvings in the shortest interval, of [0, mode] for its lower end and of [mode, 1] for the point beyond the mode
+    # of equal density: as in the quantile, enough to take each bracket below a Float's spacing.
+    INTERVAL_STEPS = 80
 
     class << self
-      # I_x(alpha, beta) for alpha, beta > 0: 0.0 for x <= 0, 1.0 for x >= 1.
+      # I_x(alpha, beta) for alpha, beta > 0: 0.0 for x <= 0, 1.0 for x >= 1. Refuses, as an ArgumentError: an
+      # alpha or beta whose to_f is not a finite number above 0, and an x whose to_f is NaN.
       def regularized(x, alpha, beta)
         x = number(x, "x")
         incomplete(x, *parameters(alpha, beta))
       end
 
-      # The x where I_x(alpha, beta) = probability, by bisection: 0.0 for probability <= 0, 1.0 for >= 1.
+      # The x where I_x(alpha, beta) = probability, by bisection: 0.0 for probability <= 0, 1.0 for >= 1. Refuses, as
+      # an ArgumentError: an alpha or beta whose to_f is not a finite number above 0, and a probability whose to_f is
+      # NaN.
       def quantile(probability, alpha, beta)
         probability = number(probability, "probability")
         alpha, beta = parameters(alpha, beta)
@@ -67,8 +89,244 @@ module SkiftetStatistical
           ((alpha - 1.0) * Math.log(x)) + ((beta - 1.0) * Math.log(1.0 - x))
       end
 
+      # The shortest interval holding `mass` of Beta(alpha, beta), as [lower, upper], for a mass strictly between 0
+      # and 1 and alpha, beta > 0.
+      #
+      # * ONE PEAK INSIDE (alpha > 1 and beta > 1): the highest-density interval. Its two ends have one density, the
+      #   lower end below the mode (alpha - 1) / (alpha + beta - 2) and the upper end above it, so it holds the mode.
+      # * A DENSITY THAT FALLS FROM 0 (alpha <= 1 <= beta, not both 1): [0, quantile(mass)]; one that rises to 1
+      #   (beta <= 1 <= alpha, not both 1): [quantile(1 - mass), 1]. Again the highest-density interval, holding the
+      #   mode on its boundary.
+      # * A FLAT DENSITY (alpha = beta = 1), where every interval of the mass is as short: the central one,
+      #   [(1 - mass) / 2, (1 + mass) / 2].
+      # * A U-SHAPED DENSITY (alpha < 1 and beta < 1), whose highest-density region is two pieces: the shorter of
+      #   [0, quantile(mass)] and [quantile(1 - mass), 1], the first on a tie.
+      #
+      # Under the flat prior Beta(1, 1), the posterior of c successes in n trials is Beta(1 + c, 1 + n - c), whose mode
+      # is the observed share c / n: its shortest interval always holds that share, which the equal-tailed interval
+      # misses at c = 0 and c = n (it leaves 0, or 1, out). For alpha, beta >= 1 the answer holds the mode for any
+      # parameters, whole or not.
+      #
+      # By bisection, no draw: on the side of the peak nearer 0 (a peak above 1/2 read on Beta(beta, alpha) and
+      # mirrored), the upper end halves [mode, 1] until the mass between it and the point below the mode of the same
+      # density is `mass`, each such point found by halving [0, mode] on the log density. Each end is the bracket's
+      # side that does not shrink it, so the answer holds `mass` to within a Float's last bits (a mirrored answer may
+      # fall that much short); unrounded.
+      #
+      # Takes: `mass` a finite real number strictly between 0 and 1 (a String is not one); `alpha` and `beta` read by
+      # to_f, as `regularized` reads them. Answers [lower, upper], two Floats with 0.0 <= lower <= upper <= 1.0.
+      # Guarantees (exact: no draw, so the same inputs answer the same two Floats on one platform; the mass goes
+      # through `regularized`, whose lgamma another math library can move in the last bits):
+      # - the interval holds `mass` within `regularized`'s accuracy, short of it by a Float's last bits at most;
+      # - with one peak inside, its ends have one density and it is no wider than the equal-tailed interval of the
+      #   same mass; the one-sided, flat and U-shaped cases are the closed forms above;
+      # - for alpha, beta >= 1 (not both 1) it holds the mode, so under the flat prior the observed share, 0 and 1
+      #   included, for whole and fractional counts alike.
+      # Refuses, as an ArgumentError: a mass that is not a finite real number strictly between 0 and 1, then an alpha
+      # or beta whose to_f is not a finite number above 0.
+      def shortest_interval(mass, alpha, beta)
+        mass = interval_mass(mass)
+        alpha, beta = parameters(alpha, beta)
+
+        if alpha > 1.0 && beta > 1.0
+          peaked_interval(mass, alpha, beta)
+        elsif alpha == 1.0 && beta == 1.0
+          [ (1.0 - mass) / 2.0, (1.0 + mass) / 2.0 ]
+        elsif alpha <= 1.0 && beta >= 1.0
+          [ 0.0, quantile(mass, alpha, beta) ]
+        elsif alpha >= 1.0 && beta <= 1.0
+          [ quantile(1.0 - mass, alpha, beta), 1.0 ]
+        else
+          upper = quantile(mass, alpha, beta)
+          lower = quantile(1.0 - mass, alpha, beta)
+          upper <= 1.0 - lower ? [ 0.0, upper ] : [ lower, 1.0 ]
+        end
+      end
+
+      # Each item's `mass` interval of a MEAN OF NON-NEGATIVE VALUES (a value per visit that is never below 0), read
+      # as a share of its visits: the shortest interval (.shortest_interval) of the flat-prior Beta posterior of the
+      # item's effective count of events, scaled by the value of one such event.
+      #
+      #   items  { key => { visits:, mean:, standard_error: } } (Symbol or String field names): `visits` the visits
+      #          the mean is over, `mean` the mean value per visit, `standard_error` its standard error (the sandwich
+      #          of the mean: the spread of the values per visit over the visits, as a Hájek or plain mean gives it).
+      #   mass   strictly between 0 and 1.
+      #
+      # With m the mean, n the visits and s the standard error, the visits' second moment is q = n * s^2 + m^2, one
+      # event is worth u = q / m and the item holds k = n * m / u = n * m^2 / q of them, never more than n. The
+      # interval is u times the shortest interval of Beta(1 + k, 1 + n - k), whose mode k / n times u is m: the mean
+      # always lies inside its interval. In the normal limit the interval's variance, u^2 * (k / n) * (1 - k / n) / n,
+      # is s^2 exactly, so a large item's interval is the mean -/+ its normal half-width; a small one's is skewed and
+      # never below 0. For a value that is 0 or 1 per visit (c of n visits at 1) q / n is c / n, so u is 1 and k is c:
+      # the interval is the share's own, Beta(1 + c, 1 + n - c)'s shortest interval.
+      #
+      # AN ITEM WITH A MEAN OF 0 has seen no event, so it has no scale of its own: it takes the set's, the value of one
+      # event over every item with a mean above 0 (the sum of n * q over the sum of n * m: their values' summed squares
+      # over their summed values), and k = 0, so its interval runs from 0 to that value times quantile(mass) of
+      # Beta(1, 1 + n), shrinking as its visits grow. With no item above 0 in the set, it has no interval (nil).
+      #
+      # Takes: `items` a Hash of key => Hash of fields, the keys any objects, answered as given; each figure, where
+      # given, a finite real number (a String, a numeric one included, is not one), visits and the mean fractional or
+      # whole; `mass` a finite real number strictly between 0 and 1.
+      #
+      # Answers { key => [lower, upper] } in the items' order, each end clamped to the mean against a last-bit rounding;
+      # nil for an item without data, a figure missing (nil: its other figures are then not read) or no visits (0), and
+      # for an item with a mean of 0 in a set with no item above 0.
+      #
+      # Guarantees (exact: no draw, so the same items answer the same Floats on one platform, through
+      # .shortest_interval's arithmetic): every item's mean lies inside its interval and no end is below 0; an item
+      # with a mean above 0 answers from its own visits, mean and standard error alone, so it answers alike in any set
+      # that holds it; an item with a mean of 0 reads the set's items above 0 for its value of one event, and its
+      # interval narrows as its visits grow; a value of 0 or 1 per visit gives the share's own interval; in the normal
+      # limit the interval's width is the normal one's.
+      #
+      # Refuses, as an ArgumentError: a mass that is not a finite real number strictly between 0 and 1; items that are
+      # not a Hash of Hashes; a visit count, mean or standard error that is given beside the other two but is not a
+      # finite real number, visits or a standard error below 0, and a mean below 0; and an item whose arithmetic leaves
+      # a Float's range ("item ... leaves a Float's range"): a value of one event (its own, or for a mean of 0 the
+      # set's) that is not a finite number above 0, which only extreme figures give (a mean whose square underflows, a
+      # tiny mean beside a huge spread, visits times a second moment past 1e308), or visits past about 2**53 that all
+      # hold one value.
+      def mean_intervals(items, mass:)
+        mass = interval_mass(mass)
+        raise ArgumentError, "items must be a Hash of key => fields, got #{items.class}" unless items.is_a?(Hash)
+
+        read = items.to_h { |key, fields| [ key, mean_item(key, fields) ] }
+        evented = read.values.compact.select { |item| item[:mean].positive? }
+        unit = evented.empty? ? nil : set_unit(evented)
+
+        read.to_h do |key, item|
+          next [ key, nil ] if item.nil?
+          next [ key, nil ] if item[:mean].zero? && unit.nil?
+
+          [ key, scaled_share(mass, key, item, unit) ]
+        end
+      end
+
       private
 
+      # A mass strictly between 0 and 1, as a Float.
+      def interval_mass(mass)
+        mass = finite(mass, "mass")
+        raise ArgumentError, "mass must be strictly between 0 and 1, got #{mass}" unless mass > 0.0 && mass < 1.0
+
+        mass
+      end
+
+      # The highest-density interval of a Beta with one peak inside (0, 1) (alpha, beta > 1), worked out on the side
+      # where the peak is nearer 0: a peak above 1/2 is read on Beta(beta, alpha) and mirrored, x for 1 - x. The mass
+      # between an upper end u in [mode, 1] and the point below the mode of the same density rises as u does, from 0
+      # at the mode to 1 at u = 1, so halving keeps the side whose mass is at least `mass`. A lower end too near 0 for
+      # the halving to tell from 0 (a peak just inside 0, as for alpha just above 1, whose density climbs from 0 within
+      # far less than a Float's spacing at the mode) is answered as 0: the mass it leaves out is below that spacing.
+      def peaked_interval(mass, alpha, beta)
+        if alpha - 1.0 > beta - 1.0
+          lower, upper = peaked_interval(mass, beta, alpha)
+          return [ 1.0 - upper, 1.0 - lower ]
+        end
+
+        mode = (alpha - 1.0) / (alpha + beta - 2.0)
+        low = mode
+        high = 1.0
+        INTERVAL_STEPS.times do
+          upper = (low + high) / 2.0
+          lower = level_point(upper, mode, alpha, beta)
+          if incomplete(upper, alpha, beta) - incomplete(lower, alpha, beta) >= mass
+            high = upper
+          else
+            low = upper
+          end
+        end
+        [ level_point(high, mode, alpha, beta), high ]
+      end
+
+      # The point at or below the mode whose density equals the density at `upper` (at most it, so the interval
+      # [point, upper] holds no less): 0.0 where that density is 0, or where the point is nearer 0 than the halving
+      # of [0, mode] can tell.
+      def level_point(upper, mode, alpha, beta)
+        target = kernel(upper, alpha, beta)
+        return 0.0 if target == -Float::INFINITY
+
+        low = 0.0
+        high = mode
+        INTERVAL_STEPS.times do
+          mid = (low + high) / 2.0
+          if kernel(mid, alpha, beta) > target
+            high = mid
+          else
+            low = mid
+          end
+        end
+        low
+      end
+
+      # The log of the Beta density without its constant, (alpha - 1) log x + (beta - 1) log(1 - x); -Infinity at and
+      # outside the ends.
+      def kernel(x, alpha, beta)
+        return -Float::INFINITY unless x > 0.0 && x < 1.0
+
+        ((alpha - 1.0) * Math.log(x)) + ((beta - 1.0) * Math.log(1.0 - x))
+      end
+
+      # One item of .mean_intervals, read: { visits:, mean:, second: } (second the visits' second moment), or nil
+      # without data.
+      def mean_item(key, fields)
+        raise ArgumentError, "item #{key.inspect} must be a Hash of fields, got #{fields.class}" unless fields.is_a?(Hash)
+
+        visits, mean, error = %i[visits mean standard_error].map { |name| fields.fetch(name) { fields[name.to_s] } }
+        return nil if visits.nil? || mean.nil? || error.nil?
+
+        visits = at_least_zero(visits, "item #{key.inspect}'s visits")
+        mean = at_least_zero(mean, "item #{key.inspect}'s mean")
+        error = at_least_zero(error, "item #{key.inspect}'s standard error")
+        return nil if visits.zero?
+
+        { visits: visits, mean: mean, second: (visits * error * error) + (mean * mean) }
+      end
+
+      def at_least_zero(value, name)
+        number = finite(value, name)
+        raise ArgumentError, "#{name} must be at least 0, got #{value.inspect}" if number.negative?
+
+        number
+      end
+
+      # The value of one event over the items with a mean above 0: their summed n * q over their summed n * m.
+      def set_unit(evented)
+        evented.sum { |item| item[:visits] * item[:second] } / evented.sum { |item| item[:visits] * item[:mean] }
+      end
+
+      # An item's interval: its own event value and count where its mean is above 0, else the set's event value and
+      # no event. Where the arithmetic has left a Float's range on the way (an event value that is not a finite number
+      # above 0, or visits so many that 1 + n - k rounds to 0), the item is refused rather than answered.
+      def scaled_share(mass, key, item, set_unit)
+        mean = item[:mean]
+        visits = item[:visits]
+        unit, events =
+          if mean.positive?
+            own = event_value(item[:second] / mean, key, "its own")
+            [ own, [ visits * mean / own, visits ].min ]
+          else
+            [ event_value(set_unit, key, "the set's"), 0.0 ]
+          end
+        rest = 1.0 + visits - events
+        unless rest.positive?
+          raise ArgumentError, "item #{key.inspect}'s interval leaves a Float's range (1 + visits - events is #{rest}): " \
+                               "rescale the values"
+        end
+
+        lower, upper = shortest_interval(mass, 1.0 + events, rest)
+        [ [ unit * lower, mean ].min, [ unit * upper, mean ].max ]
+      end
+
+      # The value of one event, a finite number above 0, else an ArgumentError naming the item.
+      def event_value(value, key, whose)
+        return value if value.finite? && value.positive?
+
+        raise ArgumentError, "item #{key.inspect}'s interval leaves a Float's range (#{whose} value of one event is " \
+                             "#{value}): rescale the values"
+      end
+
       # A finite real number, as the newer modules read one (a NaN, an infinity, a Complex and a non-number are
       # refused alike), and finite as a Float too (an Integer beyond a Float's range is not).
       def finite(value, name)

data/lib/skiftet_statistical/gamma.rb

@@ -14,6 +14,13 @@ module SkiftetStatistical
   #
   # The arithmetic and its order are part of the contract: an app that pins outputs at 1e-12 compares them with
   # this exact sequence of operations, so a reordered formula is a breaking change even when it is "the same".
+  #
+  # Accuracy (spec/gamma_spec.rb): within 5e-12 relative of the exact Poisson sums for whole a up to 200 on both sides
+  # of x = a + 1 (measured worst 2e-13), P + Q = 1, and the closed forms at a = 1/2 and a = 1. No randomness: the
+  # same inputs answer the same Float on one platform; another math library's lgamma or exp can move the last bits.
+  # Refuses, as an ArgumentError: an a whose to_f is not a finite number above 0, and an x whose to_f is NaN (both
+  # read by to_f: a numeric String reads as its number, a non-numeric one as 0.0, and an object without to_f raises
+  # NoMethodError).
   module Gamma
     # A series term or a fraction step this small next to the total is the last one taken.
     EPSILON = 1e-15

data/lib/skiftet_statistical/joint_beta.rb

@@ -17,6 +17,12 @@ module SkiftetStatistical
     class << self
       # Yields one Array per draw (one Float per arm, in order). Without a block, an Enumerator of the rows.
       # Returns nil.
+      #
+      # Takes: `posteriors`, a list of [alpha, beta] pairs (each above 0); `draws`, an Integer >= 0; `rng`, anything
+      # answering rand. Guarantees: the same pairs, draws and RNG stream give the same rows (the draw order above);
+      # every row holds one draw per arm from its Beta, the arms independent within a row. Refuses, as an
+      # ArgumentError: `draws` that is not an Integer >= 0 (before anything is drawn), and a parameter that is not
+      # above 0 at its first draw (Sampler's "shape must be > 0"; with 0 draws nothing is read).
       def each_draw(posteriors, draws:, rng:)
         draws = count(draws)
         return enum_for(:each_draw, posteriors, draws: draws, rng: rng) { draws } unless block_given?