scatter.gam: Scatter Plot with GAM Smooth Line

In statuser: Statistical Tools Designed for End Users

Scatter Plot with GAM Smooth Line

Description

Creates a scatter plot with a GAM (Generalized Additive Model) smooth line. Supports both scatter.gam(x, y) and scatter.gam(y ~ x).

Usage

scatter.gam(
  x,
  y,
  data.dots = TRUE,
  three.dots = FALSE,
  data = NULL,
  k = NULL,
  plot.dist = NULL,
  dot.pch = 16,
  dot.col = adjustcolor("gray", 0.7),
  jitter = FALSE,
  ...
)

Arguments

x	A numeric vector of x values, or a formula of the form y ~ x.
y	A numeric vector of y values. Not used if x is a formula.
data.dots	Logical. If TRUE, displays data on scatterplot
three.dots	Logical. If TRUE, divides x into tertiles and puts markers on the average x & y for each
data	An optional data frame containing the variables x and y.
k	Optional integer specifying the basis dimension for the smooth term in the GAM model (passed to s(x, k=k)). If NULL (default), uses the default basis dimension.
plot.dist	Character string specifying how to plot the distribution of x underneath the scatter plot. Options: NULL (default, auto-select based on number of unique values), "none" (no distribution plot), "plot_freq" (always use plot_freq()), or "hist" (always use hist()). When NULL, uses plot_freq() if there are 25 or fewer unique values, otherwise uses hist().
dot.pch	Plotting character for data points when data.dots = TRUE. Default is 16 (filled circle).
dot.col	Color for data points when data.dots = TRUE. Default is adjustcolor('gray', 0.7) (semi-transparent gray).
jitter	Logical. If TRUE, applies a small amount of jitter to data points to reduce overplotting. Default is FALSE.
...	Additional arguments passed to plot() and gam(). Common plot arguments include: main: Custom title for the plot (e.g., main = "My Title") col: Color of the GAM smooth line (e.g., col = "red") lwd: Line width of the GAM smooth line (e.g., lwd = 2) xlim, ylim: Axis limits (e.g., xlim = c(0, 10)) xlab, ylab: Axis labels (e.g., xlab = "Age")

Details

This function fits a GAM model with a smooth term for x and plots the fitted smooth line. The function uses the mgcv package's gam() function.

When three.dots = TRUE, the x variable is divided into three equal-sized groups (tertiles), and the mean x and y values for each group are plotted as points. This provides a simple summary of the relationship across the range of x.

Value

Invisibly returns the fitted GAM model object.

See Also

scatter.smooth for a simpler loess-based scatter plot smoother.

Examples

# Generate sample data for examples
x <- rnorm(100)
y <- 2*x + rnorm(100)

# Plot GAM smooth line only
scatter.gam(x, y)

# Equivalent call using formula syntax (y ~ x)
scatter.gam(y ~ x)

# Include scatter plot with underlying data points behind the GAM line
scatter.gam(x, y, data.dots = TRUE)

# Include summary points showing mean x and y for each tertile bin
scatter.gam(x, y, three.dots = TRUE)

# Customize the plot with a custom title, line color, and line width
scatter.gam(x, y, data.dots = TRUE, col = "red", lwd = 2, main = "GAM Fit")

# Control smoothness of the GAM line by specifying the basis dimension
scatter.gam(x, y, k = 10)

statuser documentation built on April 25, 2026, 5:06 p.m.