stat_power 0.1.0.alpha.1

data/lib/stat_power/distributions/normal.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module StatPower
+  module Distributions
+    # Utilities for the standard normal distribution.
+    module Normal
+      SQRT_TWO = Math.sqrt(2.0)
+      INV_SQRT_TWO_PI = 1.0 / Math.sqrt(2.0 * Math::PI)
+
+      A = [
+        -3.969683028665376e+01,
+        2.209460984245205e+02,
+        -2.759285104469687e+02,
+        1.383577518672690e+02,
+        -3.066479806614716e+01,
+        2.506628277459239e+00
+      ].freeze
+
+      B = [
+        -5.447609879822406e+01,
+        1.615858368580409e+02,
+        -1.556989798598866e+02,
+        6.680131188771972e+01,
+        -1.328068155288572e+01
+      ].freeze
+
+      C = [
+        -7.784894002430293e-03,
+        -3.223964580411365e-01,
+        -2.400758277161838e+00,
+        -2.549732539343734e+00,
+        4.374664141464968e+00,
+        2.938163982698783e+00
+      ].freeze
+
+      D = [
+        7.784695709041462e-03,
+        3.224671290700398e-01,
+        2.445134137142996e+00,
+        3.754408661907416e+00
+      ].freeze
+
+      LOWER_TAIL = 0.02425
+      UPPER_TAIL = 1.0 - LOWER_TAIL
+
+      module_function
+
+      # Probability density function of the standard normal distribution.
+      #
+      # @param x [Numeric] evaluation point
+      # @return [Float] density at x
+      def pdf(x)
+        value = Float(x)
+        INV_SQRT_TWO_PI * Math.exp(-0.5 * value * value)
+      end
+
+      # Cumulative distribution function of the standard normal distribution.
+      #
+      # Uses erfc rather than 1 + erf to avoid cancellation in the lower tail.
+      #
+      # @param x [Numeric] evaluation point
+      # @return [Float] probability P(Z <= x)
+      def cdf(x)
+        value = Float(x)
+        0.5 * Math.erfc(-value / SQRT_TWO)
+      end
+
+      # Survival function of the standard normal distribution.
+      #
+      # @param x [Numeric] evaluation point
+      # @return [Float] probability P(Z > x)
+      def survival(x)
+        value = Float(x)
+        0.5 * Math.erfc(value / SQRT_TWO)
+      end
+
+      # Quantile function of the standard normal distribution.
+      #
+      # Uses Peter J. Acklam's rational approximation. Boundary probabilities
+      # map to the corresponding extended-real quantiles.
+      #
+      # @param probability [Numeric] probability in [0, 1]
+      # @return [Float] z such that P(Z <= z) = probability
+      # @raise [StatPower::DomainError] if probability is outside [0, 1]
+      def quantile(probability)
+        p = Float(probability)
+        validate_probability!(p)
+
+        return -Float::INFINITY if p.zero?
+        return Float::INFINITY if p >= 1.0
+
+        if p < LOWER_TAIL
+          lower_tail_quantile(p)
+        elsif p > UPPER_TAIL
+          -lower_tail_quantile(1.0 - p)
+        else
+          central_quantile(p)
+        end
+      end
+
+      def validate_probability!(probability)
+        return if probability.finite? && probability.between?(0.0, 1.0)
+
+        raise StatPower::DomainError, "probability must be finite and lie in [0, 1]"
+      end
+      private_class_method :validate_probability!
+
+      def lower_tail_quantile(probability)
+        q = Math.sqrt(-2.0 * Math.log(probability))
+
+        numerator = (((((C[0] * q) + C[1]) * q + C[2]) * q + C[3]) * q + C[4]) * q + C[5]
+        denominator = ((((D[0] * q) + D[1]) * q + D[2]) * q + D[3]) * q + 1.0
+
+        numerator / denominator
+      end
+      private_class_method :lower_tail_quantile
+
+      def central_quantile(probability)
+        q = probability - 0.5
+        r = q * q
+
+        numerator = (((((A[0] * r) + A[1]) * r + A[2]) * r + A[3]) * r + A[4]) * r + A[5]
+        denominator = (((((B[0] * r) + B[1]) * r + B[2]) * r + B[3]) * r + B[4]) * r + 1.0
+
+        q * numerator / denominator
+      end
+      private_class_method :central_quantile
+    end
+  end
+end

data/lib/stat_power/distributions/student_t.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module StatPower
+  module Distributions
+    # Central Student t distribution utilities.
+    module StudentT
+      module_function
+
+      # Probability density function.
+      #
+      # @param x [Numeric] evaluation point
+      # @param degrees_of_freedom [Numeric] positive degrees of freedom
+      # @return [Float]
+      def pdf(x, degrees_of_freedom:)
+        value = Float(x)
+        df = normalize_degrees_of_freedom(degrees_of_freedom)
+        return Normal.pdf(value) if df.infinite?
+
+        log_scale = log_gamma((df + 1.0) / 2.0) -
+                    log_gamma(df / 2.0) -
+                    (0.5 * Math.log(df * Math::PI))
+        log_kernel = -((df + 1.0) / 2.0) * Math.log(1.0 + ((value * value) / df))
+
+        Math.exp(log_scale + log_kernel)
+      end
+
+      # Cumulative distribution function.
+      #
+      # @param x [Numeric] evaluation point
+      # @param degrees_of_freedom [Numeric] positive degrees of freedom
+      # @return [Float]
+      def cdf(x, degrees_of_freedom:)
+        value = Float(x)
+        df = normalize_degrees_of_freedom(degrees_of_freedom)
+        return Normal.cdf(value) if df.infinite?
+        return 0.5 if value.zero?
+
+        beta_argument = df / (df + (value * value))
+        beta = SpecialFunctions::Beta.regularized(
+          beta_argument,
+          a: df / 2.0,
+          b: 0.5
+        )
+
+        value.negative? ? 0.5 * beta : 1.0 - (0.5 * beta)
+      end
+
+      # Survival function P(T > x).
+      #
+      # Uses symmetry to avoid subtractive cancellation.
+      #
+      # @param x [Numeric] evaluation point
+      # @param degrees_of_freedom [Numeric] positive degrees of freedom
+      # @return [Float]
+      def survival(x, degrees_of_freedom:)
+        cdf(-Float(x), degrees_of_freedom:)
+      end
+
+      # Quantile function.
+      #
+      # @param probability [Numeric] probability in [0, 1]
+      # @param degrees_of_freedom [Numeric] positive degrees of freedom
+      # @return [Float]
+      def quantile(probability, degrees_of_freedom:)
+        target = Float(probability)
+        validate_probability!(target)
+        df = normalize_degrees_of_freedom(degrees_of_freedom)
+
+        return -Float::INFINITY if target.zero?
+        return Float::INFINITY if target >= 1.0
+        return 0.0 if (target - 0.5).abs <= Float::EPSILON
+        return Normal.quantile(target) if df.infinite?
+
+        sign = target < 0.5 ? -1.0 : 1.0
+        upper_target = target < 0.5 ? 1.0 - target : target
+        upper = quantile_upper_bound(upper_target, df)
+
+        root = Solvers::Bisection.solve(lower: 0.0, upper:) do |candidate|
+          cdf(candidate, degrees_of_freedom: df) - upper_target
+        end
+
+        sign * root
+      end
+
+      def quantile_upper_bound(target, degrees_of_freedom)
+        upper = 1.0
+
+        while cdf(upper, degrees_of_freedom:) < target
+          upper *= 2.0
+          if upper > 1e12
+            raise StatPower::ConvergenceError,
+                  "unable to bracket Student t quantile"
+          end
+        end
+
+        upper
+      end
+      private_class_method :quantile_upper_bound
+
+      def normalize_degrees_of_freedom(value)
+        df = Float(value)
+        return df if df.infinite? && df.positive?
+        return df if df.finite? && df.positive?
+
+        raise StatPower::DomainError, "degrees_of_freedom must be positive"
+      rescue ArgumentError, TypeError
+        raise StatPower::DomainError, "degrees_of_freedom must be numeric"
+      end
+      private_class_method :normalize_degrees_of_freedom
+
+      def validate_probability!(probability)
+        return if probability.finite? && probability.between?(0.0, 1.0)
+
+        raise StatPower::DomainError, "probability must be finite and lie in [0, 1]"
+      end
+      private_class_method :validate_probability!
+
+      def log_gamma(value)
+        Math.lgamma(value).first
+      end
+      private_class_method :log_gamma
+    end
+  end
+end

data/lib/stat_power/effect_size/conventional.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module StatPower
+  module EffectSize
+    # Cohen-style conventional effect-size lookup used by CRAN pwr.
+    module Conventional
+      VALUES = {
+        p: { small: 0.2, medium: 0.5, large: 0.8 },
+        t: { small: 0.2, medium: 0.5, large: 0.8 },
+        chisq: { small: 0.1, medium: 0.3, large: 0.5 },
+        r: { small: 0.1, medium: 0.3, large: 0.5 },
+        anov: { small: 0.1, medium: 0.25, large: 0.4 },
+        f2: { small: 0.02, medium: 0.15, large: 0.35 }
+      }.freeze
+
+      module_function
+
+      # Resolve a conventional effect size.
+      #
+      # @param test [Symbol, String] pwr-style test family
+      # @param size [Symbol, String] small, medium, or large
+      # @return [Float]
+      # @raise [StatPower::DomainError] for unknown tests or sizes
+      def resolve(test:, size:)
+        test_key = test.to_sym
+        size_key = size.to_sym
+        family = VALUES[test_key]
+
+        raise StatPower::DomainError, "unknown effect-size test family: #{test}" unless family
+
+        value = family[size_key]
+        return value if value
+
+        raise StatPower::DomainError, "unknown conventional effect size: #{size}"
+      end
+    end
+  end
+end

data/lib/stat_power/effect_size/proportion.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module StatPower
+  module EffectSize
+    # Effect-size utilities for proportions.
+    module Proportion
+      module_function
+
+      # Compute Cohen's h for two proportions.
+      #
+      # h = 2 asin(sqrt(p1)) - 2 asin(sqrt(p2))
+      #
+      # @param p1 [Numeric] first proportion in [0, 1]
+      # @param p2 [Numeric] second proportion in [0, 1]
+      # @return [Float] signed Cohen h
+      # @raise [StatPower::DomainError] if either proportion is outside [0, 1]
+      def cohen_h(p1:, p2:)
+        first = probability!(p1, "p1")
+        second = probability!(p2, "p2")
+
+        (2.0 * Math.asin(Math.sqrt(first))) -
+          (2.0 * Math.asin(Math.sqrt(second)))
+      end
+
+      def probability!(value, name)
+        probability = Float(value)
+        return probability if probability.finite? && probability.between?(0.0, 1.0)
+
+        raise StatPower::DomainError, "#{name} must be finite and lie in [0, 1]"
+      rescue ArgumentError, TypeError
+        raise StatPower::DomainError, "#{name} must be numeric"
+      end
+      private_class_method :probability!
+    end
+  end
+end

data/lib/stat_power/errors.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module StatPower
+  # Base error class for stat_power.
+  class Error < StandardError; end
+
+  # Raised when a numerical or statistical argument lies outside its domain.
+  class DomainError < Error; end
+
+  # Raised when an iterative numerical method fails to converge.
+  class ConvergenceError < Error; end
+end

data/lib/stat_power/integration/adaptive_simpson.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module StatPower
+  module Integration
+    # Adaptive Simpson quadrature for smooth one-dimensional integrands.
+    module AdaptiveSimpson
+      DEFAULT_TOLERANCE = 1e-10
+      DEFAULT_MAX_DEPTH = 30
+
+      module_function
+
+      # Numerically integrate a function over a finite interval.
+      #
+      # @param lower [Numeric] lower integration bound
+      # @param upper [Numeric] upper integration bound
+      # @param tolerance [Numeric] absolute error target
+      # @param max_depth [Integer] maximum recursive subdivision depth
+      # @yieldparam x [Float] evaluation point
+      # @yieldreturn [Numeric] function value
+      # @return [Float] approximate integral
+      def integrate(
+        lower:,
+        upper:,
+        tolerance: DEFAULT_TOLERANCE,
+        max_depth: DEFAULT_MAX_DEPTH,
+        &function
+      )
+        raise ArgumentError, "a function block is required" unless function
+
+        left = Float(lower)
+        right = Float(upper)
+        error_target = Float(tolerance)
+        validate_arguments!(left, right, error_target, max_depth)
+
+        midpoint = left + ((right - left) / 2.0)
+        f_left = finite_value!(function.call(left))
+        f_midpoint = finite_value!(function.call(midpoint))
+        f_right = finite_value!(function.call(right))
+        whole = simpson(left, right, f_left, f_midpoint, f_right)
+
+        recurse(
+          function:,
+          left:,
+          right:,
+          f_left:,
+          f_midpoint:,
+          f_right:,
+          whole:,
+          tolerance: error_target,
+          depth: max_depth
+        )
+      end
+
+      def recurse(
+        function:,
+        left:,
+        right:,
+        f_left:,
+        f_midpoint:,
+        f_right:,
+        whole:,
+        tolerance:,
+        depth:
+      )
+        midpoint = left + ((right - left) / 2.0)
+        left_midpoint = left + ((midpoint - left) / 2.0)
+        right_midpoint = midpoint + ((right - midpoint) / 2.0)
+
+        f_left_midpoint = finite_value!(function.call(left_midpoint))
+        f_right_midpoint = finite_value!(function.call(right_midpoint))
+
+        left_area = simpson(left, midpoint, f_left, f_left_midpoint, f_midpoint)
+        right_area = simpson(midpoint, right, f_midpoint, f_right_midpoint, f_right)
+        refined = left_area + right_area
+        correction = refined - whole
+
+        return refined + (correction / 15.0) if depth.zero? || correction.abs <= 15.0 * tolerance
+
+        half_tolerance = tolerance / 2.0
+        recurse(
+          function:,
+          left:,
+          right: midpoint,
+          f_left:,
+          f_midpoint: f_left_midpoint,
+          f_right: f_midpoint,
+          whole: left_area,
+          tolerance: half_tolerance,
+          depth: depth - 1
+        ) + recurse(
+          function:,
+          left: midpoint,
+          right:,
+          f_left: f_midpoint,
+          f_midpoint: f_right_midpoint,
+          f_right:,
+          whole: right_area,
+          tolerance: half_tolerance,
+          depth: depth - 1
+        )
+      end
+      private_class_method :recurse
+
+      def simpson(left, right, f_left, f_midpoint, f_right)
+        (right - left) * (f_left + (4.0 * f_midpoint) + f_right) / 6.0
+      end
+      private_class_method :simpson
+
+      def finite_value!(value)
+        numeric = Float(value)
+        return numeric if numeric.finite?
+
+        raise StatPower::DomainError, "integrand values must be finite"
+      end
+      private_class_method :finite_value!
+
+      def validate_arguments!(left, right, tolerance, max_depth)
+        unless left.finite? && right.finite? && left < right
+          raise StatPower::DomainError, "integration bounds must be finite with lower < upper"
+        end
+
+        unless tolerance.finite? && tolerance.positive?
+          raise StatPower::DomainError, "tolerance must be finite and positive"
+        end
+
+        return if max_depth.is_a?(Integer) && max_depth.positive?
+
+        raise StatPower::DomainError, "max_depth must be a positive integer"
+      end
+      private_class_method :validate_arguments!
+    end
+  end
+end

data/lib/stat_power/normal_mean.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module StatPower
+  # Power calculations for a normal mean with known variance.
+  #
+  # The parameterisation follows CRAN pwr's pwr.norm.test: exactly one of
+  # effect_size, sample_size, alpha, and power must be omitted and is solved
+  # from the remaining values.
+  module NormalMean
+    SAMPLE_SIZE_LOWER = 1.0 + 1e-10
+    SAMPLE_SIZE_UPPER = 1e9
+    PROBABILITY_EPSILON = 1e-10
+
+    EFFECT_SIZE_BOUNDS = {
+      two_sided: [1e-10, 10.0],
+      less: [-10.0, 5.0],
+      greater: [-5.0, 10.0]
+    }.freeze
+
+    module_function
+
+    # Solve one missing parameter of a normal-mean power analysis.
+    #
+    # @param effect_size [Numeric, Symbol, String, nil] standardised mean effect
+    # @param sample_size [Numeric, nil] number of observations
+    # @param alpha [Numeric, nil] Type I error probability
+    # @param power [Numeric, nil] statistical power
+    # @param alternative [Symbol, String] two_sided, less, or greater
+    # @return [StatPower::PowerResult]
+    def solve(
+      effect_size: nil,
+      sample_size: nil,
+      alpha: 0.05,
+      power: nil,
+      alternative: :two_sided
+    )
+      alternative = normalize_alternative(alternative)
+      ensure_one_missing!(effect_size, sample_size, alpha, power)
+
+      effect_size = normalize_effect_size(effect_size)
+      sample_size = optional_float(sample_size)
+      alpha = optional_float(alpha)
+      power = optional_float(power)
+
+      validate_known_values!(effect_size:, sample_size:, alpha:, power:)
+
+      effect_size, sample_size, alpha, power = solve_missing(
+        effect_size:,
+        sample_size:,
+        alpha:,
+        power:,
+        alternative:
+      )
+
+      PowerResult.new(
+        sample_size:,
+        power:,
+        effect_size:,
+        alpha:,
+        alternative:,
+        analysis_method: "normal mean with known variance"
+      )
+    end
+
+    def solve_missing(effect_size:, sample_size:, alpha:, power:, alternative:)
+      if power.nil?
+        power = power_for(effect_size:, sample_size:, alpha:, alternative:)
+      elsif effect_size.nil?
+        effect_size = solve_effect_size(sample_size:, alpha:, power:, alternative:)
+      elsif sample_size.nil?
+        sample_size = solve_sample_size(effect_size:, alpha:, power:, alternative:)
+      elsif alpha.nil?
+        alpha = solve_alpha(effect_size:, sample_size:, power:, alternative:)
+      end
+
+      [effect_size, sample_size, alpha, power]
+    end
+    private_class_method :solve_missing
+
+    def power_for(effect_size:, sample_size:, alpha:, alternative:)
+      d = alternative == :two_sided ? effect_size.abs : effect_size
+      noncentrality = d * Math.sqrt(sample_size)
+
+      case alternative
+      when :two_sided
+        critical = Distributions::Normal.quantile(1.0 - (alpha / 2.0))
+        Distributions::Normal.survival(critical - noncentrality) +
+          Distributions::Normal.cdf(-critical - noncentrality)
+      when :greater
+        critical = Distributions::Normal.quantile(1.0 - alpha)
+        Distributions::Normal.survival(critical - noncentrality)
+      when :less
+        critical = Distributions::Normal.quantile(alpha)
+        Distributions::Normal.cdf(critical - noncentrality)
+      end
+    end
+    private_class_method :power_for
+
+    def solve_effect_size(sample_size:, alpha:, power:, alternative:)
+      lower, upper = EFFECT_SIZE_BOUNDS.fetch(alternative)
+
+      Solvers::Bisection.solve(lower:, upper:) do |candidate|
+        power_for(
+          effect_size: candidate,
+          sample_size:,
+          alpha:,
+          alternative:
+        ) - power
+      end
+    end
+    private_class_method :solve_effect_size
+
+    def solve_sample_size(effect_size:, alpha:, power:, alternative:)
+      Solvers::Bisection.solve(
+        lower: SAMPLE_SIZE_LOWER,
+        upper: SAMPLE_SIZE_UPPER
+      ) do |candidate|
+        power_for(
+          effect_size:,
+          sample_size: candidate,
+          alpha:,
+          alternative:
+        ) - power
+      end
+    end
+    private_class_method :solve_sample_size
+
+    def solve_alpha(effect_size:, sample_size:, power:, alternative:)
+      Solvers::Bisection.solve(
+        lower: PROBABILITY_EPSILON,
+        upper: 1.0 - PROBABILITY_EPSILON
+      ) do |candidate|
+        power_for(
+          effect_size:,
+          sample_size:,
+          alpha: candidate,
+          alternative:
+        ) - power
+      end
+    end
+    private_class_method :solve_alpha
+
+    def ensure_one_missing!(*values)
+      return if values.count(&:nil?) == 1
+
+      raise StatPower::DomainError,
+            "exactly one of effect_size, sample_size, alpha, and power must be nil"
+    end
+    private_class_method :ensure_one_missing!
+
+    def normalize_effect_size(value)
+      return nil if value.nil?
+
+      return EffectSize::Conventional.resolve(test: :t, size: value) if value.is_a?(String) || value.is_a?(Symbol)
+
+      Float(value)
+    rescue ArgumentError, TypeError
+      raise StatPower::DomainError, "effect_size must be numeric or a conventional size"
+    end
+    private_class_method :normalize_effect_size
+
+    def optional_float(value)
+      value.nil? ? nil : Float(value)
+    rescue ArgumentError, TypeError
+      raise StatPower::DomainError, "numeric parameters must be coercible to Float"
+    end
+    private_class_method :optional_float
+
+    def normalize_alternative(value)
+      normalized = value.to_s.tr(".-", "_").to_sym
+      return normalized if EFFECT_SIZE_BOUNDS.key?(normalized)
+
+      raise StatPower::DomainError, "alternative must be two_sided, less, or greater"
+    end
+    private_class_method :normalize_alternative
+
+    def validate_known_values!(effect_size:, sample_size:, alpha:, power:)
+      validate_finite!("effect_size", effect_size) if effect_size
+      validate_sample_size!(sample_size) if sample_size
+      validate_probability!("alpha", alpha) if alpha
+      validate_probability!("power", power) if power
+    end
+    private_class_method :validate_known_values!
+
+    def validate_finite!(name, value)
+      return if value.finite?
+
+      raise StatPower::DomainError, "#{name} must be finite"
+    end
+    private_class_method :validate_finite!
+
+    def validate_sample_size!(sample_size)
+      return if sample_size.finite? && sample_size >= 1.0
+
+      raise StatPower::DomainError, "sample_size must be finite and at least 1"
+    end
+    private_class_method :validate_sample_size!
+
+    def validate_probability!(name, value)
+      return if value.finite? && value.positive? && value < 1.0
+
+      raise StatPower::DomainError, "#{name} must lie strictly between 0 and 1"
+    end
+    private_class_method :validate_probability!
+  end
+end

data/lib/stat_power/power_result.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module StatPower
+  # Immutable result returned by power-analysis solvers.
+  PowerResult = Data.define(
+    :sample_size,
+    :power,
+    :effect_size,
+    :alpha,
+    :alternative,
+    :analysis_method
+  ) do
+    # Smallest integer sample size that is at least the continuous solution.
+    #
+    # @return [Integer]
+    def required_sample_size
+      sample_size.ceil
+    end
+  end
+end