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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66d3d0229cc19ab03fc96007a171298ae29f1f6964d62d51d945799fa3a7a465
-  data.tar.gz: 1567693499022a1831ebaf0c216819458e9ddfd6389843d7581cd2c4d9534c65
+  metadata.gz: f1c655045d40fab84f807e1092e00ab08829ff0d9066f1081c14e9a75d411d52
+  data.tar.gz: bd2eff9c48b33c0512ce887eb704b674c2a6b8f511b65733a6c230de82f7617a
 SHA512:
-  metadata.gz: 17de540e8e06c53b81e1295c0e9176a09cbf1f25458900524d7e318a627da780bc82becc0d9963cbc9ac4ce3d334ecff2686630993d87149792e01f65afccd40
-  data.tar.gz: 278d9c38fbcf57c6d7bf522ab8126da06e1720f79b8393198620bc33049bc68123e6297f743e90b98fca31822173f8e65ae4f74e87866101921f21d453a79334
+  metadata.gz: 1f941dc407c89a7f931511b9355a0495924d0edaf09c6b599190fa39a80668224330513072c1f7cfd2f7b05dbb39d01a0bd405ef1fe1d6a7132aaf06b57cc3d7
+  data.tar.gz: eddde39e8855abf2e9df24160968f28b8ba52884b6d4d3bcf954bd0c1231740ee99e7d67007ff05f50b15b6a80728ff8a41abc2b948a38e97c6b4519bff69a06

data/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to this project will be documented in this file.
 
 ## Unreleased
 
+## 0.1.0.alpha.2 - 2026-09-20
+
+### Added
+
+- Balanced one-way ANOVA power analysis compatible with `pwr.anova.test`
+- Dedicated ANOVA result object with per-group and total sample-size helpers
+- General linear-model power analysis compatible with `pwr.f2.test`
+- Dedicated `F2Result` with implied total sample-size helpers
+- Regularized incomplete gamma functions
+- Central and noncentral chi-square distribution utilities
+- Cohen's `w` effect-size helpers for goodness-of-fit and association tests
+- Chi-square power analysis compatible with `pwr.chisq.test`
+- Dedicated `ChiSquareResult` with total sample-size helper
+- Data-first power-curve generation via `StatPower::PowerCurve.generate`
+- Immutable `PowerCurvePoint` values for plotting-library-independent output
+- Fixture-driven CRAN `pwr` parity validation across all implemented solver families
+- Documented numerical tolerance and reference-provenance policy
+
 ## 0.1.0.alpha.1 - 2026-09-19
 
 ### Added

data/README.md

@@ -17,13 +17,13 @@ gem install stat_power --prerelease
 or pin the exact alpha:
 
 ```bash
-gem install stat_power -v 0.1.0.alpha.1
+gem install stat_power -v 0.1.0.alpha.2
 ```
 
 With Bundler:
 
 ```ruby
-gem "stat_power", "0.1.0.alpha.1"
+gem "stat_power", "0.1.0.alpha.2"
 ```
 
 ## Status
@@ -41,9 +41,16 @@ Implemented compatibility currently includes:
 - `pwr.t.test`
 - `pwr.t2n.test`
 - `pwr.r.test`
+- `pwr.anova.test`
+- `pwr.f2.test`
+- `pwr.chisq.test`
+- `ES.h`
+- `ES.w1`
+- `ES.w2`
+- power-curve data generation equivalent in purpose to `plot.power.htest`
 
-The library also contains the numerical distribution machinery required for
-further power methods, including central/noncentral t and F distributions.
+The library also contains the numerical distribution machinery required by
+these methods, including central/noncentral t, F, and chi-square distributions.
 
 See [docs/pwr_parity.md](docs/pwr_parity.md) for the full compatibility matrix.
 
@@ -140,6 +147,9 @@ gem build stat_power.gemspec
 
 See [docs/mathematical_conventions.md](docs/mathematical_conventions.md).
 
+For numerical reference fixtures and tolerance rules, see
+[docs/validation.md](docs/validation.md).
+
 ## Roadmap
 
 See [ROADMAP.md](ROADMAP.md).

data/RELEASING.md

@@ -2,13 +2,12 @@
 
 This project uses prerelease versions until the public API is ready to stabilize.
 
-## One-time RubyGems trusted publisher setup
+## RubyGems trusted publishing
 
 RubyGems Trusted Publishing allows GitHub Actions to publish without storing a
 long-lived RubyGems API key.
 
-For the first release of `stat_power`, create a **pending trusted publisher**
-from the RubyGems.org account that should own the gem, using:
+The trusted publisher for `stat_power` must match:
 
 - Gem name: `stat_power`
 - Repository owner: `DiogoRibeiro7`
@@ -18,14 +17,11 @@ from the RubyGems.org account that should own the gem, using:
 
 The workflow is stored at `.github/workflows/release.yml`.
 
-After the first successful publication, the pending publisher becomes the
-trusted publisher for the gem.
-
 ## Alpha release checklist
 
 1. Ensure all CI jobs are green on `main`.
 2. Confirm `lib/stat_power/version.rb` contains the intended version.
-3. Update `CHANGELOG.md` with the release date.
+3. Move the release entries in `CHANGELOG.md` out of `Unreleased`.
 4. Build the gem locally:
 
    ```bash
@@ -47,19 +43,20 @@ trusted publisher for the gem.
 7. Run a smoke test against the installed package:
 
    ```bash
-   ruby -e 'require "stat_power"; p StatPower::VERSION'
+   ruby -e 'require "stat_power"; puts StatPower::VERSION'
    ```
 
-8. Confirm the RubyGems pending/trusted publisher is configured for
+8. Confirm the RubyGems trusted publisher still matches
    `.github/workflows/release.yml` and the `release` environment.
 
-9. Create and push the release tag. The tag must match the version exactly:
+9. Create and push the release tag. For the current release:
 
    ```bash
+   VERSION=0.1.0.alpha.2
    git checkout main
    git pull --ff-only
-   git tag v0.1.0.alpha.1
-   git push origin v0.1.0.alpha.1
+   git tag "v${VERSION}"
+   git push origin "v${VERSION}"
    ```
 
 Pushing the tag triggers the release workflow. It validates that:
@@ -71,9 +68,24 @@ Pushing the tag triggers the release workflow. It validates that:
 - RBS signatures validate
 - the gem builds successfully
 
-The workflow then publishes to RubyGems using OIDC Trusted Publishing and
-creates a GitHub Release. Prerelease versions are marked as prereleases on
-GitHub automatically.
+The workflow requests short-lived RubyGems credentials through OIDC, pushes the
+already-built gem artifact with `gem push`, and creates a GitHub Release.
+Prerelease versions are marked as prereleases on GitHub automatically.
+
+## Retrying a failed release
+
+If a release tag already exists but the workflow fails before RubyGems accepts
+the gem, do not create a new version merely to retry the same artifact.
+
+1. Open **Actions → Release gem**.
+2. Choose **Run workflow**.
+3. Enter the existing tag, for example `v0.1.0.alpha.2`.
+4. Run the workflow from `main`.
+
+The manual dispatch checks out the existing tag and publishes that exact
+artifact while using the latest release workflow definition from `main`.
+
+Once a version appears on RubyGems.org, it is immutable and must not be reused.
 
 ## After publishing
 
@@ -89,17 +101,13 @@ Then confirm:
 ruby -e 'require "stat_power"; puts StatPower::VERSION'
 ```
 
-The expected output for the first alpha is:
+For the current release the expected output is:
 
 ```text
-0.1.0.alpha.1
+0.1.0.alpha.2
 ```
 
-## Failed releases
-
-If the workflow fails before the RubyGems publishing step, fix the problem and
-move the release tag only if the version has not been published.
+## Failed releases after publication
 
 Once a version exists on RubyGems.org, do not overwrite or reuse that version.
-Increment the prerelease version, for example from `0.1.0.alpha.1` to
-`0.1.0.alpha.2`, and create a new tag.
+Increment the prerelease version and create a new tag.

data/ROADMAP.md

@@ -11,7 +11,7 @@
 - [x] Normal mean power analysis equivalent to `pwr.norm.test`
 - [x] Student t distribution utilities
 - [x] Noncentral t distribution utilities
-- [ ] Chi-square and noncentral chi-square utilities
+- [x] Chi-square and noncentral chi-square utilities
 - [x] F and noncentral F utilities
 
 ### pwr compatibility
@@ -22,24 +22,24 @@
 - [x] `pwr.2p2n.test`
 - [x] `pwr.t.test`
 - [x] `pwr.t2n.test`
-- [ ] `pwr.anova.test`
+- [x] `pwr.anova.test`
 - [x] `pwr.r.test`
-- [ ] `pwr.chisq.test`
-- [ ] `pwr.f2.test`
+- [x] `pwr.chisq.test`
+- [x] `pwr.f2.test`
 - [x] `ES.h`
-- [ ] `ES.w1`
-- [ ] `ES.w2`
-- [ ] power-curve data equivalent to `plot.power.htest`
+- [x] `ES.w1`
+- [x] `ES.w2`
+- [x] power-curve data equivalent to `plot.power.htest`
 
 Each migrated family must support the inverse problems exposed by the reference
 method and include numerical parity tests.
 
 ## 0.2.x — Validation and usability
 
-- Automated parity fixtures generated from R `pwr`
+- [x] Automated parity fixtures derived from CRAN `pwr` references
 - Published Cohen examples
 - Cross-validation against statsmodels where applicable
-- Documented numerical tolerance policy
+- [x] Documented numerical tolerance policy
 - Stable result objects
 - User-facing method documentation
 - Benchmarks

data/docs/pwr_parity.md

@@ -18,14 +18,14 @@ reference points.
 | `pwr.2p2n.test` | `StatPower::Proportion.two_sample_unequal` | Implemented |
 | `pwr.t.test` | `StatPower::TTest.one_sample`, `.paired`, `.two_sample` | Implemented |
 | `pwr.t2n.test` | `StatPower::TTest.two_sample_unequal` | Implemented |
-| `pwr.anova.test` | balanced one-way ANOVA power | Planned |
+| `pwr.anova.test` | `StatPower::Anova.solve` | Implemented |
 | `pwr.r.test` | `StatPower::Correlation.solve` | Implemented |
-| `pwr.chisq.test` | chi-square power | Planned |
-| `pwr.f2.test` | general linear-model power | Planned |
+| `pwr.chisq.test` | `StatPower::ChiSquare.solve` | Implemented |
+| `pwr.f2.test` | `StatPower::F2.solve` | Implemented |
 | `ES.h` | `StatPower::EffectSize::Proportion.cohen_h` | Implemented |
-| `ES.w1` | Cohen w for goodness of fit | Planned |
-| `ES.w2` | Cohen w for contingency tables | Planned |
-| `plot.power.htest` | power-curve data generation | Planned |
+| `ES.w1` | `StatPower::EffectSize::ChiSquare.goodness_of_fit` | Implemented |
+| `ES.w2` | `StatPower::EffectSize::ChiSquare.association` | Implemented |
+| `plot.power.htest` | `StatPower::PowerCurve.generate` | Implemented as data generation |
 
 ## Solver convention
 
@@ -60,3 +60,6 @@ Each migrated family should include:
 Parity means agreement in the statistical model and numerical result within a
 documented tolerance. Ruby naming and object design remain idiomatic rather
 than cloning R syntax.
+
+See [validation.md](validation.md) for the fixture suite, reference provenance,
+and numerical tolerance policy.

data/docs/validation.md

@@ -0,0 +1,60 @@
+# Numerical validation
+
+`stat_power` treats numerical validation as part of the public contract.
+
+## CRAN pwr reference fixtures
+
+The first compatibility target is CRAN `pwr` 1.3-0. Reference cases live in
+`spec/fixtures/pwr_parity.yml` and are exercised by
+`spec/parity/pwr_parity_spec.rb`.
+
+The fixture set deliberately uses public examples from the `pwr` reference
+manual and Cohen (1988) where available. It covers every power-analysis family
+implemented by `stat_power`, including both direct power calculations and
+representative inverse problems.
+
+The fixture file records:
+
+- the corresponding `pwr` function,
+- the source/example label,
+- the Ruby public API call,
+- the input arguments,
+- the output field being checked,
+- the expected numeric value,
+- the accepted absolute tolerance.
+
+Detailed unit tests remain alongside each implementation. The fixture suite is
+an additional end-to-end compatibility layer, not a replacement for
+distribution-level, solver-level, domain, or round-trip tests.
+
+## Tolerance policy
+
+Numerical tolerances are explicit per fixture.
+
+As a default policy:
+
+- direct probabilities and distribution values use absolute tolerances around
+  `1e-8` or tighter when the reference is stable,
+- inverse root solutions generally use `1e-5` because independent numerical
+  solvers can stop at slightly different points while agreeing statistically,
+- looser tolerances are used only when the published reference itself is
+  reported with fewer digits.
+
+A tolerance should not be widened merely to make a failing test pass. A change
+must first be traced to one of:
+
+1. a documented difference in the statistical model,
+2. a known precision limit of the numerical method,
+3. a reference value with limited published precision,
+4. an implementation defect.
+
+## Reproducibility
+
+The fixture values are versioned with the code so changes are reviewable in
+pull requests. Adding a new statistical family requires adding at least one
+forward reference case and one inverse reference case when the reference API
+supports inverse solving.
+
+The project does not execute R during normal gem CI. This keeps the Ruby test
+suite self-contained and deterministic while preserving explicit provenance
+for the reference numbers.

data/lib/stat_power/anova.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+module StatPower
+  # Power analysis for balanced one-way analysis of variance.
+  #
+  # The statistical parameterisation follows CRAN pwr.anova.test. Exactly one
+  # of groups, sample_size, effect_size, alpha, and power must be nil.
+  module Anova
+    GROUPS_LOWER = 2.0 + 1e-10
+    GROUPS_UPPER = 100.0
+    SAMPLE_SIZE_LOWER = 2.0 + 1e-10
+    SAMPLE_SIZE_MAX = 1e9
+    EFFECT_SIZE_LOWER = 1e-7
+    EFFECT_SIZE_MAX = 1e4
+    PROBABILITY_EPSILON = 1e-10
+
+    module_function
+
+    # Solve one missing parameter of a balanced one-way ANOVA power analysis.
+    #
+    # @param groups [Numeric, nil] number of groups
+    # @param sample_size [Numeric, nil] observations per group
+    # @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::AnovaResult]
+    def solve(
+      groups: nil,
+      sample_size: nil,
+      effect_size: nil,
+      alpha: 0.05,
+      power: nil
+    )
+      ensure_one_missing!(groups, sample_size, effect_size, alpha, power)
+
+      groups = optional_float(groups)
+      sample_size = optional_float(sample_size)
+      effect_size = normalize_effect_size(effect_size)
+      alpha = optional_float(alpha)
+      power = optional_float(power)
+
+      validate_known_values!(
+        groups:,
+        sample_size:,
+        effect_size:,
+        alpha:,
+        power:
+      )
+
+      groups, sample_size, effect_size, alpha, power = solve_missing(
+        groups:,
+        sample_size:,
+        effect_size:,
+        alpha:,
+        power:
+      )
+
+      AnovaResult.new(
+        groups:,
+        sample_size:,
+        power:,
+        effect_size:,
+        alpha:,
+        analysis_method: "balanced one-way analysis of variance power calculation"
+      )
+    end
+
+    def solve_missing(groups:, sample_size:, effect_size:, alpha:, power:)
+      if power.nil?
+        power = power_for(
+          groups:,
+          sample_size:,
+          effect_size:,
+          alpha:
+        )
+      elsif groups.nil?
+        groups = solve_groups(
+          sample_size:,
+          effect_size:,
+          alpha:,
+          power:
+        )
+      elsif sample_size.nil?
+        sample_size = solve_sample_size(
+          groups:,
+          effect_size:,
+          alpha:,
+          power:
+        )
+      elsif effect_size.nil?
+        effect_size = solve_effect_size(
+          groups:,
+          sample_size:,
+          alpha:,
+          power:
+        )
+      elsif alpha.nil?
+        alpha = solve_alpha(
+          groups:,
+          sample_size:,
+          effect_size:,
+          power:
+        )
+      end
+
+      [groups, sample_size, effect_size, alpha, power]
+    end
+    private_class_method :solve_missing
+
+    def power_for(groups:, sample_size:, effect_size:, alpha:)
+      numerator_df = groups - 1.0
+      denominator_df = (sample_size - 1.0) * groups
+      noncentrality = groups * sample_size * effect_size * effect_size
+
+      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_groups(sample_size:, effect_size:, alpha:, power:)
+      Solvers::Bisection.solve(
+        lower: GROUPS_LOWER,
+        upper: GROUPS_UPPER
+      ) do |candidate|
+        power_for(
+          groups: candidate,
+          sample_size:,
+          effect_size:,
+          alpha:
+        ) - power
+      end
+    end
+    private_class_method :solve_groups
+
+    def solve_sample_size(groups:, effect_size:, alpha:, power:)
+      upper = bracket_sample_size(
+        groups:,
+        effect_size:,
+        alpha:,
+        power:
+      )
+
+      Solvers::Bisection.solve(
+        lower: SAMPLE_SIZE_LOWER,
+        upper:,
+        absolute_tolerance: 1e-7,
+        relative_tolerance: 1e-9
+      ) do |candidate|
+        power_for(
+          groups:,
+          sample_size: candidate,
+          effect_size:,
+          alpha:
+        ) - power
+      end
+    end
+    private_class_method :solve_sample_size
+
+    def bracket_sample_size(groups:, effect_size:, alpha:, power:)
+      upper = 4.0
+
+      while upper < SAMPLE_SIZE_MAX
+        achieved = power_for(
+          groups:,
+          sample_size: upper,
+          effect_size:,
+          alpha:
+        )
+        return upper if achieved >= power
+
+        upper *= 2.0
+      end
+
+      raise StatPower::DomainError,
+            "target power cannot be bracketed within the supported sample-size range"
+    end
+    private_class_method :bracket_sample_size
+
+    def solve_effect_size(groups:, sample_size:, alpha:, power:)
+      upper = bracket_effect_size(
+        groups:,
+        sample_size:,
+        alpha:,
+        power:
+      )
+
+      Solvers::Bisection.solve(
+        lower: EFFECT_SIZE_LOWER,
+        upper:
+      ) do |candidate|
+        power_for(
+          groups:,
+          sample_size:,
+          effect_size: candidate,
+          alpha:
+        ) - power
+      end
+    end
+    private_class_method :solve_effect_size
+
+    def bracket_effect_size(groups:, sample_size:, alpha:, power:)
+      upper = 0.5
+
+      while upper < EFFECT_SIZE_MAX
+        achieved = power_for(
+          groups:,
+          sample_size:,
+          effect_size: upper,
+          alpha:
+        )
+        return upper if achieved >= power
+
+        upper *= 2.0
+      end
+
+      raise StatPower::DomainError,
+            "target power cannot be bracketed within the supported effect-size range"
+    end
+    private_class_method :bracket_effect_size
+
+    def solve_alpha(groups:, sample_size:, effect_size:, power:)
+      Solvers::Bisection.solve(
+        lower: PROBABILITY_EPSILON,
+        upper: 1.0 - PROBABILITY_EPSILON
+      ) do |candidate|
+        power_for(
+          groups:,
+          sample_size:,
+          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 groups, sample_size, 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: :anov, 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!(groups:, sample_size:, effect_size:, alpha:, power:)
+      validate_groups!(groups) if groups
+      validate_sample_size!(sample_size) if sample_size
+      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_groups!(groups)
+      return if groups.finite? && groups >= 2.0
+
+      raise StatPower::DomainError, "groups must be finite and at least 2"
+    end
+    private_class_method :validate_groups!
+
+    def validate_sample_size!(sample_size)
+      return if sample_size.finite? && sample_size >= 2.0
+
+      raise StatPower::DomainError, "sample_size must be finite and at least 2"
+    end
+    private_class_method :validate_sample_size!
+
+    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/anova_result.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module StatPower
+  # Immutable result for balanced one-way ANOVA power analyses.
+  AnovaResult = Data.define(
+    :groups,
+    :sample_size,
+    :power,
+    :effect_size,
+    :alpha,
+    :analysis_method
+  ) do
+    # Smallest whole-number group count not below the continuous solution.
+    #
+    # @return [Integer]
+    def required_groups
+      groups.ceil
+    end
+
+    # Smallest whole-number per-group sample size not below the solution.
+    #
+    # @return [Integer]
+    def required_sample_size
+      sample_size.ceil
+    end
+
+    # Continuous total sample size.
+    #
+    # @return [Float]
+    def total_sample_size
+      groups * sample_size
+    end
+
+    # Practical total after independently rounding groups and per-group n up.
+    #
+    # @return [Integer]
+    def required_total_sample_size
+      required_groups * required_sample_size
+    end
+  end
+end