Skip to contents

Power of the MFET

Source: R/power_modified.R
power_modified.Rd

Computes the unconditional power of the MFET at response rates \((\pi_1, \pi_2)\), i.e. the probability of rejecting \(H_0\): OR = \(\theta_0\) when the true success probabilities are \(\pi_1\) (group 1) and \(\pi_2\) (group 2). The test is defined by the \(\gamma_0\) threshold and the test frame supplied. Optionally restricts to the superiority sub-region where the observed rate in group 2 exceeds that in group 1. Computed as the bilinear form \(p_u^\top R \, p_v\) (optionally masked to the superiority sub-region), the same reduction local_size_modified() uses, where \(R\) is the rejection matrix from .build_rejection_matrix() and \(p_u\), \(p_v\) are the binomial probability vectors at \(\pi_1\), \(\pi_2\).

Usage

power_modified(
  p,
  .gamma0,
  .odds_ratio,
  .m,
  .n,
  .df,
  .alpha,
  .precision,
  .superiority,
  .rejection_matrix = NULL
)

Arguments

p

Length-2 numeric vector \((\pi_1, \pi_2)\): success probability in group 1 (\(\pi_1\)) and group 2 (\(\pi_2\)) at which power is evaluated.

.gamma0

The \(\gamma_0\) threshold: boundary values in the test frame are rejected only when their randomisation probability exceeds this value. Typically the output of optimise_gamma0().

.odds_ratio

Null hypothesis odds ratio \(\theta_0\) used to build the test frame. The power is evaluated at the response rates \((\pi_1, \pi_2)\) supplied in p, against this null.

.m

Number of trials in group 1.

.n

Number of trials in group 2.

.df

Test frame (data frame) generated by construct_test_frame(), containing critical values \(c_1\), \(c_2\) and randomisation probabilities \(\gamma_1\), \(\gamma_2\) for every possible total \(T\).

.alpha

Nominal significance level \(\alpha\). No default.

.precision

Numerical precision. No default.

.superiority

Logical. If TRUE, power is computed only over tables where the observed rate in group 2 exceeds that in group 1. Defaults to FALSE.

.rejection_matrix

Optional prebuilt rejection matrix from .build_rejection_matrix(). Defaults to NULL, in which case the matrix is built internally from .df and .gamma0. Supply a prebuilt matrix when calling repeatedly with the same test frame and \(\gamma_0\) (e.g. across a grid of \(\pi_2\) values at fixed \(\gamma_0\), as in a power curve) to avoid rebuilding it on every call. If supplied, it must correspond to the same .df and .gamma0 passed alongside it; this is not checked.

Value

A single numeric value: the power of the MFET at the response rates \((\pi_1, \pi_2)\), in \([0, 1]\).

See also

power_asymptotic(), power_probability(), power_randomised(), power_conservative() for the power under alternative tests; local_size_modified() for the size of the modified Fisher exact test as a function of the nuisance parameter; modified_fisher_exact_test() for the main user-facing function.

Other power: power_asymptotic(), power_conservative(), power_probability(), power_randomised()

Other modified: construct_test_frame(), local_size_modified(), modified_fisher_exact_test(), optimise_gamma0(), size_modified()

Examples

df <- construct_test_frame(.odds_ratio = 1, .m = 6, .n = 4,
                           .alpha = 0.05, .precision = 1e-3)
g0 <- optimise_gamma0(.odds_ratio = 1, .m = 6, .n = 4, .alpha = 0.05,
                      .precision = 1e-3, .method = "zoom", .maze = 10,
                      .zoom_iter = 6)
# Power against pi1 = 0.2, pi2 = 0.6:
power_modified(p = c(0.2, 0.6), .gamma0 = g0, .odds_ratio = 1, .m = 6,
           .n = 4, .df = df, .alpha = 0.05, .precision = 1e-3,
           .superiority = FALSE)
#> [1] 0.1755824