Internal function for the Clustered Grouped Calibration Curve (CGC)

Estimates the calibration curves using the CGC approach. The function supports two grouping methods: equal-sized groups ("grouped") or interval-based groups ("interval"). Optionally, a calibration plot can be produced with cluster-specific curves.

Usage

CGC(
  data = NULL,
  p,
  y,
  cluster,
  cl.level = 0.95,
  ntiles = 10,
  cluster_curves = FALSE,
  plot = TRUE,
  size = 1,
  linewidth = 0.4,
  univariate = FALSE,
  method = c("grouped", "interval")
)

Arguments

data: optional data frame containing the variables p, y, and cluster. If supplied, variable names should be given without quotation marks.
p: predicted probabilities (numeric vector) or name of the column in data.
y: binary outcome variable or the name of the column in data.
cluster: cluster identifier (factor, character, or integer) or name of the column in data.
cl.level: the confidence level for the calculation of the confidence interval. Default is 0.95.
ntiles: integer, number of groups (tiles) for calibration. Default is 10.
cluster_curves: logical, whether to include cluster-specific calibration curves in the plot. Default is FALSE.
plot: logical, whether to return a calibration plot. Default is TRUE.
size: numeric, point size for plotted curves. Default is 1.
linewidth: numeric, line width for plotted curves. Default is 0.4.
univariate: logical, whether to use univariate meta-analysis. Default is FALSE.
method: character, grouping method: "grouped" (equal-sized groups) or "interval" (interval-based). Default is "grouped".

Value

A list containing:

plot_data: Data frame of meta-analysis calibration estimates.
trad_grouped: Data frame with traditional grouped calibration results.
observed_data: Data frame with per-observation calibration data.
cluster_data: Data frame with cluster-specific calibration summaries.
plot: A ggplot2 object if plot = TRUE, otherwise NULL.

Details

When method = "grouped", the predictions are divided into equal-sized bins using quantiles. Conversely, if method ="interval", the predictions are divided into fixed-width bins across [0, 1].

The function performs a meta-analysis within each group. This can be either a univariate or bivariate analysis, which is specified in the univariate argument. The univariate analysis is performed using the metaprop function and the bivariate analysis employs the rma.mv function. Hereafter, the results are aggregated and plotted as calibration curves.