Select a bivariate copula family from pseudo-observation pairs — select

Screens supported copula families by maximising their native copula log-likelihood on adjacent-time pseudo-observation pairs. Pseudo-observations can be supplied directly as u1/u2, supplied as a row-aligned uniform vector or column in data, or computed from a fitted gamlss.longitudinal object.

Usage

select_copula(
  data = NULL,
  object = NULL,
  u1 = NULL,
  u2 = NULL,
  u = NULL,
  u_var = NULL,
  response_var = NULL,
  margin_dist = NULL,
  mu.formula = NULL,
  sigma.formula = NULL,
  nu.formula = NULL,
  tau.formula = NULL,
  subject_var = "subject",
  time_var = "time",
  families = c("N", "C", "F", "G", "J", "t"),
  lags = 1,
  criterion = c("AIC", "BIC", "logLik"),
  t_df_grid = c(3, 4, 6, 8, 12, 20, 30),
  min_pairs = 10,
  time_intercepts = FALSE,
  copula_time_intercepts = FALSE
)

Arguments

data: Optional long-format data frame.
object: Optional fitted gamlss.longitudinal object.
u1, u2: Optional vectors of paired pseudo-observations.
u: Optional row-aligned vector of pseudo-observations for data.
u_var: Optional name of a pseudo-observation column in data.
response_var: Optional response column name in data. Used to create pseudo-observations automatically when u1/u2, u, u_var, and object are not supplied.
margin_dist: Optional gamlss.dist family object, or a select_margin() result, used to fit the temporary marginal model for automatic pseudo-observations. If omitted, select_margin() is called and a warning is issued.
mu.formula, sigma.formula, nu.formula, tau.formula: Optional temporary marginal model formulas used when select_copula() creates pseudo-observations from response_var. If omitted, intercept-only formulas are used unless time_intercepts = TRUE or margin_dist is a time-intercept select_margin() result.
subject_var, time_var: Subject and time column names used when building adjacent-time pairs from data.
families: Candidate copula family codes. Supported values are "N", "C", "F", "G", "J", and "t".
lags: Positive integer lag(s) used when forming adjacent pairs.
criterion: Ranking criterion, one of "AIC", "BIC", or "logLik".
t_df_grid: Degrees-of-freedom grid used for the t-copula screen.
min_pairs: Minimum number of complete pairs required.
time_intercepts: Logical; when select_copula() creates pseudo-observations from response_var, use time-specific intercepts in the temporary marginal model and pass this setting through to select_margin() if the marginal family is auto-selected.
copula_time_intercepts: Logical; if TRUE, screen each copula family with separate dependence parameters for each adjacent time-pair factor level. This does not impose a linear time trend.

Value

A data frame with one row per family and class copula_selection. The selected family is stored in the selected attribute.

Details

This helper is intended as a lightweight family-screening step. By default it estimates a constant dependence parameter for each candidate family. With copula_time_intercepts = TRUE, it estimates separate dependence parameters for each observed adjacent time pair, treating time as a factor rather than a linear trend. Richer covariate or smooth dependence structures should be fitted afterwards with gamlss_longitudinal().