pwranova (version 1.0.3)

pwrcortest: Power Analysis for Pearson Correlation

Description

Computes statistical power, required total sample size, \(\alpha\), or the minimal detectable correlation coefficient for a Pearson correlation test. Two computational methods are supported: exact noncentral t (method = "t") and Fisher's z-transformation with normal approximation (method = "z").

Usage

pwrcortest(
  alternative = c("two.sided", "one.sided"),
  n_total = NULL,
  alpha = NULL,
  power = NULL,
  rho = NULL,
  method = c("t", "z"),
  bias_correction = FALSE,
  nlim = c(2, 10000)
)

Value

A one-row data.frame with class "cal_power", "cal_n", "cal_alpha", or "cal_es", depending on the solved quantity. Columns:

• df (only for method = "t")

• n_total, alpha, power

• rho, t_critical or z_critical

• ncp (noncentrality parameter or mean under the alternative: see Details)

Arguments

alternative

Character. Either "two.sided" or "one.sided".

n_total

Integer scalar. Total sample size (\(n\)). Must be \(\ge 3\) for method = "t" and \(\ge 4\) for method = "z". If NULL, the function solves for n_total.

alpha

Numeric in \((0,1)\). If NULL, it is solved for.

power

Numeric in \((0,1)\). If NULL, it is computed; if n_total is NULL, n_total is solved to attain this power.

rho

Numeric correlation coefficient in \((-1,1)\), nonzero. If NULL, rho is solved for given the other inputs.

method

Character. Either "t" (noncentral t-distribution) or "z" (Fisher's z transformation with normal approximation).

bias_correction

Logical. Applies only to method = "z". If TRUE, uses the bias-corrected Fisher z-transformation \(z_p = \operatorname{atanh}(r) + r/(2(n-1))\).

nlim

Integer vector of length 2. Search range of n_total when solving sample size.

Details

• Exactly one of n_total, rho, alpha, or power must be NULL; that quantity is then solved.

• For method = "t", computations are based on the noncentral t-distribution with noncentrality parameter \(\lambda = \tfrac{\rho}{\sqrt{1-\rho^2}} \sqrt{n}\).

• For method = "z", computations use Fisher's z transformation of the population correlation, \(z_\rho = \operatorname{atanh}(\rho)\). Let \(W = \sqrt{n-3}\, z\). Under the alternative hypothesis, \(W \sim \mathrm{Normal}(\mu,\,1)\) with \(\mu = \sqrt{n-3}\, z_\rho\). If bias_correction = TRUE, \(\rho\) is first bias-corrected before applying Fisher's transform. Critical values are taken from the central normal distribution under \(H_0:\rho=0\) (i.e., \(W \sim \mathrm{Normal}(0,1)\) under the null). The returned ncp equals \(\mu\).

• Validation against GPower: Results have been confirmed to match those produced by GPower for equivalent correlation tests using the noncentral t-distribution.

• Note: Results from method = "z" will not exactly match pwr::pwr.r.test, because pwr uses a hybrid approach combining the Fisher-z approximation with a t-based critical value.

Examples

# (1) Compute power for rho = 0.3, N = 50, two-sided test
pwrcortest(alternative = "two.sided", n_total = 50, rho = 0.3, alpha = 0.05)

# (2) Solve required N for target power, using Fisher-z method
pwrcortest(method = "z", rho = 0.2, alpha = 0.05, power = 0.8)

# (3) Solve minimal detectable correlation
pwrcortest(n_total = 60, alpha = 0.05, power = 0.9, rho = NULL)