stat_power 0.1.0.alpha.1 → 0.1.0.alpha.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66d3d0229cc19ab03fc96007a171298ae29f1f6964d62d51d945799fa3a7a465
-  data.tar.gz: 1567693499022a1831ebaf0c216819458e9ddfd6389843d7581cd2c4d9534c65
+  metadata.gz: 2c69ef6117ff1e0bf73f795f855383722810e4e0153d33fe65e5baf803c6554b
+  data.tar.gz: 68e88eb27fff0e23651c8ae4f9a954eb14718703287b9aaf596b251dd0d742af
 SHA512:
-  metadata.gz: 17de540e8e06c53b81e1295c0e9176a09cbf1f25458900524d7e318a627da780bc82becc0d9963cbc9ac4ce3d334ecff2686630993d87149792e01f65afccd40
-  data.tar.gz: 278d9c38fbcf57c6d7bf522ab8126da06e1720f79b8393198620bc33049bc68123e6297f743e90b98fca31822173f8e65ae4f74e87866101921f21d453a79334
+  metadata.gz: d8882a7378d4e07735877624fdb21ac512b9e54f5bb42a0342374fcd18e922e85b36710fe9e05fcf92a8b2a5abea3711198bc3df678a7d5796735581bfa9b108
+  data.tar.gz: b5f799b202dc11cc3a7b0290a2d90ff1061771f43cc021e7626e6c256213ff95a8a597f09f5034ec9b1e7f9b070aef0ef8f940fec7734b52263f589349ac86d8

data/CHANGELOG.md

@@ -4,6 +4,60 @@ All notable changes to this project will be documented in this file.
 
 ## Unreleased
 
+## 0.1.0.alpha.3 - 2026-09-20
+
+### Added
+
+- Contribution guide, code of conduct, and security policy
+- Issue templates, including a dedicated numerical-discrepancy report
+- Pull request template requiring independent numerical validation
+- `CODEOWNERS` and Dependabot configuration for Bundler and GitHub Actions
+- CodeQL analysis workflow
+- `bin/setup` and `bin/console` developer scripts
+- `rake verify` task running every check that CI runs
+- Steep type checking of `lib/` against `sig/`, now enforced in CI
+- SimpleCov line and branch coverage with an enforced minimum
+- `.gitattributes`, `.editorconfig`, and `.ruby-version` for reproducible
+  formatting and tooling across platforms
+
+### Changed
+
+- CI now runs lint, type check, and coverage as dedicated jobs, declares
+  least-privilege permissions, and cancels superseded runs
+- RuboCop runs with `NewCops: enable`
+- Gem metadata now includes a contact address, bug tracker, and versioned
+  source URI; maintainer-only files are no longer packaged
+
+### Fixed
+
+- **`sig/stat_power.rbs` shipped in 0.1.0.alpha.2 was not valid RBS.** The
+  block signature for `PowerCurve.generate` used an unparenthesized union
+  return type, so any consumer feeding the packaged signatures to `rbs` or
+  Steep hit a parse error at line 282. Runtime behaviour was unaffected;
+  0.1.0.alpha.1 was not affected, because it predates `PowerCurve`. `rbs
+  validate` accepts the malformed form, which is why it reached a release;
+  `steep check` now runs in CI and in the release gate.
+- `EffectSize::ChiSquare.association` computed column marginals by mutating an
+  accumulator array; it now uses `transpose`
+
+## 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

@@ -1,5 +1,11 @@
 # stat_power
 
+[![CI](https://github.com/DiogoRibeiro7/stat_power/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/DiogoRibeiro7/stat_power/actions/workflows/ci.yml)
+[![RubyGems](https://img.shields.io/gem/v/stat_power?include_prereleases)](https://rubygems.org/gems/stat_power)
+[![Gem Downloads](https://img.shields.io/gem/dt/stat_power)](https://rubygems.org/gems/stat_power)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.2-CC342D?logo=ruby&logoColor=white)](https://www.ruby-lang.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
 Native Ruby statistical power analysis and sample-size determination.
 
 > **Alpha release:** `stat_power` is under active development. The public API
@@ -17,13 +23,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.3
 ```
 
 With Bundler:
 
 ```ruby
-gem "stat_power", "0.1.0.alpha.1"
+gem "stat_power", "0.1.0.alpha.3"
 ```
 
 ## Status
@@ -41,9 +47,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.
 
@@ -105,29 +118,39 @@ freeze candidate.
 
 ## Development
 
-Install dependencies:
+Set up the checkout:
 
 ```bash
-bundle install
+bin/setup
 ```
 
-Run the test suite:
+Open a console with the library loaded:
 
 ```bash
-bundle exec rspec
+bin/console
 ```
 
-Run lint and signature validation:
+Run everything CI runs:
 
 ```bash
-bundle exec rubocop
-bundle exec rbs validate
+bundle exec rake verify
 ```
 
-Validate that the library loads:
+That is the same as running each check individually:
 
 ```bash
-ruby -Ilib -e 'require "stat_power"'
+bundle exec rspec          # specs
+bundle exec rubocop        # lint
+bundle exec rbs validate   # signature syntax
+bundle exec steep check    # lib/ type checked against sig/
+```
+
+Measure test coverage. Instrumentation roughly doubles the runtime, so it is
+opt-in; CI enforces a minimum in a dedicated job.
+
+```bash
+COVERAGE=1 bundle exec rspec
+open coverage/index.html
 ```
 
 Build the gem locally:
@@ -136,10 +159,36 @@ Build the gem locally:
 gem build stat_power.gemspec
 ```
 
+## Contributing
+
+Contributions are welcome. Because this is a numerical library, the bar is
+reproducibility: every statistical result must be justified by a published
+formula or an independently generated reference value.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow, the shape a new
+power-analysis family is expected to take, and how to supply reference values.
+
+Participation is governed by the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+### Found a wrong number?
+
+If `stat_power` disagrees with `pwr`, R, G*Power or a textbook, that is the
+highest-priority class of bug here. Open an issue using the **Numerical
+discrepancy** template.
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for supported versions and how to report a
+vulnerability privately. A numerically incorrect result is a bug, not a
+vulnerability; report those as ordinary issues.
+
 ## Mathematical conventions
 
 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/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