| Title: | Plan and Justify Sample Size Before Data Collection |
|---|---|
| Description: | Plans and documents sample size for a study before data collection, using validated power engines. |
| Authors: | emresaglamci0 [aut, cre] |
| Maintainer: | emresaglamci0 <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.0.0.9000 |
| Built: | 2026-11-16 19:36:57 UTC |
| Source: | https://github.com/emresaglamci0/r-paketi |
Sample size so that the confidence interval of one proportion has half-width
e (Cochran's normal-approximation formula, n0 = z^2 p (1 - p) / e^2).
Corrections are applied in this order, with one final rounding up: finite
population correction n0 / (1 + (n0 - 1) / N) (only if N is given), then
* deff, then / (1 - dropout). The order is a method decision from the
package design; no published source for putting the finite population
correction before the design effect was found. Applying the design effect
first would give a smaller n (407 instead of 463 for e = .05, N = 1000,
deff = 1.5, dropout = .1), so this order errs on the safe side. Some
sources use n0 / (1 + n0 / N); before deff and dropout the difference is at most 1 participant.
plan_precision(p = 0.5, e, conf_level = 0.95, N = NULL, dropout = 0, deff = 1)plan_precision(p = 0.5, e, conf_level = 0.95, N = NULL, dropout = 0, deff = 1)
p |
Expected proportion, strictly between 0 and 1. Default 0.5. |
e |
Half-width of the confidence interval, above 0 and below
|
conf_level |
Confidence level, strictly between 0 and 1. |
N |
Population size (a whole number, at least 2) or |
dropout |
Expected nonresponse or dropout proportion, in [0, 1). |
deff |
Design effect, at least 1. |
p = 0.5 is the most conservative value (largest n). The Wald (normal)
approximation is weak when p is near 0 or 1 and when n is small: for p = .1
and n = 139 the true coverage of a nominal 95% interval is about .93, and
for p = .02 and n = 31 about .47. e is the half-width of the interval, not
the full width. Precision is not power: this plan does not test a
hypothesis, so sensitivity() does not accept it.
A list of class plansize_precision; n_required is the integer
recruitment target.
Computes the analytic n for an independent two-sample t test, a paired (repeated-measures) t test, the overall F test of a one-way ANOVA with k equal groups, a comparison of two independent proportions (pooled-SE z test) or a Pearson correlation (Fisher z test of H0: rho = 0) or a chi-square test of independence (Cohen's w), then applies the design effect and dropout correction with one final ceiling.
plan_study( test = "t_independent", effect, r = NULL, k = NULL, p1 = NULL, p2 = NULL, rows = NULL, cols = NULL, predictors = NULL, tested = NULL, r2_covariates = NULL, effect_type = c("f", "eta2"), effect_basis = c("unknown", "prior_study", "pilot", "smallest_of_interest", "convention", "observed"), effect_source = NULL, alpha = 0.05, power = 0.8, alternative = c("two.sided", "one.sided"), dropout = 0, deff = 1 )plan_study( test = "t_independent", effect, r = NULL, k = NULL, p1 = NULL, p2 = NULL, rows = NULL, cols = NULL, predictors = NULL, tested = NULL, r2_covariates = NULL, effect_type = c("f", "eta2"), effect_basis = c("unknown", "prior_study", "pilot", "smallest_of_interest", "convention", "observed"), effect_source = NULL, alpha = 0.05, power = 0.8, alternative = c("two.sided", "one.sided"), dropout = 0, deff = 1 )
test |
|
effect |
Effect size, a single number: positive for the t tests and ANOVA; not used with |
r |
Only for |
k |
Number of equal-sized groups, a single whole number of at least 2.
Required for |
p1, p2
|
Expected proportions in group 1 and group 2, each strictly between 0 and 1 and
different. Required for |
rows, cols
|
Number of rows and columns of the contingency table, each a single whole number
from 2 to 1000. Required for |
predictors |
Number of predictors in the regression model, a single whole number from
1 to 1000. Required for |
tested |
Only for |
r2_covariates |
Only for |
effect_type |
For |
effect_basis |
Where the effect came from: "unknown" (default), "prior_study",
"pilot", "smallest_of_interest", "convention" or "observed". "unknown" and
"convention" give a warning of class |
effect_source |
Optional free-text source of the effect. In the methods text, parentheses inside it are shown as square brackets. |
alpha |
Significance level, in (0, 1). |
power |
Target power, from 0.01 to 0.99 and greater than alpha. |
alternative |
|
dropout |
Expected dropout proportion, in [0, 1). |
deff |
Design effect, at least 1. |
For reg_overall, print also shows the participants needed if predictors are random (Sampson's random model via DMAR). Measured predictors, as in most observational studies, are random, and recruiting that number keeps the target power. The line is absent when the suggested package DMAR is not installed, when the plan n is above 100,000, or when DMAR fails. The plan n and the methods text keep the fixed-predictor assumption.
For "prop_two", pwrss returns an already rounded n, so the dropout and design effect correction is applied to that rounded n; the recruitment target can be a few participants higher than a single final rounding would give.
For "cor_pearson", n uses the Fisher z approximation without the bias correction of pwr::pwr.r.test (about 1 participant higher), so results can differ slightly from pwr or G*Power; the approximation is rough below about 10 participants but errs on the safe side.
For "chisq_indep", n is for Pearson's chi-square test without continuity correction; in R use chisq.test(x, correct = FALSE) for 2 x 2 tables, as the default Yates correction lowers power.
For "reg_overall", n is the total for the overall F test of a multiple regression (H0: R squared = 0), with groups 1. The F model treats the predictors as fixed; with random predictors the power is slightly lower (about 0.78 instead of 0.80 in a simulation with R2 = 0.13 and 3 predictors). Tests of single predictors are covered only through "reg_partial" with tested = 1.
For "reg_partial", n is the total for the F test of the R squared change of tested of predictors predictors (H0: Delta R squared = 0), with groups 1. pwrss uses the noncentrality f squared * n (fixed predictors, as in G*Power's "R2 increase, fixed model"); this was checked against a fixed-design simulation. pwr::pwr.f2.test uses Cohen's f squared * (u + v + 1) instead, a different method that gives 0 to predictors - tested more participants; do not treat it as a reference for this test. The F model treats the predictors as fixed; with random predictors the power is lower (about 0.77 instead of 0.80 in a simulation, and lower still with a small n and a large R squared).
A list of class plansize_plan.
Print a methods paragraph
## S3 method for class 'plansize_methods' print(x, ...)## S3 method for class 'plansize_methods' print(x, ...)
x |
A |
... |
Unused. |
x, invisibly.
Print a sample size plan
## S3 method for class 'plansize_plan' print(x, ...)## S3 method for class 'plansize_plan' print(x, ...)
x |
A |
... |
Unused. |
x, invisibly.
Print a precision plan
## S3 method for class 'plansize_precision' print(x, ...)## S3 method for class 'plansize_precision' print(x, ...)
x |
A |
... |
Unused. |
x, invisibly.
Print a sensitivity table
## S3 method for class 'plansize_sensitivity' print(x, ...)## S3 method for class 'plansize_sensitivity' print(x, ...)
x |
A |
... |
Unused. |
x, invisibly.
Print a simulation check
## S3 method for class 'plansize_simulation' print(x, ...)## S3 method for class 'plansize_simulation' print(x, ...)
x |
A |
... |
Unused. |
x, invisibly.
For each combination of recruited per-group n and power, returns the smallest standardized effect detectable after dropout and design effect.
sensitivity(plan, n = NULL, power = c(0.8, 0.9, 0.95))sensitivity(plan, n = NULL, power = c(0.8, 0.9, 0.95))
plan |
A |
n |
Recruited per-group sample sizes (participants for "t_paired", "cor_pearson" and "chisq_indep"). Defaults to |
power |
Target powers, each from 0.01 to 0.99 and greater than the plan's alpha. |
n_effective is floor(n * (1 - dropout) / deff), rounded down, so the
minimum detectable effect for a plan with dropout can be slightly above the
planned effect (conservative). With a very large planned effect, the higher powers in the default grid may be infeasible; pass a smaller power grid.
A data frame of class plansize_sensitivity with columns
n_recruited, n_effective, power, mde. For "anova_oneway" mde is in the
plan's effect_type (f or eta squared); the unit is kept in attr(, "effect_type").
For "prop_two" mde is the detectable p1 with p2 fixed, in the direction of the planned difference.
For "cor_pearson" mde is the detectable r with the sign of the planned correlation.
For "chisq_indep" mde is the detectable Cohen's w.
For "reg_partial" mde is in the plan's effect_type (R squared change or f squared of the tested predictors); the unit is kept in attr(, "effect_type").
Draws reps studies with the planned effect, runs the planned test on each and compares the
share of significant results (empirical power) with the analytic power pwrss gives for the same n.
This checks that the formula holds at this n under normal, binomial or multinomial data and a
correct effect; it says nothing about real data and it is not the observed power.
simulate_power( plan, n = NULL, reps = 10000, seed = NULL, predictor_type = c("fixed", "random") )simulate_power( plan, n = NULL, reps = 10000, seed = NULL, predictor_type = c("fixed", "random") )
plan |
A |
n |
Sample size to simulate: per group (the whole sample for |
reps |
Number of simulated studies, a whole number of at least 100. The rule of the package
needs at least 10000; with fewer, |
seed |
Optional whole number. With a seed the function leaves your random number stream unchanged; without one it uses and advances your stream like any random R function. |
predictor_type |
|
status is "pass" when empirical power is within 0.02 of the analytic power and at
least the target minus 0.02, "warn" when it is more than 0.02 above the analytic power (the
plan is safe; the formula is conservative at this n) and "fail" otherwise. "warn" is
expected for two-sided correlations from r = .6 and one-sided from r = .5 (Fisher z is
conservative; for example a correlation of .8 with n = 10), and for two proportions with a small p (such as .05 and
.01), where exact binomial power exceeds the normal approximation, and for a small chi-square
table with w from about .5 (such as 2 x 2 or 3 x 3 with w = .5, or 2 x 3 with w = .8 and
n = 16). Do not widen the 0.02.
A plansize_simulation list: test, n, reps, seed, predictor_type, power_sim, mc_se, ci, power_analytic, reference, diff, target, status, pass, notes (reference is "pwrss" or
"dmar"; notes are codes the print method explains).
Turns a plan into a copyable methods paragraph in English or Turkish.
write_methods(plan, lang = NULL)write_methods(plan, lang = NULL)
plan |
A |
lang |
|
The paragraph is valid only for a plan made before data collection.
A single string of class plansize_methods.