statuser (version 0.1.9)

scatter.gam: 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,
  ...
)

Value

Invisibly returns the fitted GAM model object.

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.

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)