fit_longitudinal_surrogate_model: Longitudinal observed-data model fitting

In Surrogate: Evaluation of Surrogate Endpoints in Clinical Trials

Longitudinal observed-data model fitting

Description

This function fits a bivariate longitudinal surrogate/true-endpoint model. General-purpose functions for two continuous longitudinal endpoints measured in two treatment arms. Residual covariance is separable at the observed-data level, with treatment-specific 2 x 2 endpoint covariance matrices and a common temporal correlation matrix. Random effects may be endpoint-specific or shared within treatment arm.

Usage

fit_longitudinal_surrogate_model(
  data,
  formula,
  model_spec,
  residual_type = c("exponential", "independence", "cs"),
  start_fit = NULL,
  control = list(rel.tol = 1e-10, x.tol = 1e-10, eval.max = 5000, iter.max = 3000)
)

Arguments

data	Standardized data returned by prepare_longitudinal_surrogate_data().
formula	Fixed-effects formula using the standardized response Y.
model_spec	Random-effects specification. make_longitudinal_re_none, make_longitudinal_re_endpoint_specific, make_longitudinal_re_shared_by_arm.
residual_type	One of "exponential", "independence", or "cs".
start_fit	Optional previously fitted surrogate_longitudinal_fit used to initialize common parameters.
control	Control list passed to nlminb().

Details

The data should first be standardized using prepare_longitudinal_surrogate_data. The mean structure is specified through mean_formula, while the random-effects structure is specified through model_spec.

The argument model_spec can be created using one of the helper functions:

• make_longitudinal_re_none for Galecki's marginal model, without subject-specific random effects;

• make_longitudinal_re_endpoint_specific for endpoint-specific random-effects models;

• make_longitudinal_re_shared_by_arm for shared random-effects models by treatment arm.

The residual temporal correlation structure is selected using residual_type. The currently supported options are "exponential", "cs" denotes compound symmetry, and "independence". The exponential structure uses the actual temporal distances between measurements; for equally spaced visits, it reduces to the usual AR(1) structure.

Value

An object of class surrogate_longitudinal_fit.

References

Deliorman, G., Pardo, M. C., Van der Elst W., Molenberghs G., & Alonso, A. (submitted in 2026). Assessing Surrogate Endpoints in Longitudinal Studies: An Information-Theoretic Causal Inference Approach.

Examples

## Not run: 
data(Schizo_PANSS_BPRS)

dat <- prepare_longitudinal_surrogate_data(
       data = Schizo_PANSS_BPRS,
       id = "Id",
       treatment = "Treat",
       time = "Time_cont",
       endpoint = "Endpoint",
       outcome = "Response_log",
       baseline = "Baseline_log",
       surrogate_label = "BPRS",
       true_label = "PANSS",
       treatment_levels = c(0, 1))

# endpoint- and treatment-specific baseline adjustment.

mean_formula <- Y ~ 0 + endpoint:visitF:treatF + endpoint:treatF:Ybase

spec_galecki <- make_longitudinal_re_none(name = "Galecki's marginal model")

#do not run
fit_galecki <- fit_longitudinal_surrogate_model(dat,
                                                mean_formula,
                                                model_spec = spec_galecki,
                                                residual_type = "exponential")

longitudinal_fit_stats(fit_galecki)
extract_longitudinal_parameters(fit_galecki)
longitudinal_matrix_diagnostics(fit_galecki)
## End(Not run)

Surrogate documentation built on Oct. 16, 2026, 9:07 a.m.