stat_power 0.1.0.alpha.1

checksums.yaml

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

data/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## Unreleased
+
+## 0.1.0.alpha.1 - 2026-09-19
+
+### Added
+
+- Initial gem structure
+- RSpec, RuboCop, and Steep configuration
+- CI across supported Ruby versions
+- Project roadmap
+- Mathematical conventions
+- Standard normal PDF, CDF, survival function, and quantile utilities
+- Deterministic bracketed bisection root solver
+- Numerical domain and convergence error types
+- CRAN `pwr` compatibility and validation strategy
+- Normal-mean power analysis compatible with `pwr.norm.test`
+- Conventional Cohen effect-size lookup
+- Continuous and integer-required sample-size reporting
+- Cohen's h effect-size calculation for proportions
+- One-sample proportion power analysis compatible with `pwr.p.test`
+- Equal-size two-sample proportion power analysis compatible with `pwr.2p.test`
+- Unequal-size two-sample proportion power analysis compatible with `pwr.2p2n.test`
+- Dedicated result object for unequal two-group designs
+- Regularized incomplete beta special function
+- Adaptive Simpson quadrature
+- Central Student t PDF, CDF, survival, and quantile utilities
+- Noncentral Student t CDF and survival utilities
+- One-sample, paired, and equal-size two-sample t-test power analysis compatible with `pwr.t.test`
+- Unequal-size two-sample t-test power analysis compatible with `pwr.t2n.test`
+- Pearson correlation power analysis compatible with `pwr.r.test`
+- Central F PDF, CDF, survival, and quantile utilities
+- Noncentral F CDF and survival utilities

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Diogo Ribeiro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,153 @@
+# stat_power
+
+Native Ruby statistical power analysis and sample-size determination.
+
+> **Alpha release:** `stat_power` is under active development. The public API
+> may change before the first stable release. Pin an exact version in production
+> or research environments where reproducibility matters.
+
+## Installation
+
+The current release is a prerelease:
+
+```bash
+gem install stat_power --prerelease
+```
+
+or pin the exact alpha:
+
+```bash
+gem install stat_power -v 0.1.0.alpha.1
+```
+
+With Bundler:
+
+```ruby
+gem "stat_power", "0.1.0.alpha.1"
+```
+
+## Status
+
+The first compatibility target is the established CRAN `pwr` package. The
+implementation is native Ruby and is validated against published formulas and
+reference numerical results rather than being a line-by-line source port.
+
+Implemented compatibility currently includes:
+
+- `pwr.norm.test`
+- `pwr.p.test`
+- `pwr.2p.test`
+- `pwr.2p2n.test`
+- `pwr.t.test`
+- `pwr.t2n.test`
+- `pwr.r.test`
+
+The library also contains the numerical distribution machinery required for
+further power methods, including central/noncentral t and F distributions.
+
+See [docs/pwr_parity.md](docs/pwr_parity.md) for the full compatibility matrix.
+
+## Example
+
+```ruby
+require "stat_power"
+
+result = StatPower::TTest.two_sample(
+  effect_size: 0.5,
+  alpha: 0.05,
+  power: 0.8
+)
+
+result.sample_size
+# continuous observations required per group
+
+result.required_sample_size
+# smallest whole-number sample size per group
+```
+
+Power-analysis methods follow a common convention: one principal parameter is
+omitted and solved from the remaining values.
+
+For example, achieved power:
+
+```ruby
+result = StatPower::Correlation.solve(
+  correlation: 0.3,
+  sample_size: 50,
+  alpha: 0.05
+)
+
+result.power
+```
+
+## Goals
+
+- parity with the statistical families provided by CRAN `pwr`
+- idiomatic Ruby APIs
+- sample-size determination and achieved-power calculations
+- inverse power problems
+- effect-size utilities
+- explicit assumptions and numerical tolerances
+- independently reproducible numerical validation
+- later extensions beyond `pwr`
+
+## Alpha stability policy
+
+During the `0.1.0.alpha.*` series:
+
+- numerical correctness and validation take priority over API stability
+- method and result names may change when inconsistencies are found
+- every implemented statistical family should include independent reference tests
+- new CRAN `pwr` parity targets may be added between alpha releases
+
+The transition to beta will indicate that the public API is approaching a
+freeze candidate.
+
+## Development
+
+Install dependencies:
+
+```bash
+bundle install
+```
+
+Run the test suite:
+
+```bash
+bundle exec rspec
+```
+
+Run lint and signature validation:
+
+```bash
+bundle exec rubocop
+bundle exec rbs validate
+```
+
+Validate that the library loads:
+
+```bash
+ruby -Ilib -e 'require "stat_power"'
+```
+
+Build the gem locally:
+
+```bash
+gem build stat_power.gemspec
+```
+
+## Mathematical conventions
+
+See [docs/mathematical_conventions.md](docs/mathematical_conventions.md).
+
+## Roadmap
+
+See [ROADMAP.md](ROADMAP.md).
+
+## Releasing
+
+See [RELEASING.md](RELEASING.md).
+
+## License
+
+MIT.

data/RELEASING.md

@@ -0,0 +1,105 @@
+# Releasing stat_power
+
+This project uses prerelease versions until the public API is ready to stabilize.
+
+## One-time RubyGems trusted publisher setup
+
+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:
+
+- Gem name: `stat_power`
+- Repository owner: `DiogoRibeiro7`
+- Repository name: `stat_power`
+- Workflow filename: `release.yml`
+- Environment: `release`
+
+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.
+4. Build the gem locally:
+
+   ```bash
+   gem build stat_power.gemspec
+   ```
+
+5. Inspect the built package:
+
+   ```bash
+   gem specification stat_power-*.gem name version files --yaml
+   ```
+
+6. Install the built gem into a clean location:
+
+   ```bash
+   GEM_HOME="$(mktemp -d)" gem install stat_power-*.gem --no-document
+   ```
+
+7. Run a smoke test against the installed package:
+
+   ```bash
+   ruby -e 'require "stat_power"; p StatPower::VERSION'
+   ```
+
+8. Confirm the RubyGems pending/trusted publisher is configured for
+   `.github/workflows/release.yml` and the `release` environment.
+
+9. Create and push the release tag. The tag must match the version exactly:
+
+   ```bash
+   git checkout main
+   git pull --ff-only
+   git tag v0.1.0.alpha.1
+   git push origin v0.1.0.alpha.1
+   ```
+
+Pushing the tag triggers the release workflow. It validates that:
+
+- the tag matches `StatPower::VERSION`
+- the tagged commit is contained in `main`
+- the test suite passes
+- RuboCop passes
+- 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.
+
+## After publishing
+
+Verify the public installation path:
+
+```bash
+gem install stat_power --prerelease
+```
+
+Then confirm:
+
+```bash
+ruby -e 'require "stat_power"; puts StatPower::VERSION'
+```
+
+The expected output for the first alpha is:
+
+```text
+0.1.0.alpha.1
+```
+
+## 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.
+
+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.

data/ROADMAP.md

@@ -0,0 +1,99 @@
+# Roadmap
+
+## 0.1.x — CRAN pwr parity and numerical foundations
+
+### Foundations
+
+- [x] Core result and error types
+- [x] Standard normal distribution utilities
+- [x] Root-finding infrastructure
+- [x] Conventional Cohen effect-size lookup
+- [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] F and noncentral F utilities
+
+### pwr compatibility
+
+- [x] `pwr.norm.test`
+- [x] `pwr.p.test`
+- [x] `pwr.2p.test`
+- [x] `pwr.2p2n.test`
+- [x] `pwr.t.test`
+- [x] `pwr.t2n.test`
+- [ ] `pwr.anova.test`
+- [x] `pwr.r.test`
+- [ ] `pwr.chisq.test`
+- [ ] `pwr.f2.test`
+- [x] `ES.h`
+- [ ] `ES.w1`
+- [ ] `ES.w2`
+- [ ] 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`
+- Published Cohen examples
+- Cross-validation against statsmodels where applicable
+- Documented numerical tolerance policy
+- Stable result objects
+- User-facing method documentation
+- Benchmarks
+
+## 0.3.x — Beyond pwr: regression and richer designs
+
+- Additional regression power models
+- Partial and semi-partial correlation
+- Unequal allocation helpers
+- Attrition and dropout adjustments
+
+## 0.4.x — Equivalence and non-inferiority
+
+- TOST
+- One-sided non-inferiority tests
+- Equivalence for means and proportions
+
+## 0.5.x — Repeated and clustered designs
+
+- Repeated-measures designs
+- Mixed designs
+- Cluster-randomised trials
+- Design effects
+- Intra-cluster correlation
+- Unequal cluster sizes
+
+## 0.6.x — Precision-based design
+
+- Confidence-interval width targets
+- Mean, proportion, and difference precision
+
+## 0.7.x — Simulation-based power
+
+- User-defined simulation models
+- Monte Carlo uncertainty estimates
+- Reproducible random seeds
+- Parallel execution interface
+
+## 0.8.x — pwrss-inspired extensions
+
+- Broader sample-size methods
+- Minimum detectable effects
+- Additional test families selected from mature reference implementations
+
+## 0.9.x — API hardening
+
+- Complete validation matrix
+- Performance review
+- Documentation audit
+- API stability review
+
+## 1.0.0
+
+- Stable public API
+- Complete user and mathematical documentation
+- Reproducible validation suite
+- RubyGems release

data/docs/mathematical_conventions.md

@@ -0,0 +1,88 @@
+# Mathematical conventions
+
+This document defines the conventions that all implementations in `stat_power` must follow.
+
+## Probability and significance
+
+The significance level is denoted by \(\alpha\), with \(0 < \alpha < 1\).
+
+Statistical power is
+
+\[
+1 - \beta,
+\]
+
+where \(\beta\) is the Type II error probability.
+
+Unless a method explicitly states otherwise, two-sided tests split \(\alpha\) equally across both tails.
+
+## Sample size
+
+For compatibility and numerical validation, solvers retain the continuous
+sample-size solution produced by the underlying power equation.
+
+A result may additionally expose the smallest design-valid integer sample size
+not below that solution. This distinction is explicit: continuous values are
+useful for parity checks and mathematical work, while integer values are useful
+for study design.
+
+For two-group designs, total sample size and per-group sample size must be
+distinguished explicitly in the public API and documentation.
+
+## Effect sizes
+
+Standardised effect sizes follow conventional definitions:
+
+- Cohen's \(d\) for standardised mean differences
+- Cohen's \(h\) for differences between proportions on the arcsine scale
+- Cohen's \(f\) for ANOVA
+- Cohen's \(f^2\) for regression
+- Cohen's \(w\) for chi-square tests
+
+Conversions must document their assumptions and must not silently assume interchangeable effect-size definitions.
+
+## Tail conventions
+
+Alternatives use explicit names:
+
+- `two_sided`
+- `greater`
+- `less`
+
+Compatibility layers may accept reference-package spellings such as
+`"two.sided"`, but results are normalised to the Ruby convention.
+
+## Numerical solving
+
+Inverse power problems are solved numerically only when a closed-form expression is unavailable or undesirable.
+
+Root-finding routines must:
+
+1. define a mathematically valid search interval,
+2. verify that the requested solution is identifiable,
+3. fail clearly when the target cannot be bracketed,
+4. expose deterministic tolerances,
+5. be covered by reference-value tests.
+
+## Precision and tolerances
+
+Reference comparisons must distinguish between:
+
+- exact algebraic identities,
+- floating-point agreement,
+- agreement with external software that uses different numerical algorithms.
+
+Tolerance values belong in tests or numerical configuration, not as undocumented magic constants.
+
+## Validation
+
+Every implemented test family must include at least one independently reproducible validation source, preferably two.
+
+CRAN `pwr` is the initial compatibility target. Its documented statistical
+models and numerical results are reference points, but `stat_power` uses an
+independent native Ruby implementation.
+
+Suitable additional references include peer-reviewed formulas, established
+statistical textbooks, Python implementations, and published G*Power examples.
+
+Agreement with another software package is evidence of consistency, not a substitute for verifying the underlying mathematics.

data/docs/pwr_parity.md

@@ -0,0 +1,62 @@
+# CRAN pwr parity
+
+`stat_power` uses CRAN `pwr` as its first compatibility and validation target.
+
+The implementation is native Ruby. The project does not translate or copy the
+GPL-licensed R source line by line. Public statistical definitions, documented
+behaviour, published formulas, and numerical outputs are used as independent
+reference points.
+
+## Compatibility target
+
+| CRAN pwr function | stat_power target | Status |
+| --- | --- | --- |
+| `pwr.norm.test` | `StatPower::NormalMean.solve` | Implemented |
+| `cohen.ES` | `StatPower::EffectSize::Conventional.resolve` | Implemented for conventional values |
+| `pwr.p.test` | `StatPower::Proportion.one_sample` | Implemented |
+| `pwr.2p.test` | `StatPower::Proportion.two_sample` | Implemented |
+| `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.r.test` | `StatPower::Correlation.solve` | Implemented |
+| `pwr.chisq.test` | chi-square power | Planned |
+| `pwr.f2.test` | general linear-model power | Planned |
+| `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 |
+
+## Solver convention
+
+As in `pwr`, a power-analysis family solves one omitted quantity from the
+remaining quantities. Ruby uses explicit keyword arguments and `nil` for the
+unknown parameter.
+
+For example:
+
+```ruby
+StatPower::NormalMean.solve(
+  effect_size: 0.5,
+  alpha: 0.05,
+  power: 0.8
+)
+```
+
+returns the continuous sample-size solution. Call
+`required_sample_size` on the result to obtain the smallest integer not below
+that solution.
+
+## Validation policy
+
+Each migrated family should include:
+
+1. formula-level tests where a closed form or independently derived expression
+   is available,
+2. numerical reference tests against CRAN `pwr`,
+3. edge and invalid-domain tests,
+4. inverse-problem tests for every parameter the family can solve.
+
+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.