Package {dsFedAteClient}

Estimate ATE from multiple RCTs

Description

Client-side function that orchestrates the federated estimation of an average treatment effect (ATE) – and, optionally, its variance and confidence interval – from multiple independent RCTs, each held on a separate data server. Randomisation holds within each study; the combined dataset is not necessarily itself a single RCT.

Usage

ds.EstimateAte(
  datasources = NULL,
  base_name,
  outcome_name,
  treatment_name,
  covariate_names,
  compute_variance = TRUE,
  study_effects = FALSE,
  heterogeneous = TRUE,
  heteroscedastic_arms = FALSE,
  quiet = FALSE
)

Arguments

Details

The function fits separate arm-specific linear models via ds.glm, broadcasts the pooled coefficients back to the servers, and collects local statistics via a single aggregate call to localAteDS. When compute_variance = FALSE, three scalars are returned per server (n_k, n_k^{(1)}, \hat\tau_k): \hat\tau_k and n_k suffice for the point estimate; n_k^{(1)} is additionally returned so that arm sizes can be checked for asymptotic reliability. The residual sum of squares and projected scatter are omitted, as these constitute additional disclosure.

Server-side objects created. Two symbols are always created per server: base_name_treated (treated-arm subset) and base_name_control (control-arm subset), both used by ds.glm. When study_effects = TRUE, a third symbol base_name_study_adj is also created, holding the data frame augmented with the K-1 study dummy columns. All three persist in the server workspace after the function returns, as is typical for DataSHIELD assign operations. The caller's original base_name object is never modified.

When compute_variance = TRUE (the default), a delta-method variance estimate and 95% confidence interval are also returned. The formula used depends on the heterogeneous argument; see below.

Value

A list. When compute_variance = TRUE (the default), seven elements:

ate

Federated ATE estimate \hat\tau.

variance

Variance estimate \hat V(\hat\tau).

ci_lower

Lower 95-percent confidence interval bound.

ci_upper

Upper 95-percent confidence interval bound.

n_total

Total sample size across all servers.

n_k

Integer vector of per-server sample sizes.

ate_k

Numeric vector of per-server local ATE estimates.

When compute_variance = FALSE, four elements: ate, n_total, n_k, ate_k. The structure is the same regardless of study_effects.

References

Khellaf, R., Bellet, A., and Josse, J. (2025). Federated Causal Inference: Multi-Study ATE Estimation beyond Meta-Analysis. Proceedings of the 28th International Conference on Artificial Intelligence and Statistics (AISTATS 2025).

Examples

if (requireNamespace("DSLite", quietly = TRUE) &&
    requireNamespace("dsFedAte", quietly = TRUE)) {
  library(dsFedAte)
  library(DSLite)

  set.seed(1)
  n <- 200
  study_data <- data.frame(W = rbinom(n, 1, 0.5), X1 = rnorm(n))
  study_data$Y <- 0.5 * study_data$W + study_data$X1 + rnorm(n)

  datashield_env <- new.env(parent = emptyenv())
  options(datashield.env = datashield_env,
          datashield.privacyControlLevel = "banana",
          nfilter.glm = 0.33)

  srv <- DSLite::newDSLiteServer(tables = list(study_data = study_data))
  srv$config(DSLite::defaultDSConfiguration(include = c("dsBase", "dsFedAte")))
  srv$aggregateMethod("localAteDS", "localAteDS")
  srv$aggregateMethod("listDisclosureSettingsDS", "listDisclosureSettingsDS")
  srv$aggregateMethod("checkPermissivePrivacyControlLevel",
                      "checkPermissivePrivacyControlLevel")
  assign("dslite.server", srv, envir = datashield_env)

  builder <- DSI::newDSLoginBuilder()
  builder$append(server = "s1", url = "dslite.server",
                 table = "study_data", driver = "DSLiteDriver")
  conns <- DSI::datashield.login(logins = builder$build(), assign = FALSE)
  DSI::datashield.assign.table(conns, symbol = "study_data", table = "study_data")

  result <- ds.EstimateAte(
    datasources     = conns,
    base_name       = "study_data",
    outcome_name    = "Y",
    treatment_name  = "W",
    covariate_names = "X1",
    quiet           = TRUE
  )
  print(result$ate)

  DSI::datashield.logout(conns)
}