stat_power 0.1.0.alpha.1

data/lib/stat_power/proportion.rb

@@ -0,0 +1,460 @@
+# frozen_string_literal: true
+
+module StatPower
+  # Power analysis for one- and two-sample proportions using Cohen's arcsine
+  # transformation. These methods target CRAN pwr.p.test and pwr.2p.test.
+  module Proportion
+    SAMPLE_SIZE_LOWER = 2.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
+
+    # Power analysis for one proportion.
+    #
+    # Exactly one of effect_size, sample_size, alpha, and power must be nil.
+    #
+    # @return [StatPower::PowerResult]
+    def one_sample(
+      effect_size: nil,
+      sample_size: nil,
+      alpha: 0.05,
+      power: nil,
+      alternative: :two_sided
+    )
+      solve(
+        effect_size:,
+        sample_size:,
+        alpha:,
+        power:,
+        alternative:,
+        information_factor: 1.0,
+        analysis_method: "proportion power calculation for binomial distribution (arcsine transformation)"
+      )
+    end
+
+    # Power analysis for two proportions with equal sample sizes.
+    #
+    # sample_size is the number of observations in each group.
+    # Exactly one of effect_size, sample_size, alpha, and power must be nil.
+    #
+    # @return [StatPower::PowerResult]
+    def two_sample(
+      effect_size: nil,
+      sample_size: nil,
+      alpha: 0.05,
+      power: nil,
+      alternative: :two_sided
+    )
+      solve(
+        effect_size:,
+        sample_size:,
+        alpha:,
+        power:,
+        alternative:,
+        information_factor: 0.5,
+        analysis_method: "difference of proportion power calculation for binomial distribution (arcsine transformation)"
+      )
+    end
+
+    # Power analysis for two proportions with unequal sample sizes.
+    #
+    # Exactly one of effect_size, sample_size1, sample_size2, alpha, and power
+    # must be nil.
+    #
+    # @return [StatPower::UnequalPowerResult]
+    def two_sample_unequal(
+      effect_size: nil,
+      sample_size1: nil,
+      sample_size2: nil,
+      alpha: 0.05,
+      power: nil,
+      alternative: :two_sided
+    )
+      ensure_one_missing!(effect_size, sample_size1, sample_size2, alpha, power)
+
+      alternative = normalize_alternative(alternative)
+      effect_size = normalize_effect_size(effect_size)
+      sample_size1 = optional_float(sample_size1)
+      sample_size2 = optional_float(sample_size2)
+      alpha = optional_float(alpha)
+      power = optional_float(power)
+
+      validate_unequal_known_values!(
+        effect_size:,
+        sample_size1:,
+        sample_size2:,
+        alpha:,
+        power:
+      )
+
+      effect_size, sample_size1, sample_size2, alpha, power =
+        solve_unequal_missing(
+          effect_size:,
+          sample_size1:,
+          sample_size2:,
+          alpha:,
+          power:,
+          alternative:
+        )
+
+      UnequalPowerResult.new(
+        sample_size1:,
+        sample_size2:,
+        power:,
+        effect_size:,
+        alpha:,
+        alternative:,
+        analysis_method: "difference of proportion power calculation for unequal sample sizes"
+      )
+    end
+
+    def solve_unequal_missing(
+      effect_size:,
+      sample_size1:,
+      sample_size2:,
+      alpha:,
+      power:,
+      alternative:
+    )
+      if power.nil?
+        power = unequal_power_for(
+          effect_size:,
+          sample_size1:,
+          sample_size2:,
+          alpha:,
+          alternative:
+        )
+      elsif effect_size.nil?
+        effect_size = solve_unequal_effect_size(
+          sample_size1:,
+          sample_size2:,
+          alpha:,
+          power:,
+          alternative:
+        )
+      elsif sample_size1.nil?
+        sample_size1 = solve_unequal_sample_size(
+          fixed_sample_size: sample_size2,
+          effect_size:,
+          alpha:,
+          power:,
+          alternative:
+        )
+      elsif sample_size2.nil?
+        sample_size2 = solve_unequal_sample_size(
+          fixed_sample_size: sample_size1,
+          effect_size:,
+          alpha:,
+          power:,
+          alternative:
+        )
+      elsif alpha.nil?
+        alpha = solve_unequal_alpha(
+          effect_size:,
+          sample_size1:,
+          sample_size2:,
+          power:,
+          alternative:
+        )
+      end
+
+      [effect_size, sample_size1, sample_size2, alpha, power]
+    end
+    private_class_method :solve_unequal_missing
+
+    def unequal_power_for(effect_size:, sample_size1:, sample_size2:, alpha:, alternative:)
+      effect = alternative == :two_sided ? effect_size.abs : effect_size
+      information = (sample_size1 * sample_size2) / (sample_size1 + sample_size2)
+      noncentrality = effect * Math.sqrt(information)
+
+      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 :unequal_power_for
+
+    def solve_unequal_effect_size(sample_size1:, sample_size2:, alpha:, power:, alternative:)
+      lower, upper = EFFECT_SIZE_BOUNDS.fetch(alternative)
+
+      Solvers::Bisection.solve(lower:, upper:) do |candidate|
+        unequal_power_for(
+          effect_size: candidate,
+          sample_size1:,
+          sample_size2:,
+          alpha:,
+          alternative:
+        ) - power
+      end
+    end
+    private_class_method :solve_unequal_effect_size
+
+    def solve_unequal_sample_size(fixed_sample_size:, effect_size:, alpha:, power:, alternative:)
+      Solvers::Bisection.solve(
+        lower: SAMPLE_SIZE_LOWER,
+        upper: SAMPLE_SIZE_UPPER
+      ) do |candidate|
+        unequal_power_for(
+          effect_size:,
+          sample_size1: fixed_sample_size,
+          sample_size2: candidate,
+          alpha:,
+          alternative:
+        ) - power
+      end
+    end
+    private_class_method :solve_unequal_sample_size
+
+    def solve_unequal_alpha(effect_size:, sample_size1:, sample_size2:, power:, alternative:)
+      Solvers::Bisection.solve(
+        lower: PROBABILITY_EPSILON,
+        upper: 1.0 - PROBABILITY_EPSILON
+      ) do |candidate|
+        unequal_power_for(
+          effect_size:,
+          sample_size1:,
+          sample_size2:,
+          alpha: candidate,
+          alternative:
+        ) - power
+      end
+    end
+    private_class_method :solve_unequal_alpha
+
+    def solve(effect_size:, sample_size:, alpha:, power:, alternative:, information_factor:, analysis_method:)
+      ensure_one_missing!(effect_size, sample_size, alpha, power)
+
+      alternative = normalize_alternative(alternative)
+      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:,
+        information_factor:
+      )
+
+      PowerResult.new(
+        sample_size:,
+        power:,
+        effect_size:,
+        alpha:,
+        alternative:,
+        analysis_method:
+      )
+    end
+    private_class_method :solve
+
+    def solve_missing(effect_size:, sample_size:, alpha:, power:, alternative:, information_factor:)
+      if power.nil?
+        power = power_for(
+          effect_size:,
+          sample_size:,
+          alpha:,
+          alternative:,
+          information_factor:
+        )
+      elsif effect_size.nil?
+        effect_size = solve_effect_size(
+          sample_size:,
+          alpha:,
+          power:,
+          alternative:,
+          information_factor:
+        )
+      elsif sample_size.nil?
+        sample_size = solve_sample_size(
+          effect_size:,
+          alpha:,
+          power:,
+          alternative:,
+          information_factor:
+        )
+      elsif alpha.nil?
+        alpha = solve_alpha(
+          effect_size:,
+          sample_size:,
+          power:,
+          alternative:,
+          information_factor:
+        )
+      end
+
+      [effect_size, sample_size, alpha, power]
+    end
+    private_class_method :solve_missing
+
+    def power_for(effect_size:, sample_size:, alpha:, alternative:, information_factor:)
+      effect = alternative == :two_sided ? effect_size.abs : effect_size
+      noncentrality = effect * Math.sqrt(sample_size * information_factor)
+
+      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:, information_factor:)
+      lower, upper = EFFECT_SIZE_BOUNDS.fetch(alternative)
+
+      Solvers::Bisection.solve(lower:, upper:) do |candidate|
+        power_for(
+          effect_size: candidate,
+          sample_size:,
+          alpha:,
+          alternative:,
+          information_factor:
+        ) - power
+      end
+    end
+    private_class_method :solve_effect_size
+
+    def solve_sample_size(effect_size:, alpha:, power:, alternative:, information_factor:)
+      Solvers::Bisection.solve(
+        lower: SAMPLE_SIZE_LOWER,
+        upper: SAMPLE_SIZE_UPPER
+      ) do |candidate|
+        power_for(
+          effect_size:,
+          sample_size: candidate,
+          alpha:,
+          alternative:,
+          information_factor:
+        ) - power
+      end
+    end
+    private_class_method :solve_sample_size
+
+    def solve_alpha(effect_size:, sample_size:, power:, alternative:, information_factor:)
+      Solvers::Bisection.solve(
+        lower: PROBABILITY_EPSILON,
+        upper: 1.0 - PROBABILITY_EPSILON
+      ) do |candidate|
+        power_for(
+          effect_size:,
+          sample_size:,
+          alpha: candidate,
+          alternative:,
+          information_factor:
+        ) - 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: :p, 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_unequal_known_values!(
+      effect_size:,
+      sample_size1:,
+      sample_size2:,
+      alpha:,
+      power:
+    )
+      validate_finite!("effect_size", effect_size) if effect_size
+      validate_group_size!("sample_size1", sample_size1) if sample_size1
+      validate_group_size!("sample_size2", sample_size2) if sample_size2
+      validate_probability!("alpha", alpha) if alpha
+      validate_probability!("power", power) if power
+    end
+    private_class_method :validate_unequal_known_values!
+
+    def validate_group_size!(name, sample_size)
+      return if sample_size.finite? && sample_size >= 2.0
+
+      raise StatPower::DomainError, "#{name} must be finite and at least 2"
+    end
+    private_class_method :validate_group_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/result.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module StatPower
+  # Immutable container for a solved power-analysis quantity.
+  Result = Data.define(:sample_size, :power, :effect_size, :alpha)
+end

data/lib/stat_power/solvers/bisection.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module StatPower
+  module Solvers
+    # Deterministic bracketed root finding using the bisection method.
+    module Bisection
+      DEFAULT_ABSOLUTE_TOLERANCE = 1e-10
+      DEFAULT_RELATIVE_TOLERANCE = 1e-10
+      DEFAULT_MAX_ITERATIONS = 256
+
+      module_function
+
+      # Solve f(x) = 0 on a bracket [lower, upper].
+      #
+      # The function values at the endpoints must have opposite signs unless
+      # one endpoint is itself a root.
+      #
+      # @param lower [Numeric] lower bracket endpoint
+      # @param upper [Numeric] upper bracket endpoint
+      # @param absolute_tolerance [Float] absolute interval tolerance
+      # @param relative_tolerance [Float] relative interval tolerance
+      # @param max_iterations [Integer] maximum number of bisection iterations
+      # @yieldparam x [Float] point at which the function is evaluated
+      # @yieldreturn [Numeric] function value
+      # @return [Float] approximate root
+      # @raise [StatPower::DomainError] for an invalid bracket or arguments
+      # @raise [StatPower::ConvergenceError] if convergence is not reached
+      def solve(
+        lower:,
+        upper:,
+        absolute_tolerance: DEFAULT_ABSOLUTE_TOLERANCE,
+        relative_tolerance: DEFAULT_RELATIVE_TOLERANCE,
+        max_iterations: DEFAULT_MAX_ITERATIONS,
+        &function
+      )
+        raise ArgumentError, "a function block is required" unless function
+
+        left = Float(lower)
+        right = Float(upper)
+        abs_tol = Float(absolute_tolerance)
+        rel_tol = Float(relative_tolerance)
+
+        validate_arguments!(
+          left: left,
+          right: right,
+          absolute_tolerance: abs_tol,
+          relative_tolerance: rel_tol,
+          max_iterations: max_iterations
+        )
+
+        f_left = finite_function_value!(function.call(left))
+        f_right = finite_function_value!(function.call(right))
+
+        return left if f_left.zero?
+        return right if f_right.zero?
+
+        unless opposite_signs?(f_left, f_right)
+          raise StatPower::DomainError, "root is not bracketed by the supplied interval"
+        end
+
+        max_iterations.times do
+          midpoint = left + ((right - left) / 2.0)
+          f_midpoint = finite_function_value!(function.call(midpoint))
+
+          return midpoint if f_midpoint.zero? || converged?(left, right, midpoint, abs_tol, rel_tol)
+          return midpoint if midpoint == left || midpoint == right
+
+          if opposite_signs?(f_left, f_midpoint)
+            right = midpoint
+            f_right = f_midpoint
+          else
+            left = midpoint
+            f_left = f_midpoint
+          end
+        end
+
+        raise StatPower::ConvergenceError,
+              "bisection did not converge within #{max_iterations} iterations"
+      end
+
+      def validate_arguments!(left:, right:, absolute_tolerance:, relative_tolerance:, max_iterations:)
+        unless left.finite? && right.finite? && left < right
+          raise StatPower::DomainError, "lower and upper must be finite with lower < upper"
+        end
+
+        unless absolute_tolerance.finite? && absolute_tolerance.positive?
+          raise StatPower::DomainError, "absolute_tolerance must be finite and positive"
+        end
+
+        unless relative_tolerance.finite? && relative_tolerance >= 0.0
+          raise StatPower::DomainError, "relative_tolerance must be finite and non-negative"
+        end
+
+        return if max_iterations.is_a?(Integer) && max_iterations.positive?
+
+        raise StatPower::DomainError, "max_iterations must be a positive integer"
+      end
+      private_class_method :validate_arguments!
+
+      def finite_function_value!(value)
+        numeric_value = Float(value)
+        return numeric_value if numeric_value.finite?
+
+        raise StatPower::DomainError, "function values must be finite"
+      end
+      private_class_method :finite_function_value!
+
+      def opposite_signs?(left, right)
+        left.negative? != right.negative?
+      end
+      private_class_method :opposite_signs?
+
+      def converged?(left, right, midpoint, absolute_tolerance, relative_tolerance)
+        width = right - left
+        scale = [midpoint.abs, 1.0].max
+        width <= [absolute_tolerance, relative_tolerance * scale].max
+      end
+      private_class_method :converged?
+    end
+  end
+end

data/lib/stat_power/special_functions/beta.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module StatPower
+  module SpecialFunctions
+    # Numerical utilities for the beta function.
+    module Beta
+      MAX_ITERATIONS = 256
+      EPSILON = 3e-14
+      MIN_DENOMINATOR = 1e-300
+
+      module_function
+
+      # Regularized incomplete beta I_x(a, b).
+      #
+      # @param x [Numeric] integration limit in [0, 1]
+      # @param a [Numeric] first positive shape parameter
+      # @param b [Numeric] second positive shape parameter
+      # @return [Float]
+      def regularized(x, a:, b:)
+        value = Float(x)
+        shape_a = Float(a)
+        shape_b = Float(b)
+        validate_arguments!(value, shape_a, shape_b)
+
+        return 0.0 if value.zero?
+        return 1.0 if value >= 1.0
+
+        log_beta = log_gamma(shape_a) + log_gamma(shape_b) - log_gamma(shape_a + shape_b)
+        front = Math.exp(
+          (shape_a * Math.log(value)) +
+          (shape_b * Math.log(1.0 - value)) -
+          log_beta
+        )
+
+        threshold = (shape_a + 1.0) / (shape_a + shape_b + 2.0)
+        if value < threshold
+          front * continued_fraction(shape_a, shape_b, value) / shape_a
+        else
+          1.0 - (front * continued_fraction(shape_b, shape_a, 1.0 - value) / shape_b)
+        end
+      end
+
+      def continued_fraction(a, b, x)
+        qab = a + b
+        qap = a + 1.0
+        qam = a - 1.0
+
+        c = 1.0
+        d = stabilize(1.0 - (qab * x / qap))
+        d = 1.0 / d
+        result = d
+
+        1.upto(MAX_ITERATIONS) do |iteration|
+          doubled = 2.0 * iteration
+          first = iteration * (b - iteration) * x /
+                  ((qam + doubled) * (a + doubled))
+
+          d = 1.0 / stabilize(1.0 + (first * d))
+          c = stabilize(1.0 + (first / c))
+          result *= d * c
+
+          second = -(a + iteration) * (qab + iteration) * x /
+                   ((a + doubled) * (qap + doubled))
+
+          d = 1.0 / stabilize(1.0 + (second * d))
+          c = stabilize(1.0 + (second / c))
+          delta = d * c
+          result *= delta
+
+          return result if (delta - 1.0).abs <= EPSILON
+        end
+
+        raise StatPower::ConvergenceError,
+              "incomplete beta continued fraction did not converge"
+      end
+      private_class_method :continued_fraction
+
+      def stabilize(value)
+        return value if value.abs >= MIN_DENOMINATOR
+
+        value.negative? ? -MIN_DENOMINATOR : MIN_DENOMINATOR
+      end
+      private_class_method :stabilize
+
+      def validate_arguments!(x, a, b)
+        raise StatPower::DomainError, "x must be finite and lie in [0, 1]" unless x.finite? && x.between?(0.0, 1.0)
+
+        return if a.finite? && b.finite? && a.positive? && b.positive?
+
+        raise StatPower::DomainError, "beta shape parameters must be finite and positive"
+      end
+      private_class_method :validate_arguments!
+
+      def log_gamma(value)
+        Math.lgamma(value).first
+      end
+      private_class_method :log_gamma
+    end
+  end
+end