Package 'paweh'

Specialized Case-Control Genotype Misclassification Functions

Description

Convenience functions for genotype-only case-control chi-square calculations under conditional model-based genotype frequencies and genotype misclassification. These functions are narrower than cc_mssn and cc_power: they compute only the genotype chi-square test for one specific misclassification model.

Usage

cc_chisq_mssn_genotype_misclassification_1p(
  power,
  alpha,
  prev,
  pd,
  R2,
  MOI = c("M", "D", "Rec"),
  k = 1,
  e = 0,
  verbose = TRUE
)

cc_chisq_power_genotype_misclassification_1p(
  N_case,
  alpha,
  prev,
  pd,
  R2,
  MOI = c("M", "D", "Rec"),
  k = 1,
  e = 0,
  verbose = TRUE
)

cc_chisq_mssn_genotype_misclassification_2p(
  power,
  alpha,
  prev,
  pd,
  R2,
  MOI = c("M", "D", "Rec"),
  k = 1,
  e1 = 0,
  e2 = 0,
  verbose = TRUE
)

cc_chisq_power_genotype_misclassification_2p(
  N_case,
  alpha,
  prev,
  pd,
  R2,
  MOI = c("M", "D", "Rec"),
  k = 1,
  e1 = 0,
  e2 = 0,
  verbose = TRUE
)

cc_chisq_mssn_genotype_misclassification_3p(
  power,
  alpha,
  prev,
  pd,
  R2,
  MOI = c("M", "D", "Rec"),
  k = 1,
  e01 = 0,
  e02 = 0,
  e03 = 0,
  verbose = TRUE
)

cc_chisq_power_genotype_misclassification_3p(
  N_case,
  alpha,
  prev,
  pd,
  R2,
  MOI = c("M", "D", "Rec"),
  k = 1,
  e01 = 0,
  e02 = 0,
  e03 = 0,
  verbose = TRUE
)

cc_chisq_mssn_genotype_misclassification_differential_3p(
  power,
  alpha,
  prev,
  pd,
  R2,
  MOI = c("M", "D", "Rec"),
  k = 1,
  case_e01 = 0,
  case_e02 = 0,
  case_e03 = 0,
  ctrl_e01 = 0,
  ctrl_e02 = 0,
  ctrl_e03 = 0,
  verbose = TRUE
)

cc_chisq_power_genotype_misclassification_differential_3p(
  N_case,
  alpha,
  prev,
  pd,
  R2,
  MOI = c("M", "D", "Rec"),
  k = 1,
  case_e01 = 0,
  case_e02 = 0,
  case_e03 = 0,
  ctrl_e01 = 0,
  ctrl_e02 = 0,
  ctrl_e03 = 0,
  verbose = TRUE
)

Arguments

power	Numeric in $(0,1)$. Desired target power for MSSN functions.
alpha	Numeric in $(0,1)$. Significance level.
prev	Numeric in $(0,1)$. Disease prevalence.
pd	Numeric in $(0,1)$. Disease-allele frequency.
R2	Numeric $> 0$. Homozygote relative risk.
MOI	Character. Mode of inheritance: "M", "D", or "Rec".
k	Numeric $> 0$. Control-to-case ratio $N_{ctrl}/N_{case}$.
e	Numeric in $[0,0.5]$. One-parameter symmetric error probability assigned to each adjacent off-diagonal call. The matrix diagonal is $1-2e$; textbook Eq. 2.5 uses a total error parameter $\epsilon=2e$.
verbose	Logical. If TRUE, prints a formatted summary.
N_case	Numeric $> 0$. Number of cases for power functions.
e1, e2	Numeric. Two-parameter genotype misclassification rates.
e01, e02, e03	Numeric. Three-parameter non-differential genotype misclassification rates.
case_e01, case_e02, case_e03	Numeric. Case-specific three-parameter genotype misclassification rates for differential misclassification.
ctrl_e01, ctrl_e02, ctrl_e03	Numeric. Control-specific three-parameter genotype misclassification rates for differential misclassification.

Details

These are specialized convenience functions retained for users who want a focused genotype-only calculation. The all-in-one case-control functions are recommended when combining model-free inputs, locus heterogeneity, trend tests, or multiple modifier choices in one call.

Conditional genotype probabilities are constructed from prevalence, allele frequency, and relative risks using Chapter 1, Section 1.4.2 and Eqs. 1.6–1.7 (p. 13) of Gordon, Finch, and Kim (2020). The genotype test uses the two-degree-of-freedom NCP in Eq. 1.22 (p. 26). The error matrices are the one-, two-, and three-parameter families in Eqs. 2.5, 2.6, and 2.7 (pp. 57–58). Douglas et al. (2002) and Sobel et al. (2002) support the corresponding error-model families; Gordon et al. (2002) supports their use in case-control power and sample-size calculations.

For the 1p functions, package e is the probability in each adjacent off-diagonal cell, and the diagonal is $1-2e$. Textbook Eq. 2.5 instead writes each off-diagonal as $\epsilon/2$ and the diagonal as $1-\epsilon$; therefore $\epsilon=2e$.

Differential 3p functions use separate Eq. 2.7-family matrices for cases and controls, as discussed in Chapter 2, Section 2.5.2 (pp. 61–69). Their power is nominal asymptotic power, and their MSSN is nominal MSSN, evaluated with the usual chi-square critical value. Different case and control error mechanisms can distort the null distribution and inflate type I error. These functions do not independently recalibrate the null distribution for arbitrary differential genotyping error.

The returned objects keep internal effect-size components such as S and, for differential misclassification, per-genotype components, for validation and debugging.

Value

A list with class matching the function name. MSSN functions include target non-centrality parameter, case/control sample sizes, model parameters, penetrances, misclassification matrices, internal S values, and true and observed genotype frequencies. Power functions include case/control sample sizes, non-centrality parameter, power, model parameters, penetrances, misclassification matrices, internal S values, and true and observed genotype frequencies.

References

Gordon, D., Finch, S. J., & Kim, W. (2020). Heterogeneity in Statistical Genetics: How to Assess, Address, and Account for Mixtures in Association Studies. Springer. doi:10.1007/978-3-030-61121-7.

Gordon, D., Finch, S. J., Nothnagel, M., & Ott, J. (2002). Power and sample size calculations for case-control genetic association tests when errors are present: application to single nucleotide polymorphisms. Human Heredity, 54(1), 22–33. doi:10.1159/000066696.

Douglas, J. A., Skol, A. D., & Boehnke, M. (2002). Probability of detection of genotyping errors and mutations as inheritance inconsistencies in nuclear-family data. American Journal of Human Genetics, 70(2), 487–495. doi:10.1086/338919.

Sobel, E., Papp, J. C., & Lange, K. (2002). Detection and integration of genotyping errors in statistical genetics. American Journal of Human Genetics, 70(2), 496–508. doi:10.1086/338920.

Ahn, K., Gordon, D., & Finch, S. J. (2009). Increase of rejection rate in case-control studies with the differential genotyping error rates. Statistical Applications in Genetics and Molecular Biology, 8(1), Article 25. doi:10.2202/1544-6115.1429.

See Also

cc_power, cc_mssn, case_control_locus_heterogeneity, and case_control_phenotype_misclassification.

Examples

cc_chisq_mssn_genotype_misclassification_1p(
  power = 0.8, alpha = 0.05, prev = 0.1, pd = 0.3, R2 = 1.8,
  MOI = "D", e = 0.02, verbose = FALSE
)

cc_chisq_power_genotype_misclassification_1p(
  N_case = 500, alpha = 0.05, prev = 0.1, pd = 0.3, R2 = 1.8,
  MOI = "D", e = 0.02, verbose = FALSE
)

cc_chisq_mssn_genotype_misclassification_2p(
  power = 0.8, alpha = 0.05, prev = 0.1, pd = 0.3, R2 = 1.8,
  MOI = "D", e1 = 0.02, e2 = 0.01, verbose = FALSE
)

cc_chisq_power_genotype_misclassification_2p(
  N_case = 500, alpha = 0.05, prev = 0.1, pd = 0.3, R2 = 1.8,
  MOI = "D", e1 = 0.02, e2 = 0.01, verbose = FALSE
)

cc_chisq_mssn_genotype_misclassification_3p(
  power = 0.8, alpha = 0.05, prev = 0.1, pd = 0.3, R2 = 1.8,
  MOI = "D", e01 = 0.02, e02 = 0.01, e03 = 0.005,
  verbose = FALSE
)

cc_chisq_power_genotype_misclassification_3p(
  N_case = 500, alpha = 0.05, prev = 0.1, pd = 0.3, R2 = 1.8,
  MOI = "D", e01 = 0.02, e02 = 0.01, e03 = 0.005,
  verbose = FALSE
)

cc_chisq_mssn_genotype_misclassification_differential_3p(
  power = 0.8, alpha = 0.05, prev = 0.1, pd = 0.3, R2 = 1.8,
  MOI = "D",
  case_e01 = 0.02, case_e02 = 0.01, case_e03 = 0.005,
  ctrl_e01 = 0.01, ctrl_e02 = 0.005, ctrl_e03 = 0.002,
  verbose = FALSE
)

cc_chisq_power_genotype_misclassification_differential_3p(
  N_case = 500, alpha = 0.05, prev = 0.1, pd = 0.3, R2 = 1.8,
  MOI = "D",
  case_e01 = 0.02, case_e02 = 0.01, case_e03 = 0.005,
  ctrl_e01 = 0.01, ctrl_e02 = 0.005, ctrl_e03 = 0.002,
  verbose = FALSE
)

---

Specialized Case-Control Locus-Heterogeneity Functions

Description

Convenience functions for case-control association calculations under locus heterogeneity. These focused functions compute genotype chi-square or genotype trend calculations one test at a time. The all-in-one case-control functions remain the recommended interface when multiple tests or modifiers are needed in one call.

Usage

cc_chisq_mssn_locus_heterogeneity(
  power,
  alpha,
  g_case_assoc,
  g_ctrl,
  pi,
  k = 1,
  verbose = TRUE
)

cc_chisq_power_locus_heterogeneity(
  N_case,
  alpha,
  g_case_assoc,
  g_ctrl,
  pi,
  k = 1,
  verbose = TRUE
)

cc_trend_mssn_locus_heterogeneity(
  power,
  alpha,
  g_case_assoc,
  g_ctrl,
  pi,
  k = 1,
  w = c(0, 1, 2),
  verbose = TRUE
)

cc_trend_power_locus_heterogeneity(
  N_case,
  alpha,
  g_case_assoc,
  g_ctrl,
  pi,
  k = 1,
  w = c(0, 1, 2),
  verbose = TRUE
)

Arguments

power	Numeric in $(0,1)$. Desired target power for MSSN functions.
alpha	Numeric in $(0,1)$. Significance level.
g_case_assoc	Numeric vector of length 3. Case genotype frequencies under the associated-locus model, ordered as c(g0, g1, g2) and summing to 1.
g_ctrl	Numeric vector of length 3. Control genotype frequencies, ordered as c(g0, g1, g2) and summing to 1.
pi	Numeric in $[0,1]$. Locus-homogeneity fraction. The adjusted case genotype frequencies are $\pi g_{case,assoc} + (1 - \pi) g_{ctrl}$.
k	Numeric $> 0$. Control-to-case ratio $N_{ctrl}/N_{case}$.
verbose	Logical. If TRUE, prints a formatted summary.
N_case	Numeric $> 0$. Number of cases for power functions.
w	Numeric vector of length 3. Trend-test genotype scores. The three weights cannot all be equal.

Details

The associated case distribution is mixed with the control distribution as $\pi g_{case,assoc} + (1-\pi)g_{ctrl}$, following textbook Eq. 2.16 (p. 88). Thus pi is the homogeneous/associated fraction and $1-\pi$ is the heterogeneous fraction. The adjusted probabilities are then passed to either the genotype chi-square NCP in Eq. 1.22 (p. 26) or the trend-test NCP in Eq. 1.24 (p. 27). The trend construction under locus heterogeneity is given more specifically by Eqs. 5.29a–b (pp. 287–288).

Value

A list with class matching the function name. MSSN functions include target non-centrality parameter, sample sizes, internal S values, and adjusted frequencies. Power functions include sample sizes, non-centrality parameter, power, internal S values, and adjusted frequencies. Trend functions additionally return the trend numerator and denominator.

References

Gordon, D., Finch, S. J., & Kim, W. (2020). Heterogeneity in Statistical Genetics: How to Assess, Address, and Account for Mixtures in Association Studies. Springer. doi:10.1007/978-3-030-61121-7.

Armitage, P. (1955). Tests for linear trends in proportions and frequencies. Biometrics, 11(3), 375–386. doi:10.2307/3001775.

Slager, S. L., & Schaid, D. J. (2001). Case-control studies of genetic markers: power and sample size approximations for Armitage's test for trend. Human Heredity, 52(3), 149–153. doi:10.1159/000053370.

See Also

cc_power, cc_mssn, and case_control_genotype_misclassification.

Examples

cc_chisq_mssn_locus_heterogeneity(
  power = 0.8, alpha = 0.05,
  g_case_assoc = c(0.25, 0.50, 0.25),
  g_ctrl = c(0.36, 0.48, 0.16),
  pi = 0.8,
  verbose = FALSE
)

cc_chisq_power_locus_heterogeneity(
  N_case = 500, alpha = 0.05,
  g_case_assoc = c(0.25, 0.50, 0.25),
  g_ctrl = c(0.36, 0.48, 0.16), pi = 0.8, verbose = FALSE
)

cc_trend_mssn_locus_heterogeneity(
  power = 0.8, alpha = 0.05,
  g_case_assoc = c(0.25, 0.50, 0.25),
  g_ctrl = c(0.36, 0.48, 0.16), pi = 0.8, verbose = FALSE
)

cc_trend_power_locus_heterogeneity(
  N_case = 500, alpha = 0.05,
  g_case_assoc = c(0.25, 0.50, 0.25),
  g_ctrl = c(0.36, 0.48, 0.16),
  pi = 0.8,
  verbose = FALSE
)

---

Specialized Case-Control Phenotype Misclassification Functions

Description

Convenience functions for genotype chi-square case-control calculations in the presence of phenotype misclassification only. These focused functions are narrower than cc_mssn and cc_power: they use true affected and true unaffected genotype frequencies supplied directly by the user and do not apply locus heterogeneity or genotype misclassification.

Usage

cc_chisq_power_phenotype_misclassification(
  N_case,
  alpha = 0.05,
  g_aff,
  g_unaff,
  prev,
  theta = 0,
  phi = 0,
  k = 1
)

cc_chisq_mssn_phenotype_misclassification(
  target_power = 0.8,
  alpha = 0.05,
  g_aff,
  g_unaff,
  prev,
  theta = 0,
  phi = 0,
  k = 1
)

Arguments

N_case	Numeric $> 0$. Number of cases for power calculations.
alpha	Numeric in $(0,1)$. Significance level.
g_aff	Numeric vector of true affected genotype frequencies, ordered consistently across affected and unaffected groups and summing to 1.
g_unaff	Numeric vector of true unaffected genotype frequencies, ordered consistently with g_aff and summing to 1.
prev	Numeric in $(0,1)$. Disease prevalence.
theta	Numeric in $[0,1)$. Probability that a truly affected individual is classified as a control, Pr(affected -> control).
phi	Numeric in $[0,1)$. Probability that a truly unaffected individual is classified as a case, Pr(unaffected -> case).
k	Numeric $> 0$. Control-to-case ratio $N_{ctrl}/N_{case}$.
target_power	Numeric in $(0,1)$. Desired target power for MSSN calculations.

Details

Phenotype misclassification is applied by mixing the true affected genotype distribution g_aff and true unaffected genotype distribution g_unaff using disease prevalence and the phenotype-error probabilities. Here theta = Pr(affected -> control) and phi = Pr(unaffected -> case). These specialized functions apply only phenotype misclassification; use the full case-control functions for combined phenotype misclassification, locus heterogeneity, genotype misclassification, or trend tests. The observed case distribution is a prevalence-weighted mixture of true affected and unaffected genotype probabilities conditional on being classified as a case; the control distribution is constructed analogously.

Value

cc_chisq_power_phenotype_misclassification() returns a list containing sample sizes, phenotype-error parameters, observed case/control genotype frequencies, internal S, non-centrality parameter lambda, and power. cc_chisq_mssn_phenotype_misclassification() returns a list containing target power, phenotype-error parameters, observed case/control genotype frequencies, internal S, target non-centrality parameter lambda_star, and case/control/total MSSN.

References

Edwards, B. J., Haynes, C., Levenstien, M. A., Finch, S. J., & Gordon, D. (2005). Power and sample size calculations in the presence of phenotype errors for case/control genetic association studies. BMC Genetics, 6, 18. doi:10.1186/1471-2156-6-18. PMID: 15819990.

Gordon, D., Finch, S. J., & Kim, W. (2020). Heterogeneity in Statistical Genetics: How to Assess, Address, and Account for Mixtures in Association Studies. Springer. doi:10.1007/978-3-030-61121-7.

See Also

cc_power, cc_mssn, and case_control_genotype_misclassification.

Examples

g_aff <- c((1 - 0.05)^2, 2 * 0.05 * (1 - 0.05), 0.05^2)
g_unaff <- c((1 - 0.15)^2, 2 * 0.15 * (1 - 0.15), 0.15^2)

cc_chisq_power_phenotype_misclassification(
  N_case = 250, alpha = 0.01,
  g_aff = g_aff, g_unaff = g_unaff,
  prev = 0.05, theta = 0, phi = 0.01
)

cc_chisq_mssn_phenotype_misclassification(
  target_power = 0.8, alpha = 0.01,
  g_aff = g_aff, g_unaff = g_unaff,
  prev = 0.05, theta = 0, phi = 0.01
)

---

Case-Control Minimum Sample Size for Conditional Genotype Frequencies

Description

Computes the minimum sample size necessary (MSSN) for case-control association tests using conditional genotype frequencies. The function supports model-based genotype frequencies, model-free genotype frequencies, optional locus heterogeneity, optional phenotype misclassification, optional genotype misclassification, genotype chi-square tests, and genotype trend tests.

Usage

cc_mssn(
  power,
  alpha,
  input_mode = c("model_based", "model_free"),
  prev = NULL,
  pd = NULL,
  R2 = NULL,
  MOI = c("M", "D", "Rec"),
  g1 = NULL,
  g0 = NULL,
  locus_het = FALSE,
  pi = 1,
  pheno_misclass = FALSE,
  theta = 0,
  phi = 0,
  k = 1,
  w = c(0, 1, 2),
  geno_misclass = c("none", "1p", "2p", "3p", "diff3p"),
  e = 0,
  e1 = 0,
  e2 = 0,
  e01 = 0,
  e02 = 0,
  e03 = 0,
  case_e01 = 0,
  case_e02 = 0,
  case_e03 = 0,
  ctrl_e01 = 0,
  ctrl_e02 = 0,
  ctrl_e03 = 0,
  diff_source = c("explicit", "case", "ctrl"),
  diff_multiplier = 1,
  verbose = TRUE
)

Arguments

power	Numeric in $(0,1)$. Desired target power.
alpha	Numeric in $(0,1)$. Significance level.
input_mode	Character. One of "model_based" or "model_free". See Details.
prev	Numeric in $(0,1)$. Disease prevalence for input_mode = "model_based".
pd	Numeric in $(0,1)$. Disease-allele frequency for input_mode = "model_based".
R2	Numeric $> 0$. Homozygote relative risk for input_mode = "model_based".
MOI	Character. Mode of inheritance for model-based frequencies: "M" for multiplicative, "D" for dominant, or "Rec" for recessive.
g1, g0	Numeric vectors of length 3 for input_mode = "model_free". g1 gives case genotype frequencies and g0 gives control genotype frequencies, each ordered as c(g0, g1, g2) and summing to 1.
locus_het	Logical. If TRUE, requests a separate locus- heterogeneity sensitivity scenario starting from the baseline frequencies.
pi	Numeric in $[0,1]$. Locus-homogeneity fraction used when locus_het = TRUE. When locus_het = FALSE, pi must remain at its default value of 1.
pheno_misclass	Logical. If TRUE, requests a separate phenotype-misclassification sensitivity scenario starting from baseline.
theta	Numeric in $[0,1)$. Probability that a truly affected individual is classified as a control.
phi	Numeric in $[0,1)$. Probability that a truly unaffected individual is classified as a case.
k	Numeric $> 0$. Control-to-case sample size ratio $N_{ctrl} / N_{case}$.
w	Numeric vector of length 3. Genotype trend-test scores. The three weights cannot all be equal.
geno_misclass	Character. Genotype misclassification model: "none", "1p", "2p", "3p", or "diff3p".
e	Numeric in $[0,0.5]$. For geno_misclass = "1p", the probability assigned to each adjacent off-diagonal genotype call; the diagonal probability is $1-2e$. Thus the $\epsilon$ in textbook Eq. 2.5 equals $2e$; see Details.
e1, e2	Numeric. Two-parameter misclassification rates for geno_misclass = "2p".
e01, e02, e03	Numeric. Non-differential three-parameter misclassification rates for geno_misclass = "3p".
case_e01, case_e02, case_e03	Numeric. Case-specific three-parameter misclassification rates for geno_misclass = "diff3p".
ctrl_e01, ctrl_e02, ctrl_e03	Numeric. Control-specific three-parameter misclassification rates for geno_misclass = "diff3p".
diff_source	Character. For geno_misclass = "diff3p", one of "explicit", "case", or "ctrl". See Details.
diff_multiplier	Numeric $\ge 0$. Multiplier used when diff_source = "case" or diff_source = "ctrl".
verbose	Logical. If TRUE, prints a clean formatted summary.

Details

The no-error scenario is always calculated from the baseline conditional case and control genotype frequencies. Each requested modifier is evaluated independently from that same baseline:

• no error: baseline -> tests;

• phenotype misclassification: baseline -> phenotype misclassification -> tests;

• locus heterogeneity: baseline -> locus heterogeneity -> tests;

• genotype misclassification: baseline -> genotype misclassification -> tests.

Supplying several modifiers requests several independent sensitivity scenarios. Ordinary cc_mssn() does not combine modifiers. Specialized joint-error methods such as LRTae and LTTae are separate methods and are not implemented here.

With input_mode = "model_based", conditional case and control genotype frequencies are derived from prev, pd, R2, and MOI using Chapter 1, Section 1.4.2, Eqs. 1.6–1.7 (p. 13) of Gordon, Finch, and Kim (2020). With input_mode = "model_free", the user supplies g1 and g0 directly; when phenotype misclassification is enabled, g1 is treated as the true affected genotype distribution and g0 is treated as the true unaffected genotype distribution.

Phenotype misclassification requires prev in both input modes because disease prevalence is used to mix the baseline affected and unaffected genotype distributions into observed case and control distributions. Locus heterogeneity uses $g_{case,het} = \pi g_{case,base} + (1 - \pi) g_{ctrl,base}$ and leaves controls unchanged. Genotype misclassification matrices are likewise applied directly to baseline case and control frequencies.

The genotype misclassification models are: "none" for identity matrices, "1p" for one symmetric error rate, "2p" for adjacent homozygote/heterozygote and heterozygote error rates, "3p" for a non-differential three-parameter matrix, and "diff3p" for separate case and control three-parameter matrices. The one-, two-, and three-parameter matrices correspond to textbook Eqs. 2.5, 2.6, and 2.7 (pp. 57–58). For "1p", package e is the probability in each adjacent off-diagonal cell and the diagonal is $1-2e$; textbook Eq. 2.5 uses off-diagonal $\epsilon/2$, so $\epsilon=2e$.

The genotype test uses Eq. 1.22 (p. 26). The trend test is defined by Eqs. 1.20–1.21 (p. 24) and uses the NCP in Eq. 1.24 (p. 27). Locus heterogeneity follows Eq. 2.16 (p. 88): pi is the homogeneous fraction and $1-\pi$ is the heterogeneous fraction. Its trend-test construction corresponds to Eqs. 5.29a–b (pp. 287–288).

For geno_misclass = "diff3p", diff_source = "explicit" uses the case and control error parameters exactly as supplied. With diff_source = "case", control parameters are computed by multiplying the case parameters by diff_multiplier. With diff_source = "ctrl", case parameters are computed by multiplying the control parameters by diff_multiplier.

With geno_misclass = "diff3p", returned MSSNs are nominal, asymptotic values evaluated with the usual chi-square critical value. Different case and control error mechanisms can distort the null distribution and inflate type I error. This function does not independently recalibrate that null distribution for arbitrary differential genotyping error.

Internal effect-size components S are retained in the returned object for validation and debugging, but are not printed in the clean verbose output.

Value

An object of class "cc_mssn", containing:

alpha, target_power

Requested significance level and power.

input_mode, k, w, locus_het

Input mode, control-to-case ratio, trend scores, and locus-heterogeneity settings.

errors

Genotype-error model and matrices, plus phenotype-error settings and intermediate frequencies.

model_info

Model-based penetrances and risk-model inputs, or model-free identifying information.

scenarios

Named independent results. no_error always exists; requested modifiers add phenotype_misclassification, heterogeneity, and genotype_misclassification. Each contains scenario frequencies, modifier metadata, and genotype/trend MSSN results.

tests, freqs, compatibility_scenario

Compatibility fields. With zero or one modifier, they mirror the sole design previously returned. With several modifiers, they explicitly mirror no_error; use scenarios for each sensitivity result.

References

Gordon, D., Finch, S. J., & Kim, W. (2020). Heterogeneity in Statistical Genetics: How to Assess, Address, and Account for Mixtures in Association Studies. Springer. doi:10.1007/978-3-030-61121-7.

Gordon, D., Finch, S. J., Nothnagel, M., & Ott, J. (2002). Power and sample size calculations for case-control genetic association tests when errors are present: application to single nucleotide polymorphisms. Human Heredity, 54(1), 22–33. doi:10.1159/000066696.

Armitage, P. (1955). Tests for linear trends in proportions and frequencies. Biometrics, 11(3), 375–386. doi:10.2307/3001775.

Slager, S. L., & Schaid, D. J. (2001). Case-control studies of genetic markers: power and sample size approximations for Armitage's test for trend. Human Heredity, 52(3), 149–153. doi:10.1159/000053370.

Edwards, B. J., Haynes, C., Levenstien, M. A., Finch, S. J., & Gordon, D. (2005). Power and sample size calculations in the presence of phenotype errors for case/control genetic association studies. BMC Genetics, 6, 18. doi:10.1186/1471-2156-6-18.

See Also

cc_power, case_control_genotype_misclassification, case_control_locus_heterogeneity, and case_control_phenotype_misclassification.

Examples

cc_mssn(
  power = 0.8, alpha = 0.05,
  input_mode = "model_free",
  g1 = c(0.25, 0.50, 0.25),
  g0 = c(0.36, 0.48, 0.16),
  geno_misclass = "none",
  verbose = FALSE
)

cc_mssn(
  power = 0.8, alpha = 0.05,
  input_mode = "model_free",
  g1 = c(0.25, 0.50, 0.25),
  g0 = c(0.36, 0.48, 0.16),
  locus_het = TRUE, pi = 0.8,
  verbose = FALSE
)

cc_mssn(
  power = 0.8, alpha = 0.05,
  input_mode = "model_free",
  g1 = c(0.25, 0.50, 0.25),
  g0 = c(0.36, 0.48, 0.16),
  locus_het = TRUE, pi = 0.8,
  geno_misclass = "3p", e01 = 0.02, e02 = 0.01, e03 = 0.005,
  verbose = FALSE
)

cc_mssn(
  power = 0.8, alpha = 0.05,
  input_mode = "model_free",
  g1 = c(0.25, 0.50, 0.25),
  g0 = c(0.36, 0.48, 0.16),
  prev = 0.05,
  pheno_misclass = TRUE, theta = 0.05, phi = 0.01,
  verbose = FALSE
)

---

Analytic MSSN for a Case-Control Sequencing Study

Description

Computes the minimum sample size necessary (MSSN) for a model-based case-control sequencing trend design. It evaluates the same independent sequencing-only, phenotype, heterogeneity, and post-call genotype-error scenarios as cc_ngs_power.

Usage

cc_ngs_mssn(
  power,
  alpha,
  prev,
  pd,
  R2,
  coverage = NULL,
  seq_error = NULL,
  MOI = c("M", "D", "Rec"),
  k = 1,
  verbose = TRUE,
  locus_het = FALSE,
  pi = 1,
  case_coverage = coverage,
  ctrl_coverage = coverage,
  case_seq_error = seq_error,
  ctrl_seq_error = seq_error,
  pheno_misclass = FALSE,
  theta = 0,
  phi = 0,
  geno_misclass = c("none", "1p", "2p", "3p", "diff3p"),
  e = 0,
  e1 = 0,
  e2 = 0,
  e01 = 0,
  e02 = 0,
  e03 = 0,
  case_e01 = 0,
  case_e02 = 0,
  case_e03 = 0,
  ctrl_e01 = 0,
  ctrl_e02 = 0,
  ctrl_e03 = 0,
  diff_source = c("explicit", "case", "ctrl"),
  diff_multiplier = 1
)

Arguments

power	Numeric in $(0,1)$. Requested power.
alpha	Numeric in $(0,1)$. Significance level.
prev	Numeric in $(0,1)$. Disease prevalence.
pd	Numeric in $(0,1)$. Disease-allele frequency.
R2	Numeric $> 0$. Homozygote relative risk.
coverage	Common positive integer fixed sequencing depth. May be omitted when both group-specific depths are supplied.
seq_error	Symmetric per-read sequencing-error probability in $[0,0.5)$. Common shorthand; may be omitted when both group-specific errors are supplied.
MOI	Character mode of inheritance: "M" for multiplicative, "D" for dominant, or "Rec" for recessive.
k	Numeric $> 0$. Planned control-to-case sample-size ratio.
verbose	Logical. If TRUE, print a concise result summary.
locus_het	Logical. If TRUE, apply the canonical PAWEH case-control locus-heterogeneity mixture before sequencing observation.
pi	Numeric in $[0,1]$. Locus-homogeneity fraction used when locus_het = TRUE. One retains the original associated-case distribution; zero makes the case distribution equal to controls. When locus_het = FALSE, pi must remain at its default value of 1.
case_coverage, ctrl_coverage	Case/control fixed depths, respectively. Each defaults to coverage; an explicit value overrides it.
case_seq_error, ctrl_seq_error	Case/control per-read error probabilities. Each defaults to seq_error; an explicit value overrides it. Effective depths and errors obey the common parameter constraints.
pheno_misclass	Logical. If TRUE, apply the ordinary PAWEH case-control phenotype-misclassification model before sequencing.
theta	Numeric in $[0,1)$. Probability that a truly affected individual is classified as a control.
phi	Numeric in $[0,1)$. Probability that a truly unaffected individual is classified as a case.
geno_misclass	Character genotype-misclassification model: "none", "1p", "2p", "3p", or "diff3p". The selected model is applied after sequencing calls.
e	Numeric in $[0,0.5]$. One-parameter symmetric error rate.
e1, e2	Numeric two-parameter homozygote-to-heterozygote and heterozygote-to-homozygote error rates.
e01, e02, e03	Numeric non-differential three-parameter error rates.
case_e01, case_e02, case_e03	Case-specific three-parameter error rates.
ctrl_e01, ctrl_e02, ctrl_e03	Control-specific three-parameter error rates.
diff_source	Character source for differential three-parameter errors: "explicit", "case", or "ctrl".
diff_multiplier	Nonnegative multiplier used to derive the other group's rates when diff_source is "case" or "ctrl".

Details

Locus heterogeneity uses $g_{case,H}=\pi g_{case}+(1-\pi)g_{control}$ in its independent branch. The prevalence-weighted phenotype transformation from cc_mssn is applied directly to the common biological baseline in its branch. Case and control sequencing settings are then applied to the corresponding pre-sequencing groups. Conventional genotype misclassification is applied after sequencing only in its own branch. See cc_ngs_power for the scenario paths and matrix convention. When $\pi=0$ and sequencing mechanisms are equal, no finite MSSN exists for target power greater than alpha if the observed contrast is zero. Differential mechanisms may create an observed contrast even under a biological null. MSSN is a nominal asymptotic calculation using the existing chi-square critical value, without separate null-distribution or Type I error recalibration.

The function numerically inverts the one-degree-of-freedom noncentral chi-square distribution only to obtain the target NCP. It then solves the Ahn/Chapman-Nam trend-test sample-size equation analytically. Planned cases are the ceiling of the continuous requirement and planned controls are ceiling(k * MSSN_case), following the PAWEH convention. Achieved NCP and power are recomputed using these actual integer sample sizes, with a local boundary adjustment if required to ensure target attainment and integer minimality.

Scores are c(0,1,2) for "M", c(0,1,1) for "D", and c(0,0,1) for "Rec". Finite depth can cause genotype-call uncertainty even when seq_error = 0, because a true heterozygote can yield reads from only one allele.

This is an analytic study-design calculation, not LTTae,NGS, a raw-read latent-genotype likelihood or EM method, downstream association testing, or simulation.

Value

Invisibly, an object of class "cc_ngs_mssn" containing a scenario-first scenarios list. Each scenario records target NCP, D/Q, continuous and integer sample sizes, achieved NCP and power, rounding metadata, staged frequencies, and sequencing/error matrices. Legacy fields follow the compatibility_scenario convention documented for cc_ngs_power.

References

Ahn, K., Haynes, C., Kim, W., St. Fleur, R., Gordon, D., & Finch, S. J. (2007). The effects of SNP genotyping errors on the power of the Cochran-Armitage linear trend test for case/control association studies. Annals of Human Genetics, 71, 249–261. doi:10.1111/j.1469-1809.2006.00318.x.

Gordon, D., Finch, S. J., & Kim, W. (2020). Heterogeneity in Statistical Genetics. Springer. doi:10.1007/978-3-030-61121-7.

Examples

cc_ngs_mssn(
  power = 0.80, alpha = 0.05,
  prev = 0.05, pd = 0.30, R2 = 1.8,
  coverage = 20, seq_error = 0.01,
  MOI = "M", verbose = FALSE
)

---

Analytic Power for a Case-Control Sequencing Study

Description

Computes prospective asymptotic power for a model-based case-control sequencing design. Sequencing is the common reference mechanism. Optional phenotype misclassification, locus heterogeneity, and conventional genotype misclassification are evaluated as independent sensitivity scenarios from the same biological baseline and sequencing design.

Usage

cc_ngs_power(
  N_case,
  alpha,
  prev,
  pd,
  R2,
  coverage = NULL,
  seq_error = NULL,
  MOI = c("M", "D", "Rec"),
  k = 1,
  verbose = TRUE,
  locus_het = FALSE,
  pi = 1,
  case_coverage = coverage,
  ctrl_coverage = coverage,
  case_seq_error = seq_error,
  ctrl_seq_error = seq_error,
  pheno_misclass = FALSE,
  theta = 0,
  phi = 0,
  geno_misclass = c("none", "1p", "2p", "3p", "diff3p"),
  e = 0,
  e1 = 0,
  e2 = 0,
  e01 = 0,
  e02 = 0,
  e03 = 0,
  case_e01 = 0,
  case_e02 = 0,
  case_e03 = 0,
  ctrl_e01 = 0,
  ctrl_e02 = 0,
  ctrl_e03 = 0,
  diff_source = c("explicit", "case", "ctrl"),
  diff_multiplier = 1
)

Arguments

N_case	Numeric $> 0$. Number of cases.
alpha	Numeric in $(0,1)$. Significance level.
prev	Numeric in $(0,1)$. Disease prevalence.
pd	Numeric in $(0,1)$. Disease-allele frequency.
R2	Numeric $> 0$. Homozygote relative risk.
coverage	Common positive integer fixed sequencing depth. May be omitted when both group-specific depths are supplied.
seq_error	Symmetric per-read sequencing-error probability in $[0,0.5)$. Common shorthand; may be omitted when both group-specific errors are supplied.
MOI	Character mode of inheritance: "M" for multiplicative, "D" for dominant, or "Rec" for recessive.
k	Numeric $> 0$. Control-to-case sample-size ratio $N_{ctrl}/N_{case}$.
verbose	Logical. If TRUE, print a concise result summary.
locus_het	Logical. If TRUE, apply the canonical PAWEH case-control locus-heterogeneity mixture before sequencing observation.
pi	Numeric in $[0,1]$. Locus-homogeneity fraction used when locus_het = TRUE. One retains the original associated-case distribution; zero makes the case distribution equal to controls. When locus_het = FALSE, pi must remain at its default value of 1.
case_coverage, ctrl_coverage	Case/control fixed depths, respectively. Each defaults to coverage; an explicit value overrides it.
case_seq_error, ctrl_seq_error	Case/control per-read error probabilities. Each defaults to seq_error; an explicit value overrides it. Effective depths and errors obey the common parameter constraints.
pheno_misclass	Logical. If TRUE, apply the ordinary PAWEH case-control phenotype-misclassification model before sequencing.
theta	Numeric in $[0,1)$. Probability that a truly affected individual is classified as a control.
phi	Numeric in $[0,1)$. Probability that a truly unaffected individual is classified as a case.
geno_misclass	Character genotype-misclassification model: "none", "1p", "2p", "3p", or "diff3p". The selected model is applied after sequencing calls.
e	Numeric in $[0,0.5]$. One-parameter symmetric error rate.
e1, e2	Numeric two-parameter homozygote-to-heterozygote and heterozygote-to-homozygote error rates.
e01, e02, e03	Numeric non-differential three-parameter error rates.
case_e01, case_e02, case_e03	Case-specific three-parameter error rates.
ctrl_e01, ctrl_e02, ctrl_e03	Control-specific three-parameter error rates.
diff_source	Character source for differential three-parameter errors: "explicit", "case", or "ctrl".
diff_multiplier	Nonnegative multiplier used to derive the other group's rates when diff_source is "case" or "ctrl".

Details

Trend scores are selected from MOI: "M" uses c(0,1,2), "D" uses c(0,1,1), and "Rec" uses c(0,0,1). Power is the upper-tail probability beyond the central one-degree-of-freedom chi-square critical value under a noncentral chi-square distribution with the calculated NCP.

Locus heterogeneity uses the same parameterization as ordinary PAWEH case-control design:

$g_{case,H} = \pi g_{case} + (1-\pi)g_{control},$

with the control distribution unchanged. The scenario paths are: sequencing only, baseline to sequencing to test; phenotype, baseline to phenotype misclassification to sequencing to test; heterogeneity, baseline to locus heterogeneity to sequencing to test; and genotype, baseline to sequencing to conventional genotype misclassification to test. Supplying multiple modifiers returns multiple independent scenarios; modifiers are not combined. The same effective case/control coverage and sequencing-error settings are used in every scenario. Phenotype misclassification uses the same prevalence-weighted transformation as cc_power, with theta = Pr(affected -> control) and phi = Pr(unaffected -> case). The resulting observed-case and observed-control distributions enter sequencing. Separate row-true, column-called matrices are then constructed using each observed group's effective depth and error, and applied as t(M_case) %*% g_case and t(M_ctrl) %*% g_control. The ordinary PAWEH 1p, 2p, 3p, or differential 3p genotype-error matrices are applied only in their independent scenario, after sequencing calls, with the same row-current, column-observed convention. Only equal sequencing mechanisms permit commuting a shared biological mixture and sequencing. At $\pi=0$, equal mechanisms with no phenotype-induced difference give zero NCP and power equal to alpha.

Differential sequencing or genotype-misclassification mechanisms can create observed case/control differences even under a biological null. Results remain nominal asymptotic calculations using the existing chi-square critical value; the null distribution and Type I error are not separately recalibrated here.

This is an analytic study-design calculation applied to sequencing-derived called genotypes. It is not a raw-read likelihood or EM analysis, performs no downstream association testing, and uses no simulation. Even when seq_error = 0, finite depth can cause call uncertainty because a true heterozygote can yield reads from only one allele.

Value

Invisibly, an object of class "cc_ngs_power". The scenarios list always contains sequencing_only and each explicitly requested modifier scenario. Every scenario records staged frequencies, sequencing and error matrices, Ahn components D and Q, NCP, and power. Legacy top-level result fields mirror sequencing only with zero or multiple optional modifiers and the requested modifier with exactly one; compatibility_scenario identifies it. The frequency list distinguishes post-sequencing calls from final post-genotype-misclassification values. The sequencing list records the four effective group parameters and case_transition_matrix/ctrl_transition_matrix. Legacy coverage/seq_error retain supplied common inputs (or NULL); transition_matrix aliases the case matrix, shared when mechanisms are equal. Use the two explicit matrices for differential designs.

References

Ahn, K., Haynes, C., Kim, W., St. Fleur, R., Gordon, D., & Finch, S. J. (2007). The effects of SNP genotyping errors on the power of the Cochran-Armitage linear trend test for case/control association studies. Annals of Human Genetics, 71, 249–261. doi:10.1111/j.1469-1809.2006.00318.x.

Gordon, D., Finch, S. J., & Kim, W. (2020). Heterogeneity in Statistical Genetics. Springer. doi:10.1007/978-3-030-61121-7.

Examples

cc_ngs_power(
  N_case = 1000, alpha = 0.05,
  prev = 0.05, pd = 0.30, R2 = 1.8,
  coverage = 20, seq_error = 0.01,
  MOI = "M", verbose = FALSE
)

---

Case-Control Power for Conditional Genotype Frequencies

Description

Computes power for fixed case-control sample sizes using conditional genotype frequencies. The function supports model-based genotype frequencies, model-free genotype frequencies, optional locus heterogeneity, optional phenotype misclassification, optional genotype misclassification, genotype chi-square tests and genotype trend tests.

Usage

cc_power(
  N_case,
  alpha,
  input_mode = c("model_based", "model_free"),
  prev = NULL,
  pd = NULL,
  R2 = NULL,
  MOI = c("M", "D", "Rec"),
  g1 = NULL,
  g0 = NULL,
  locus_het = FALSE,
  pi = 1,
  pheno_misclass = FALSE,
  theta = 0,
  phi = 0,
  k = 1,
  w = c(0, 1, 2),
  geno_misclass = c("none", "1p", "2p", "3p", "diff3p"),
  e = 0,
  e1 = 0,
  e2 = 0,
  e01 = 0,
  e02 = 0,
  e03 = 0,
  case_e01 = 0,
  case_e02 = 0,
  case_e03 = 0,
  ctrl_e01 = 0,
  ctrl_e02 = 0,
  ctrl_e03 = 0,
  diff_source = c("explicit", "case", "ctrl"),
  diff_multiplier = 1,
  verbose = TRUE
)

Arguments

N_case	Numeric $> 0$. Number of cases.
alpha	Numeric in $(0,1)$. Significance level.
input_mode	Character. One of "model_based" or "model_free". See Details.
prev	Numeric in $(0,1)$. Disease prevalence for input_mode = "model_based".
pd	Numeric in $(0,1)$. Disease-allele frequency for input_mode = "model_based".
R2	Numeric $> 0$. Homozygote relative risk for input_mode = "model_based".
MOI	Character. Mode of inheritance for model-based frequencies: "M" for multiplicative, "D" for dominant, or "Rec" for recessive.
g1, g0	Numeric vectors of length 3 for input_mode = "model_free". g1 gives case genotype frequencies and g0 gives control genotype frequencies, each ordered as c(g0, g1, g2) and summing to 1.
locus_het	Logical. If TRUE, requests a separate locus- heterogeneity sensitivity scenario starting from the baseline frequencies.
pi	Numeric in $[0,1]$. Locus-homogeneity fraction used when locus_het = TRUE. When locus_het = FALSE, pi must remain at its default value of 1.
pheno_misclass	Logical. If TRUE, requests a separate phenotype-misclassification sensitivity scenario starting from baseline.
theta	Numeric in $[0,1)$. Probability that a truly affected individual is classified as a control.
phi	Numeric in $[0,1)$. Probability that a truly unaffected individual is classified as a case.
k	Numeric $> 0$. Control-to-case sample size ratio $N_{ctrl} / N_{case}$.
w	Numeric vector of length 3. Genotype trend-test scores. The three weights cannot all be equal.
geno_misclass	Character. Genotype misclassification model: "none", "1p", "2p", "3p", or "diff3p".
e	Numeric in $[0,0.5]$. For geno_misclass = "1p", the probability assigned to each adjacent off-diagonal genotype call. The textbook Eq. 2.5 parameter satisfies $\epsilon=2e$; see Details.
e1, e2	Numeric. Two-parameter misclassification rates for geno_misclass = "2p".
e01, e02, e03	Numeric. Non-differential three-parameter misclassification rates for geno_misclass = "3p".
case_e01, case_e02, case_e03	Numeric. Case-specific three-parameter misclassification rates for geno_misclass = "diff3p".
ctrl_e01, ctrl_e02, ctrl_e03	Numeric. Control-specific three-parameter misclassification rates for geno_misclass = "diff3p".
diff_source	Character. For geno_misclass = "diff3p", one of "explicit", "case", or "ctrl". See Details.
diff_multiplier	Numeric $\ge 0$. Multiplier used when diff_source = "case" or diff_source = "ctrl".
verbose	Logical. If TRUE, prints a clean formatted summary.

Details

The no-error scenario is always calculated from the baseline conditional case and control genotype frequencies. Each requested modifier is evaluated independently from that same baseline:

• no error: baseline -> tests;

• phenotype misclassification: baseline -> phenotype misclassification -> tests;

• locus heterogeneity: baseline -> locus heterogeneity -> tests;

• genotype misclassification: baseline -> genotype misclassification -> tests.

Supplying several modifiers requests several independent sensitivity scenarios. Ordinary cc_power() does not combine modifiers. Specialized joint-error methods such as LRTae and LTTae are separate methods and are not implemented here.

With input_mode = "model_based", conditional case and control genotype frequencies are derived from prev, pd, R2, and MOI using Chapter 1, Section 1.4.2, Eqs. 1.6–1.7 (p. 13) of Gordon, Finch, and Kim (2020). With input_mode = "model_free", the user supplies g1 and g0 directly; when phenotype misclassification is enabled, g1 is treated as the true affected genotype distribution and g0 is treated as the true unaffected genotype distribution.

Phenotype misclassification requires prev in both input modes because disease prevalence is used to mix the baseline affected and unaffected genotype distributions into observed case and control distributions. Locus heterogeneity uses $g_{case,het} = \pi g_{case,base} + (1 - \pi) g_{ctrl,base}$ and leaves controls unchanged. Genotype misclassification matrices are likewise applied directly to baseline case and control frequencies.

The genotype misclassification models are: "none" for identity matrices, "1p" for one symmetric error rate, "2p" for adjacent homozygote/heterozygote and heterozygote error rates, "3p" for a non-differential three-parameter matrix, and "diff3p" for separate case and control three-parameter matrices. These matrices correspond to Eqs. 2.5–2.7 (pp. 57–58). For "1p", package e is the probability in each adjacent off-diagonal cell and the diagonal is $1-2e$; textbook Eq. 2.5 uses off-diagonal $\epsilon/2$, so $\epsilon=2e$. The genotype and trend tests use Eqs. 1.22 and 1.24 (pp. 26–27), with the trend statistic defined by Eqs. 1.20–1.21 (p. 24). Locus heterogeneity follows Eq. 2.16 (p. 88), where pi is the homogeneous fraction; its trend-test form is given in Eqs. 5.29a–b (pp. 287–288).

For geno_misclass = "diff3p", diff_source = "explicit" uses the case and control error parameters exactly as supplied. With diff_source = "case", control parameters are computed by multiplying the case parameters by diff_multiplier. With diff_source = "ctrl", case parameters are computed by multiplying the control parameters by diff_multiplier.

With geno_misclass = "diff3p", returned power is nominal asymptotic power evaluated with the usual chi-square critical value. Different case and control error mechanisms can distort the null distribution and inflate type I error. This function does not independently recalibrate the null distribution for arbitrary differential genotyping error.

Internal effect-size components S are retained in the returned object for validation and debugging, but are not printed in the clean verbose output.

Value

An object of class "cc_power", containing:

alpha, N_case, N_ctrl, N_total

Significance level and numbers of case, control, and total individuals.

input_mode, k, w, locus_het

Input mode, control-to-case ratio, trend scores, and locus-heterogeneity settings.

errors

Genotype-error model and matrices, plus phenotype-error settings and intermediate frequencies.

model_info

Model-based penetrances and risk-model inputs, or model-free identifying information.

scenarios

Named independent results. no_error always exists; requested modifiers add phenotype_misclassification, heterogeneity, and genotype_misclassification. Each contains scenario frequencies, modifier metadata, and genotype/trend power results.

tests, freqs, compatibility_scenario

Compatibility fields. With zero or one modifier, they mirror the sole design previously returned. With several modifiers, they explicitly mirror no_error; use scenarios for each sensitivity result.

References

Gordon, D., Finch, S. J., & Kim, W. (2020). Heterogeneity in Statistical Genetics: How to Assess, Address, and Account for Mixtures in Association Studies. Springer. doi:10.1007/978-3-030-61121-7.

Gordon, D., Finch, S. J., Nothnagel, M., & Ott, J. (2002). Power and sample size calculations for case-control genetic association tests when errors are present: application to single nucleotide polymorphisms. Human Heredity, 54(1), 22–33. doi:10.1159/000066696.

Armitage, P. (1955). Tests for linear trends in proportions and frequencies. Biometrics, 11(3), 375–386. doi:10.2307/3001775.

Slager, S. L., & Schaid, D. J. (2001). Case-control studies of genetic markers: power and sample size approximations for Armitage's test for trend. Human Heredity, 52(3), 149–153. doi:10.1159/000053370.

Edwards, B. J., Haynes, C., Levenstien, M. A., Finch, S. J., & Gordon, D. (2005). Power and sample size calculations in the presence of phenotype errors for case/control genetic association studies. BMC Genetics, 6, 18. doi:10.1186/1471-2156-6-18.

See Also

cc_mssn, case_control_genotype_misclassification, case_control_locus_heterogeneity, and case_control_phenotype_misclassification.

Examples

cc_power(
  N_case = 500, alpha = 0.05,
  input_mode = "model_free",
  g1 = c(0.25, 0.50, 0.25),
  g0 = c(0.36, 0.48, 0.16),
  geno_misclass = "none",
  verbose = FALSE
)

cc_power(
  N_case = 500, alpha = 0.05,
  input_mode = "model_free",
  g1 = c(0.25, 0.50, 0.25),
  g0 = c(0.36, 0.48, 0.16),
  locus_het = TRUE, pi = 0.8,
  verbose = FALSE
)

cc_power(
  N_case = 500, alpha = 0.05,
  input_mode = "model_free",
  g1 = c(0.25, 0.50, 0.25),
  g0 = c(0.36, 0.48, 0.16),
  locus_het = TRUE, pi = 0.8,
  geno_misclass = "3p", e01 = 0.02, e02 = 0.01, e03 = 0.005,
  verbose = FALSE
)

cc_power(
  N_case = 500, alpha = 0.05,
  input_mode = "model_based",
  prev = 0.05, pd = 0.30, R2 = 1.8, MOI = "M",
  pheno_misclass = TRUE, theta = 0.05, phi = 0.01,
  verbose = FALSE
)

cc_power(
  N_case = 500, alpha = 0.05,
  input_mode = "model_based",
  prev = 0.05, pd = 0.30, R2 = 1.8, MOI = "M",
  locus_het = TRUE, pi = 0.8,
  geno_misclass = "3p", e01 = 0.02, e02 = 0.01, e03 = 0.005,
  verbose = FALSE
)

cc_power(
  N_case = 500, alpha = 0.05,
  input_mode = "model_free",
  g1 = c(0.25, 0.50, 0.25),
  g0 = c(0.36, 0.48, 0.16),
  geno_misclass = "diff3p",
  diff_source = "explicit",
  case_e01 = 0.02, case_e02 = 0.01, case_e03 = 0.005,
  ctrl_e01 = 0.01, ctrl_e02 = 0.005, ctrl_e03 = 0.002,
  verbose = FALSE
)

cc_power(
  N_case = 500, alpha = 0.05,
  input_mode = "model_free",
  g1 = c(0.25, 0.50, 0.25),
  g0 = c(0.36, 0.48, 0.16),
  geno_misclass = "diff3p",
  diff_source = "case", diff_multiplier = 0.5,
  case_e01 = 0.02, case_e02 = 0.01, case_e03 = 0.005,
  verbose = FALSE
)

---

Minimum Total Sample Size for an LRTae Design

Description

Finds the minimum integer total sample size required to attain a requested prospective LRTae power while preserving a requested allocation among the four measurement and validation tiers as closely as integer counts permit. This is a prospective-design calculation and is not an observed-data test.

Usage

lrtae_mssn(
  true_control_genotype_frequencies,
  true_case_genotype_frequencies,
  true_sampling_proportions,
  phenotype_misclassification_matrix,
  genotype_misclassification_matrix,
  target_power,
  alpha,
  prop_fallible,
  prop_pheno_validated,
  prop_geno_validated,
  prop_both_validated
)

Arguments

true_control_genotype_frequencies	Numeric vector of true genotype frequencies among controls.
true_case_genotype_frequencies	Numeric vector of true genotype frequencies among cases, in the same category order as true_control_genotype_frequencies.
true_sampling_proportions	Numeric vector of length two containing the true control and case sampling proportions, in that order.
phenotype_misclassification_matrix	Numeric two-by-two matrix whose rows are true phenotype categories (control, case) and whose columns are observed phenotype categories (control, case).
genotype_misclassification_matrix	Numeric square matrix whose rows are true genotype categories and whose columns are observed genotype categories, in the genotype-frequency order.
target_power	Requested power, strictly greater than alpha and less than one.
alpha	Significance level, strictly between zero and one.
prop_fallible	Proportion allocated to fallible phenotype and genotype measurements only.
prop_pheno_validated	Proportion allocated to phenotype validation with fallible genotype measurement.
prop_geno_validated	Proportion allocated to genotype validation with fallible phenotype measurement.
prop_both_validated	Proportion allocated to validation of both phenotype and genotype.

Details

The four allocation proportions must be nonnegative and sum to one. For every candidate total N, integer counts are assigned by the largest-remainder (Hamilton) rule: floor N * proportion for each tier, then distribute the remaining individuals in descending order of fractional remainder. Exact ties are resolved in the fixed order: fallible, phenotype validated, genotype validated, both validated. Thus allocated counts always sum exactly to N.

The search doubles an upper bound until it attains target_power, applies integer binary search within the bracket, and explicitly verifies the neighboring design at N - 1. Power at each candidate is evaluated through lrtae_power(), which uses the validated corrected lrtae_ncp() engine, k - 1 degrees of freedom, and a noncentral chi-square distribution.

Value

An object of class lrtae_mssn, containing MSSN_total, target_power, achieved_power, achieved_ncp, df, alpha, critical_value, requested allocation proportions, and the four allocated integer tier counts.

Examples

lrtae_mssn(
  true_control_genotype_frequencies = c(0.81, 0.18, 0.01),
  true_case_genotype_frequencies = c(0.64, 0.32, 0.04),
  true_sampling_proportions = c(0.5, 0.5),
  phenotype_misclassification_matrix = matrix(
    c(0.95, 0.05, 0.05, 0.95), 2, byrow = TRUE
  ),
  genotype_misclassification_matrix = matrix(
    c(0.950, 0.050, 0.000,
      0.025, 0.950, 0.025,
      0.000, 0.050, 0.950),
    3, byrow = TRUE
  ),
  target_power = 0.80,
  alpha = 0.05,
  prop_fallible = 0.7,
  prop_pheno_validated = 0.1,
  prop_geno_validated = 0.1,
  prop_both_validated = 0.1
)

---

Noncentrality Parameter for Prospective LRTae Designs

Description

Computes the analytic noncentrality parameter (NCP) for the likelihood-ratio test allowing for error (LRTae) in a prospective case-control design. The calculation incorporates fallible measurements and validation subsamples for phenotype, genotype, or both. It does not analyze observed study data.

Usage

lrtae_ncp(
  true_control_genotype_frequencies,
  true_case_genotype_frequencies,
  true_sampling_proportions,
  phenotype_misclassification_matrix,
  genotype_misclassification_matrix,
  n_fallible,
  n_pheno_validated,
  n_geno_validated,
  n_both_validated
)

Arguments

true_control_genotype_frequencies	Numeric vector of true genotype frequencies among controls.
true_case_genotype_frequencies	Numeric vector of true genotype frequencies among cases, in the same category order as true_control_genotype_frequencies.
true_sampling_proportions	Numeric vector of length two containing the true control and case sampling proportions, in that order.
phenotype_misclassification_matrix	Numeric two-by-two matrix whose rows are true phenotype categories (control, case) and whose columns are observed phenotype categories (control, case).
genotype_misclassification_matrix	Numeric square matrix whose rows are true genotype categories and whose columns are observed genotype categories, in the genotype-frequency order.
n_fallible	Number sampled with fallible phenotype and genotype measurements only.
n_pheno_validated	Number whose phenotype is validated while genotype is measured fallibly.
n_geno_validated	Number whose genotype is validated while phenotype is measured fallibly.
n_both_validated	Number whose phenotype and genotype are both validated.

Value

A single nonnegative numeric value: the LRTae NCP.

References

Ji, F., Yang, Y., Haynes, C., Finch, S. J., & Gordon, D. (2005). Computing asymptotic power and sample size for case-control genetic association studies in the presence of phenotype and/or genotype misclassification errors. Statistical Applications in Genetics and Molecular Biology, 4(1), Article 37. doi:10.2202/1544-6115.1184

Barral, S., Haynes, C., Stone, M., & Gordon, D. (2006). LRTae: improving statistical power for genetic association with case/control data when phenotype and/or genotype misclassification errors are present. BMC Genetics, 7, 24. doi:10.1186/1471-2156-7-24

Gordon, D., Finch, S. J., & Kim, W. (2020). Heterogeneity in Statistical Genetics: How to Assess, Address, and Account for Mixtures in Association Studies. Springer. doi:10.1007/978-3-030-61121-7

Examples

lrtae_ncp(
  true_control_genotype_frequencies = c(0.81, 0.18, 0.01),
  true_case_genotype_frequencies = c(0.64, 0.32, 0.04),
  true_sampling_proportions = c(0.5, 0.5),
  phenotype_misclassification_matrix = matrix(
    c(0.95, 0.05, 0.05, 0.95), nrow = 2, byrow = TRUE
  ),
  genotype_misclassification_matrix = matrix(
    c(0.950, 0.050, 0.000,
      0.025, 0.950, 0.025,
      0.000, 0.050, 0.950),
    nrow = 3, byrow = TRUE
  ),
  n_fallible = 700,
  n_pheno_validated = 100,
  n_geno_validated = 100,
  n_both_validated = 100
)

---

Prospective Power for an LRTae Design

Description

Computes prospective power for the likelihood-ratio test allowing for error (LRTae). The function uses lrtae_ncp() and the corrected LRTae information matrix; it does not perform an observed-data hypothesis test.

Usage

lrtae_power(
  true_control_genotype_frequencies,
  true_case_genotype_frequencies,
  true_sampling_proportions,
  phenotype_misclassification_matrix,
  genotype_misclassification_matrix,
  n_fallible,
  n_pheno_validated,
  n_geno_validated,
  n_both_validated,
  alpha
)

Arguments

true_control_genotype_frequencies	Numeric vector of true genotype frequencies among controls.
true_case_genotype_frequencies	Numeric vector of true genotype frequencies among cases, in the same category order as true_control_genotype_frequencies.
true_sampling_proportions	Numeric vector of length two containing the true control and case sampling proportions, in that order.
phenotype_misclassification_matrix	Numeric two-by-two matrix whose rows are true phenotype categories (control, case) and whose columns are observed phenotype categories (control, case).
genotype_misclassification_matrix	Numeric square matrix whose rows are true genotype categories and whose columns are observed genotype categories, in the genotype-frequency order.
n_fallible	Number sampled with fallible phenotype and genotype measurements only.
n_pheno_validated	Number whose phenotype is validated while genotype is measured fallibly.
n_geno_validated	Number whose genotype is validated while phenotype is measured fallibly.
n_both_validated	Number whose phenotype and genotype are both validated.
alpha	Significance level, strictly between zero and one.

Details

For k genotype categories, the asymptotic reference distribution has k - 1 degrees of freedom. The rejection threshold is the upper alpha quantile of the central chi-square distribution, and power is the corresponding upper-tail probability from a noncentral chi-square distribution with the NCP returned by lrtae_ncp().

Value

An object of class lrtae_power, containing power, ncp, df, alpha, critical_value, the four sampling-tier counts, and N_total.

Examples

lrtae_power(
  true_control_genotype_frequencies = c(0.81, 0.18, 0.01),
  true_case_genotype_frequencies = c(0.64, 0.32, 0.04),
  true_sampling_proportions = c(0.5, 0.5),
  phenotype_misclassification_matrix = matrix(
    c(0.95, 0.05, 0.05, 0.95), 2, byrow = TRUE
  ),
  genotype_misclassification_matrix = matrix(
    c(0.950, 0.050, 0.000,
      0.025, 0.950, 0.025,
      0.000, 0.050, 0.950),
    3, byrow = TRUE
  ),
  n_fallible = 700,
  n_pheno_validated = 100,
  n_geno_validated = 100,
  n_both_validated = 100,
  alpha = 0.05
)

---

Sequencing-Derived Genotype Error Matrix

Description

Constructs the analytic genotype transition matrix induced by fixed sequencing coverage, symmetric per-read sequencing error, and deterministic maximum-likelihood genotype calling.

Usage

ngs_genotype_error_matrix(coverage, seq_error)

Arguments

coverage	A single finite integer greater than or equal to 1 giving sequencing coverage (read depth).
seq_error	A single finite numeric sequencing-error probability in [0, 0.5).

Details

For true genotype $G \in \{0,1,2\}$, the alternate-read count follows

$X \mid G,V,\epsilon \sim \mathrm{Binomial}(V,q_G),$

where $q_0=\epsilon$, $q_1=0.5$, and $q_2=1-\epsilon$. For every possible alternate-read count, the called genotype maximizes its binomial likelihood among the three genotype models.

Numerical likelihood ties within 1e-12 are resolved symmetrically: below an alternate-read fraction of one half, the lower tied genotype is selected; above one half, the higher tied genotype is selected; at exactly one half, the tied genotype closest to 1 is selected.

Rows correspond to true genotypes and columns to called genotypes. Thus, if E is the returned matrix and g_true is a length-three vector of true genotype probabilities, called-genotype probabilities are obtained as as.numeric(t(E) %*% g_true). Every row sums to one within numerical precision.

At finite coverage, even with zero sequencing error, a true heterozygote can produce all-reference or all-alternate reads. Consequently the finite-depth matrix need not be exactly the identity, especially at very low coverage.

Value

A numeric 3 x 3 matrix. Rows true_0, true_1, and true_2 identify the true genotype; columns called_0, called_1, and called_2 identify the maximum-likelihood call.

Examples

E <- ngs_genotype_error_matrix(coverage = 10, seq_error = 0.01)
g_true <- c(0.70, 0.25, 0.05)
as.numeric(t(E) %*% g_true)

---

Construct the paweh Shiny Dashboard

Description

Creates the modular bslib dashboard for paweh study design. The Case-Control and TDT / Family workspaces provide canonical power, minimum-sample-size, sensitivity, and study-specific visual results. The Quantitative Trait workspace collects the canonical function inputs and displays that function's verbose console output. Dashboard calculations delegate to the same canonical package functions as the programmatic R interface.

Usage

paweh_app()

Details

paweh_app() returns the application object without launching it. This makes the app safe to construct in package code, tests, and deployment tooling. Launch it explicitly with shiny::runApp().

Value

A Shiny application object inheriting from shiny.appobj.

Examples

app <- paweh_app()
inherits(app, "shiny.appobj")
if (interactive()) {
  shiny::runApp(app)
}

---

Plot Case-Control Minimum Sample Size Necessary

Description

Sweeps one x-axis parameter and repeatedly calls cc_mssn() to plot the minimum sample size necessary (MSSN) for case-control tests.

Usage

plot_cc_mssn(
  x_var,
  x_values,
  test = c("genotypes", "trend"),
  input_mode = c("model_based", "model_free"),
  sample_size = c("total", "case", "control"),
  compare_tests = FALSE,
  title = NULL,
  x_label = NULL,
  y_label = NULL,
  return_data = FALSE,
  ...
)

Arguments

x_var	Character. Parameter to vary on the x-axis.
x_values	Numeric vector of x-axis values.
test	One of "genotypes" or "trend".
input_mode	One of "model_based" or "model_free".
sample_size	One of "total", "case", or "control".
compare_tests	Logical. If TRUE, plot genotype and trend tests together and ignore test.
title	Optional character title override.
x_label	Optional x-axis label override.
y_label	Optional y-axis label override.
return_data	Logical. If TRUE, return the data frame instead of a ggplot.
...	Arguments passed to cc_mssn().

Details

The supported test values are "genotypes" and "trend". sample_size selects whether to plot required cases, controls, or total sample size. compare_tests = TRUE plots both tests together.

Supported x_var values are the same heterogeneity and misclassification variables documented for plot_cc_power(), plus "power" for target power. Fixed sample-size variables such as "N_case" are not valid because sample size is the MSSN output.

Multiplier behavior matches plot_cc_power(): pheno_error_multiplier multiplies baseline theta_base and phi_base; geno_error_multiplier multiplies the corresponding baseline genotype-error parameters for the selected genotype misclassification model. All arguments in ... remain fixed while x_var is swept. The y-axis is the required number of selected cases, controls, or total individuals returned by cc_mssn(), according to sample_size. For locus-heterogeneity sweeps, an exact pi = 0 design has no finite MSSN when target power exceeds alpha. That scientifically structural boundary is retained with MSSN NA, finite_mssn = FALSE, and status = "no finite MSSN"; other errors are propagated unchanged.

Value

A ggplot object, or a data frame if return_data = TRUE.

See Also

cc_mssn, plot_cc_power.

Examples

plot_cc_mssn(
  x_var = "geno_error_multiplier",
  x_values = c(0, 1, 2),
  test = "trend",
  input_mode = "model_based",
  power = 0.80,
  alpha = 0.05,
  prev = 0.10,
  pd = 0.25,
  R2 = 2,
  MOI = "M",
  geno_misclass = "3p",
  e01_base = 0.02,
  e02_base = 0.01,
  e03_base = 0.005,
  k = 1
)

---

Plot Case-Control Power

Description

Sweeps one x-axis parameter and repeatedly calls cc_power() to plot case-control power. The wrapper supports both input_mode = "model_based" and input_mode = "model_free".

Usage

plot_cc_power(
  x_var,
  x_values,
  test = c("genotypes", "trend"),
  input_mode = c("model_based", "model_free"),
  compare_tests = FALSE,
  title = NULL,
  x_label = NULL,
  y_label = NULL,
  return_data = FALSE,
  ...
)

Arguments

x_var	Character. Parameter to vary on the x-axis.
x_values	Numeric vector of x-axis values.
test	One of "genotypes" or "trend".
input_mode	One of "model_based" or "model_free".
compare_tests	Logical. If TRUE, plot genotype and trend tests together and ignore test.
title	Optional character title override.
x_label	Optional x-axis label override.
y_label	Optional y-axis label override.
return_data	Logical. If TRUE, return the data frame instead of a ggplot.
...	Arguments passed to cc_power().

Details

Supported x_var values include fixed sample-size variables "N_case", "N_ctrl", and "N_total"; model and design variables "alpha", "prev", "pd", "R2", and "k"; locus-heterogeneity variables "pi" and "locus_het_rate"; phenotype-misclassification variables "theta", "phi", and "pheno_error_multiplier"; and genotype-misclassification variables "e", "e1", "e2", "e01", "e02", "e03", case/control differential three-parameter error rates, "geno_error_multiplier", and "diff_multiplier".

When x_var = "pheno_error_multiplier", baseline phenotype-error values are read from theta_base and phi_base, falling back to theta and phi if the baseline arguments are not supplied. When x_var = "geno_error_multiplier", baseline genotype-error values are read from e_base; e1_base and e2_base; e01_base, e02_base, and e03_base; or case/control baseline parameters for geno_misclass = "diff3p". All arguments supplied through ... remain fixed while x_var is swept. The x-axis contains x_values; the y-axis is the power returned by cc_power() for the selected genotype chi-square or trend test. With compare_tests = TRUE, both powers are drawn on the same axes. When sweeping x_var = "pi", set locus_het = TRUE. The exact pi = 0 null boundary is retained in returned and plotted data with zero NCP and power equal to alpha.

Value

A ggplot object, or a data frame if return_data = TRUE.

See Also

cc_power, plot_cc_mssn.

Examples

g_aff <- c((1 - 0.05)^2, 2 * 0.05 * (1 - 0.05), 0.05^2)
g_unaff <- c((1 - 0.15)^2, 2 * 0.15 * (1 - 0.15), 0.15^2)

plot_cc_power(
  x_var = "phi",
  x_values = c(0, 0.02, 0.04),
  test = "genotypes",
  input_mode = "model_free",
  N_case = 250,
  alpha = 0.01,
  g1 = g_aff,
  g0 = g_unaff,
  prev = 0.05,
  pheno_misclass = TRUE,
  theta = 0,
  k = 1
)

---

Plot MSSN Sensitivity for Sequencing Designs

Description

Plots analytic minimum sample size necessary (MSSN) against equal fixed sequencing coverage for either a case-control sequencing trend design or a TDT1-NGS design. Calculations delegate to the corresponding public MSSN API.

Usage

plot_ngs_mssn(
  design = c("cc", "tdt"),
  coverage,
  seq_error,
  return_data = FALSE,
  ...
)

Arguments

design	Either "cc" for cc_ngs_mssn() or "tdt" for tdt_ngs_mssn().
coverage	Non-empty numeric vector of integer fixed sequencing depths. TDT1-NGS requires coverage of at least 2.
seq_error	Non-empty numeric vector of symmetric per-read sequencing error probabilities in $[0,0.5)$. Multiple values produce separate curves.
return_data	Logical. If TRUE, return the exact plotting data rather than a ggplot object.
...	Fixed arguments passed to cc_ngs_mssn() or tdt_ngs_mssn(). For case-control designs, locus_het = TRUE permits a vector of pi values. TDT1-NGS accepts a fixed locus_het and heter_rate through ...; its public convention is heter_rate = 1 - pi.

Details

The primary case-control y-axis is required cases; returned plot data also retain required controls, total MSSN, and achieved power. The primary TDT1-NGS y-axis is required complete trios; returned data also retain total individuals and achieved power.

At the case-control exact-null boundary pi = 0, no finite MSSN exists when requested power exceeds alpha. The row is retained with MSSN and achieved power set to NA, finite_mssn = FALSE, and status "no finite MSSN". No artificial finite value is plotted. Only this expected scientific condition is converted; invalid inputs and unexpected calculation errors propagate unchanged.

Coverage is fixed and equal for the relevant study members. These plots do not model variable/BGE coverage distributions, cost optimization, or sample-specific depth. They use no simulation.

Value

A ggplot object with exact results in plot$data, or a data frame when return_data = TRUE.

See Also

plot_ngs_power, cc_ngs_mssn, tdt_ngs_mssn

Examples

plot_ngs_mssn(
  design = "tdt", coverage = c(4, 12, 20), seq_error = 0.005,
  power = 0.80, pd = 0.325, R1 = 1.2, alpha = 5e-8,
  verbose = FALSE
)

---

Plot Power Sensitivity for Sequencing Designs

Description

Plots prospective analytic power against equal fixed sequencing coverage for either a case-control sequencing trend design or a TDT1-NGS design. Exact values are obtained by repeated calls to the corresponding validated public design function.

Usage

plot_ngs_power(
  design = c("cc", "tdt"),
  coverage,
  seq_error,
  target_power = NULL,
  return_data = FALSE,
  ...
)

Arguments

design	Either "cc" for cc_ngs_power() or "tdt" for tdt_ngs_power().
coverage	Non-empty numeric vector of integer fixed sequencing depths. TDT1-NGS requires coverage of at least 2.
seq_error	Non-empty numeric vector of symmetric per-read sequencing error probabilities in $[0,0.5)$. Multiple values produce separate curves.
target_power	Optional finite scalar in $(0,1)$. If supplied, a dashed horizontal reference line is added without changing calculations.
return_data	Logical. If TRUE, return the exact plotting data rather than a ggplot object.
...	Fixed arguments passed to cc_ngs_power() or tdt_ngs_power(). For case-control designs, locus_het = TRUE permits a vector of pi values. TDT1-NGS accepts a fixed locus_het and heter_rate through ...; its public convention is heter_rate = 1 - pi.

Details

Case-control output retains coverage, sequencing error, locus-homogeneity fraction, sample sizes, NCP, and power. At pi = 0, the exact null point is retained with NCP zero and power equal to alpha. TDT1-NGS uses raw read-count probabilities and does not use the case-control hard-call model.

Coverage is fixed and equal for the relevant study members. These plots do not model variable/BGE coverage distributions, cost optimization, or sample-specific depth. They introduce no simulation and delegate all statistical calculations to public PAWEH sequencing design APIs.

Value

A ggplot object with exact results in plot$data, or a data frame when return_data = TRUE.

See Also

plot_ngs_mssn, cc_ngs_power, tdt_ngs_power

Examples

plot_ngs_power(
  design = "cc", coverage = c(4, 12, 20), seq_error = c(0, 0.01),
  N_case = 1000, alpha = 0.05, prev = 0.05, pd = 0.30, R2 = 1.8,
  MOI = "M", verbose = FALSE
)

---

Plot One-Way ANOVA Minimum Sample Size Under the Falconer Model

Description

Sweeps one model or design parameter and repeatedly calls qtl_anova_mssn().

Usage

plot_qtl_anova_mssn(
  x_var,
  x_values,
  title = NULL,
  x_label = NULL,
  y_label = NULL,
  return_data = FALSE,
  ...
)

Arguments

x_var	Parameter to vary. One of "power", "alpha", "qtl_var", "tau", or "pd".
x_values	Numeric vector of at least two finite x-axis values.
title	Optional plot-title override.
x_label	Optional x-axis-label override.
y_label	Optional y-axis-label override.
return_data	Logical. If TRUE, returns plotting data rather than a ggplot object.
...	Fixed arguments passed to qtl_anova_mssn().

Details

The x-axis is x_values for the selected x_var; the y-axis is the minimum total sample size returned by qtl_anova_mssn(). Target power and other arguments in ... remain fixed unless selected as x_var.

Value

A ggplot object, or a data frame with the swept parameter and required_N if return_data = TRUE.

See Also

qtl_anova_mssn, plot_qtl_anova_power.

Examples

plot_qtl_anova_mssn(
  x_var = "qtl_var", x_values = c(0.015, 0.025, 0.05),
  power = 0.8, alpha = 0.0001, tau = 0.5, pd = 0.15
)

---

Plot One-Way ANOVA Power Under the Falconer Model

Description

Sweeps one model or design parameter and repeatedly calls qtl_anova_power() for a single continuous quantitative trait.

Usage

plot_qtl_anova_power(
  x_var,
  x_values,
  title = NULL,
  x_label = NULL,
  y_label = NULL,
  return_data = FALSE,
  ...
)

Arguments

x_var	Parameter to vary. One of "N", "alpha", "qtl_var", "tau", or "pd".
x_values	Numeric vector of at least two finite x-axis values.
title	Optional plot-title override.
x_label	Optional x-axis-label override.
y_label	Optional y-axis-label override.
return_data	Logical. If TRUE, returns plotting data rather than a ggplot object.
...	Fixed arguments passed to qtl_anova_power().

Details

The x-axis is x_values for the selected x_var; the y-axis is one-way ANOVA power from qtl_anova_power(). Every argument in ... remains fixed while the selected parameter is swept.

Value

A ggplot object, or a data frame with the swept parameter and power if return_data = TRUE.

See Also

qtl_anova_power, plot_qtl_anova_mssn.

Examples

plot_qtl_anova_power(
  x_var = "N", x_values = c(600, 800, 1000),
  alpha = 0.0001, qtl_var = 0.025, tau = 0.5, pd = 0.15
)

---

Plot Falconer Genotype-Specific Quantitative-Trait Distributions

Description

Displays the three normal quantitative-trait distributions implied by a validated single-trait Falconer model. Large QTL variance separates the genotype distributions relative to their residual variation; small QTL variance makes them overlap heavily.

Usage

plot_qtl_genotype_distribution(
  qtl_var,
  tau,
  pd,
  type = c("density", "histogram", "binned"),
  scale = c("density", "frequency"),
  n = 3000,
  seed = NULL,
  show_means = TRUE,
  verbose = FALSE,
  title = NULL,
  return_data = FALSE,
  bins = 30L
)

Arguments

qtl_var	QTL variance in ⁠(0, 1)⁠.
tau	Dominance-to-additivity ratio.
pd	Increaser-allele frequency in ⁠(0, 1)⁠.
type	One of "density" for theoretical normal curves, "histogram" for a simulated population, or "binned" for a deterministic histogram-style display calculated from Normal CDF differences.
scale	Either "density" or "frequency". For theoretical curves, frequency scaling weights each density by its Hardy–Weinberg genotype frequency. For histograms, it selects normalized densities or counts.
n	Total population size simulated in histogram mode.
seed	Optional non-negative integer used locally for reproducible histogram simulation. The caller's random-number state is restored.
show_means	Logical; mark the three theoretical genotype means.
verbose	Logical; passed to the validated Falconer parameter backend.
title	Optional plot title.
return_data	Logical; return the plotting data frame instead of the ggplot object. The Falconer model is retained in its falconer_model attribute.
bins	Positive integer number of equal-width bins used when type = "binned". This does not affect the existing density or simulated histogram modes.

Details

Conditional on genotype j, the plotted trait follows a normal distribution with the corresponding Falconer mean and common residual variance 1 - qtl_var. Genotypes 0, 1, and 2 have Hardy–Weinberg frequencies (1 - pd)^2, 2 * pd * (1 - pd), and pd^2. Genotypes may also be interpreted as bb, Bb, and BB, respectively.

Density and binned modes are analytic and perform no simulation. In binned mode, each conditional bin probability is the difference between Normal CDF values at the upper and lower bin boundaries. Histogram mode first samples genotypes from their Hardy–Weinberg frequencies and then samples trait values from the corresponding conditional normal distributions. The x-axis is the quantitative-trait value. In analytic density mode, the y-axis is genotype-specific density when scale = "density" and population-weighted density when scale = "frequency". Binned mode uses conditional bin probability divided by bin width, with an additional genotype-frequency multiplier under scale = "frequency". In simulated histogram mode, the y-axis is normalized density or bin count for those respective scales.

Value

A ggplot object, or a plotting data frame when return_data = TRUE.

See Also

qtl_falconer_parameters(), plot_qtl_anova_power(), and plot_qtl_threshold_chisq_power().

Examples

# A large QTL effect visibly separates the genotype distributions.
plot_qtl_genotype_distribution(
  qtl_var = 0.5, tau = 0, pd = 0.25, scale = "frequency"
)

# A very small QTL effect produces almost complete overlap.
plot_qtl_genotype_distribution(
  qtl_var = 0.0005, tau = 0, pd = 0.25, scale = "frequency"
)

---

Plot Threshold-Selected Genotype Chi-Square Minimum Sample Size

Description

Sweeps one model, selection, or design parameter and repeatedly calls qtl_threshold_chisq_mssn().

Usage

plot_qtl_threshold_chisq_mssn(
  x_var,
  x_values,
  sample_size = c("total", "case", "control"),
  title = NULL,
  x_label = NULL,
  y_label = NULL,
  return_data = FALSE,
  ...
)

Arguments

x_var	Parameter to vary. One of "power", "alpha", "qtl_var", "tau", "pd", "x_upper", "x_lower", or "k".
x_values	Numeric vector of at least two finite x-axis values.
sample_size	Selected-sample result to plot: "total", "case", or "control". Population screening counts are deliberately excluded because they are not statistical MSSN values.
title	Optional plot-title override.
x_label	Optional x-axis-label override.
y_label	Optional y-axis-label override.
return_data	Logical. If TRUE, returns plotting data rather than a ggplot object.
...	Fixed arguments passed to qtl_threshold_chisq_mssn().

Details

The x-axis is x_values for the selected model, selection, or design parameter. The y-axis is the selected case, control, or total MSSN requested by sample_size; it is not a source-population screening count. Other arguments remain fixed while x_var is swept.

Value

A ggplot object, or a data frame with the swept parameter and the selected MSSN result if return_data = TRUE.

See Also

qtl_threshold_chisq_mssn, plot_qtl_threshold_chisq_power.

Examples

plot_qtl_threshold_chisq_mssn(
  x_var = "qtl_var", x_values = c(0.015, 0.025, 0.05),
  power = 0.8, alpha = 0.0001, tau = 0.5, pd = 0.15,
  x_upper = 5, x_lower = 5, k = 1
)

---

Plot Threshold-Selected Genotype Chi-Square Power

Description

Sweeps one model, selection, or design parameter and repeatedly calls qtl_threshold_chisq_power().

Usage

plot_qtl_threshold_chisq_power(
  x_var,
  x_values,
  title = NULL,
  x_label = NULL,
  y_label = NULL,
  return_data = FALSE,
  ...
)

Arguments

x_var	Parameter to vary. One of "N_case", "alpha", "qtl_var", "tau", "pd", "x_upper", "x_lower", or "k".
x_values	Numeric vector of at least two finite x-axis values.
title	Optional plot-title override.
x_label	Optional x-axis-label override.
y_label	Optional y-axis-label override.
return_data	Logical. If TRUE, returns plotting data rather than a ggplot object.
...	Fixed arguments passed to qtl_threshold_chisq_power().

Details

The x-axis is x_values for the selected model, selection, or design parameter. The y-axis is power for the two-df genotype chi-square test after upper-tail case and lower-tail control selection. Arguments in ... remain fixed while x_var is swept.

Value

A ggplot object, or a data frame with the swept parameter and power if return_data = TRUE.

See Also

qtl_threshold_chisq_power, plot_qtl_threshold_chisq_mssn.

Examples

plot_qtl_threshold_chisq_power(
  x_var = "N_case", x_values = c(75, 100, 125, 150),
  alpha = 0.0001, qtl_var = 0.025, tau = 0.5, pd = 0.15,
  x_upper = 5, x_lower = 5, k = 1
)

---

Plot TDT Minimum Sample Size Necessary

Description

Sweeps one x-axis parameter and repeatedly calls tdt_mssn() to plot MSSN in affected trios. The wrapper supports both input_mode = "model_based" and input_mode = "model_free".

Usage

plot_tdt_mssn(
  x_var,
  x_values,
  scenario = c("auto", "no_error", "misclassification", "heterogeneity"),
  input_mode = c("model_based", "model_free"),
  title = NULL,
  x_label = NULL,
  y_label = NULL,
  return_data = FALSE,
  ...
)

Arguments

x_var	Character. Parameter to vary on the x-axis.
x_values	Numeric vector of x-axis values.
scenario	One of "auto", "no_error", "misclassification", or "heterogeneity".
input_mode	One of "model_based" or "model_free".
title	Optional character title override.
x_label	Optional x-axis label override.
y_label	Optional y-axis label override.
return_data	Logical. If TRUE, return the data frame instead of a ggplot.
...	Arguments passed to tdt_mssn().

Details

scenario selects the component of the canonical TDT backend output: "no_error", "misclassification", or "heterogeneity". With scenario = "auto", the wrapper chooses the scenario from x_var using the same rules as plot_tdt_power(). This wrapper does not include a compare-scenarios mode. x_var = "N" is not allowed because required trios are the output; use "target_power" to sweep target power.

With input_mode = "model_based" (the default), this wrapper's x_var choices and output are numerically identical to sweeping tdt_mssn() directly. "pd", "prev", "R1", "R2", and "delta_prime" are only valid x_var choices in this mode.

With input_mode = "model_free", sweep "ET", "ENT", or "n_trios" instead (or any of the shared "misclass_rate", "heter_rate", "locus_het_rate", or "pheno_error_multiplier" variables). A resolved scenario = "heterogeneity" requires a fixed pd argument, and scenario = "misclassification" requires fixed pd and prev arguments, because the conditional backend needs them to apply heter_rate/misclass_rate to the supplied ET/ENT. Unlike tdt_mssn()'s own default of 0.01, heter_rate and misclass_rate default to 0 here in input_mode = "model_free" (unless fixed via ... or swept via x_var), so scenario = "no_error" always works without pd/prev. All arguments passed through ... remain fixed while x_var is swept. The y-axis is MSSN expressed as the required number of affected trios for the resolved scenario. When x_var = "heter_rate", it is the heterogeneous trio fraction $1-\pi$; target_power remains fixed unless it is itself the swept variable.

Value

A ggplot object, or a data frame if return_data = TRUE.

See Also

tdt_mssn, plot_tdt_power, plot_tdt_mssn_phenotype_misclassification, and plot_tdt_mssn_locus_heterogeneity.

Examples

plot_tdt_mssn(
  x_var = "misclass_rate",
  x_values = c(0, 0.02, 0.04),
  scenario = "misclassification",
  input_mode = "model_based",
  target_power = 0.80,
  pd = 0.30,
  prev = 0.05,
  R1 = 1.5,
  R2 = 2.25,
  alpha = 0.05,
  delta_prime = 1
)

---

Plot TDT MSSN Sensitivity to Locus Heterogeneity

Description

Plot required number of trios vs heterogeneity rate (1 - pi), holding misclassification fixed.

Usage

plot_tdt_mssn_locus_heterogeneity(
  pd,
  prev,
  R1,
  R2,
  alpha = 0.05,
  delta_prime = 1,
  target_power,
  heter_seq = seq(0, 0.5, by = 0.05),
  misclass_fixed = 0,
  title = "Required trios vs heterogeneity (1 - pi)"
)

Arguments

pd	Disease allele frequency.
prev	Disease prevalence.
R1	Genotype relative risk for heterozygotes.
R2	Genotype relative risk for risk homozygotes.
alpha	Significance level.
delta_prime	Linkage disequilibrium scaling parameter.
target_power	Desired statistical power.
heter_seq	Numeric vector. Sequence of heterogeneity rates.
misclass_fixed	Numeric. Misclassification rate held fixed (default 0). (Other params same meaning as in plot_tdt_power_phenotype_misclassification.)
title	Plot title.

Details

The x-axis is the heterogeneous trio fraction $1-\pi$; the homogeneous/linked fraction is $\pi$. The y-axis is MSSN, the required number of affected trios returned by tdt_mssn() for fixed target_power. misclass_fixed and genetic-model parameters remain fixed.

Value

A ggplot object, returned invisibly after it is printed.

See Also

tdt_mssn, plot_tdt_mssn_phenotype_misclassification, and plot_tdt_mssn.

Examples

# Required sample size sensitivity to locus heterogeneity
plot_tdt_mssn_locus_heterogeneity(
  target_power = 0.80,
  pd   = 0.30,
  prev = 0.05,
  R1   = 1.5,
  R2   = 2.25,
  heter_seq      = c(0, 0.1, 0.2),
  misclass_fixed = 0
)

---

Plot TDT MSSN Sensitivity to Phenotype Misclassification

Description

Plot required number of trios vs misclassification rate (pi01), holding heterogeneity fixed.

Usage

plot_tdt_mssn_phenotype_misclassification(
  pd,
  prev,
  R1,
  R2,
  alpha = 0.05,
  delta_prime = 1,
  target_power,
  misclass_seq = seq(0, 0.15, by = 0.01),
  heter_fixed = 0,
  title = "Required trios vs misclassification (pi01)"
)

Arguments

pd	Disease allele frequency.
prev	Disease prevalence.
R1	Genotype relative risk for heterozygotes.
R2	Genotype relative risk for risk homozygotes.
alpha	Significance level.
delta_prime	Linkage disequilibrium scaling parameter.
target_power	Numeric. Desired power for sample size calculation.
misclass_seq	Numeric vector. Sequence of misclassification rates.
heter_fixed	Numeric. Heterogeneity rate held fixed (default 0). (Other params same meaning as in plot_tdt_power_phenotype_misclassification.)
title	Plot title.

Details

The x-axis is phenotype misclassification probability $\pi_{01}$. The y-axis is MSSN, the required number of affected trios returned by tdt_mssn() for fixed target_power. heter_fixed and all genetic-model parameters remain fixed.

Value

A ggplot object, returned invisibly after it is printed.

See Also

tdt_mssn, plot_tdt_mssn_locus_heterogeneity, and plot_tdt_mssn.

Examples

# Required sample size sensitivity to phenotype misclassification
plot_tdt_mssn_phenotype_misclassification(
  target_power = 0.80,
  pd   = 0.30,
  prev = 0.05,
  R1   = 1.5,
  R2   = 2.25,
  misclass_seq = c(0, 0.03, 0.06),
  heter_fixed  = 0
)

---

Plot TDT Power

Description

Sweeps one x-axis parameter and repeatedly calls tdt_power() to plot Transmission Disequilibrium Test (TDT) power. The wrapper supports both input_mode = "model_based" and input_mode = "model_free".

Usage

plot_tdt_power(
  x_var,
  x_values,
  scenario = c("auto", "no_error", "misclassification", "heterogeneity"),
  input_mode = c("model_based", "model_free"),
  title = NULL,
  x_label = NULL,
  y_label = NULL,
  return_data = FALSE,
  ...
)

Arguments

x_var	Character. Parameter to vary on the x-axis.
x_values	Numeric vector of x-axis values.
scenario	One of "auto", "no_error", "misclassification", or "heterogeneity".
input_mode	One of "model_based" or "model_free".
title	Optional character title override.
x_label	Optional x-axis label override.
y_label	Optional y-axis label override.
return_data	Logical. If TRUE, return the data frame instead of a ggplot.
...	Arguments passed to tdt_power().

Details

scenario selects the component of the canonical TDT backend output: "no_error", "misclassification", or "heterogeneity". With scenario = "auto", the wrapper chooses misclassification for x_var = "misclass_rate" or "pheno_error_multiplier", heterogeneity for x_var = "heter_rate" or "locus_het_rate", and no error otherwise. This wrapper does not include a compare-scenarios mode.

With input_mode = "model_based" (the default), this wrapper's x_var choices and output are numerically identical to sweeping tdt_power() directly. "pd", "prev", "R1", "R2", and "delta_prime" are only valid x_var choices in this mode.

With input_mode = "model_free", sweep "ET" or "ENT" instead (or any of the shared "misclass_rate", "heter_rate", "locus_het_rate", or "pheno_error_multiplier" variables). A resolved scenario = "heterogeneity" requires a fixed pd argument, and scenario = "misclassification" requires fixed pd and prev arguments, because the conditional backend needs them to apply heter_rate/misclass_rate to the supplied ET/ENT. Unlike tdt_power()'s own default of 0.01, heter_rate and misclass_rate default to 0 here in input_mode = "model_free" (unless fixed via ... or swept via x_var), so scenario = "no_error" always works without pd/prev. All arguments passed through ... remain fixed while x_var is swept. The x-axis contains x_values; the y-axis is TDT power for the resolved scenario. When x_var = "heter_rate", the axis is the heterogeneous trio fraction $1-\pi$.

Value

A ggplot object, or a data frame if return_data = TRUE.

See Also

tdt_power, plot_tdt_mssn, plot_tdt_power_phenotype_misclassification, and plot_tdt_power_locus_heterogeneity.

Examples

plot_tdt_power(
  x_var = "heter_rate",
  x_values = c(0, 0.1, 0.2),
  scenario = "heterogeneity",
  input_mode = "model_based",
  N = 600,
  pd = 0.30,
  prev = 0.05,
  R1 = 1.5,
  R2 = 2.25,
  alpha = 0.05,
  delta_prime = 1
)

---

Plot TDT Power Sensitivity to Locus Heterogeneity

Description

Plot TDT power vs locus heterogeneity rate (1 - pi), holding misclassification fixed.

Usage

plot_tdt_power_locus_heterogeneity(
  pd,
  prev,
  R1,
  R2,
  alpha = 0.05,
  delta_prime = 1,
  N,
  heter_seq = seq(0, 0.5, by = 0.05),
  misclass_fixed = 0,
  title = "TDT power vs heterogeneity (1 - pi)"
)

Arguments

pd	Disease allele frequency.
prev	Disease prevalence.
R1	Genotype relative risk for heterozygotes.
R2	Genotype relative risk for risk homozygotes.
alpha	Significance level.
delta_prime	Linkage disequilibrium scaling parameter.
N	Number of affected trios.
heter_seq	Numeric vector. Sequence of heterogeneity rates.
misclass_fixed	Numeric. Misclassification rate held fixed (default 0). (Other params same meaning as in plot_tdt_power_phenotype_misclassification.)
title	Plot title.

Details

The x-axis is the heterogeneous trio fraction $1-\pi$; the homogeneous/linked fraction is $\pi$. The y-axis is heterogeneity-scenario power from tdt_power(). N, misclass_fixed, and all genetic-model parameters remain fixed while heter_seq is swept.

Value

A ggplot object, returned invisibly after it is printed.

See Also

tdt_power, plot_tdt_power_phenotype_misclassification, and plot_tdt_power.

Examples

# Power sensitivity to locus heterogeneity
plot_tdt_power_locus_heterogeneity(
  N    = 600,
  pd   = 0.30,
  prev = 0.05,
  R1   = 1.5,
  R2   = 2.25,
  heter_seq      = c(0, 0.1, 0.2),
  misclass_fixed = 0
)

---

Plot TDT Power Sensitivity to Phenotype Misclassification

Description

Plot TDT power vs phenotype misclassification rate (pi01), holding heterogeneity fixed.

Usage

plot_tdt_power_phenotype_misclassification(
  pd,
  prev,
  R1,
  R2,
  alpha = 0.05,
  delta_prime = 1,
  N,
  misclass_seq = seq(0, 0.15, by = 0.01),
  heter_fixed = 0,
  title = "TDT power vs misclassification (pi01)"
)

Arguments

pd	Numeric in (0,1). High-risk allele frequency at the marker.
prev	Numeric in (0,1). Disease prevalence (phi1).
R1, R2	Numeric. Genotype relative risks.
alpha	Numeric. Significance level (default 0.05).
delta_prime	Numeric. LD scale parameter (default 1).
N	Integer. Number of affected trios.
misclass_seq	Numeric vector. Sequence of misclassification rates.
heter_fixed	Numeric. Heterogeneity rate held fixed (default 0).
title	Character. Plot title.

Details

The x-axis is phenotype misclassification probability $\pi_{01}$ and the y-axis is the corresponding power from tdt_power(). N is a fixed number of affected trios; heter_fixed and all genetic-model parameters remain fixed while misclass_seq is swept.

Value

A ggplot object, returned invisibly after it is printed.

See Also

tdt_power, plot_tdt_power_locus_heterogeneity, and plot_tdt_power.

Examples

# Power sensitivity to phenotype misclassification
plot_tdt_power_phenotype_misclassification(
  N    = 600,
  pd   = 0.30,
  prev = 0.05,
  R1   = 1.5,
  R2   = 2.25,
  misclass_seq = c(0, 0.03, 0.06),
  heter_fixed  = 0
)

---

Plot a Generalized 3D TDT Sensitivity Surface

Description

Builds an interactive sensitivity surface for model-based TDT power or minimum sample size. Any two supported model parameters can be swept while the remaining parameters are held fixed. Every grid point is evaluated by the canonical tdt_power() or tdt_mssn() backend.

Usage

plot_tdt_surface3d(
  metric = c("power", "mssn"),
  scenario = c("misclassification", "heterogeneity", "no_error"),
  x = "pd",
  y = "misclass_rate",
  x_values = NULL,
  y_values = NULL,
  N = 600,
  target_power = 0.8,
  pd = 0.3,
  prev = 0.05,
  R1 = 1.5,
  R2 = 2.25,
  alpha = 0.05,
  delta_prime = 1,
  misclass_rate = 0.01,
  heter_rate = 0.1,
  ceiling_N = TRUE,
  title = NULL
)

Arguments

metric	Character. Surface height: "power" (default) or "mssn".
scenario	Character. One of "misclassification" (default), "heterogeneity", or "no_error".
x, y	Character scalars naming two distinct swept parameters. Supported axes are "pd", "prev", "R1", "R2", "alpha", "delta_prime", "misclass_rate", and "heter_rate".
x_values, y_values	Numeric grid values for x and y. Each must contain at least two distinct, finite values. If NULL, documented parameter-specific defaults are used; see Details.
N	Numeric scalar greater than zero. Number of affected trios, used when metric = "power".
target_power	Numeric scalar in ⁠(0, 1)⁠, used when metric = "mssn".
pd	Numeric in ⁠(0, 1)⁠. Fixed risk-allele frequency when pd is not an axis.
prev	Numeric in ⁠(0, 1)⁠. Fixed disease prevalence when prev is not an axis.
R1, R2	Positive numeric scalars. Fixed genotype relative risks when they are not axes.
alpha	Numeric in ⁠(0, 1)⁠. Fixed significance level when alpha is not an axis.
delta_prime	Numeric in ⁠[0, 1]⁠. Fixed positive linkage-disequilibrium scale when delta_prime is not an axis.
misclass_rate	Numeric in ⁠[0, 1)⁠. Fixed phenotype misclassification rate when it is not an axis.
heter_rate	Numeric in ⁠[0, 1)⁠. Fixed locus-heterogeneity rate when it is not an axis.
ceiling_N	Logical scalar. For MSSN surfaces, whether to plot the integer ceiling of the canonical sample-size result (default TRUE). The unrounded result remains available in the attached surface data.
title	Optional character scalar. If NULL, an informative title is generated from metric and scenario.

Details

The supported axes and their default grids are: pd = seq(0.10, 0.50, length.out = 20), prev = seq(0.01, 0.10, length.out = 20), R1 = seq(1.1, 2, length.out = 20), R2 = seq(1.2, 3, length.out = 20), alpha = seq(0.01, 0.10, length.out = 20), delta_prime = seq(0.25, 1, length.out = 20), misclass_rate = seq(0, 0.20, length.out = 20), and heter_rate = seq(0, 0.50, length.out = 20). The package's implemented LD convention is D = delta_prime * pd * (1 - pd), where delta_prime is the proportion of maximum positive disequilibrium: 0 represents linkage equilibrium and 1 represents maximum positive LD under the model assumptions. Negative LD would require a different, allele-frequency-dependent normalization and is not represented by this parameterization.

The surface is deliberately model-based. N and target_power define the design calculation and therefore remain fixed rather than becoming axes. The model-free inputs ET, ENT, and n_trios, as well as nonnumeric controls such as verbose, are outside this visualization interface. MSSN is measured in affected-child trios. heter_rate is the heterogeneous fraction, 1 - pi.

The canonical TDT backends report separate scenarios, not a combined-error scenario. Consequently, misclass_rate is an active axis only for scenario = "misclassification", and heter_rate is active only for scenario = "heterogeneity". An inactive modifier axis is rejected rather than silently producing a flat, misleading surface.

This function requires the optional plotly package. The plotting layer introduces no independent statistical approximation: it only constructs the grid, delegates calculations to tdt_power() or tdt_mssn(), extracts the selected scenario, and renders the result.

Value

An object inheriting from "plotly" and "htmlwidget". The Cartesian grid is attached as attr(x, "surface_data"), with dynamically named axis columns, metric_value (the plotted height), and raw_metric_value. The plotted z matrix is attached as attr(x, "surface_matrix"), and calculation settings as attr(x, "surface_spec").

See Also

tdt_power(), tdt_mssn(), plot_tdt_power(), plot_tdt_mssn()

Examples

if (requireNamespace("plotly", quietly = TRUE)) {
  power_surface <- plot_tdt_surface3d(
    metric = "power", scenario = "misclassification",
    x = "pd", y = "misclass_rate",
    x_values = c(0.2, 0.3, 0.4),
    y_values = c(0, 0.03, 0.06),
    N = 600
  )

  mssn_surface <- plot_tdt_surface3d(
    metric = "mssn", scenario = "heterogeneity",
    x = "prev", y = "heter_rate",
    x_values = c(0.02, 0.05, 0.08),
    y_values = c(0, 0.1, 0.2),
    target_power = 0.8
  )
}

---