Getting started with paweh

What problem does `paweh` solve?

paweh supports prospective power and minimum-sample-size-necessary (MSSN) calculations for genetic association study designs. It is intended for the stage at which a researcher is deciding what data to collect, how many subjects or trios are needed, and how sensitive that design may be to model assumptions.

The relevant design inputs differ across studies. They can include sample size, allele frequency, genotype relative risk, genotype or phenotype misclassification, locus heterogeneity, family-based transmission, extreme-phenotype sampling, and correlation among quantitative traits. These quantities are assumptions or design targets, not estimates produced from raw genomic data by paweh.

Power and MSSN answer inverse questions

Power: given a sample size and model, what probability of rejection is expected under the specified alternative?
MSSN: given a target power and model, how many cases, controls, trios, or total individuals are required?

For example, suppose pilot work supplies conditional genotype probabilities for cases and controls. A compact power calculation is:

g_case <- c(0.25, 0.50, 0.25)
g_control <- c(0.36, 0.48, 0.16)

starter_power <- cc_power(
  N_case = 500,
  alpha = 0.05,
  input_mode = "model_free",
  g1 = g_case,
  g0 = g_control,
  k = 1,
  verbose = FALSE
)

starter_power$tests$genotypes$power
#> [1] 0.9852151

The corresponding cc_mssn() calculation reverses the design question by replacing N_case with a target power.

Five study-design families

Case-control association

Cases and controls are compared using a genotype chi-square or trend test. The canonical cc_power() and cc_mssn() interfaces support model-based and model-free inputs, along with compatible heterogeneity and error modifiers.

Affected-child trios

The transmission disequilibrium test (TDT) compares transmitted and non-transmitted alleles in affected-child trios. tdt_power() and tdt_mssn() report power or required trio counts under distinct no-error, phenotype-misclassification, and locus-heterogeneity scenarios.

Quantitative traits

For continuous traits, paweh supports one-way genotype-group ANOVA, threshold-selected genotype chi-square designs, and multivariate designs using Pillai MANOVA or joint threshold selection.

Sequencing-based designs

For fixed-depth sequencing studies, cc_ngs_power() and cc_ngs_mssn() support case-control designs, while tdt_ngs_power() and tdt_ngs_mssn() support TDT1-NGS designs. ngs_genotype_error_matrix() constructs the sequencing-to-called-genotype transition matrix used by supported workflows; these functions do not process FASTQ, BAM, or VCF files.

LRTae validation/error-aware designs

lrtae_ncp(), lrtae_power(), and lrtae_mssn() provide prospective error-aware case-control design calculations with validation data. They do not fit an observed-data likelihood, and LTTae is not implemented.

Model-based and model-free inputs

These modes locate the scientific assumptions in different places.

For case-control studies, model-based input uses prevalence, disease-allele frequency, genotype relative risk, and mode of inheritance. Model-free input uses supplied conditional genotype probabilities: g1 for cases or affected subjects and g0 for controls or unaffected subjects.

For the TDT, model-based input uses pd, prev, R1, R2, and delta_prime. Model-free input starts from expected transmission and non-transmission counts (ET and ENT), with the associated number of trios needed for MSSN calculations.

Model-free input is useful when these quantities come from pilot data, prior publications, external calculations, or direct design assumptions. It does not remove assumptions; it moves them into the supplied conditional quantities.

Where should I start?

Scientific design	Canonical starting functions	Detailed vignette
Case-control association	`cc_power()`, `cc_mssn()`	Case-Control Study Design
Affected-child trios	`tdt_power()`, `tdt_mssn()`	TDT Study Design
Continuous single-trait QTL	`qtl_anova_power()`, `qtl_anova_mssn()`	Quantitative-Trait Study Design
Extreme-trait QTL	`qtl_threshold_chisq_power()`, `qtl_threshold_chisq_mssn()`	Quantitative-Trait Study Design
Multivariate quantitative traits	`qtl_multivariate_power_full()`, `qtl_multivariate_mssn_full()`	Quantitative-Trait Study Design
Sequencing case-control	`cc_ngs_power()`, `cc_ngs_mssn()`	Sequencing Study Design
Sequencing TDT	`tdt_ngs_power()`, `tdt_ngs_mssn()`	Sequencing Study Design
Error-aware case-control / LRTae	`lrtae_ncp()`, `lrtae_power()`, `lrtae_mssn()`	LRTae Power and Sample-Size Design

Why Bioconductor?

paweh is being prepared for Bioconductor because it provides prospective study-design infrastructure for genetic and genomic association research, including sequencing-based designs. These calculations complement downstream genomic analysis by examining operating characteristics before data generation or collection. The package does not currently claim sequencing-file, genomic-range, or SummarizedExperiment integration.

Published validation philosophy

The remaining vignettes distinguish three uses of literature:

Published-example reproduction: a reported analytic result is evaluated with a matching paweh design.
Published methodological context: a paper explains an important risk or method, but its exact analysis is not claimed to be reproduced.
Motivating published application: an application motivates a design question while using a different statistical procedure.

The study-design vignettes reproduce validated examples across case-control, TDT, and multivariate quantitative-trait settings and then extend those fixed designs with sensitivity calculations.

Installation

Once paweh is available through Bioconductor, the standard installation path will be:

if (!requireNamespace("BiocManager", quietly = TRUE)) {
  install.packages("BiocManager")
}
BiocManager::install("paweh")

No installation is performed while this vignette is built.

Session information

sessionInfo()
#> R version 4.6.1 (2026-06-24)
#> Platform: aarch64-apple-darwin23
#> Running under: macOS Tahoe 26.6.2
#> 
#> Matrix products: default
#> BLAS:   /Library/Frameworks/R.framework/Versions/4.6/Resources/lib/libRblas.0.dylib 
#> LAPACK: /Library/Frameworks/R.framework/Versions/4.6/Resources/lib/libRlapack.dylib;  LAPACK version 3.12.1
#> 
#> locale:
#> [1] C.UTF-8/C.UTF-8/C.UTF-8/C/C.UTF-8/C.UTF-8
#> 
#> time zone: America/New_York
#> tzcode source: internal
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] paweh_0.99.0     BiocStyle_2.40.0
#> 
#> loaded via a namespace (and not attached):
#>  [1] gtable_0.3.6        jsonlite_2.0.0      dplyr_1.2.1        
#>  [4] compiler_4.6.1      BiocManager_1.30.27 tidyselect_1.2.1   
#>  [7] dichromat_2.0-1     jquerylib_0.1.4     systemfonts_1.3.2  
#> [10] scales_1.4.0        textshaping_1.0.5   yaml_2.3.12        
#> [13] fastmap_1.2.0       ggplot2_4.0.3       R6_2.6.1           
#> [16] generics_0.1.4      knitr_1.51          htmlwidgets_1.6.4  
#> [19] tibble_3.3.1        bookdown_0.47       desc_1.4.3         
#> [22] bslib_0.12.0        pillar_1.11.1       RColorBrewer_1.1-3 
#> [25] rlang_1.3.0         cachem_1.1.0        xfun_0.60          
#> [28] fs_2.1.0            sass_0.4.10         S7_0.2.2           
#> [31] otel_0.2.0          cli_3.6.6           pkgdown_2.2.1      
#> [34] magrittr_2.0.5      digest_0.6.39       grid_4.6.1         
#> [37] mvtnorm_1.4-2       lifecycle_1.0.5     vctrs_0.7.3        
#> [40] evaluate_1.0.5      glue_1.8.1          farver_2.1.2       
#> [43] ragg_1.5.2          rmarkdown_2.31      pkgconfig_2.0.3    
#> [46] tools_4.6.1         htmltools_0.5.9

paweh package authors

What problem does paweh solve?