stat_power 0.1.0.alpha.1

data/lib/stat_power/correlation.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+module StatPower
+  # Power analysis for tests of a Pearson correlation coefficient.
+  #
+  # The statistical parameterisation follows CRAN pwr.r.test, including the
+  # Fisher z transform and the package's bias correction convention.
+  module Correlation
+    SAMPLE_SIZE_LOWER = 4.0 + 1e-10
+    SAMPLE_SIZE_UPPER = 1e9
+    PROBABILITY_EPSILON = 1e-10
+    CORRELATION_EPSILON = 1e-10
+
+    CORRELATION_BOUNDS = {
+      two_sided: [CORRELATION_EPSILON, 1.0 - CORRELATION_EPSILON],
+      less: [-1.0 + CORRELATION_EPSILON, 1.0 - CORRELATION_EPSILON],
+      greater: [-1.0 + CORRELATION_EPSILON, 1.0 - CORRELATION_EPSILON]
+    }.freeze
+
+    module_function
+
+    # Solve one missing parameter of a correlation power analysis.
+    #
+    # Exactly one of correlation, sample_size, alpha, and power must be nil.
+    #
+    # @param correlation [Numeric, Symbol, String, nil] hypothesized Pearson r
+    # @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(
+      correlation: nil,
+      sample_size: nil,
+      alpha: 0.05,
+      power: nil,
+      alternative: :two_sided
+    )
+      ensure_one_missing!(correlation, sample_size, alpha, power)
+
+      alternative = normalize_alternative(alternative)
+      correlation = normalize_correlation(correlation)
+      correlation = correlation.abs if alternative == :two_sided && correlation
+      sample_size = optional_float(sample_size)
+      alpha = optional_float(alpha)
+      power = optional_float(power)
+
+      validate_known_values!(
+        correlation:,
+        sample_size:,
+        alpha:,
+        power:
+      )
+
+      correlation, sample_size, alpha, power = solve_missing(
+        correlation:,
+        sample_size:,
+        alpha:,
+        power:,
+        alternative:
+      )
+
+      PowerResult.new(
+        sample_size:,
+        power:,
+        effect_size: correlation,
+        alpha:,
+        alternative:,
+        analysis_method: "approximate correlation power calculation (Fisher z transformation)"
+      )
+    end
+
+    def solve_missing(correlation:, sample_size:, alpha:, power:, alternative:)
+      if power.nil?
+        power = power_for(
+          correlation:,
+          sample_size:,
+          alpha:,
+          alternative:
+        )
+      elsif correlation.nil?
+        correlation = solve_correlation(
+          sample_size:,
+          alpha:,
+          power:,
+          alternative:
+        )
+      elsif sample_size.nil?
+        sample_size = solve_sample_size(
+          correlation:,
+          alpha:,
+          power:,
+          alternative:
+        )
+      elsif alpha.nil?
+        alpha = solve_alpha(
+          correlation:,
+          sample_size:,
+          power:,
+          alternative:
+        )
+      end
+
+      [correlation, sample_size, alpha, power]
+    end
+    private_class_method :solve_missing
+
+    def power_for(correlation:, sample_size:, alpha:, alternative:)
+      effective_correlation = alternative == :less ? -correlation : correlation
+      effective_correlation = effective_correlation.abs if alternative == :two_sided
+
+      critical_tail = alternative == :two_sided ? alpha / 2.0 : alpha
+      degrees_of_freedom = sample_size - 2.0
+      critical_t = Distributions::StudentT.quantile(
+        1.0 - critical_tail,
+        degrees_of_freedom:
+      )
+      critical_r = Math.sqrt(
+        (critical_t * critical_t) /
+        ((critical_t * critical_t) + degrees_of_freedom)
+      )
+
+      transformed_r = Math.atanh(effective_correlation) +
+                      (effective_correlation / (2.0 * (sample_size - 1.0)))
+      transformed_critical = Math.atanh(critical_r)
+      scale = Math.sqrt(sample_size - 3.0)
+
+      first_tail = Distributions::Normal.cdf(
+        (transformed_r - transformed_critical) * scale
+      )
+      return first_tail unless alternative == :two_sided
+
+      first_tail + Distributions::Normal.cdf(
+        (-transformed_r - transformed_critical) * scale
+      )
+    end
+    private_class_method :power_for
+
+    def solve_correlation(sample_size:, alpha:, power:, alternative:)
+      lower, upper = CORRELATION_BOUNDS.fetch(alternative)
+
+      Solvers::Bisection.solve(lower:, upper:) do |candidate|
+        power_for(
+          correlation: candidate,
+          sample_size:,
+          alpha:,
+          alternative:
+        ) - power
+      end
+    end
+    private_class_method :solve_correlation
+
+    def solve_sample_size(correlation:, alpha:, power:, alternative:)
+      Solvers::Bisection.solve(
+        lower: SAMPLE_SIZE_LOWER,
+        upper: SAMPLE_SIZE_UPPER,
+        absolute_tolerance: 1e-7,
+        relative_tolerance: 1e-9
+      ) do |candidate|
+        power_for(
+          correlation:,
+          sample_size: candidate,
+          alpha:,
+          alternative:
+        ) - power
+      end
+    end
+    private_class_method :solve_sample_size
+
+    def solve_alpha(correlation:, sample_size:, power:, alternative:)
+      Solvers::Bisection.solve(
+        lower: PROBABILITY_EPSILON,
+        upper: 1.0 - PROBABILITY_EPSILON
+      ) do |candidate|
+        power_for(
+          correlation:,
+          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 correlation, sample_size, alpha, and power must be nil"
+    end
+    private_class_method :ensure_one_missing!
+
+    def normalize_correlation(value)
+      return nil if value.nil?
+      return EffectSize::Conventional.resolve(test: :r, size: value) if value.is_a?(String) || value.is_a?(Symbol)
+
+      Float(value)
+    rescue ArgumentError, TypeError
+      raise StatPower::DomainError, "correlation must be numeric or a conventional size"
+    end
+    private_class_method :normalize_correlation
+
+    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 CORRELATION_BOUNDS.key?(normalized)
+
+      raise StatPower::DomainError, "alternative must be two_sided, less, or greater"
+    end
+    private_class_method :normalize_alternative
+
+    def validate_known_values!(correlation:, sample_size:, alpha:, power:)
+      validate_correlation!(correlation) if correlation
+      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_correlation!(correlation)
+      return if correlation.finite? && correlation > -1.0 && correlation < 1.0
+
+      raise StatPower::DomainError, "correlation must be finite and lie strictly between -1 and 1"
+    end
+    private_class_method :validate_correlation!
+
+    def validate_sample_size!(sample_size)
+      return if sample_size.finite? && sample_size >= 4.0
+
+      raise StatPower::DomainError, "sample_size must be finite and at least 4"
+    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/distributions/f_distribution.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module StatPower
+  module Distributions
+    # Central Fisher-Snedecor F distribution utilities.
+    module FDistribution
+      module_function
+
+      # Probability density function.
+      #
+      # @param x [Numeric] evaluation point
+      # @param numerator_df [Numeric] positive numerator degrees of freedom
+      # @param denominator_df [Numeric] positive denominator degrees of freedom
+      # @return [Float]
+      def pdf(x, numerator_df:, denominator_df:)
+        value = Float(x)
+        numerator = normalize_df(numerator_df, "numerator_df")
+        denominator = normalize_df(denominator_df, "denominator_df")
+        raise StatPower::DomainError, "x must be finite" unless value.finite?
+        return 0.0 if value.negative?
+
+        if value.zero?
+          return Float::INFINITY if numerator < 2.0
+          return 1.0 if (numerator - 2.0).abs <= Float::EPSILON
+
+          return 0.0
+        end
+
+        shape_a = numerator / 2.0
+        shape_b = denominator / 2.0
+        ratio = numerator / denominator
+        log_beta = Math.lgamma(shape_a).first +
+                   Math.lgamma(shape_b).first -
+                   Math.lgamma(shape_a + shape_b).first
+
+        log_density = (shape_a * Math.log(ratio)) +
+                      ((shape_a - 1.0) * Math.log(value)) -
+                      log_beta -
+                      ((shape_a + shape_b) * Math.log(1.0 + (ratio * value)))
+
+        Math.exp(log_density)
+      end
+
+      # Cumulative distribution function.
+      #
+      # @return [Float]
+      def cdf(x, numerator_df:, denominator_df:)
+        value = Float(x)
+        numerator = normalize_df(numerator_df, "numerator_df")
+        denominator = normalize_df(denominator_df, "denominator_df")
+        raise StatPower::DomainError, "x must be finite" unless value.finite?
+        return 0.0 if value <= 0.0
+
+        transformed = beta_argument(value, numerator, denominator)
+        SpecialFunctions::Beta.regularized(
+          transformed,
+          a: numerator / 2.0,
+          b: denominator / 2.0
+        )
+      end
+
+      # Survival function P(F > x), using the complementary beta form.
+      #
+      # @return [Float]
+      def survival(x, numerator_df:, denominator_df:)
+        value = Float(x)
+        numerator = normalize_df(numerator_df, "numerator_df")
+        denominator = normalize_df(denominator_df, "denominator_df")
+        raise StatPower::DomainError, "x must be finite" unless value.finite?
+        return 1.0 if value <= 0.0
+
+        transformed = beta_argument(value, numerator, denominator)
+        SpecialFunctions::Beta.regularized(
+          1.0 - transformed,
+          a: denominator / 2.0,
+          b: numerator / 2.0
+        )
+      end
+
+      # Quantile function.
+      #
+      # @return [Float]
+      def quantile(probability, numerator_df:, denominator_df:)
+        target = Float(probability)
+        validate_probability!(target)
+        numerator = normalize_df(numerator_df, "numerator_df")
+        denominator = normalize_df(denominator_df, "denominator_df")
+
+        return 0.0 if target.zero?
+        return Float::INFINITY if target >= 1.0
+
+        upper = quantile_upper_bound(target, numerator, denominator)
+
+        Solvers::Bisection.solve(lower: 0.0, upper:) do |candidate|
+          cdf(
+            candidate,
+            numerator_df: numerator,
+            denominator_df: denominator
+          ) - target
+        end
+      end
+
+      def quantile_upper_bound(target, numerator, denominator)
+        upper = 1.0
+
+        while cdf(upper, numerator_df: numerator, denominator_df: denominator) < target
+          upper *= 2.0
+          if upper > 1e15
+            raise StatPower::ConvergenceError,
+                  "unable to bracket F quantile"
+          end
+        end
+
+        upper
+      end
+      private_class_method :quantile_upper_bound
+
+      def beta_argument(value, numerator, denominator)
+        numerator * value / ((numerator * value) + denominator)
+      end
+      private_class_method :beta_argument
+
+      def normalize_df(value, name)
+        degrees = Float(value)
+        return degrees if degrees.finite? && degrees.positive?
+
+        raise StatPower::DomainError, "#{name} must be finite and positive"
+      rescue ArgumentError, TypeError
+        raise StatPower::DomainError, "#{name} must be numeric"
+      end
+      private_class_method :normalize_df
+
+      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!
+    end
+  end
+end

data/lib/stat_power/distributions/noncentral_f.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+module StatPower
+  module Distributions
+    # Noncentral Fisher-Snedecor F distribution utilities.
+    #
+    # The CDF and survival function are evaluated with the standard Poisson
+    # mixture of regularized incomplete-beta probabilities.
+    module NoncentralF
+      MIXTURE_TOLERANCE = 1e-13
+      MAX_MIXTURE_STEPS = 100_000
+
+      module_function
+
+      # Cumulative distribution function.
+      #
+      # @return [Float]
+      def cdf(x, numerator_df:, denominator_df:, noncentrality:)
+        mixture_probability(
+          x,
+          numerator_df:,
+          denominator_df:,
+          noncentrality:,
+          tail: :cdf
+        )
+      end
+
+      # Survival function P(F > x).
+      #
+      # @return [Float]
+      def survival(x, numerator_df:, denominator_df:, noncentrality:)
+        mixture_probability(
+          x,
+          numerator_df:,
+          denominator_df:,
+          noncentrality:,
+          tail: :survival
+        )
+      end
+
+      def mixture_probability(x, numerator_df:, denominator_df:, noncentrality:, tail:)
+        value = Float(x)
+        numerator = normalize_df(numerator_df, "numerator_df")
+        denominator = normalize_df(denominator_df, "denominator_df")
+        lambda = normalize_noncentrality(noncentrality)
+        raise StatPower::DomainError, "x must be finite" unless value.finite?
+
+        return boundary_probability(value, tail) if value <= 0.0
+        return central_probability(value, numerator, denominator, tail) if lambda.zero?
+
+        transformed = numerator * value / ((numerator * value) + denominator)
+        poisson_mean = lambda / 2.0
+        shape_a = numerator / 2.0
+        shape_b = denominator / 2.0
+
+        poisson_beta_mixture(
+          poisson_mean:,
+          transformed:,
+          shape_a:,
+          shape_b:,
+          tail:
+        )
+      end
+      private_class_method :mixture_probability
+
+      def poisson_beta_mixture(poisson_mean:, transformed:, shape_a:, shape_b:, tail:)
+        mode = poisson_mean.floor.to_i
+        mode_weight = Math.exp(
+          -poisson_mean +
+          (mode * Math.log(poisson_mean)) -
+          Math.lgamma(mode + 1.0).first
+        )
+
+        total = mode_weight * beta_term(
+          transformed,
+          shape_a + mode,
+          shape_b,
+          tail
+        )
+        weight_sum = mode_weight
+
+        lower_index = mode
+        lower_weight = mode_weight
+        upper_index = mode
+        upper_weight = mode_weight
+
+        1.upto(MAX_MIXTURE_STEPS) do
+          lower_weight, lower_index, lower_term = lower_step(
+            lower_weight,
+            lower_index,
+            poisson_mean,
+            transformed,
+            shape_a,
+            shape_b,
+            tail
+          )
+          upper_weight, upper_index, upper_term = upper_step(
+            upper_weight,
+            upper_index,
+            poisson_mean,
+            transformed,
+            shape_a,
+            shape_b,
+            tail
+          )
+
+          total += lower_term + upper_term
+          weight_sum += lower_weight + upper_weight
+
+          break if mixture_converged?(weight_sum, lower_weight, upper_weight)
+        end
+
+        [[total, 0.0].max, 1.0].min
+      end
+      private_class_method :poisson_beta_mixture
+
+      def lower_step(weight, index, poisson_mean, transformed, shape_a, shape_b, tail)
+        return [0.0, index, 0.0] if index.zero?
+
+        next_weight = weight * index / poisson_mean
+        next_index = index - 1
+        term = next_weight * beta_term(
+          transformed,
+          shape_a + next_index,
+          shape_b,
+          tail
+        )
+
+        [next_weight, next_index, term]
+      end
+      private_class_method :lower_step
+
+      def upper_step(weight, index, poisson_mean, transformed, shape_a, shape_b, tail)
+        next_index = index + 1
+        next_weight = weight * poisson_mean / next_index
+        term = next_weight * beta_term(
+          transformed,
+          shape_a + next_index,
+          shape_b,
+          tail
+        )
+
+        [next_weight, next_index, term]
+      end
+      private_class_method :upper_step
+
+      def beta_term(transformed, shape_a, shape_b, tail)
+        if tail == :cdf
+          SpecialFunctions::Beta.regularized(
+            transformed,
+            a: shape_a,
+            b: shape_b
+          )
+        else
+          SpecialFunctions::Beta.regularized(
+            1.0 - transformed,
+            a: shape_b,
+            b: shape_a
+          )
+        end
+      end
+      private_class_method :beta_term
+
+      def mixture_converged?(weight_sum, lower_weight, upper_weight)
+        residual = (1.0 - weight_sum).abs
+        residual <= MIXTURE_TOLERANCE &&
+          lower_weight <= MIXTURE_TOLERANCE &&
+          upper_weight <= MIXTURE_TOLERANCE
+      end
+      private_class_method :mixture_converged?
+
+      def boundary_probability(value, tail)
+        return tail == :cdf ? 0.0 : 1.0 if value <= 0.0
+
+        raise StatPower::DomainError, "unreachable boundary state"
+      end
+      private_class_method :boundary_probability
+
+      def central_probability(value, numerator, denominator, tail)
+        if tail == :cdf
+          FDistribution.cdf(
+            value,
+            numerator_df: numerator,
+            denominator_df: denominator
+          )
+        else
+          FDistribution.survival(
+            value,
+            numerator_df: numerator,
+            denominator_df: denominator
+          )
+        end
+      end
+      private_class_method :central_probability
+
+      def normalize_df(value, name)
+        degrees = Float(value)
+        return degrees if degrees.finite? && degrees.positive?
+
+        raise StatPower::DomainError, "#{name} must be finite and positive"
+      rescue ArgumentError, TypeError
+        raise StatPower::DomainError, "#{name} must be numeric"
+      end
+      private_class_method :normalize_df
+
+      def normalize_noncentrality(value)
+        lambda = Float(value)
+        return lambda if lambda.finite? && !lambda.negative?
+
+        raise StatPower::DomainError, "noncentrality must be finite and non-negative"
+      rescue ArgumentError, TypeError
+        raise StatPower::DomainError, "noncentrality must be numeric"
+      end
+      private_class_method :normalize_noncentrality
+    end
+  end
+end

data/lib/stat_power/distributions/noncentral_t.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module StatPower
+  module Distributions
+    # Noncentral Student t distribution utilities.
+    #
+    # The CDF is evaluated from the defining normal/chi-square mixture using
+    # adaptive quadrature on the logarithm of the chi-square variate.
+    module NoncentralT
+      LOG_WEIGHT_UNDERFLOW = -745.0
+
+      module_function
+
+      # Cumulative distribution function.
+      #
+      # @param x [Numeric] evaluation point
+      # @param degrees_of_freedom [Numeric] positive degrees of freedom
+      # @param noncentrality [Numeric] noncentrality parameter
+      # @return [Float]
+      def cdf(x, degrees_of_freedom:, noncentrality:)
+        value = Float(x)
+        df = normalize_degrees_of_freedom(degrees_of_freedom)
+        delta = Float(noncentrality)
+        validate_noncentrality!(delta)
+
+        return StudentT.cdf(value, degrees_of_freedom: df) if delta.zero?
+        return Normal.cdf(value - delta) if df.infinite?
+        return Normal.cdf(-delta) if value.zero?
+
+        shape = df / 2.0
+        center = Math.log(df)
+        half_width = [8.0, 30.0 * Math.sqrt(2.0 / df)].max
+        log_normalizer = -(shape * Math.log(2.0)) - Math.lgamma(shape).first
+
+        result = Integration::AdaptiveSimpson.integrate(
+          lower: center - half_width,
+          upper: center + half_width,
+          tolerance: 1e-10,
+          max_depth: 30
+        ) do |log_variance|
+          mixture_integrand(
+            log_variance,
+            value:,
+            df:,
+            delta:,
+            shape:,
+            log_normalizer:
+          )
+        end
+
+        [[result, 0.0].max, 1.0].min
+      end
+
+      # Survival function P(T > x).
+      #
+      # Uses the identity P(T_delta > x) = F_{-delta}(-x).
+      #
+      # @param x [Numeric] evaluation point
+      # @param degrees_of_freedom [Numeric] positive degrees of freedom
+      # @param noncentrality [Numeric] noncentrality parameter
+      # @return [Float]
+      def survival(x, degrees_of_freedom:, noncentrality:)
+        cdf(
+          -Float(x),
+          degrees_of_freedom:,
+          noncentrality: -Float(noncentrality)
+        )
+      end
+
+      def mixture_integrand(log_variance, value:, df:, delta:, shape:, log_normalizer:)
+        variance = Math.exp(log_variance)
+        log_weight = (shape * log_variance) -
+                     (variance / 2.0) +
+                     log_normalizer
+        return 0.0 if log_weight < LOG_WEIGHT_UNDERFLOW
+
+        conditional = Normal.cdf(
+          (value * Math.sqrt(variance / df)) - delta
+        )
+        conditional * Math.exp(log_weight)
+      end
+      private_class_method :mixture_integrand
+
+      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_noncentrality!(value)
+        return if value.finite?
+
+        raise StatPower::DomainError, "noncentrality must be finite"
+      end
+      private_class_method :validate_noncentrality!
+    end
+  end
+end