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

data/lib/stat_power/f2.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+module StatPower
+  # Power analysis for general linear models using Cohen's f².
+  #
+  # The statistical parameterisation follows CRAN pwr.f2.test. Exactly one of
+  # numerator_df, denominator_df, effect_size, alpha, and power must be nil.
+  module F2
+    DF_LOWER = 1e-10
+    DF_UPPER = 1e9
+    EFFECT_SIZE_LOWER = 1e-10
+    EFFECT_SIZE_UPPER = 1e4
+    PROBABILITY_EPSILON = 1e-10
+
+    module_function
+
+    # Solve one missing parameter of a general linear-model power analysis.
+    #
+    # @param numerator_df [Numeric, nil] numerator degrees of freedom, u
+    # @param denominator_df [Numeric, nil] denominator degrees of freedom, v
+    # @param effect_size [Numeric, Symbol, String, nil] Cohen's f²
+    # @param alpha [Numeric, nil] Type I error probability
+    # @param power [Numeric, nil] statistical power
+    # @return [StatPower::F2Result]
+    def solve(
+      numerator_df: nil,
+      denominator_df: nil,
+      effect_size: nil,
+      alpha: 0.05,
+      power: nil
+    )
+      ensure_one_missing!(
+        numerator_df,
+        denominator_df,
+        effect_size,
+        alpha,
+        power
+      )
+
+      numerator_df = optional_float(numerator_df)
+      denominator_df = optional_float(denominator_df)
+      effect_size = normalize_effect_size(effect_size)
+      alpha = optional_float(alpha)
+      power = optional_float(power)
+
+      validate_known_values!(
+        numerator_df:,
+        denominator_df:,
+        effect_size:,
+        alpha:,
+        power:
+      )
+
+      numerator_df, denominator_df, effect_size, alpha, power = solve_missing(
+        numerator_df:,
+        denominator_df:,
+        effect_size:,
+        alpha:,
+        power:
+      )
+
+      F2Result.new(
+        numerator_df:,
+        denominator_df:,
+        power:,
+        effect_size:,
+        alpha:,
+        analysis_method: "general linear model power calculation"
+      )
+    end
+
+    def solve_missing(numerator_df:, denominator_df:, effect_size:, alpha:, power:)
+      if power.nil?
+        power = power_for(
+          numerator_df:,
+          denominator_df:,
+          effect_size:,
+          alpha:
+        )
+      elsif numerator_df.nil?
+        numerator_df = solve_numerator_df(
+          denominator_df:,
+          effect_size:,
+          alpha:,
+          power:
+        )
+      elsif denominator_df.nil?
+        denominator_df = solve_denominator_df(
+          numerator_df:,
+          effect_size:,
+          alpha:,
+          power:
+        )
+      elsif effect_size.nil?
+        effect_size = solve_effect_size(
+          numerator_df:,
+          denominator_df:,
+          alpha:,
+          power:
+        )
+      elsif alpha.nil?
+        alpha = solve_alpha(
+          numerator_df:,
+          denominator_df:,
+          effect_size:,
+          power:
+        )
+      end
+
+      [numerator_df, denominator_df, effect_size, alpha, power]
+    end
+    private_class_method :solve_missing
+
+    def power_for(numerator_df:, denominator_df:, effect_size:, alpha:)
+      noncentrality = effect_size * (numerator_df + denominator_df + 1.0)
+
+      critical = Distributions::FDistribution.quantile(
+        1.0 - alpha,
+        numerator_df:,
+        denominator_df:
+      )
+
+      Distributions::NoncentralF.survival(
+        critical,
+        numerator_df:,
+        denominator_df:,
+        noncentrality:
+      )
+    end
+    private_class_method :power_for
+
+    def solve_numerator_df(denominator_df:, effect_size:, alpha:, power:)
+      Solvers::Bisection.solve(
+        lower: DF_LOWER,
+        upper: DF_UPPER
+      ) do |candidate|
+        power_for(
+          numerator_df: candidate,
+          denominator_df:,
+          effect_size:,
+          alpha:
+        ) - power
+      end
+    end
+    private_class_method :solve_numerator_df
+
+    def solve_denominator_df(numerator_df:, effect_size:, alpha:, power:)
+      Solvers::Bisection.solve(
+        lower: DF_LOWER,
+        upper: DF_UPPER
+      ) do |candidate|
+        power_for(
+          numerator_df:,
+          denominator_df: candidate,
+          effect_size:,
+          alpha:
+        ) - power
+      end
+    end
+    private_class_method :solve_denominator_df
+
+    def solve_effect_size(numerator_df:, denominator_df:, alpha:, power:)
+      Solvers::Bisection.solve(
+        lower: EFFECT_SIZE_LOWER,
+        upper: EFFECT_SIZE_UPPER
+      ) do |candidate|
+        power_for(
+          numerator_df:,
+          denominator_df:,
+          effect_size: candidate,
+          alpha:
+        ) - power
+      end
+    end
+    private_class_method :solve_effect_size
+
+    def solve_alpha(numerator_df:, denominator_df:, effect_size:, power:)
+      Solvers::Bisection.solve(
+        lower: PROBABILITY_EPSILON,
+        upper: 1.0 - PROBABILITY_EPSILON
+      ) do |candidate|
+        power_for(
+          numerator_df:,
+          denominator_df:,
+          effect_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 numerator_df, denominator_df, effect_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: :f2, 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!(numerator_df:, denominator_df:, effect_size:, alpha:, power:)
+      validate_df!("numerator_df", numerator_df) if numerator_df
+      validate_df!("denominator_df", denominator_df) if denominator_df
+      validate_effect_size!(effect_size) if effect_size
+      validate_probability!("alpha", alpha) if alpha
+      validate_probability!("power", power) if power
+    end
+    private_class_method :validate_known_values!
+
+    def validate_df!(name, value)
+      return if value.finite? && value.positive?
+
+      raise StatPower::DomainError, "#{name} 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_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/f2_result.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module StatPower
+  # Immutable result for general linear-model power analyses based on Cohen's f².
+  F2Result = Data.define(
+    :numerator_df,
+    :denominator_df,
+    :power,
+    :effect_size,
+    :alpha,
+    :analysis_method
+  ) do
+    # Implied total sample size N = u + v + 1.
+    #
+    # @return [Float]
+    def total_sample_size
+      numerator_df + denominator_df + 1.0
+    end
+
+    # Smallest whole-number total sample size not below the continuous value.
+    #
+    # @return [Integer]
+    def required_total_sample_size
+      total_sample_size.ceil
+    end
+  end
+end

data/lib/stat_power/power_curve.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module StatPower
+  # Data-first power-curve generation.
+  #
+  # A caller supplies the sample sizes and a block that evaluates an existing
+  # power solver at each sample size. The block may return either a numeric
+  # power value or any result object exposing a +power+ reader.
+  module PowerCurve
+    module_function
+
+    # Generate power-curve points.
+    #
+    # @param sample_sizes [Enumerable<Numeric>] sample sizes to evaluate
+    # @yieldparam sample_size [Float] current sample size
+    # @yieldreturn [Numeric, #power] achieved power or result object
+    # @return [Array<StatPower::PowerCurvePoint>]
+    def generate(sample_sizes:)
+      unless block_given?
+        raise StatPower::DomainError,
+              "a block evaluating power at each sample size is required"
+      end
+
+      sizes = normalize_sample_sizes(sample_sizes)
+
+      sizes.map do |sample_size|
+        evaluated = yield(sample_size)
+        power = extract_power(evaluated)
+
+        PowerCurvePoint.new(
+          sample_size:,
+          power:
+        )
+      end
+    end
+
+    def normalize_sample_sizes(values)
+      unless values.respond_to?(:map)
+        raise StatPower::DomainError,
+              "sample_sizes must be an enumerable collection"
+      end
+
+      sizes = values.map do |value|
+        sample_size = Float(value)
+
+        unless sample_size.finite? && sample_size.positive?
+          raise StatPower::DomainError,
+                "sample sizes must be finite and positive"
+        end
+
+        sample_size
+      rescue ArgumentError, TypeError
+        raise StatPower::DomainError,
+              "sample sizes must be numeric"
+      end
+
+      if sizes.empty?
+        raise StatPower::DomainError,
+              "sample_sizes must contain at least one value"
+      end
+
+      sizes
+    end
+    private_class_method :normalize_sample_sizes
+
+    def extract_power(value)
+      power = if value.respond_to?(:power)
+                value.power
+              else
+                Float(value)
+              end
+
+      power = Float(power)
+
+      return power if power.finite? && power >= 0.0 && power <= 1.0
+
+      raise StatPower::DomainError,
+            "power evaluations must lie in [0, 1]"
+    rescue ArgumentError, TypeError
+      raise StatPower::DomainError,
+            "power evaluations must be numeric or expose a numeric power value"
+    end
+    private_class_method :extract_power
+  end
+end

data/lib/stat_power/power_curve_point.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module StatPower
+  # Immutable point on a statistical power curve.
+  PowerCurvePoint = Data.define(:sample_size, :power)
+end

data/lib/stat_power/special_functions/gamma.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module StatPower
+  module SpecialFunctions
+    # Numerical utilities for the regularized incomplete gamma functions.
+    module Gamma
+      MAX_ITERATIONS = 10_000
+      EPSILON = 3e-14
+      MIN_DENOMINATOR = 1e-300
+
+      module_function
+
+      # Regularized lower incomplete gamma P(a, x).
+      #
+      # @param a [Numeric] positive shape parameter
+      # @param x [Numeric] non-negative evaluation point
+      # @return [Float]
+      def regularized_lower(a:, x:)
+        shape = Float(a)
+        value = Float(x)
+        validate_arguments!(shape, value)
+
+        return 0.0 if value.zero?
+
+        if value < shape + 1.0
+          lower_series(shape, value)
+        else
+          1.0 - upper_continued_fraction(shape, value)
+        end
+      end
+
+      # Regularized upper incomplete gamma Q(a, x).
+      #
+      # @param a [Numeric] positive shape parameter
+      # @param x [Numeric] non-negative evaluation point
+      # @return [Float]
+      def regularized_upper(a:, x:)
+        shape = Float(a)
+        value = Float(x)
+        validate_arguments!(shape, value)
+
+        return 1.0 if value.zero?
+
+        if value < shape + 1.0
+          1.0 - lower_series(shape, value)
+        else
+          upper_continued_fraction(shape, value)
+        end
+      end
+
+      def lower_series(shape, value)
+        term = 1.0 / shape
+        sum = term
+        shifted_shape = shape
+
+        1.upto(MAX_ITERATIONS) do
+          shifted_shape += 1.0
+          term *= value / shifted_shape
+          sum += term
+
+          return sum * scale_factor(shape, value) if term.abs <= sum.abs * EPSILON
+        end
+
+        raise StatPower::ConvergenceError,
+              "regularized gamma series did not converge"
+      end
+      private_class_method :lower_series
+
+      def upper_continued_fraction(shape, value)
+        b = value + 1.0 - shape
+        c = 1.0 / MIN_DENOMINATOR
+        d = 1.0 / stabilize(b)
+        result = d
+
+        1.upto(MAX_ITERATIONS) do |iteration|
+          coefficient = -iteration * (iteration - shape)
+          b += 2.0
+          d = 1.0 / stabilize((coefficient * d) + b)
+          c = stabilize(b + (coefficient / c))
+          delta = d * c
+          result *= delta
+
+          return result * scale_factor(shape, value) if (delta - 1.0).abs <= EPSILON
+        end
+
+        raise StatPower::ConvergenceError,
+              "regularized gamma continued fraction did not converge"
+      end
+      private_class_method :upper_continued_fraction
+
+      def scale_factor(shape, value)
+        Math.exp(
+          (-value) +
+          (shape * Math.log(value)) -
+          Math.lgamma(shape).first
+        )
+      end
+      private_class_method :scale_factor
+
+      def stabilize(value)
+        return value if value.abs >= MIN_DENOMINATOR
+
+        value.negative? ? -MIN_DENOMINATOR : MIN_DENOMINATOR
+      end
+      private_class_method :stabilize
+
+      def validate_arguments!(shape, value)
+        unless shape.finite? && shape.positive?
+          raise StatPower::DomainError, "gamma shape parameter must be finite and positive"
+        end
+
+        return if value.finite? && !value.negative?
+
+        raise StatPower::DomainError, "gamma evaluation point must be finite and non-negative"
+      end
+      private_class_method :validate_arguments!
+    end
+  end
+end

data/lib/stat_power/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StatPower
-  VERSION = "0.1.0.alpha.1"
+  VERSION = "0.1.0.alpha.2"
 end

data/lib/stat_power.rb

@@ -4,22 +4,34 @@ require_relative "stat_power/version"
 require_relative "stat_power/result"
 require_relative "stat_power/power_result"
 require_relative "stat_power/unequal_power_result"
+require_relative "stat_power/anova_result"
+require_relative "stat_power/f2_result"
+require_relative "stat_power/chi_square_result"
+require_relative "stat_power/power_curve_point"
 require_relative "stat_power/errors"
 require_relative "stat_power/special_functions/beta"
+require_relative "stat_power/special_functions/gamma"
 require_relative "stat_power/integration/adaptive_simpson"
 require_relative "stat_power/distributions/normal"
 require_relative "stat_power/distributions/student_t"
 require_relative "stat_power/distributions/noncentral_t"
 require_relative "stat_power/distributions/f_distribution"
 require_relative "stat_power/distributions/noncentral_f"
+require_relative "stat_power/distributions/chi_square"
+require_relative "stat_power/distributions/noncentral_chi_square"
 require_relative "stat_power/solvers/bisection"
 require_relative "stat_power/effect_size/conventional"
 require_relative "stat_power/effect_size/proportion"
+require_relative "stat_power/effect_size/chi_square"
 require_relative "stat_power/normal_mean"
 require_relative "stat_power/proportion"
 require_relative "stat_power/t_test"
 require_relative "stat_power/t_test_unequal"
 require_relative "stat_power/correlation"
+require_relative "stat_power/anova"
+require_relative "stat_power/f2"
+require_relative "stat_power/chi_square"
+require_relative "stat_power/power_curve"
 
 module StatPower
 end

data/sig/stat_power.rbs

@@ -69,6 +69,80 @@ module StatPower
     def required_total_sample_size: () -> Integer
   end
 
+  class AnovaResult
+    attr_reader groups: Float
+    attr_reader sample_size: Float
+    attr_reader power: Float
+    attr_reader effect_size: Float
+    attr_reader alpha: Float
+    attr_reader analysis_method: String
+
+    def initialize: (
+      groups: Float,
+      sample_size: Float,
+      power: Float,
+      effect_size: Float,
+      alpha: Float,
+      analysis_method: String
+    ) -> void
+
+    def required_groups: () -> Integer
+    def required_sample_size: () -> Integer
+    def total_sample_size: () -> Float
+    def required_total_sample_size: () -> Integer
+  end
+
+  class F2Result
+    attr_reader numerator_df: Float
+    attr_reader denominator_df: Float
+    attr_reader power: Float
+    attr_reader effect_size: Float
+    attr_reader alpha: Float
+    attr_reader analysis_method: String
+
+    def initialize: (
+      numerator_df: Float,
+      denominator_df: Float,
+      power: Float,
+      effect_size: Float,
+      alpha: Float,
+      analysis_method: String
+    ) -> void
+
+    def total_sample_size: () -> Float
+    def required_total_sample_size: () -> Integer
+  end
+
+  class ChiSquareResult
+    attr_reader degrees_of_freedom: Float
+    attr_reader sample_size: Float
+    attr_reader power: Float
+    attr_reader effect_size: Float
+    attr_reader alpha: Float
+    attr_reader analysis_method: String
+
+    def initialize: (
+      degrees_of_freedom: Float,
+      sample_size: Float,
+      power: Float,
+      effect_size: Float,
+      alpha: Float,
+      analysis_method: String
+    ) -> void
+
+    def required_sample_size: () -> Integer
+  end
+
+  class PowerCurvePoint
+    attr_reader sample_size: Float
+    attr_reader power: Float
+
+    def initialize: (
+      sample_size: Float,
+      power: Float
+    ) -> void
+  end
+
   module EffectSize
     module Conventional
       def self.resolve: (test: Symbol | String, size: Symbol | String) -> Float
@@ -77,6 +151,17 @@ module StatPower
     module Proportion
       def self.cohen_h: (p1: Numeric, p2: Numeric) -> Float
     end
+
+    module ChiSquare
+      def self.goodness_of_fit: (
+        null_probabilities: Array[Numeric],
+        alternative_probabilities: Array[Numeric]
+      ) -> Float
+
+      def self.association: (
+        probabilities: Array[Array[Numeric]]
+      ) -> Float
+    end
   end
 
   module NormalMean
@@ -161,10 +246,51 @@ module StatPower
     ) -> PowerResult
   end
 
+  module Anova
+    def self.solve: (
+      ?groups: Numeric | nil,
+      ?sample_size: Numeric | nil,
+      ?effect_size: Numeric | Symbol | String | nil,
+      ?alpha: Numeric | nil,
+      ?power: Numeric | nil
+    ) -> AnovaResult
+  end
+
+  module F2
+    def self.solve: (
+      ?numerator_df: Numeric | nil,
+      ?denominator_df: Numeric | nil,
+      ?effect_size: Numeric | Symbol | String | nil,
+      ?alpha: Numeric | nil,
+      ?power: Numeric | nil
+    ) -> F2Result
+  end
+
+  module ChiSquare
+    def self.solve: (
+      degrees_of_freedom: Numeric,
+      ?effect_size: Numeric | Symbol | String | nil,
+      ?sample_size: Numeric | nil,
+      ?alpha: Numeric | nil,
+      ?power: Numeric | nil
+    ) -> ChiSquareResult
+  end
+
+  module PowerCurve
+    def self.generate: (
+      sample_sizes: Enumerable[Numeric]
+    ) { (Float) -> Numeric | PowerResult | UnequalPowerResult | AnovaResult | F2Result | ChiSquareResult } -> Array[PowerCurvePoint]
+  end
+
   module SpecialFunctions
     module Beta
       def self.regularized: (Numeric x, a: Numeric, b: Numeric) -> Float
     end
+
+    module Gamma
+      def self.regularized_lower: (a: Numeric, x: Numeric) -> Float
+      def self.regularized_upper: (a: Numeric, x: Numeric) -> Float
+    end
   end
 
   module Integration
@@ -248,6 +374,27 @@ module StatPower
         noncentrality: Numeric
       ) -> Float
     end
+
+    module ChiSquare
+      def self.pdf: (Numeric x, degrees_of_freedom: Numeric) -> Float
+      def self.cdf: (Numeric x, degrees_of_freedom: Numeric) -> Float
+      def self.survival: (Numeric x, degrees_of_freedom: Numeric) -> Float
+      def self.quantile: (Numeric probability, degrees_of_freedom: Numeric) -> Float
+    end
+
+    module NoncentralChiSquare
+      def self.cdf: (
+        Numeric x,
+        degrees_of_freedom: Numeric,
+        noncentrality: Numeric
+      ) -> Float
+
+      def self.survival: (
+        Numeric x,
+        degrees_of_freedom: Numeric,
+        noncentrality: Numeric
+      ) -> Float
+    end
   end
 
   module Solvers