Package 'p3d'

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

d	Numeric vector of effect sizes (Cohen's d).
n	Single sample size. Must be >= 2.
alpha	Significance level. Default: 0.05.

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

d	Numeric vector of effect sizes (Cohen's d). Typical range: -2 to 2.
n	Numeric vector of sample sizes. Must be >= 2. Typical range: 5 to 200.
alpha	Significance level for the critical effect size. Default: 0.05.

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

surface	A list returned by p_surface.
theta, phi	Viewing angles in degrees. See persp for details. Defaults: theta = 30, phi = 20.
col	Color palette for the surface. Either a single color or a vector of colors matching the number of $d \times n$ grid cells.
shade	Logical; if TRUE (default), the surface is shaded using persp's shading.
alpha	Significance level. A horizontal plane at $p = \alpha$ is overlaid on the surface. Default: 0.05.

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

surface	A list returned by p_surface.
engine	Character; either "rgl" (default) or "plotly". Determines the rendering backend.
alpha	Significance level. A horizontal plane at $p = \alpha$ is overlaid on the surface. Default: 0.05.
col	Color palette for the surface. If NULL (default), a built-in palette is used.
show_boundary	Logical; if TRUE (default), the intersection curve between the surface and the $\alpha$-plane is drawn.

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")
}

---