skiftet_statistical 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b72f7bccf09703650bb6232fef2bf588bc41564bf10ecc4a3802d9a432ecaee8
+  data.tar.gz: 9bb85de398e7bd00633db142d08122cdc3b55fda9320ef5035eab53b04051883
+SHA512:
+  metadata.gz: 17c6847d2e87c057b4f1a22901f6b9d542a1576af7edf0cb261c7962542113359e63ebb69a1ec408d2f80937d3dfc13ecd3c11f12c24841d277f11b47487195a
+  data.tar.gz: 0e37add790389b5362df68bbf9c71e7e08b8ec967a0af6a615bb2958a4bbcde67ba1e0766cb52bb1a8560a4001b61cf9a7429e9d10578c613cd285e5e4a79107

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## [0.1.0] - 2026-06-23
+
+Initial release — Skiftet's shared statistics toolkit.
+
+- `SkiftetStatistical::Descriptive` — mean, variance, standard deviation,
+  percentiles and median.
+- `SkiftetStatistical::Significance` — A/B significance testing: two-proportion
+  z-test, Welch's t-test, exact normal CDF and two-tailed p-values (consolidates
+  the duplicated significance math from mej.la and skram.la).
+- `SkiftetStatistical::Bandit` — arms + a pluggable policy, with `#select`,
+  `#record`, `#best_arm`, `#stats`, and Hash (de)serialisation.
+- `SkiftetStatistical::Arm` — online reward statistics (pulls, mean, variance,
+  Beta-Bernoulli successes/failures).
+- Policies: `ThompsonSampling` (Beta-Bernoulli), `EpsilonGreedy`, `UCB1`,
+  `Softmax`.
+- `SkiftetStatistical::Sampler` — RNG-injectable Gamma/Beta/Gaussian sampling, so
+  every stochastic policy is deterministic under test.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Skiftet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,164 @@
+# skiftet_statistical
+
+Skiftet's shared, dependency-free **statistics toolkit** — the workspace home for
+reusable statistical analysis code, so the same z-test, percentile, or sampler
+isn't re-implemented (differently) in every app.
+
+Modules:
+
+- **`Descriptive`** — mean, variance, standard deviation, percentiles/median.
+- **`Significance`** — A/B significance testing: two-proportion z-test, Welch's
+  t-test, exact normal CDF and two-tailed p-values.
+- **`Sampler`** — Gamma/Beta/Gaussian random sampling, RNG-injectable.
+- **`Bandit`** (+ `Policies`) — multi-armed bandit (Thompson Sampling,
+  epsilon-greedy, UCB1, Softmax) for online explore/exploit decisions.
+
+## Install
+
+In a Gemfile (path dependency within the Skiftet workspace):
+
+```ruby
+gem "skiftet_statistical", path: "../skiftet_statistical"
+```
+
+Or build/install locally:
+
+```sh
+cd skiftet_statistical
+bundle install
+gem build skiftet_statistical.gemspec
+```
+
+## Descriptive statistics
+
+```ruby
+SkiftetStatistical::Descriptive.mean([1, 2, 3, 4])             # => 2.5
+SkiftetStatistical::Descriptive.variance([1, 2, 3, 4, 5])      # => 2.5  (sample; pass sample: false for population)
+SkiftetStatistical::Descriptive.standard_deviation(values)
+SkiftetStatistical::Descriptive.percentile(incomes, 90)       # interpolated 90th percentile
+SkiftetStatistical::Descriptive.median(values)
+```
+
+## A/B significance
+
+```ruby
+S = SkiftetStatistical::Significance
+
+# Two-proportion z-test: did variant B convert better than A?
+result = S.two_proportion_z_test(conversions_a, visitors_a, conversions_b, visitors_b)
+result.statistic        # the z score (positive => B higher)
+result.p_value          # two-tailed p
+result.significant?(0.05)
+result.significant_95?  # also _90? / _99?
+result.confidence       # 1 - p
+
+# Welch's t-test for a continuous metric (e.g. revenue per visitor):
+S.welch_t_test(mean_a, var_a, n_a, mean_b, var_b, n_b)
+
+# And the building blocks directly:
+S.normal_cdf(1.96)         # => ~0.975
+S.two_tailed_p_value(1.96) # => ~0.05
+```
+
+`two_proportion_z_test` / `welch_t_test` return `nil` when the test is undefined
+(an empty group or zero variance), matching the existing analyzers' behaviour.
+
+## Quick start (multi-armed bandit)
+
+```ruby
+require "skiftet_statistical"
+
+bandit = SkiftetStatistical.bandit(
+  arms: %w[facebook whatsapp bluesky x email],
+  policy: SkiftetStatistical::Policies::ThompsonSampling.new,
+)
+
+choice = bandit.select          # which channel to promote right now, e.g. "whatsapp"
+# ... show that option to the user ...
+bandit.record(choice, 1)        # reward: 1 = it converted, 0 = it didn't
+
+bandit.best_arm                 # current best by empirical mean
+bandit.stats                    # { "whatsapp" => { pulls:, mean:, reward_sum: }, ... }
+```
+
+Rewards are expected in **[0.0, 1.0]** — a binary `0`/`1` (e.g. "did this share
+lead to a signup?") is the common case, but any value in that range works.
+
+## Policies
+
+| Policy | How it picks | Good when | Key params |
+|---|---|---|---|
+| `ThompsonSampling` | Sample `theta ~ Beta(successes, failures)` per arm, play the highest draw | The default. Best all-round explore/exploit balance; self-tunes | `prior_alpha`, `prior_beta` |
+| `EpsilonGreedy` | Exploit the best mean with prob. `1 - epsilon`, else a random arm | You want a simple, predictable explore rate | `epsilon` (default `0.1`) |
+| `UCB1` | Play `argmax(mean + sqrt(c·ln N / n))` — optimism under uncertainty | You prefer deterministic selection (no RNG in the choice) | `c` (default `2.0`) |
+| `Softmax` | Play arm `i` with prob. `∝ exp(mean_i / temperature)` | You want exploration weighted by how good each arm looks | `temperature` (default `0.1`) |
+
+```ruby
+SkiftetStatistical::Policies::ThompsonSampling.new(prior_alpha: 1.0, prior_beta: 1.0)
+SkiftetStatistical::Policies::EpsilonGreedy.new(epsilon: 0.1)
+SkiftetStatistical::Policies::UCB1.new(c: 2.0)
+SkiftetStatistical::Policies::Softmax.new(temperature: 0.1)
+```
+
+**Which to use?** When unsure, use `ThompsonSampling` — it converges fast, needs
+no tuning, and explores exactly as much as the evidence warrants. Cold start (no
+data) is `Beta(1,1)` on every arm, i.e. uniform random, so early plays are pure
+exploration.
+
+## Persistence
+
+A bandit's state is just its arms' counters, so it round-trips through a `Hash`
+(store it as JSON/JSONB, in Redis, in a column — wherever):
+
+```ruby
+saved = bandit.to_h
+# => { arms: [{ name:, pulls:, reward_sum:, reward_square_sum: }, ...], policy: {...} }
+
+restored = SkiftetStatistical::Bandit.from_h(
+  saved,
+  policy: SkiftetStatistical::Policies::ThompsonSampling.new,
+)
+```
+
+The policy holds an RNG, so it is **not** rebuilt from the serialised config —
+pass the policy instance you want to run with.
+
+## Deterministic testing
+
+Every stochastic policy (and the sampler) takes an `rng:`. Inject a seeded
+`Random` and selection becomes reproducible:
+
+```ruby
+policy = SkiftetStatistical::Policies::ThompsonSampling.new(rng: Random.new(42))
+```
+
+## Example: f1 share-channel bandit
+
+The motivating use case — make the petition ShareStep's **primary** button the
+channel that drives the most signups, while continuously testing the others:
+
+```ruby
+# Nightly (or per request) build a bandit from observed share -> signup data.
+bandit = SkiftetStatistical::Bandit.from_h(
+  Rails.cache.read("share_bandit_state") || { arms: SHARE_CHANNELS.map { { name: _1 } } },
+  policy: SkiftetStatistical::Policies::ThompsonSampling.new,
+)
+primary = bandit.select            # the channel to feature as the primary CTA
+
+# When a share converts:
+bandit.record(channel, 1)
+Rails.cache.write("share_bandit_state", bandit.to_h)
+```
+
+## Development
+
+```sh
+bundle install
+bundle exec rake spec      # run the specs
+bundle exec rake rubocop   # lint
+bundle exec rake           # both
+```
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/lib/skiftet_statistical/arm.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module SkiftetStatistical
+  # One option ("arm") the bandit can choose, tracking online reward statistics.
+  #
+  # Rewards are expected in [0.0, 1.0] for the Bernoulli/Beta policies (Thompson
+  # Sampling, UCB1, Epsilon-Greedy treat the mean as a success rate). A binary
+  # 0/1 reward is the common case ("did this share convert?"), but any value in
+  # [0, 1] works (the summed rewards act as fractional successes).
+  class Arm
+    attr_reader :name, :pulls, :reward_sum, :reward_square_sum
+
+    def initialize(name, pulls: 0, reward_sum: 0.0, reward_square_sum: 0.0)
+      raise ArgumentError, "arm name cannot be nil" if name.nil?
+
+      @name = name
+      @pulls = Integer(pulls)
+      @reward_sum = Float(reward_sum)
+      @reward_square_sum = Float(reward_square_sum)
+    end
+
+    # Record one observed reward for this arm. Returns self for chaining.
+    def update(reward)
+      r = Float(reward)
+      @pulls += 1
+      @reward_sum += r
+      @reward_square_sum += r * r
+      self
+    end
+
+    # Empirical mean reward (0.0 when never pulled).
+    def mean
+      return 0.0 if @pulls.zero?
+
+      @reward_sum / @pulls
+    end
+    alias rate mean
+
+    # Population variance of observed rewards (0.0 with fewer than two pulls).
+    def variance
+      return 0.0 if @pulls < 2
+
+      m = mean
+      [ (@reward_square_sum / @pulls) - (m * m), 0.0 ].max
+    end
+
+    # Beta-Bernoulli view: summed rewards are "successes", the remaining pulls
+    # "failures". With [0, 1] rewards these can be fractional — Beta handles that.
+    def successes
+      @reward_sum
+    end
+
+    def failures
+      [ @pulls - @reward_sum, 0.0 ].max
+    end
+
+    def pulled?
+      @pulls.positive?
+    end
+
+    def to_h
+      {
+        name: @name,
+        pulls: @pulls,
+        reward_sum: @reward_sum,
+        reward_square_sum: @reward_square_sum
+      }
+    end
+
+    def self.from_h(hash)
+      h = hash.transform_keys(&:to_sym)
+      new(
+        h.fetch(:name),
+        pulls: h.fetch(:pulls, 0),
+        reward_sum: h.fetch(:reward_sum, 0.0),
+        reward_square_sum: h.fetch(:reward_square_sum, 0.0),
+      )
+    end
+  end
+end

data/lib/skiftet_statistical/bandit.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module SkiftetStatistical
+  # The bandit: a named set of arms plus a selection policy. Ask it which arm to
+  # play (`#select`), observe a reward, and tell it (`#record`). All state lives
+  # in the arms, so a bandit serialises to a plain Hash and back for persistence.
+  #
+  #   bandit = SkiftetStatistical::Bandit.new(
+  #     arms: %w[facebook whatsapp x],
+  #     policy: SkiftetStatistical::Policies::ThompsonSampling.new,
+  #   )
+  #   choice = bandit.select          # => "whatsapp"
+  #   bandit.record("whatsapp", 1)    # a conversion
+  #   bandit.best_arm                 # => highest empirical mean
+  class Bandit
+    attr_reader :policy
+
+    def initialize(arms: [], policy: nil)
+      @arms = {}
+      Array(arms).each { |a| add_arm(a) }
+      @policy = policy || Policies::ThompsonSampling.new
+    end
+
+    # Add an arm by name (String/Symbol) or an existing Arm. Idempotent — an
+    # already-known name is left untouched. Returns the arm.
+    def add_arm(arm)
+      a = arm.is_a?(Arm) ? arm : Arm.new(arm)
+      @arms[a.name] ||= a
+    end
+
+    def arm(name)
+      @arms.fetch(name) { raise Error, "unknown arm: #{name.inspect}" }
+    end
+
+    def arms
+      @arms.values
+    end
+
+    def arm_names
+      @arms.keys
+    end
+
+    # Choose an arm to play. Returns the arm's name.
+    def select
+      raise Error, "bandit has no arms" if @arms.empty?
+
+      @policy.choose(@arms.values).name
+    end
+
+    # Record an observed reward for the named arm. Returns self for chaining.
+    def record(name, reward)
+      arm(name).update(reward)
+      self
+    end
+
+    # The arm with the highest empirical mean — the current exploitation choice.
+    def best_arm
+      return nil if @arms.empty?
+
+      @arms.values.max_by(&:mean)&.name
+    end
+
+    # Per-arm summary: { name => { pulls:, mean:, reward_sum: } }.
+    def stats
+      @arms.transform_values do |a|
+        { pulls: a.pulls, mean: a.mean, reward_sum: a.reward_sum }
+      end
+    end
+
+    def to_h
+      { arms: @arms.values.map(&:to_h), policy: @policy.to_h }
+    end
+
+    # Rebuild a bandit's ARM STATE from a hash produced by #to_h. The policy is
+    # not reconstructed from its serialised config (policies carry an RNG); pass
+    # the policy instance you want to run with.
+    def self.from_h(hash, policy: nil)
+      h = hash.transform_keys(&:to_sym)
+      arms = Array(h[:arms]).map { |ah| Arm.from_h(ah) }
+      new(arms: arms, policy: policy)
+    end
+  end
+end

data/lib/skiftet_statistical/descriptive.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module SkiftetStatistical
+  # Descriptive statistics over a collection of numbers — mean, variance,
+  # standard deviation, and interpolated percentiles. Consolidates the ad-hoc
+  # mean/variance (skram.la's revenue-per-visitor stats) and percentile logic
+  # (ekonomidata.nu's income distributions) scattered across the workspace.
+  module Descriptive
+    module_function
+
+    # Arithmetic mean (0.0 for an empty collection).
+    def mean(values)
+      return 0.0 if values.empty?
+
+      values.sum.to_f / values.length
+    end
+
+    # Variance. `sample: true` (default) divides by n-1 (Bessel's correction);
+    # `sample: false` divides by n (population variance). 0.0 for n < 2.
+    def variance(values, sample: true)
+      n = values.length
+      return 0.0 if n < 2
+
+      m = mean(values)
+      ss = values.sum { |v| (v - m)**2 }
+      ss / (sample ? (n - 1) : n).to_f
+    end
+
+    def standard_deviation(values, sample: true)
+      Math.sqrt(variance(values, sample: sample))
+    end
+
+    # Linear-interpolation percentile, `p` in [0, 100]. nil for an empty
+    # collection. percentile(values, 50) == median.
+    def percentile(values, p)
+      return nil if values.empty?
+
+      sorted = values.sort
+      return sorted.first.to_f if sorted.length == 1
+
+      rank = (p.clamp(0, 100) / 100.0) * (sorted.length - 1)
+      lower = rank.floor
+      upper = rank.ceil
+      return sorted[lower].to_f if lower == upper
+
+      weight = rank - lower
+      (sorted[lower] * (1.0 - weight)) + (sorted[upper] * weight)
+    end
+
+    def median(values)
+      percentile(values, 50)
+    end
+  end
+end

data/lib/skiftet_statistical/policies/base.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module SkiftetStatistical
+  module Policies
+    # A selection policy decides which arm to pull next from the current stats.
+    # Subclasses implement `#choose(arms)`, returning the chosen Arm.
+    class Base
+      # Pick an arm. `arms` is a non-empty Array<Arm>; returns the chosen Arm.
+      def choose(_arms)
+        raise NotImplementedError, "#{self.class} must implement #choose"
+      end
+
+      # Serialisable config (so a Bandit can describe its policy).
+      def to_h
+        { type: self.class.name.split("::").last }
+      end
+
+      private
+
+      def ensure_arms!(arms)
+        raise Error, "no arms to choose from" if arms.nil? || arms.empty?
+      end
+
+      # Arms never pulled yet — explored first by the deterministic policies so
+      # no arm is starved by an undefined/zero initial estimate.
+      def unpulled(arms)
+        arms.reject(&:pulled?)
+      end
+
+      # Given [[arm, score], ...] return the arm with the highest score, breaking
+      # ties uniformly at random via the supplied rng.
+      def pick_max(scored, rng)
+        best_score = scored.map { |(_, s)| s }.max
+        leaders = scored.select { |(_, s)| s == best_score }.map(&:first)
+        leaders.length == 1 ? leaders.first : leaders[rng.rand(leaders.length)]
+      end
+    end
+  end
+end

data/lib/skiftet_statistical/policies/epsilon_greedy.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module SkiftetStatistical
+  module Policies
+    # epsilon-greedy: exploit the best-mean arm with probability (1 - epsilon),
+    # explore a uniformly random arm with probability epsilon. Every arm is
+    # pulled once first so none is starved by a zero initial mean.
+    class EpsilonGreedy < Base
+      attr_reader :epsilon
+
+      def initialize(epsilon: 0.1, rng: Random.new)
+        super()
+        raise ArgumentError, "epsilon must be in [0, 1]" unless (0.0..1.0).cover?(epsilon)
+
+        @epsilon = Float(epsilon)
+        @rng = rng
+      end
+
+      def choose(arms)
+        ensure_arms!(arms)
+
+        fresh = unpulled(arms)
+        return fresh[@rng.rand(fresh.length)] unless fresh.empty?
+
+        if @rng.rand < @epsilon
+          arms[@rng.rand(arms.length)]
+        else
+          pick_max(arms.map { |a| [ a, a.mean ] }, @rng)
+        end
+      end
+
+      def to_h
+        super.merge(epsilon: @epsilon)
+      end
+    end
+  end
+end

data/lib/skiftet_statistical/policies/softmax.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module SkiftetStatistical
+  module Policies
+    # Softmax / Boltzmann exploration: pick arm i with probability proportional
+    # to exp(mean_i / temperature). Low temperature => near-greedy; high
+    # temperature => near-uniform exploration.
+    class Softmax < Base
+      attr_reader :temperature
+
+      def initialize(temperature: 0.1, rng: Random.new)
+        super()
+        raise ArgumentError, "temperature must be > 0" unless temperature.positive?
+
+        @temperature = Float(temperature)
+        @rng = rng
+      end
+
+      def choose(arms)
+        ensure_arms!(arms)
+
+        # Shift by the max mean for numerical stability (exp can overflow).
+        max_mean = arms.map(&:mean).max
+        weights = arms.map { |a| Math.exp((a.mean - max_mean) / @temperature) }
+        total = weights.sum
+        target = @rng.rand * total
+
+        cumulative = 0.0
+        arms.each_with_index do |arm, i|
+          cumulative += weights[i]
+          return arm if cumulative >= target
+        end
+        arms.last
+      end
+
+      def to_h
+        super.merge(temperature: @temperature)
+      end
+    end
+  end
+end

data/lib/skiftet_statistical/policies/thompson_sampling.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module SkiftetStatistical
+  module Policies
+    # Thompson Sampling (Beta-Bernoulli). For each arm draw theta ~ Beta(alpha0 +
+    # successes, beta0 + failures) and pull the arm with the highest draw. It
+    # balances exploration and exploitation automatically: under-sampled arms
+    # have wide posteriors and get tried often, while the best arm is chosen more
+    # and more as evidence accrues. With no data every arm is Beta(1, 1) =
+    # uniform, so the opening pulls are pure (random) exploration.
+    class ThompsonSampling < Base
+      attr_reader :prior_alpha, :prior_beta
+
+      def initialize(prior_alpha: 1.0, prior_beta: 1.0, rng: Random.new)
+        super()
+        @prior_alpha = Float(prior_alpha)
+        @prior_beta = Float(prior_beta)
+        @sampler = Sampler.new(rng)
+        @rng = rng
+      end
+
+      def choose(arms)
+        ensure_arms!(arms)
+
+        scored = arms.map do |arm|
+          theta = @sampler.beta(@prior_alpha + arm.successes, @prior_beta + arm.failures)
+          [ arm, theta ]
+        end
+        pick_max(scored, @rng)
+      end
+
+      def to_h
+        super.merge(prior_alpha: @prior_alpha, prior_beta: @prior_beta)
+      end
+    end
+  end
+end

data/lib/skiftet_statistical/policies/ucb1.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module SkiftetStatistical
+  module Policies
+    # UCB1: deterministic optimism under uncertainty. Pull the arm maximising
+    # mean + sqrt(c * ln(total_pulls) / arm_pulls). Each arm is pulled once first
+    # (the confidence bound is undefined at zero pulls). Larger `c` explores more;
+    # c = 2.0 is the classic Auer et al. value.
+    class UCB1 < Base
+      attr_reader :c
+
+      def initialize(c: 2.0, rng: Random.new)
+        super()
+        raise ArgumentError, "c must be > 0" unless c.positive?
+
+        @c = Float(c)
+        @rng = rng
+      end
+
+      def choose(arms)
+        ensure_arms!(arms)
+
+        fresh = unpulled(arms)
+        return fresh[@rng.rand(fresh.length)] unless fresh.empty?
+
+        ln_total = Math.log(arms.sum(&:pulls))
+        scored = arms.map do |arm|
+          bonus = Math.sqrt(@c * ln_total / arm.pulls)
+          [ arm, arm.mean + bonus ]
+        end
+        pick_max(scored, @rng)
+      end
+
+      def to_h
+        super.merge(c: @c)
+      end
+    end
+  end
+end

data/lib/skiftet_statistical/sampler.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module SkiftetStatistical
+  # Random sampling used by the stochastic policies (Thompson Sampling, Softmax,
+  # Epsilon-Greedy). An injectable RNG (a `Random`) makes every policy fully
+  # deterministic under test — pass `rng: Random.new(seed)`.
+  class Sampler
+    attr_reader :rng
+
+    def initialize(rng = Random.new)
+      @rng = rng
+    end
+
+    # Standard normal deviate via Box–Muller.
+    def gaussian
+      u1 = rand_open
+      u2 = @rng.rand
+      Math.sqrt(-2.0 * Math.log(u1)) * Math.cos(2.0 * Math::PI * u2)
+    end
+
+    # Gamma(shape, scale = 1) via Marsaglia–Tsang. Shapes < 1 are handled by the
+    # standard boosting identity: Gamma(k) = Gamma(k + 1) * U**(1/k).
+    def gamma(shape)
+      raise ArgumentError, "shape must be > 0" unless shape.positive?
+
+      return gamma(shape + 1.0) * (rand_open**(1.0 / shape)) if shape < 1.0
+
+      d = shape - (1.0 / 3.0)
+      c = 1.0 / Math.sqrt(9.0 * d)
+      loop do
+        x = gaussian
+        v = (1.0 + (c * x))**3
+        next if v <= 0.0
+
+        u = @rng.rand
+        return d * v if u < 1.0 - (0.0331 * (x**4))
+        return d * v if Math.log(u) < (0.5 * x * x) + (d * (1.0 - v + Math.log(v)))
+      end
+    end
+
+    # Beta(alpha, beta) drawn as G1 / (G1 + G2) with Gi ~ Gamma(., 1).
+    def beta(alpha, beta)
+      g1 = gamma(alpha)
+      g2 = gamma(beta)
+      total = g1 + g2
+      total.zero? ? 0.5 : g1 / total
+    end
+
+    private
+
+    # Uniform on (0, 1] — keeps log(u) finite in Box–Muller / boosting.
+    def rand_open
+      u = @rng.rand
+      u.zero? ? Float::MIN : u
+    end
+  end
+end

data/lib/skiftet_statistical/significance.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module SkiftetStatistical
+  # Frequentist significance testing for A/B experiments. Consolidates the
+  # two-proportion z-test, Welch's t-test and the normal CDF that were previously
+  # re-implemented (inconsistently) across mej.la's AbTestAnalyzer and skram.la's
+  # CRM::AbTestAnalysis. One correct, exact (erf-based) normal CDF — no polynomial
+  # approximations.
+  module Significance
+    module_function
+
+    # Standard normal cumulative distribution Phi(z), exact via erf.
+    def normal_cdf(z)
+      0.5 * (1.0 + Math.erf(z / Math.sqrt(2.0)))
+    end
+
+    # Two-tailed p-value for a z (or normal-approx t) statistic. Clamped to [0, 1].
+    def two_tailed_p_value(z)
+      (2.0 * (1.0 - normal_cdf(z.abs))).clamp(0.0, 1.0)
+    end
+
+    # Two-proportion z-test with a pooled standard error, two-tailed. Pass the
+    # successes and trials for each group. Returns a Result, or nil when the test
+    # is undefined (an empty group, or zero pooled variance). The z sign follows
+    # b - a, so a positive z means group B converts higher.
+    def two_proportion_z_test(successes_a, trials_a, successes_b, trials_b)
+      return nil if trials_a <= 0 || trials_b <= 0
+
+      p_a = successes_a.to_f / trials_a
+      p_b = successes_b.to_f / trials_b
+      p_pool = (successes_a + successes_b).to_f / (trials_a + trials_b)
+      se = Math.sqrt(p_pool * (1.0 - p_pool) * ((1.0 / trials_a) + (1.0 / trials_b)))
+      return nil if se.zero?
+
+      z = (p_b - p_a) / se
+      Result.new(statistic: z, p_value: two_tailed_p_value(z))
+    end
+
+    # Welch's t-test (normal approximation) for two means given their sample
+    # variances and sizes. Suitable for revenue-per-visitor style metrics. Returns
+    # a Result, or nil when undefined (n < 2 or zero combined variance).
+    def welch_t_test(mean_a, variance_a, n_a, mean_b, variance_b, n_b)
+      return nil if n_a < 2 || n_b < 2
+
+      denom = (variance_a.to_f / n_a) + (variance_b.to_f / n_b)
+      return nil if denom <= 0
+
+      t = (mean_b - mean_a) / Math.sqrt(denom)
+      Result.new(statistic: t, p_value: two_tailed_p_value(t))
+    end
+
+    # The outcome of a significance test: the test statistic and its two-tailed
+    # p-value, with convenience predicates for the usual confidence levels.
+    Result = Struct.new(:statistic, :p_value, keyword_init: true) do
+      def significant?(alpha = 0.05)
+        p_value < alpha
+      end
+
+      def significant_90? = significant?(0.10)
+      def significant_95? = significant?(0.05)
+      def significant_99? = significant?(0.01)
+
+      # Certainty = 1 - p, the complement of the p-value.
+      def confidence
+        1.0 - p_value
+      end
+    end
+  end
+end

data/lib/skiftet_statistical/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SkiftetStatistical
+  VERSION = "0.1.0"
+end

data/lib/skiftet_statistical.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "skiftet_statistical/version"
+require_relative "skiftet_statistical/sampler"
+require_relative "skiftet_statistical/descriptive"
+require_relative "skiftet_statistical/significance"
+require_relative "skiftet_statistical/arm"
+require_relative "skiftet_statistical/policies/base"
+require_relative "skiftet_statistical/policies/epsilon_greedy"
+require_relative "skiftet_statistical/policies/thompson_sampling"
+require_relative "skiftet_statistical/policies/ucb1"
+require_relative "skiftet_statistical/policies/softmax"
+require_relative "skiftet_statistical/bandit"
+
+# Skiftet's shared statistics toolkit — a home for reusable, app-independent
+# statistical analysis code across the workspace.
+#
+# Modules:
+# - {Descriptive} — mean, variance, standard deviation, percentiles/median.
+# - {Significance} — A/B significance testing (two-proportion z-test, Welch's
+#   t-test, normal CDF / two-tailed p-values).
+# - {Sampler} — Gamma/Beta/Gaussian random sampling (RNG-injectable).
+# - {Bandit} + {Policies} — multi-armed bandit (Thompson Sampling, epsilon-greedy,
+#   UCB1, Softmax) for online explore/exploit decisions.
+#
+#   bandit = SkiftetStatistical.bandit(arms: %w[facebook whatsapp x])
+#   choice = bandit.select          # which arm to play now
+#   bandit.record(choice, 1)        # observed a reward (e.g. a conversion)
+#   bandit.best_arm                 # current best by empirical mean
+module SkiftetStatistical
+  class Error < StandardError; end
+
+  # Convenience constructor for a multi-armed bandit.
+  def self.bandit(...)
+    Bandit.new(...)
+  end
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: skiftet_statistical
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Skiftet
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |-
+  A small, dependency-free toolkit for online decision-making under uncertainty:
+  register arms, ask which to play, record rewards, and let a pluggable policy
+  balance exploration and exploitation. Ships Thompson Sampling, epsilon-greedy,
+  UCB1 and Softmax; state serialises to a plain Hash for persistence and every
+  policy is deterministic under an injected RNG for testing.
+email:
+- joel@skram.la
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/skiftet_statistical.rb
+- lib/skiftet_statistical/arm.rb
+- lib/skiftet_statistical/bandit.rb
+- lib/skiftet_statistical/descriptive.rb
+- lib/skiftet_statistical/policies/base.rb
+- lib/skiftet_statistical/policies/epsilon_greedy.rb
+- lib/skiftet_statistical/policies/softmax.rb
+- lib/skiftet_statistical/policies/thompson_sampling.rb
+- lib/skiftet_statistical/policies/ucb1.rb
+- lib/skiftet_statistical/sampler.rb
+- lib/skiftet_statistical/significance.rb
+- lib/skiftet_statistical/version.rb
+homepage: https://github.com/Skiftet/skiftet_statistical
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  github_repo: https://github.com/Skiftet/skiftet_statistical
+  homepage_uri: https://github.com/Skiftet/skiftet_statistical
+  source_code_uri: https://github.com/Skiftet/skiftet_statistical
+  changelog_uri: https://github.com/Skiftet/skiftet_statistical/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Multi-armed bandit policies (Thompson Sampling, epsilon-greedy, UCB1, Softmax)
+  for Ruby.
+test_files: []