https://github.com/centerforopenscience/rphbpower

https://github.com/centerforopenscience/rphbpower

Last synced: 4 months ago
JSON representation

• Host: GitHub
• URL: https://github.com/centerforopenscience/rphbpower
• Owner: CenterForOpenScience
• License: other
• Created: 2025-06-11T17:45:27.000Z (7 months ago)
• Default Branch: main
• Last Pushed: 2025-07-24T16:06:03.000Z (6 months ago)
• Last Synced: 2025-07-27T08:59:25.407Z (6 months ago)
• Language: R
• Size: 352 KB
• Stars: 0
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.Rmd
  • License: LICENSE

Awesome Lists containing this project

README

          
---

output: github_document

---

```{r, include = FALSE}

knitr::opts_chunk$set(

  collapse = TRUE,

  comment = "#>",

  fig.path = "man/figures/README-",

  out.width = "100%"

)

# The library call is here for knitting, but users should follow install instructions.

# library(rphbPower) 

```

# rphbPower - Unified Statistical Power Analysis Framework Package

A comprehensive R framework for a priori statistical power analysis. It provides easy-to-use functions for 11 different statistical methods, all unified by a common effect size metric and a philosophy of conservative study planning.

## Framework Overview

This package provides power analysis for a diverse suite of statistical methods unified under a **partial correlation framework**. All analyses convert common effect sizes (e.g., Cohen's d, f²) into partial correlations (`r_partial`), enabling direct and intuitive comparisons of effect magnitude across all included methods.

The framework is built on two core principles:

1. **Unified Effect Size**: Using `r_partial` as the common metric simplifies interpretation and promotes a deeper understanding of effect sizes, regardless of the statistical test being used.

2. **Conservative Planning**: A built-in **0.75 discount factor** is automatically applied to all user-provided effect sizes. This encourages prudent and realistic study planning, helping to prevent underpowered research that can result from overly optimistic effect size estimations.

## Core Features

- **11 Validated Modules**: Covers a wide range of common statistical tests

- **Unified Effect Size Metric**: All calculations are based on partial correlations (`r_partial`)

- **Parameter Auto-Detection**: For any given test, provide any two of (effect size, sample size, power) and the framework will solve for the third

- **Built-in Effect Size Conversion**: Automatically converts from Cohen's d, f², R², and η² into `r_partial`

- **Conservative by Default**: A 0.75 discount factor is automatically applied to effect size inputs to encourage robust planning

## Quick Start

### 1. Install and Load the Package

The package can be installed directly from the Center For Open Science GitHub repository.

```{r install, eval=FALSE}

# install.packages("devtools") # Run this if you don't have devtools

devtools::install_github("CenterForOpenScience/rphbPower", build_vignettes = TRUE)

library(rphbPower)

```

### 2. Run the Power Analysis

The functions follow a consistent pattern. Provide the parameters you know, and leave the one you want to find as NULL.

```{r basic_examples, eval=FALSE}

# Example 1: Solve for required sample size (N)

result_n <- linear_regression_power(r_partial = 0.25, power = 0.8, n_predictors = 2)

print(result_n$n)

# Example 2: Solve for the power of a planned study

result_power <- linear_regression_power(r_partial = 0.25, n = 121, n_predictors = 2)

print(result_power$power)

```

### 3. Use Any Effect Size

The `effect_input` and `effect_type` arguments allow you to use effect sizes directly from the literature. The 0.75 discount factor will be applied automatically.

```{r effect_conversion, eval=FALSE}

# Use a Cohen's d of 0.5 from a previous study

result <- linear_regression_power(

  effect_input = 0.5,

  effect_type = "d",

  power = 0.8,

  n_predictors = 2

)

print(result)

```

## Available Analysis Methods

### Basic and Regression Methods

- **Correlation**: `correlation_power()`

- **Linear Regression**: `linear_regression_power()`

- **Logistic Regression**: `logistic_regression_power()`

### Longitudinal Methods

- **Cross-Lagged Panel**: `cross_lagged_panel_power()`

- **Fixed Effects**: `fixed_effects_power()`

- **Repeated Measures**: `repeated_measures_power()`

### Mediation Methods

- **Mediation (Regression)**: `mediation_regression_power()`

- **Mediation (SEM)**: `mediation_sem_power()`

### Advanced Methods

- **Multilevel Models**: `mixed_models_power()`

- **SEM (Direct Effects)**: `sem_direct_effects_power()`

- **Wilcoxon Signed-Rank Test**: `wilcoxon_signed_rank_power()`

## Method Selection Guide

### By Research Design

- **Single predictor, continuous outcome** → Linear regression

- **Multiple predictors, continuous outcome** → Linear regression (multiple)

- **Binary/categorical outcome** → Logistic regression

- **Mediation hypotheses** → Mediation regression or SEM

- **Clustered/nested data** → Multilevel models

- **Complex structural models with latent vars** → SEM direct effects

- **Simple bivariate association** → Correlation

### By Data Characteristics

- **Normal, continuous variables** → Linear regression methods

- **Hierarchical/grouped data** → Multilevel models

- **Longitudinal/panel data** → Cross-lagged, fixed effects, repeated measures

- **Latent variable models** → SEM approaches

## Sample Size Planning Guidelines

A critical reality in study planning is that model complexity significantly impacts sample size requirements. With the corrected engine, the impact of adding covariates is now estimated more accurately.

**Example Impact** (Effect Size r = 0.20, Target Power = 80%):

- **Correlation (1 predictor)**: ~192 participants

- **Regression (5 predictors)**: ~192 participants (+0% increase)

- **Regression (10 predictors)**: ~197 participants (+3% increase)

This framework helps you account for this complexity directly in your power analysis.

## Framework Status

- **Current Version**: 2.2

- **Mathematical Status**: All 11 modules have been re-engineered and have passed comprehensive validation tests. The framework is considered complete and robust.

- **Validation**: 100% pass rate achieved across all modules against external benchmarks or internal consistency checks.

## Documentation Structure

For detailed tutorials and guides, refer to the vignettes accessed through `browseVignettes("rphbPower")`:

- **Getting Started**: Installation and basic usage

- **Effect Size Guidelines**: Guidance on choosing an appropriate effect size

- **Method Selection Guide**: In-depth help for choosing the right analysis

- **Quick Reference Guide**: A fast lookup for functions and parameters

- **Troubleshooting**: Solutions for common issues