stat_power 0.1.0.alpha.1 → 0.1.0.alpha.2

data/lib/stat_power/chi_square.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+module StatPower
+  # Power analysis for chi-square tests using Cohen's w.
+  #
+  # The statistical parameterisation follows CRAN pwr.chisq.test. Degrees of
+  # freedom are required; exactly one of effect_size, sample_size, alpha, and
+  # power must be nil.
+  module ChiSquare
+    SAMPLE_SIZE_LOWER = 1e-10
+    SAMPLE_SIZE_UPPER = 1e9
+    EFFECT_SIZE_LOWER = 1e-10
+    EFFECT_SIZE_UPPER = 10.0
+    PROBABILITY_EPSILON = 1e-10
+
+    module_function
+
+    # Solve one missing parameter of a chi-square power analysis.
+    #
+    # @param degrees_of_freedom [Numeric] positive chi-square degrees of freedom
+    # @param effect_size [Numeric, Symbol, String, nil] Cohen's w
+    # @param sample_size [Numeric, nil] total number of observations
+    # @param alpha [Numeric, nil] Type I error probability
+    # @param power [Numeric, nil] statistical power
+    # @return [StatPower::ChiSquareResult]
+    def solve(
+      degrees_of_freedom:,
+      effect_size: nil,
+      sample_size: nil,
+      alpha: 0.05,
+      power: nil
+    )
+      ensure_one_missing!(effect_size, sample_size, alpha, power)
+
+      df = Float(degrees_of_freedom)
+      effect_size = normalize_effect_size(effect_size)
+      sample_size = optional_float(sample_size)
+      alpha = optional_float(alpha)
+      power = optional_float(power)
+
+      validate_known_values!(
+        degrees_of_freedom: df,
+        effect_size:,
+        sample_size:,
+        alpha:,
+        power:
+      )
+
+      effect_size, sample_size, alpha, power = solve_missing(
+        degrees_of_freedom: df,
+        effect_size:,
+        sample_size:,
+        alpha:,
+        power:
+      )
+
+      ChiSquareResult.new(
+        degrees_of_freedom: df,
+        sample_size:,
+        power:,
+        effect_size:,
+        alpha:,
+        analysis_method: "chi-square power calculation"
+      )
+    rescue ArgumentError, TypeError
+      raise StatPower::DomainError, "degrees_of_freedom must be numeric"
+    end
+
+    def solve_missing(degrees_of_freedom:, effect_size:, sample_size:, alpha:, power:)
+      if power.nil?
+        power = power_for(
+          degrees_of_freedom:,
+          effect_size:,
+          sample_size:,
+          alpha:
+        )
+      elsif effect_size.nil?
+        effect_size = solve_effect_size(
+          degrees_of_freedom:,
+          sample_size:,
+          alpha:,
+          power:
+        )
+      elsif sample_size.nil?
+        sample_size = solve_sample_size(
+          degrees_of_freedom:,
+          effect_size:,
+          alpha:,
+          power:
+        )
+      elsif alpha.nil?
+        alpha = solve_alpha(
+          degrees_of_freedom:,
+          effect_size:,
+          sample_size:,
+          power:
+        )
+      end
+
+      [effect_size, sample_size, alpha, power]
+    end
+    private_class_method :solve_missing
+
+    def power_for(degrees_of_freedom:, effect_size:, sample_size:, alpha:)
+      noncentrality = sample_size * effect_size * effect_size
+      critical = Distributions::ChiSquare.quantile(
+        1.0 - alpha,
+        degrees_of_freedom:
+      )
+
+      Distributions::NoncentralChiSquare.survival(
+        critical,
+        degrees_of_freedom:,
+        noncentrality:
+      )
+    end
+    private_class_method :power_for
+
+    def solve_effect_size(degrees_of_freedom:, sample_size:, alpha:, power:)
+      Solvers::Bisection.solve(
+        lower: EFFECT_SIZE_LOWER,
+        upper: EFFECT_SIZE_UPPER
+      ) do |candidate|
+        power_for(
+          degrees_of_freedom:,
+          effect_size: candidate,
+          sample_size:,
+          alpha:
+        ) - power
+      end
+    end
+    private_class_method :solve_effect_size
+
+    def solve_sample_size(degrees_of_freedom:, effect_size:, alpha:, power:)
+      Solvers::Bisection.solve(
+        lower: SAMPLE_SIZE_LOWER,
+        upper: SAMPLE_SIZE_UPPER,
+        absolute_tolerance: 1e-7,
+        relative_tolerance: 1e-9
+      ) do |candidate|
+        power_for(
+          degrees_of_freedom:,
+          effect_size:,
+          sample_size: candidate,
+          alpha:
+        ) - power
+      end
+    end
+    private_class_method :solve_sample_size
+
+    def solve_alpha(degrees_of_freedom:, effect_size:, sample_size:, power:)
+      Solvers::Bisection.solve(
+        lower: PROBABILITY_EPSILON,
+        upper: 1.0 - PROBABILITY_EPSILON
+      ) do |candidate|
+        power_for(
+          degrees_of_freedom:,
+          effect_size:,
+          sample_size:,
+          alpha: candidate
+        ) - 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: :chisq, 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 validate_known_values!(degrees_of_freedom:, effect_size:, sample_size:, alpha:, power:)
+      validate_df!(degrees_of_freedom)
+      validate_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_df!(degrees_of_freedom)
+      return if degrees_of_freedom.finite? && degrees_of_freedom.positive?
+
+      raise StatPower::DomainError,
+            "degrees_of_freedom must be finite and positive"
+    end
+    private_class_method :validate_df!
+
+    def validate_effect_size!(effect_size)
+      return if effect_size.finite? && !effect_size.negative?
+
+      raise StatPower::DomainError,
+            "effect_size must be finite and non-negative"
+    end
+    private_class_method :validate_effect_size!
+
+    def validate_sample_size!(sample_size)
+      return if sample_size.finite? && sample_size.positive?
+
+      raise StatPower::DomainError,
+            "sample_size must be finite and positive"
+    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/chi_square_result.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module StatPower
+  # Immutable result for chi-square power analyses.
+  ChiSquareResult = Data.define(
+    :degrees_of_freedom,
+    :sample_size,
+    :power,
+    :effect_size,
+    :alpha,
+    :analysis_method
+  ) do
+    # Smallest whole-number total sample size not below the solution.
+    #
+    # @return [Integer]
+    def required_sample_size
+      sample_size.ceil
+    end
+  end
+end

data/lib/stat_power/distributions/chi_square.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module StatPower
+  module Distributions
+    # Central chi-square distribution utilities.
+    module ChiSquare
+      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)
+        raise StatPower::DomainError, "x must be finite" unless value.finite?
+        return 0.0 if value.negative?
+
+        if value.zero?
+          return Float::INFINITY if df < 2.0
+          return 0.5 if (df - 2.0).abs <= Float::EPSILON
+
+          return 0.0
+        end
+
+        shape = df / 2.0
+        log_density = ((shape - 1.0) * Math.log(value)) -
+                      (value / 2.0) -
+                      (shape * Math.log(2.0)) -
+                      Math.lgamma(shape).first
+
+        Math.exp(log_density)
+      end
+
+      # Cumulative distribution function.
+      #
+      # @return [Float]
+      def cdf(x, degrees_of_freedom:)
+        value = Float(x)
+        df = normalize_degrees_of_freedom(degrees_of_freedom)
+        raise StatPower::DomainError, "x must be finite" unless value.finite?
+        return 0.0 if value <= 0.0
+
+        SpecialFunctions::Gamma.regularized_lower(
+          a: df / 2.0,
+          x: value / 2.0
+        )
+      end
+
+      # Survival function P(X > x).
+      #
+      # @return [Float]
+      def survival(x, degrees_of_freedom:)
+        value = Float(x)
+        df = normalize_degrees_of_freedom(degrees_of_freedom)
+        raise StatPower::DomainError, "x must be finite" unless value.finite?
+        return 1.0 if value <= 0.0
+
+        SpecialFunctions::Gamma.regularized_upper(
+          a: df / 2.0,
+          x: value / 2.0
+        )
+      end
+
+      # Quantile function.
+      #
+      # @return [Float]
+      def quantile(probability, degrees_of_freedom:)
+        target = Float(probability)
+        validate_probability!(target)
+        df = normalize_degrees_of_freedom(degrees_of_freedom)
+
+        return 0.0 if target.zero?
+        return Float::INFINITY if target >= 1.0
+
+        upper = quantile_upper_bound(target, df)
+
+        Solvers::Bisection.solve(lower: 0.0, upper:) do |candidate|
+          cdf(candidate, degrees_of_freedom: df) - target
+        end
+      end
+
+      def quantile_upper_bound(target, degrees_of_freedom)
+        upper = [degrees_of_freedom, 1.0].max
+
+        while cdf(upper, degrees_of_freedom:) < target
+          upper *= 2.0
+          if upper > 1e15
+            raise StatPower::ConvergenceError,
+                  "unable to bracket chi-square quantile"
+          end
+        end
+
+        upper
+      end
+      private_class_method :quantile_upper_bound
+
+      def normalize_degrees_of_freedom(value)
+        df = Float(value)
+        return df if df.finite? && df.positive?
+
+        raise StatPower::DomainError, "degrees_of_freedom must be finite and 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!
+    end
+  end
+end

data/lib/stat_power/distributions/noncentral_chi_square.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module StatPower
+  module Distributions
+    # Noncentral chi-square distribution utilities.
+    #
+    # Probabilities are evaluated as a Poisson mixture of central chi-square
+    # distributions with degrees of freedom increased by 2j.
+    module NoncentralChiSquare
+      MIXTURE_TOLERANCE = 1e-13
+      MAX_MIXTURE_STEPS = 100_000
+
+      module_function
+
+      # Cumulative distribution function.
+      #
+      # @return [Float]
+      def cdf(x, degrees_of_freedom:, noncentrality:)
+        mixture_probability(
+          x,
+          degrees_of_freedom:,
+          noncentrality:,
+          tail: :cdf
+        )
+      end
+
+      # Survival function P(X > x).
+      #
+      # @return [Float]
+      def survival(x, degrees_of_freedom:, noncentrality:)
+        mixture_probability(
+          x,
+          degrees_of_freedom:,
+          noncentrality:,
+          tail: :survival
+        )
+      end
+
+      def mixture_probability(x, degrees_of_freedom:, noncentrality:, tail:)
+        value = Float(x)
+        df = normalize_degrees_of_freedom(degrees_of_freedom)
+        lambda = normalize_noncentrality(noncentrality)
+        raise StatPower::DomainError, "x must be finite" unless value.finite?
+
+        return tail == :cdf ? 0.0 : 1.0 if value <= 0.0
+        return central_probability(value, df, tail) if lambda.zero?
+
+        poisson_mixture(
+          value:,
+          df:,
+          poisson_mean: lambda / 2.0,
+          tail:
+        )
+      end
+      private_class_method :mixture_probability
+
+      def poisson_mixture(value:, df:, poisson_mean:, 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 * central_probability(
+          value,
+          df + (2.0 * mode),
+          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,
+            value,
+            df,
+            tail
+          )
+          upper_weight, upper_index, upper_term = upper_step(
+            upper_weight,
+            upper_index,
+            poisson_mean,
+            value,
+            df,
+            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_mixture
+
+      def lower_step(weight, index, poisson_mean, value, df, tail)
+        return [0.0, index, 0.0] if index.zero?
+
+        next_weight = weight * index / poisson_mean
+        next_index = index - 1
+        term = next_weight * central_probability(
+          value,
+          df + (2.0 * next_index),
+          tail
+        )
+
+        [next_weight, next_index, term]
+      end
+      private_class_method :lower_step
+
+      def upper_step(weight, index, poisson_mean, value, df, tail)
+        next_index = index + 1
+        next_weight = weight * poisson_mean / next_index
+        term = next_weight * central_probability(
+          value,
+          df + (2.0 * next_index),
+          tail
+        )
+
+        [next_weight, next_index, term]
+      end
+      private_class_method :upper_step
+
+      def central_probability(value, df, tail)
+        if tail == :cdf
+          ChiSquare.cdf(value, degrees_of_freedom: df)
+        else
+          ChiSquare.survival(value, degrees_of_freedom: df)
+        end
+      end
+      private_class_method :central_probability
+
+      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 normalize_degrees_of_freedom(value)
+        df = Float(value)
+        return df if df.finite? && df.positive?
+
+        raise StatPower::DomainError, "degrees_of_freedom must be finite and positive"
+      rescue ArgumentError, TypeError
+        raise StatPower::DomainError, "degrees_of_freedom must be numeric"
+      end
+      private_class_method :normalize_degrees_of_freedom
+
+      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/effect_size/chi_square.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module StatPower
+  module EffectSize
+    # Cohen's w effect-size utilities for chi-square tests.
+    module ChiSquare
+      SUM_TOLERANCE = 1e-10
+
+      module_function
+
+      # Cohen's w for a goodness-of-fit chi-square test.
+      #
+      # @param null_probabilities [Array<Numeric>] probabilities under H0
+      # @param alternative_probabilities [Array<Numeric>] probabilities under H1
+      # @return [Float]
+      def goodness_of_fit(null_probabilities:, alternative_probabilities:)
+        null_values = probability_vector!(null_probabilities, "null_probabilities")
+        alternative_values = probability_vector!(
+          alternative_probabilities,
+          "alternative_probabilities"
+        )
+
+        unless null_values.length == alternative_values.length
+          raise StatPower::DomainError,
+                "probability vectors must have the same length"
+        end
+
+        if null_values.any?(&:zero?)
+          raise StatPower::DomainError,
+                "null probabilities must be strictly positive"
+        end
+
+        sum = null_values.zip(alternative_values).sum do |null_value, alternative_value|
+          difference = alternative_value - null_value
+          (difference * difference) / null_value
+        end
+
+        Math.sqrt(sum)
+      end
+
+      # Cohen's w for a chi-square test of association.
+      #
+      # @param probabilities [Array<Array<Numeric>>] two-way probability table
+      # @return [Float]
+      def association(probabilities:)
+        table = probability_table!(probabilities)
+        row_totals = table.map(&:sum)
+        column_count = table.first.length
+        column_totals = Array.new(column_count, 0.0)
+
+        table.each do |row|
+          row.each_with_index do |value, column|
+            column_totals[column] += value
+          end
+        end
+
+        if row_totals.any?(&:zero?) || column_totals.any?(&:zero?)
+          raise StatPower::DomainError,
+                "all row and column marginal probabilities must be positive"
+        end
+
+        sum = table.each_with_index.sum do |row, row_index|
+          row.each_with_index.sum do |observed, column_index|
+            expected = row_totals[row_index] * column_totals[column_index]
+            difference = observed - expected
+            (difference * difference) / expected
+          end
+        end
+
+        Math.sqrt(sum)
+      end
+
+      def probability_vector!(values, name)
+        unless values.is_a?(Array) && values.length >= 2
+          raise StatPower::DomainError, "#{name} must contain at least two probabilities"
+        end
+
+        normalized = values.map { |value| probability!(value, name) }
+        validate_probability_sum!(normalized.sum, name)
+        normalized
+      end
+      private_class_method :probability_vector!
+
+      def probability_table!(values)
+        unless values.is_a?(Array) && values.length >= 2 &&
+               values.all? { |row| row.is_a?(Array) }
+          raise StatPower::DomainError,
+                "probabilities must be a two-dimensional table"
+        end
+
+        column_count = values.first.length
+        unless column_count >= 2 && values.all? { |row| row.length == column_count }
+          raise StatPower::DomainError,
+                "probability table must be rectangular with at least two columns"
+        end
+
+        table = values.map do |row|
+          row.map { |value| probability!(value, "probabilities") }
+        end
+        validate_probability_sum!(table.flatten.sum, "probabilities")
+        table
+      end
+      private_class_method :probability_table!
+
+      def probability!(value, name)
+        probability = Float(value)
+        return probability if probability.finite? &&
+                              probability >= 0.0 &&
+                              probability <= 1.0
+
+        raise StatPower::DomainError, "#{name} must contain probabilities in [0, 1]"
+      rescue ArgumentError, TypeError
+        raise StatPower::DomainError, "#{name} must contain numeric probabilities"
+      end
+      private_class_method :probability!
+
+      def validate_probability_sum!(sum, name)
+        return if (sum - 1.0).abs <= SUM_TOLERANCE
+
+        raise StatPower::DomainError, "#{name} must sum to 1"
+      end
+      private_class_method :validate_probability_sum!
+    end
+  end
+end