Skip to contents

Plot empirical pseudo-observation pairs with a fitted copula overlay

Source: R/common_functions.R
plot_copula_fit.Rd

plot_copula_fit() and plot_copula_overlay() standardise the copula-screen visual check used in examples and vignettes. They accept raw pseudo-observations plus a select_copula() result, or a final gamlss.longitudinal fit whose row-specific fitted copula density is averaged over paired observations.

Usage

plot_copula_fit(
  data = NULL,
  copula_dist = NULL,
  fit = NULL,
  object = NULL,
  u1 = NULL,
  u2 = NULL,
  u = NULL,
  u_var = NULL,
  response_var = NULL,
  margin_dist = NULL,
  subject_var = "subject",
  time_var = "time",
  lags = 1,
  by_time = FALSE,
  transform = c("normal", "uniform"),
  grid_n = 80,
  bins = 28,
  contour_bins = 8,
  max_pairs_overlay = 300,
  plot = TRUE,
  ...
)

plot_copula_overlay(
  data = NULL,
  copula_dist = NULL,
  fit = NULL,
  object = NULL,
  u1 = NULL,
  u2 = NULL,
  u = NULL,
  u_var = NULL,
  response_var = NULL,
  margin_dist = NULL,
  subject_var = "subject",
  time_var = "time",
  lags = 1,
  by_time = FALSE,
  transform = c("normal", "uniform"),
  grid_n = 80,
  bins = 28,
  contour_bins = 8,
  max_pairs_overlay = 300,
  plot = TRUE,
  ...
)

Arguments

data

Optional long-format data frame. If a fitted gamlss.longitudinal object is supplied here, it is treated as fit.

copula_dist

A copula_selection result, one-row selection data frame, family code(s), or "best"/"auto" to screen all supported families. Character values are fitted to the supplied pseudo-observation pairs before the overlay is drawn. Required unless fit is supplied.

fit

Optional fitted gamlss.longitudinal object.

object

Optional alias for fit.

u1, u2

Optional direct paired pseudo-observations.

u

Optional row-aligned pseudo-observation vector for data.

u_var

Optional pseudo-observation column name in data.

response_var

Optional response column name used to create temporary pseudo-observations when u, u_var, and u1/u2 are absent.

margin_dist

Optional margin family used when creating temporary pseudo-observations from response_var.

subject_var, time_var

Subject and time column names.

lags

Positive integer lag(s) used when forming pairs.

by_time

Logical; if TRUE, facet the copula overlay by adjacent time pair.

transform

Character; either "normal" or "uniform".

grid_n

Grid size for fitted density contours.

bins

Number of empirical two-dimensional bins.

contour_bins

Number of fitted contour levels.

max_pairs_overlay

Maximum paired observations used when averaging fitted copula densities.

plot

Logical; if TRUE, print the plot.

...

Additional arguments reserved for future methods.

Value

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