Package {p3d}

p3d: Interactive 3D Visualization of p-Value Surfaces

Description

Provides interactive three-dimensional visualization of p-value surfaces for single-sample t-tests. Enables simultaneous exploration of effect size, sample size, and significance level, making the continuous nature of p-values and the moderating effect of sample size visually apparent. Includes both interactive ('rgl', 'plotly') and static (persp()) rendering options. The p-value surface is based on the approach of Infanger and Schmidt-Trucksäss (2019) doi:10.1002/sim.8293.

Author(s)

Maintainer: Ahmet Kutuk ahmetkutuk@gmail.com

Authors:

• Ahmet Kutuk ahmetkutuk@gmail.com

See Also

Useful links:

• https://github.com/ahmetkutuk1/p3d

• https://ahmetkutuk1.github.io/p3d/

• Report bugs at https://github.com/ahmetkutuk1/p3d/issues

Compute 2D p-value curve for a fixed sample size

Description

Computes the p-value as a function of effect size (Cohen's d) for a single, fixed sample size. This is the 2D analogue of p_surface and is provided for comparison with existing 2D visualization packages such as pvaluefunctions.

Usage

p_curve_2d(d, n, alpha = 0.05)

Arguments

Details

The p-value is computed as:

p(d) = 2 \left[ 1 - F_{t(n-1)}(d \sqrt{n}) \right]

Value

A data frame with columns:

d

Effect sizes.

p

Two-sided p-values.

significant

Logical; whether p < alpha.

Examples

# 2D curve for n = 30
curve_30 <- p_curve_2d(d = seq(-2, 2, 0.1), n = 30)
head(curve_30)

# Compare with 3D surface
surface <- p_surface(d = seq(-2, 2, 0.1), n = c(10, 30, 100))

Compute p-value surface for single-sample t-test

Description

Computes the p-value of a single-sample t-test as a function of effect size (Cohen's d) and sample size (n). Returns a grid of p-values suitable for 3D visualization.

Usage

p_surface(d, n, alpha = 0.05)

Arguments

Details

The p-value is computed using the formula:

p(d, n) = 2 \left[ 1 - F_{t(n-1)}(d \sqrt{n}) \right]

where F_{t(n-1)} is the cumulative distribution function of the t-distribution with n-1 degrees of freedom.

The critical effect size at level \alpha is:

d_{crit}(n) = \frac{F^{-1}_{t(n-1)}(1 - \alpha/2)}{\sqrt{n}}

Value

A list with the following elements:

d

The input vector of effect sizes.

n

The input vector of sample sizes.

p

A matrix of p-values with dimensions length(d) x length(n).

d_crit

A numeric vector of critical effect sizes for each sample size at level alpha.

alpha

The significance level used.

grid

A data frame with the full grid of (d, n, p) combinations.

Examples

# Small example
result <- p_surface(d = seq(-1, 1, 0.1), n = c(10, 30, 100))
str(result)

# Typical use
result <- p_surface(d = seq(-2, 2, 0.05), n = seq(5, 200, 5))
image(result$d, result$n, result$p)

Static 2D perspective plot of p-value surface

Description

Plots the output of p_surface using base R's persp function. This produces a static 3D perspective plot with no external dependencies, making it suitable for PDF output, journal figures, and CRAN checks.

Usage

plot_p_static(
  surface,
  theta = 30,
  phi = 20,
  col = "steelblue",
  shade = TRUE,
  alpha = 0.05
)

Arguments

Details

Unlike plot_p_surface, which requires rgl or plotly, this function uses only base R graphics. It is ideal for inclusion in static documents such as PDF articles and printed reports.

Value

Invisibly returns the input surface object. Called for its side effect (a plot).

Examples

# Compute surface
surface <- p_surface(d = seq(-2, 2, 0.1), n = seq(5, 200, 5))

# Static perspective plot
plot_p_static(surface)

# Different viewing angle
plot_p_static(surface, theta = 45, phi = 30)

Interactive 3D visualization of p-value surface

Description

Plots the output of p_surface as an interactive three-dimensional surface. Two rendering engines are supported: "rgl" (default, interactive window) and "plotly" (HTML widget, ideal for R Markdown / Quarto documents).

Usage

plot_p_surface(
  surface,
  engine = c("rgl", "plotly"),
  alpha = 0.05,
  col = NULL,
  show_boundary = TRUE
)

Arguments

Details

The 3D surface shows the p-value as a function of both effect size (d) and sample size (n). The \alpha-plane visualizes the conventional significance threshold. The intersection curve marks the boundary between "significant" and "non-significant" regions.

For engine = "rgl", the rgl package must be installed. For engine = "plotly", the plotly package must be installed. Both are listed in Suggests.

Value

Invisibly returns the input surface object. Called for its side effect (a plot).

Examples

# Compute surface (non-interactive part)
surface <- p_surface(d = seq(-2, 2, 0.1), n = seq(5, 200, 5))
str(surface, max.level = 1)

# Interactive visualization (only in interactive sessions)
if (interactive()) {
  # rgl engine (interactive window)
  plot_p_surface(surface)

  # plotly engine (HTML widget)
  plot_p_surface(surface, engine = "plotly")
}