skiftet_statistical 0.1.0 → 0.4.0

data/lib/skiftet_statistical/cholesky.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+module SkiftetStatistical
+  # The Cholesky factor of a covariance matrix: the lower-triangular L with L * L^T = matrix, for drawing correlated
+  # normals as means + L * n from independent standard normals n. Pure Ruby, no matrix library.
+  #
+  #   SkiftetStatistical::Cholesky.factor([ [ 4.0, 2.0 ], [ 2.0, 5.0 ] ])
+  #   # => [[2.0, 0.0], [1.0, 2.0]]
+  #
+  # Rows in, rows out: n rows of n numbers in, n rows of n Floats out, 0.0 above the diagonal; the input is never
+  # changed. The matrix must be square, of finite real numbers (finite as Floats too) and symmetric: entries (i, j) and
+  # (j, i) may differ by at most 1e-12 times the larger of their sizes and sqrt(|a_ii| * |a_jj|), the scale of a
+  # covariance's entry, so the rounding of a computed zero passes and a real asymmetry does not. The lower triangle is
+  # read.
+  #
+  # Column by column, the pivot of column j is a_jj - sum over k < j of L_jk^2, and the residual of a row i > j under
+  # it is r_ij = a_ij - sum over k < j of L_ik * L_jk:
+  # - a pivot below -1e-9 times the trace raises ArgumentError: the matrix is not positive semidefinite. A trace not
+  #   above 0 gives no rounding at all, so a pivot of exactly 0 passes and any pivot below 0 raises;
+  # - a pivot below 1e-12 times the largest diagonal entry, or not above 0, is set to 0 with its whole column, so a
+  #   part with no variance (or none left once the others are known) is drawn at its mean and still takes its normal.
+  #   Every residual under it must be within what that pivot holds plus rounding: |r_ij| at most
+  #   sqrt(pivot * q_ij) + 1e-9 times the trace, where q_ij = a_ii - sum over k < j of L_ik^2 is the pivot row i has
+  #   at column j (a pivot or a q_ij not above 0 counts as 0). The square root is the bound every positive
+  #   semidefinite matrix keeps; the rounding is the one a pivot is given. A larger residual raises ArgumentError: the
+  #   matrix is not positive semidefinite (a part with no variance cannot covary), and setting the column to 0 would
+  #   drop the residual from L * L^T;
+  # - otherwise L_jj = sqrt(pivot) and L_ij = r_ij / L_jj below it.
+  #
+  # A matrix of lower rank is the one `factor` can refuse although it is positive semidefinite: in the given order a
+  # pivot of what is left may be rounding, kept because it is above 1e-12 of the largest diagonal entry, and dividing by
+  # it carries that rounding into every later pivot. `root` is the same arithmetic taken largest pivot first, so nothing
+  # is divided by rounding while a larger pivot is left:
+  #
+  #   SkiftetStatistical::Cholesky.root([ [ 1.0, 2.0 ], [ 2.0, 4.0 ] ])
+  #   # => [[1.0, 0.0], [2.0, 0.0]]
+  #
+  # It answers a square root S, n rows of n Floats with S * S^T = matrix within the tolerance below, each row the row of
+  # the same index given. S is NOT triangular in the given order: column k holds the k-th pivot taken, and the columns
+  # after the last pivot kept are 0.0. The matrix is read as `factor` reads it. `rounding`, a finite number of at least
+  # 0, is how far the caller says each entry given may be off. The tolerance of residual (i, j) is the larger of 1e-9
+  # times the trace (a trace not above 0 gives none) and rounding * reach_i * reach_j. A residual row is the row given
+  # less multiples of the pivots' rows given, and reach_i is 1 plus the sizes of those multiples, so that product is
+  # what `rounding` on every entry can move the residual by; before any pivot it is `rounding` itself. A pivot kept is
+  # above its own tolerance, so a large multiple raises the tolerance less than it lowers a pivot it did not earn: an
+  # indefinite matrix cannot pass on its own multiples. At each step the largest residual pivot left is taken:
+  # - a residual pivot below minus its tolerance raises ArgumentError: the matrix is not positive semidefinite;
+  # - one within its tolerance reads as zero and ends its column, which stays 0.0. Every residual beside it must be
+  #   within what that pivot holds plus their tolerance, or it raises ArgumentError as `factor` does: the column would
+  #   drop the residual from S * S^T;
+  # - otherwise S takes the pivot's column and the residuals give up its share.
+  # An accepted matrix is rebuilt within about twice the tolerance, the largest residual dropped.
+  module Cholesky
+    # A pivot below this times the largest diagonal entry is no variance: set to 0 with its column.
+    ZERO_PIVOT = 1e-12
+    # A pivot below minus this times the trace is no rounding: the matrix is not positive semidefinite. A residual
+    # under a pivot set to 0 is given the same rounding beyond what that pivot holds. A trace not above 0 gives none.
+    NEGATIVE_PIVOT = 1e-9
+    # How far apart entries (i, j) and (j, i) may be, relative to their scale.
+    SYMMETRY = 1e-12
+
+    class << self
+      def factor(rows)
+        matrix = read(rows)
+        size = matrix.size
+        diagonal = Array.new(size) { |i| matrix[i][i] }
+        zero_below = ZERO_PIVOT * (diagonal.max || 0.0)
+        rounding = NEGATIVE_PIVOT * [ diagonal.sum(0.0), 0.0 ].max
+        lower = Array.new(size) { Array.new(size, 0.0) }
+
+        size.times do |j|
+          pivot = matrix[j][j] - (0...j).sum(0.0) { |k| lower[j][k] * lower[j][k] }
+          if pivot < -rounding
+            raise ArgumentError, "the matrix is not positive semidefinite (pivot #{pivot} in column #{j})"
+          end
+
+          if pivot < zero_below || pivot <= 0.0
+            check_held(matrix, lower, j, pivot, rounding)
+            next
+          end
+
+          root = Math.sqrt(pivot)
+          lower[j][j] = root
+          ((j + 1)...size).each do |i|
+            lower[i][j] = (matrix[i][j] - (0...j).sum(0.0) { |k| lower[i][k] * lower[j][k] }) / root
+          end
+        end
+
+        lower
+      end
+
+      # The square root S of the matrix, largest pivot first (see the module's notes).
+      def root(rows, rounding: 0.0)
+        margin = read_rounding(rounding)
+        matrix = read(rows)
+        floor = [ (0...matrix.size).sum(0.0) { |i| NEGATIVE_PIVOT * matrix[i][i] }, 0.0 ].max
+        Elimination.new(matrix, floor, margin).square_root
+      end
+
+      private
+
+      def read_rounding(value)
+        number = value.to_f if value.is_a?(Numeric) && value.real? && value.finite?
+        return number if number&.finite? && !number.negative?
+
+        raise ArgumentError, "rounding must be a finite number of at least 0, got #{value.inspect}"
+      end
+
+      # Column j's pivot is set to 0 with its column: every residual under it must be within what the pivot holds,
+      # sqrt(pivot * q_ij), plus rounding, or it would be dropped from L * L^T.
+      def check_held(matrix, lower, j, pivot, rounding)
+        held = pivot.positive? ? pivot : 0.0
+        ((j + 1)...matrix.size).each do |i|
+          residual = matrix[i][j] - (0...j).sum(0.0) { |k| lower[i][k] * lower[j][k] }
+          own = matrix[i][i] - (0...j).sum(0.0) { |k| lower[i][k] * lower[i][k] }
+          next if residual.abs <= Math.sqrt(held * (own.positive? ? own : 0.0)) + rounding
+
+          raise ArgumentError, "the matrix is not positive semidefinite (residual #{residual} in row #{i} under " \
+                               "the zero pivot of column #{j})"
+        end
+      end
+
+      # The rows as Floats, checked square, finite and symmetric.
+      def read(rows)
+        raise ArgumentError, "the matrix must be an Array of rows, got #{rows.class}" unless rows.is_a?(Array)
+
+        size = rows.size
+        matrix = rows.each_with_index.map do |row, i|
+          unless row.is_a?(Array) && row.size == size
+            raise ArgumentError, "the matrix must be square: row #{i} is not #{size} entries"
+          end
+
+          row.each_with_index.map { |value, j| entry(value, i, j) }
+        end
+        check_symmetric(matrix)
+        matrix
+      end
+
+      # A finite real number, finite as a Float too (an Integer or Rational beyond a Float's range is not).
+      def entry(value, i, j)
+        number = value.to_f if value.is_a?(Numeric) && value.real? && value.finite?
+        return number if number&.finite?
+
+        raise ArgumentError, "entry (#{i}, #{j}) must be a finite number, got #{value.inspect}"
+      end
+
+      def check_symmetric(matrix)
+        matrix.each_index do |i|
+          (0...i).each do |j|
+            upper = matrix[j][i]
+            low = matrix[i][j]
+            scale = [ upper.abs, low.abs, Math.sqrt(matrix[i][i].abs * matrix[j][j].abs) ].max
+            next if (upper - low).abs <= SYMMETRY * scale
+
+            raise ArgumentError, "the matrix is not symmetric: entries (#{i}, #{j}) and (#{j}, #{i}) differ"
+          end
+        end
+      end
+    end
+
+    # One call of `root`: the residuals left, the column of S each pivot gave, and how far `rounding` reaches each row.
+    class Elimination
+      def initialize(matrix, floor, margin)
+        @size = matrix.size
+        @floor = floor
+        @margin = margin
+        @residual = Array.new(@size) { |i| Array.new(@size) { |j| i < j ? matrix[j][i] : matrix[i][j] } }
+        @square = Array.new(@size) { Array.new(@size, 0.0) }
+        @multiples = Array.new(@size) { Array.new(@size, 0.0) }
+        @reach = Array.new(@size, 1.0)
+        @left = (0...@size).to_a
+      end
+
+      def square_root
+        @size.times do |column|
+          row = largest_pivot
+          @left.delete(row)
+          if @residual[row][row] > tolerance(row, row)
+            take_pivot(row, column)
+          else
+            check_dropped(row)
+          end
+        end
+
+        @square
+      end
+
+      private
+
+      def tolerance(first, second)
+        [ @floor, @margin * @reach[first] * @reach[second] ].max
+      end
+
+      # The row of the largest residual pivot left, each read first: elimination only lowers a pivot, so one beyond its
+      # tolerance (or an infinity or a NaN, which an overflow of an indefinite matrix leaves) never comes back.
+      def largest_pivot
+        largest = nil
+        @left.each do |i|
+          pivot = @residual[i][i]
+          unless pivot.finite? && pivot >= -tolerance(i, i)
+            raise ArgumentError, "the matrix is not positive semidefinite (pivot #{pivot} in column #{i})"
+          end
+
+          largest = i if largest.nil? || pivot > @residual[largest][largest]
+        end
+        largest
+      end
+
+      # Column `column` of S from row `row`'s pivot, and what is left of the rows still to come.
+      def take_pivot(row, column)
+        top = Math.sqrt(@residual[row][row])
+        @square[row][column] = top
+        @left.each { |i| @square[i][column] = @residual[i][row] / top }
+        @left.each do |i|
+          share = @square[i][column]
+          @left.each { |j| @residual[i][j] -= share * @square[j][column] }
+          carry(i, row, column, share / top) unless @margin.zero?
+        end
+      end
+
+      # Row i gives up `multiple` of the pivot's row, itself the row given less the multiples it gave up.
+      def carry(row, pivot, column, multiple)
+        multiples = @multiples[row]
+        given = @multiples[pivot]
+        column.times { |earlier| multiples[earlier] -= multiple * given[earlier] }
+        multiples[column] = multiple
+        @reach[row] = 1.0 + multiples.sum(0.0, &:abs)
+      end
+
+      # Row `row`'s pivot reads as zero: what stands beside it must be within what it holds, or S * S^T would drop it.
+      def check_dropped(row)
+        held = [ @residual[row][row], 0.0 ].max
+        @left.each do |i|
+          beside = @residual[i][row]
+          next if beside.abs <= Math.sqrt(held * [ @residual[i][i], 0.0 ].max) + tolerance(i, row)
+
+          raise ArgumentError, "the matrix is not positive semidefinite (residual #{beside} in row #{i} under " \
+                               "the zero pivot of column #{row})"
+        end
+      end
+    end
+    private_constant :Elimination
+  end
+end

data/lib/skiftet_statistical/cusum.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module SkiftetStatistical
+  # A one-sided change test (Page 1954): has a stream of standardised values z_1, z_2, ... moved up? The statistic
+  # gathers each value's excess over a reference k and never falls below 0:
+  #
+  #   S_0 = 0, S_t = max(0, S_(t-1) + z_t - k), an alarm at the first t with S_t > h
+  #
+  # Steps count from 1, so the first alarm's step is the run length. Nothing resets after an alarm.
+  #
+  # How long a run lasts is Siegmund's approximation. For values of mean shift, a drift theta = shift - k and a boundary
+  # b = h + 1.166:
+  #
+  #   average run length = (exp(-2 * theta * b) + 2 * theta * b - 1) / (2 * theta**2), b**2 at theta = 0
+  #
+  # threshold turns a stated false-alarm rate into h by that approximation, one alarm in false_alarm_steps while
+  # nothing moves (shift 0). minimum_detectable then states the smallest change that h can see: the shift, in standard
+  # units, whose run length is at most horizon_steps. The caller scales it by its standard error, and it is the caller
+  # who states the rate.
+  #
+  #   SkiftetStatistical::Cusum.run([ 0.0, 0.0, 5.0 ], reference: 0.5, threshold: 4.0)
+  #   # => { statistic: 4.5, alarm_at: 3, path: [0.0, 0.0, 4.5] }
+  #   SkiftetStatistical::Cusum.average_run_length(shift: 0.0, reference: 0.5, threshold: 4.0)    # => 338.09...
+  #   SkiftetStatistical::Cusum.threshold(reference: 0.5, false_alarm_steps: 365.0)               # => 4.0743...
+  #   SkiftetStatistical::Cusum.minimum_detectable(reference: 0.5, threshold: 4.07, horizon_steps: 30.0) # => 0.4747...
+  #
+  # The run length falls from infinity to 0 as the shift rises and it rises with the threshold, so each search has one
+  # answer. Near theta = 0 the formula cancels (at b = 5 it reads 0 or -55.5 at theta = 1e-9, not 25), so there the
+  # same function is summed as its series. A run length past what exp or a Float can say reads as Infinity, the
+  # formula's own limit. Every other number in and out is a finite Float: one past a Float's range is refused.
+  module Cusum
+    # Siegmund's correction to the boundary: 2 * 0.583.
+    BOUNDARY_CORRECTION = 1.166
+    # threshold searches [0, LARGEST_THRESHOLD].
+    LARGEST_THRESHOLD = 50.0
+    # Below this |2 * theta * b| the run length is summed as a series; at this size the formula has lost one digit.
+    SERIES_BELOW = 0.5
+    # The series stops at the term with this divisor, 2 * x**18 / 20!: under SERIES_BELOW the first term left out is
+    # under 1e-24 of the sum.
+    SERIES_LAST_DIVISOR = 20
+    # A bound, not a tuning knob: each search ends once its two ends are neighbouring Floats.
+    BISECTIONS = 200
+    # Math.exp overflows past this.
+    LARGEST_EXPONENT = Math.log(Float::MAX)
+
+    class << self
+      # The statistic over z, an Array of finite numbers: { statistic:, alarm_at:, path: }, path every S_t (one per
+      # value, none for an empty z), statistic the last of them (S_0 = 0.0 for an empty z) and alarm_at the step of
+      # the first S_t above the threshold, nil if there is none. The threshold is >= 0.
+      def run(z, reference:, threshold:)
+        raise ArgumentError, "z must be an Array of numbers, got #{z.class}" unless z.is_a?(Array)
+
+        k = number(reference, "reference")
+        h = level(threshold)
+        statistic = 0.0
+        alarm_at = nil
+        path = z.map.with_index(1) do |value, step|
+          statistic = gather(statistic, number(value, "each z"), k)
+          alarm_at ||= step if statistic > h
+          statistic
+        end
+        { statistic: statistic, alarm_at: alarm_at, path: path }
+      end
+
+      # Siegmund's run length for values of mean shift. The threshold is >= 0.
+      def average_run_length(shift:, reference:, threshold:)
+        run_length(drift(shift, reference), boundary(threshold))
+      end
+
+      # The threshold in [0, LARGEST_THRESHOLD] whose in-control run length is false_alarm_steps, a number > 0, by
+      # Siegmund's approximation: the first Float whose approximate run length reaches it. The rate is that
+      # approximation's, not a bound on the test. Simulated at 200,000 runs a setting over 30 to 5,000 steps, a real run
+      # lasts within 1 % of the stated steps at a reference of 0.25 or below, within about 2 % at 0.5, 3 % at 0.75 and
+      # 7 % at 1.0, mostly short, and a run that much shorter alarms that much more often. A run length no threshold in
+      # the range gives raises ArgumentError, because answering an end would answer a rate nobody stated.
+      def threshold(reference:, false_alarm_steps:)
+        theta = drift(0.0, reference)
+        target = positive(false_alarm_steps, "false_alarm_steps")
+        lowest = run_length(theta, BOUNDARY_CORRECTION)
+        highest = run_length(theta, LARGEST_THRESHOLD + BOUNDARY_CORRECTION)
+        unless target.between?(lowest, highest)
+          raise ArgumentError, "no threshold in [0, #{LARGEST_THRESHOLD}] has a run length of #{target} at reference " \
+                               "#{reference}: they run from #{lowest} to #{highest}"
+        end
+        return 0.0 if target == lowest
+
+        bisect(0.0, LARGEST_THRESHOLD) { |h| run_length(theta, h + BOUNDARY_CORRECTION) >= target }
+      end
+
+      # The smallest shift, in standard units, whose run length is at most horizon_steps, a number > 0: the first Float
+      # that meets the horizon. A horizon at or past the in-control run length answers a shift at or below 0, as the
+      # formula has it: noise alone alarms inside such a horizon.
+      def minimum_detectable(reference:, threshold:, horizon_steps:)
+        k = number(reference, "reference")
+        b = boundary(threshold)
+        horizon = positive(horizon_steps, "horizon_steps")
+
+        low, high = drift_bracket(b, horizon)
+        low = number(k + low, "the smallest shift")
+        high = number(k + high, "the smallest shift")
+        bisect(low, high) { |shift| run_length(shift - k, b) <= horizon }
+      end
+
+      private
+
+      def gather(statistic, value, k)
+        moved = statistic + value - k
+        raise ArgumentError, "the statistic has left a Float's range, at #{moved}" unless moved.finite?
+
+        moved.positive? ? moved : 0.0
+      end
+
+      # The formula, with x = 2 * theta * b. Since x / (2 * theta**2) = b / theta, the same function writes as
+      # (b / theta) * (1 + (exp(-x) - 1) / x), in which nothing overflows that the answer does not.
+      def run_length(theta, b)
+        x = 2.0 * theta * b
+        return Float::INFINITY if x < -LARGEST_EXPONENT
+        return b * b * near_zero(x) if x.abs < SERIES_BELOW
+
+        (b / theta) * (1.0 + ((Math.exp(-x) - 1.0) / x))
+      end
+
+      # The run length over b**2: 2 * (exp(-x) - 1 + x) / x**2 = the sum over n >= 0 of 2 * (-x)**n / (n + 2)!, whose
+      # first term is 1 and each next the last times -x / (n + 2). Exactly 1.0 at x = 0.
+      def near_zero(x)
+        term = 1.0
+        (3..SERIES_LAST_DIVISOR).sum(1.0) { |divisor| term *= -x / divisor }
+      end
+
+      # Two drifts around the one whose run length is horizon. Above 0 the run length lies under b / theta, so that
+      # drift is an upper end. Below 0 it grows past any horizon: b >= 1.166 takes it past exp's range by 305.
+      def drift_bracket(b, horizon)
+        return [ 0.0, b / horizon ] if run_length(0.0, b) > horizon
+
+        low = -1.0
+        low *= 2.0 until run_length(low, b) > horizon
+        [ low, 0.0 ]
+      end
+
+      # The first Float of [low, high] where the block holds, for a block that holds from one point of the range up.
+      def bisect(low, high)
+        BISECTIONS.times do
+          middle = low + ((high - low) / 2.0)
+          break if middle <= low || middle >= high
+
+          yield(middle) ? high = middle : low = middle
+        end
+        high
+      end
+
+      def drift(shift, reference)
+        number(number(shift, "shift") - number(reference, "reference"), "shift - reference")
+      end
+
+      def boundary(threshold)
+        level(threshold) + BOUNDARY_CORRECTION
+      end
+
+      def level(threshold)
+        h = number(threshold, "threshold")
+        raise ArgumentError, "threshold must be >= 0, got #{threshold.inspect}" unless h >= 0.0
+
+        h
+      end
+
+      def positive(value, name)
+        float = number(value, name)
+        raise ArgumentError, "#{name} must be > 0, got #{value.inspect}" unless float.positive?
+
+        float
+      end
+
+      # A finite real number, as the other modules read one (a NaN, an infinity, a Complex and a non-number are refused
+      # alike), and finite as a Float too (an Integer or Rational beyond a Float's range is not).
+      def number(value, name)
+        float = value.to_f if value.is_a?(Numeric) && value.real? && value.finite?
+        return float if float&.finite?
+
+        raise ArgumentError, "#{name} must be a finite number, got #{value.inspect}"
+      end
+    end
+  end
+end

data/lib/skiftet_statistical/descriptive.rb

@@ -2,9 +2,9 @@
 
 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.
+  # standard deviation, and interpolated percentiles. One home for the mean and
+  # variance of an amount per view and the percentiles of a distribution, so
+  # callers stop writing their own ad-hoc copies.
   module Descriptive
     module_function
 

data/lib/skiftet_statistical/gamma.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module SkiftetStatistical
+  # The regularized incomplete gamma functions: P(a, x), the Gamma(a, 1) distribution function at x, and
+  # Q(a, x) = 1 - P(a, x). The chi-squared survival (Significance.chi_squared_survival) and an exact Poisson
+  # interval or p-value are both read off them.
+  #
+  # Below x = a + 1 the power series converges fast and gives P; at and above it the continued fraction
+  # (modified Lentz) converges fast and gives Q. Each function reads the other half as one minus it
+  # (Numerical Recipes, gammp / gammq).
+  #
+  #   SkiftetStatistical::Gamma.regularized_lower(1.0, 2.0) # => 0.8646647167633873 (1 - e**-2)
+  #   SkiftetStatistical::Gamma.regularized_upper(1.0, 2.0) # => 0.1353352832366127 (e**-2)
+  #
+  # 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".
+  module Gamma
+    # A series term or a fraction step this small next to the total is the last one taken.
+    EPSILON = 1e-15
+    # A bound, not a tuning knob: near x = a the series takes 7 323 terms at a = 1e6 and 62 463 at a = 1e8 (the
+    # fraction fewer), measured. A lower bound gives different digits for large a.
+    MAX_TERMS = 100_000
+    # Lentz's floor for a denominator that would otherwise be zero.
+    TINY = 1e-300
+
+    class << self
+      # P(a, x) for a > 0. 0.0 for x <= 0.
+      def regularized_lower(a, x)
+        a, x = arguments(a, x)
+        return 0.0 if x <= 0.0
+        return 1.0 if x.infinite?
+
+        x < a + 1.0 ? series(a, x) : 1.0 - fraction(a, x)
+      end
+
+      # Q(a, x) = 1 - P(a, x) for a > 0. 1.0 for x <= 0.
+      def regularized_upper(a, x)
+        a, x = arguments(a, x)
+        return 1.0 if x <= 0.0
+        return 0.0 if x.infinite?
+
+        x < a + 1.0 ? 1.0 - series(a, x) : fraction(a, x)
+      end
+
+      private
+
+      def arguments(a, x)
+        a = a.to_f
+        x = x.to_f
+        raise ArgumentError, "a must be a finite number > 0, got #{a}" unless a.finite? && a.positive?
+        raise ArgumentError, "x must be a number, got #{x}" if x.nan?
+
+        [ a, x ]
+      end
+
+      # x**a * e**-x / Gamma(a), in logs so it neither overflows nor underflows on its way.
+      def prefix(a, x)
+        Math.exp((a * Math.log(x)) - x - Math.lgamma(a).first)
+      end
+
+      # P(a, x) by its power series; converges fast for x < a + 1.
+      def series(a, x)
+        term = 1.0 / a
+        sum = term
+        denominator = a
+        MAX_TERMS.times do
+          denominator += 1.0
+          term *= x / denominator
+          sum += term
+          break if term.abs < sum.abs * EPSILON
+        end
+        sum * prefix(a, x)
+      end
+
+      # Q(a, x) by its continued fraction, modified Lentz; converges fast for x >= a + 1.
+      def fraction(a, x)
+        b = x + 1.0 - a
+        c = 1.0 / TINY
+        d = 1.0 / b
+        h = d
+        (1..MAX_TERMS).each do |i|
+          an = -i * (i - a)
+          b += 2.0
+          d = (an * d) + b
+          d = TINY if d.abs < TINY
+          c = b + (an / c)
+          c = TINY if c.abs < TINY
+          d = 1.0 / d
+          delta = d * c
+          h *= delta
+          break if (delta - 1.0).abs < EPSILON
+        end
+        h * prefix(a, x)
+      end
+    end
+  end
+end

data/lib/skiftet_statistical/gauss_legendre.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module SkiftetStatistical
+  # The n-point Gauss-Legendre rule on [-1, 1]: n nodes x_i and weights w_i with sum w_i * f(x_i) = the integral of f
+  # over [-1, 1] for every polynomial f of degree up to 2n - 1. The nodes are the roots of the Legendre polynomial P_n,
+  # found by Newton's method from the cosine first guess cos(pi * (i - 1/4) / (n + 1/2)); each weight is
+  # 2 / ((1 - x**2) * P_n'(x)**2). For a panel [a, b], x maps to (a + b) / 2 + (b - a) / 2 * x and w to (b - a) / 2 * w.
+  #
+  #   SkiftetStatistical::GaussLegendre.nodes(2)
+  #   # => [[-0.5773502691896257, 1.0], [0.5773502691896257, 1.0]] (x = -+1 / sqrt(3), w = 1)
+  #
+  # The rule is computed once per n and kept: every later call answers the same frozen pairs. The positive roots are
+  # found by Newton's method and mirrored, so the rule is exactly symmetric, and for odd n the middle node is exactly 0
+  # (P_n is odd). The pairs come in ascending order of x.
+  module GaussLegendre
+    # Newton's method stops once a step is this small (the roots lie in (-1, 1), so the bound is absolute); from there
+    # one more step could not move a node by a Float's spacing.
+    NEWTON_TOLERANCE = 1e-15
+    # A bound, not a tuning knob: from the cosine guess Newton takes 2 to 5 steps for every root at every n from 1 to
+    # 300 and at 500, 1 000, 2 000 and 4 000 (measured).
+    NEWTON_STEPS = 100
+
+    @rules = {}
+    @lock = Mutex.new
+
+    class << self
+      # [[x, w]] for the n-point rule on [-1, 1], ascending in x; n an Integer >= 1.
+      def nodes(n)
+        raise ArgumentError, "n must be an Integer >= 1, got #{n.inspect}" unless n.is_a?(Integer) && n >= 1
+
+        @lock.synchronize { @rules[n] ||= build(n) }
+      end
+
+      private
+
+      def build(n)
+        half = n / 2
+        positive = (1..half).map { |i| root(n, i) }
+        middle = n.odd? ? [ [ 0.0, weight(n, 0.0) ] ] : []
+        lower = positive.map { |x, w| [ -x, w ].freeze }
+        (lower + middle + positive.reverse).map(&:freeze).freeze
+      end
+
+      # The i-th largest root of P_n and its weight.
+      def root(n, i)
+        x = Math.cos(Math::PI * (i - 0.25) / (n + 0.5))
+        NEWTON_STEPS.times do
+          value, derivative = legendre(n, x)
+          step = value / derivative
+          x -= step
+          break if step.abs <= NEWTON_TOLERANCE
+        end
+        [ x, weight(n, x) ]
+      end
+
+      def weight(n, x)
+        _value, derivative = legendre(n, x)
+        2.0 / ((1.0 - (x * x)) * derivative * derivative)
+      end
+
+      # P_n(x) by the three-term recurrence j P_j = (2j - 1) x P_(j-1) - (j - 1) P_(j-2), and its derivative
+      # n (x P_n - P_(n-1)) / (x**2 - 1).
+      def legendre(n, x)
+        previous = 1.0
+        current = x
+        (2..n).each do |j|
+          previous, current = current, ((((2 * j) - 1) * x * current) - ((j - 1) * previous)) / j
+        end
+        [ current, n * ((x * current) - previous) / ((x * x) - 1.0) ]
+      end
+    end
+  end
+end