Check if a dlm block has the treatment as covariate

Description

Check if a dlm block has the treatment as covariate

Usage

check_has_G(formula, name.G, inside_dlm = FALSE)

Arguments

Check if a formula term is a dlm block

Description

Check if a formula term is a dlm block

Usage

check_is_dlm_block(term)

Arguments

Fit marginal and conditional state-space models for longitudinal surrogate evaluation

Description

Fits two Gaussian state-space models (Dynamic Linear Models) to jointly longitudinal outcome data: (i) a marginal model for the outcome trajectory given treatment and time, and (ii) a conditional model that additionally adjusts for a user-specified surrogate structure. The function returns per-time treatment-effect estimates from both models and subject-level bootstrap draws obtained via subject-level resampling.

Usage

fit.surr(
  formula,
  id,
  surrogate,
  treat,
  data = NULL,
  time = NULL,
  N.boots = 2000,
  verbose = 1,
  D.local = 0.8
)

Arguments

Details

The implementation follows a two-model decomposition used for estimating longitudinal treatment effects and surrogate-adjusted (residual) treatment effects in a state-space framework.

See dos Santos Jr. and Parast (2026) for details on the methodology.

See West and Harrison (1997) for best practices on model specification in the state-space model setting.

Data requirements. The data must have at most one row per subject-time pair; time must be numeric and equally spaced (or omitted, in which case an index is created). Treatment and subject identifiers are coerced to factors with sorted levels.

Model structure. The marginal model includes treatment-by-time fixed effects and a subject-specific random-walk component to capture within-subject correlation. The conditional model adds the user-specified surrogate structure to the design, and checks that treatment is not a linear combination of the surrogate design (rank check).

Bootstrap. Subjects are resampled with replacement. Subject-specific filtered quantities are computed once and recombined in each bootstrap iteration to reduce computational cost, consistent with a subject-level nonparametric bootstrap strategy for replicated time series.

Value

An object of class "fitted_onlinesurr": a named list with elements $Marginal and $Conditional. Each of these contains:

• point: the point estimate vector of the treatment effect at each time point.

• smp: a matrix of bootstrap draws for the treatment effect at each time point, with one column per bootstrap replicate. The draws are generated from the joint distribution of the full vector, thereby accounting for the dependence among different time points. The samples from the marginal (total effect) and conditional (residual effect) models are paired, so that the i-th samples from both models are drawn jointly from the distribution of the estimators.

The object also includes:

• T: number of unique time points.

• N: number of subjects.

• n.fixed: number of fixed-effect coefficients implied by formula for a single subject prior to stacking across subjects.

References

Mike West, Jeff Harrison (1997). Bayesian Forecasting and Dynamic Models (Springer Series in Statistics). Springer-Verlag. ISBN 0387947256.

Silvaneo V. dos Santos Jr., Layla Parast (2026). “A Causal Framework for Evaluating Jointly Longitudinal Outcomes and Surrogate Markers: A State-Space Approach.” 2604.12882, https://arxiv.org/abs/2604.12882.

Examples

fit <- fit.surr(y ~ 1,
  id = id,
  surrogate = ~s,
  treat = trt,
  data = sim_onlinesurr, # This dataset is included in the OnlineSurr package
  time = time,
  verbose = 0,
  N.boots = 500 # Generally, this value would be too small.
  # Remember to increase it for your dataset.
)
summary(fit)

formula.to.structure

Description

formula.to.structure

Usage

## S3 method for class 'to.structure'
formula(formula, data, label = "mu")

Arguments

Compute a spline configuration

Description

Derive the configuration needed to evaluate s() for a given input vector. This helper resolves boundary limits, chooses or validates knot locations, augments the knot vector with repeated boundary knots, and returns the arguments in a form that can be used to rebuild or update spline calls.

Usage

get.config.s(
  x,
  P = 3,
  K = min(7, max(3, floor(log2(length(unique(x)))))),
  limits = c(NA, NA),
  knots = "eq"
)

Arguments

Details

This function is intended for programmatic use, for example when rewriting model formulas that contain calls to s(...).

Value

A named list containing:

x

The unevaluated expression supplied as x, returned via substitute(x).

knots

The full augmented knot vector, including repeated boundary knots.

limits

The resolved lower and upper boundary limits.

P

The spline degree.

K

The number of basis functions.

ginv

Description

This function receives a covariance matrix S and calculates the generalized inverse of S.

Usage

ginv(S)

Arguments

Test whether an expression contains a function call

Description

Recursively checks whether expr contains a call to fun.

Usage

has_call(expr, fun = "s")

Arguments

Value

TRUE if expr contains a call to fun, otherwise FALSE.

Compute lagged values of a vector

Description

Returns a lagged version of x by shifting its values forward by k positions and padding the first k entries with zeros.

Usage

lagged(x, k = 1)

Arguments

Details

This function is intended for use in model formulas when delayed effects of a predictor should be included explicitly.

Value

A vector of the same length as x, with the first k values set to 0 and the remaining values taken from x shifted by k positions.

Examples

x <- 1:5

lagged(x)
lagged(x, k = 2)

Plot time-varying PTE measures and treatment effects from a "fitted_onlinesurr" object

Description

Produces a ggplot2 figure showing, over time, either the Local PTE (LPTE), the Cumulative PTE (CPTE), or the marginal and residual treatment effects \Delta(t) and \Delta_R(t) (labeled \Delta and \Delta_R in the plot). Point estimates are taken from object$Marginal$point and object$Conditional$point, with uncertainty bands computed from the stored bootstrap draws.

Usage

## S3 method for class 'fitted_onlinesurr'
plot(x, type = "LPTE", conf.level = 0.95, one.sided = TRUE, ...)

Arguments

Details

The function extracts time-indexed treatment-effect estimates \Delta(t) (marginal) and \Delta_R(t) (residual/conditional) from the fitted object, along with bootstrap draws for each. It then constructs:

• LPTE: \mathrm{LPTE}(t) = 1 - \Delta_R(t)/\Delta(t).

• CPTE: \mathrm{CPTE}(t) = 1 - \sum_{u\le t}\Delta_R(u)/\sum_{u\le t}\Delta(u).

• Delta: plots \Delta(t) and \Delta_R(t) directly.

Point estimates are plotted as points; intervals are empirical quantile intervals computed from the bootstrap sample matrices stored in object.

Value

A ggplot object.

Examples

fit <- fit.surr(y ~ 1,
  id = id,
  surrogate = ~s,
  treat = trt,
  data = sim_onlinesurr, # This dataset is included in the OnlineSurr package
  time = time,
  verbose = 0,
  N.boots = 500 # Generally, this value would be too small.
  # Remember to increase it for your dataset.
)

plot(fit, type = "LPTE")
plot(fit, type = "CPTE", conf.level = 0.90, one.sided = FALSE)
plot(fit, type = "Delta")

print.fitted_onlinesurr

Description

This method is wrapper for the summary.fitted_onlinesurr method.

Usage

## S3 method for class 'fitted_onlinesurr'
print(x, ...)

Arguments

Value

No return value, called to print a summary of the fitted kDGLM model.

Rewrite function calls in an expression

Description

Recursively traverses expr and replaces calls to fun using the configuration returned by config_fun.

Usage

rewrite_calls(
  expr,
  fun = "s",
  config_fun = get.config.s,
  eval_env = parent.frame()
)

Arguments

Value

A modified language object with matching calls rewritten.

rmvnorm

Description

Obtains a sample from a multivariate normal distribution.

Usage

rmvnorm(n, mu, Sigma, norm.x = matrnorm(k, n, seed = round(runif(1) * 1e+15)))

Arguments

Construct a B-spline basis matrix

Description

Build a B-spline basis for a numeric vector using a Cox-de Boor style recursion. By default, the function constructs a cubic spline basis (P = 3) and chooses the number of basis functions from the number of unique values in x.

Usage

s(
  x,
  P = 3,
  K = min(7, max(3, floor(log2(length(unique(x)))))),
  limits = c(NA, NA),
  knots = "eq"
)

Arguments

Details

Boundary limits are taken from x unless supplied explicitly. Knot locations may be given directly as a numeric vector, or generated either at equally spaced locations ("eq") or at empirical quantiles ("quantile").

The returned basis has length(x) rows and k columns.

When knots is generated internally, the function first creates K - P + 1 knot locations and then augments them with repeated boundary knots so the recursion can be evaluated.

Value

A numeric matrix with one row per element of x and one column per spline basis function.

Examples

x <- seq(0, 1, length.out = 10)

# Default cubic basis
B <- s(x)
dim(B)

# Equally spaced knots with custom basis size
B2 <- s(x, K = 5, knots = "eq")

# Quantile-based knots
B3 <- s(x, knots = "quantile")

Simulated longitudinal surrogate dataset for 'OnlineSurr'

Description

A simulated long-format dataset illustrating the input structure expected by [fit.surr()] for surrogate evaluation with jointly longitudinal outcomes and surrogate markers.

Usage

sim_onlinesurr

Format

A data frame with 600 rows and 5 variables:

id

Integer subject identifier.

trt

Binary treatment indicator: '0' for control and '1' for treated.

time

Numeric measurement time index taking values '1' through '6'.

s

Continuous longitudinal surrogate marker.

y

Continuous longitudinal primary outcome.

Details

The dataset contains 100 subjects observed at 6 equally spaced time points. Treatment assignment is binary and constant within subject. The surrogate marker 's' varies over time and is affected by treatment. The primary outcome 'y' depends on treatment, time, and the surrogate marker.

Rows are ordered by subject identifier and time.

This dataset was generated for package examples and testing. It represents a balanced longitudinal design with one observation per subject-time pair. Measurement times are equally spaced, which is a requirement for use with [fit.surr()].

In the data-generating mechanism, the surrogate marker is affected by time and treatment, and the outcome depends on time, treatment, and the surrogate.

Source

Simulated data generated within the package; not based on an external study.

Summarize a "fitted_onlinesurr" object

Description

Prints a human-readable report for an object of class "fitted_onlinesurr" returned by fit.surr. The report includes marginal and conditional treatment-effect estimates at a selected time point (or cumulatively up to that time), an estimate of the LPTE/CPTE, and a time-homogeneity test of the LPTE.

Usage

## S3 method for class 'fitted_onlinesurr'
summary(object, t = object$T, cumulative = TRUE, signif.level = 0.05, ...)

Arguments

Details

The "fitted_onlinesurr" object stores point estimates and bootstrap samples for marginal and surrogate-adjusted (conditional) models in object$Marginal and object$Conditional.

Value

No return value. Called for its side effect of printing a summary report.

Examples

fit <- fit.surr(y ~ 1,
  id = id,
  surrogate = ~s,
  treat = trt,
  data = sim_onlinesurr, # This dataset is included in the OnlineSurr package
  time = time,
  verbose = 0,
  N.boots = 500 # Generally, this value would be too small.
  # Remember to increase it for your dataset.
)

# Cumulative up to time 5
summary(fit, t = 5, cumulative = TRUE, signif.level = 0.05)

# Time-specific at time 5
summary(fit, t = 5, cumulative = FALSE)

Extract formula terms containing a function call

Description

Returns the term labels from a formula whose parsed expressions contain a call to fun.

Usage

terms_with_call(formula, fun = "s")

Arguments

Value

A character vector of term labels containing a call to fun.

Test time-homogeneity of the PTE

Description

Tests the null hypothesis that the LPTE is constant over time. The test is based on the difference between the conditional and marginal treatment-effect trajectories implied by a fitted "fitted_onlinesurr" object, standardized by an estimated covariance, and uses a max-type statistic to control the family wise error across time points.

Usage

time_homo_test(model, signif.level = 0.05, N.boots = 50000)

Arguments

Details

See dos Santos Jr. and Parast (2026) for the theoretical details about this test.

Notes:

• The function assumes the first T time-specific treatment-effect parameters are stored contiguously at the beginning of model$Marginal$point and model$Conditional$point (and similarly for smp). It uses the index 1:(n.fixed) as implemented in the code: 1:(T + n.fixed - T).

• N.boots here is a Monte Carlo size for the null simulation (distinct from the bootstrap size used when fitting model).

Value

A named list with:

• T: the observed test statistic (maximum absolute standardized deviation).

• T.crit: the 1-signif.level critical value.

• p.value: the Monte Carlo p-value mean(T_null > T_obs).

References

Silvaneo V. dos Santos Jr., Layla Parast (2026). “A Causal Framework for Evaluating Jointly Longitudinal Outcomes and Surrogate Markers: A State-Space Approach.” 2604.12882, https://arxiv.org/abs/2604.12882.

Examples

fit <- fit.surr(y ~ 1,
  id = id,
  surrogate = ~s,
  treat = trt,
  data = sim_onlinesurr, # This dataset is included in the OnlineSurr package
  time = time,
  verbose = 0,
  N.boots = 500 # Generally, this value would be too small.
  # Remember to increase it for your dataset.
)

time_homo_test(fit, signif.level = 0.05, N.boots = 500)

Update spline calls in a formula

Description

Rewrites calls to fun in a formula using config_fun, evaluating arguments in an environment built from data.

Usage

update_s_in_formula(formula, data, config_fun = get.config.s, fun = "s")

Arguments

Value

A formula with updated calls to fun.

var_decomp

Description

This function receives a covariance matrix S and creates a matrix Q, so that t(Q) %*% Q = S.

Usage

var_decomp(S)

Arguments