fps_effect_estimation: Estimate causal effect of a functional treatment
In FPScausal: Functional Propensity Score for Causal Inference

fps_effect_estimation

R Documentation

Estimate causal effect of a functional treatment

Description

Given the FPS weights produced by fps_weighting, estimates the causal effect function \hat\mu(t) (scalar/binary outcome) or the causal effect surface \hat\mu(s,t) (functional outcome) via weighted least squares. Optional bootstrap inference is available.

Usage

fps_effect_estimation(
  outcome,
  fps_object,
  outcome_t_grid = NULL,
  outcome_domain = NULL,
  outcome_domain_name = "t",
  outcome_nbasis = NULL,
  outcome_pve = 0.95,
  treatment_pve = NULL,
  bootstrap = FALSE,
  B = 1000,
  alpha = 0.05,
  true_beta = NULL,
  seed = NULL
)

Arguments

`outcome`	Numeric vector (scalar/binary, length n) or n x T matrix (functional outcome).
`fps_object`	Object of class `"fps_weighting"` returned by `fps_weighting`.
`outcome_t_grid`	Numeric vector. Observation grid for functional outcome. Required when `outcome` is a matrix.
`outcome_domain`	Numeric `c(a, b)`. Domain for functional outcome. Required when `outcome` is a matrix.
`outcome_domain_name`	Character. Name of the outcome domain (default `"s"`).
`outcome_nbasis`	Integer or `NULL`. B-spline basis size for the outcome FPCA. Auto-selected if `NULL`.
`outcome_pve`	Numeric in (0, 1]. PVE threshold for outcome FPCA (default 0.95).
`treatment_pve`	Numeric or `NULL`. If not `NULL`, re-runs FPCA on the treatment with this PVE threshold for the outcome estimation step (allowing L* != L). Default `NULL` (reuses `fps_object$fpca_treatment`).
`bootstrap`	Logical. If `TRUE`, compute bootstrap confidence intervals (default `FALSE`).
`B`	Integer. Number of bootstrap resamples (default 1000).
`alpha`	Numeric. Significance level for bootstrap CIs (default 0.05).
`true_beta`	Optional. Numeric vector (scalar/binary) or matrix (functional) containing the true causal effect, used for visual comparison in plots and error metrics in `summary`.
`seed`	Integer or `NULL`. Random seed for bootstrap reproducibility.

Details

Scalar and binary outcomes. The treatment FPC scores A_i are regressed on the outcome using lm (scalar or binary, linear probability model) with the FPS weights. The estimated effect function is then reconstructed as \hat\mu(t) = \sum_k \hat\mu_k \phi_k(t).

Functional outcome. For each outcome FPC component j, the regression c_{ij} \sim A_i is solved with the FPS weights. The causal surface is reconstructed as \hat\mu(s,t) = \Phi_X \hat{B} \Phi_Y^\top where \hat{B} collects the regression coefficients.

Bootstrap CIs. Scalar/binary: residual bootstrap, B resamples. Functional: pairs bootstrap, B resamples. Pointwise reflected-percentile confidence intervals are returned.

Value

An object of class "fps_effect_estimation", a named list with:

outcome_type: Character: "scalar", "binary", or "functional".
beta: Estimated causal effect, evaluated on t_grid (numeric vector for scalar/binary) or on the t_grid x outcome_t_grid grid (matrix for functional).
beta_unweighted: Same as beta but from unweighted regression.
fpca_treatment: FPCA of the treatment used in estimation.
fpca_outcome: NULL for scalar/binary; FPCA list for functional outcome.
ci_lower, ci_upper: NULL if bootstrap = FALSE; otherwise lower and upper bootstrap CI bounds (same shape as beta).
alpha: Significance level used.
t_grid: Treatment domain grid.
outcome_t_grid: NULL for scalar/binary; outcome grid for functional.
domain_name: Treatment domain name.
outcome_domain_name: Outcome domain name.
true_beta: Passed through unchanged.
fps_object: The input fps_weighting object.
call: The matched call.

Examples


dat <- simulate_fps_data(n = 2000, setting = "LL", seed = 1)

w <- fps_weighting(dat$X, dat$t_grid, c(0, 1), covariates = dat$C)

# Scalar outcome, no bootstrap
eff <- fps_effect_estimation(dat$Y, w, true_beta = dat$true_beta)
plot(eff, type = "effect")
plot(eff, type = "comparison")

# With bootstrap (small B for illustration)
eff_boot <- fps_effect_estimation(dat$Y, w, bootstrap = TRUE, B = 100,
                                  true_beta = dat$true_beta, seed = 42)
plot(eff_boot, type = "significance")

FPScausal documentation built on Aug. 9, 2026, 9:07 a.m.