Skip to contents

Plot an observed marginal response with a fitted GAMLSS density overlay

Source: R/common_functions.R
plot_margin_fit.Rd

plot_margin_fit() replaces the common exploratory use of gamlss::histDist() with a ggplot-based helper that also understands final gamlss.longitudinal fits. With raw data it fits the supplied family as an intercept-only marginal model. With a fitted longitudinal model it overlays the average row-specific fitted marginal density.

Usage

plot_margin_fit(
  x = NULL,
  margin_dist = NULL,
  data = NULL,
  fit = NULL,
  response_var = "response",
  bins = 30,
  grid_n = 200,
  response_scale = c("response", "log"),
  time_intercepts = FALSE,
  by_time = FALSE,
  time_var = "time",
  fit_control = gamlss::gamlss.control(n.cyc = 50),
  plot = TRUE,
  ...
)

Arguments

x

Numeric response vector, data frame, or fitted gamlss.longitudinal object.

margin_dist

A gamlss.dist family object, family name, or margin_selection result. Required for raw data unless fit is supplied.

data

Optional data frame containing the response.

fit

Optional fitted gamlss.longitudinal object. When supplied, the fitted marginal density is overlaid using the model distribution and row-specific fitted parameters.

response_var

Response column name when x or data is a data frame.

bins

Number of histogram bins.

grid_n

Number of grid points used for the fitted density.

response_scale

Plot the density on the original response scale or, for positive responses, on the log-response scale.

time_intercepts

Logical; for raw data, fit time-specific intercepts for each marginal distribution parameter before drawing the overlay.

by_time

Logical; facet the plot by time. For fitted longitudinal models, fitted densities are averaged within each time point.

time_var

Time column name used when time_intercepts = TRUE or by_time = TRUE for raw data.

fit_control

Control object passed to the internal gamlss() overlay fit for raw-data plots. Defaults to gamlss::gamlss.control(n.cyc = 50).

plot

Logical; if TRUE, print the plot.

...

Additional arguments reserved for future methods.

Value

Invisibly returns a list containing the plot, observed data, and fitted density grid.