fps_weighting: Estimate functional propensity score weights
In FPScausal: Functional Propensity Score for Causal Inference

fps_weighting

R Documentation

Estimate functional propensity score weights

Description

Computes covariate-balancing weights for a functional treatment using the empirical-likelihood balancing framework of Ciardulli, S. and Fontana, N. (2026). Treatment is represented via FPCA (Karhunen–Loeve expansion); The treatment is first represented via Functional Principal Component Analysis (FPCA) through its Karhunen–Loeve expansion truncated at rank L; the resulting FPC scores and observed confounders are balanced by solving the dual of the empirical-likelihood problem via the BFGS quasi-Newton algorithm. Functional covariates enter the balancing step through their own FPC scores.

Usage

fps_weighting(
  treatment,
  treat_grid = NULL,
  treat_domain = NULL,
  domain_name = "s",
  nbasis = NULL,
  pve = 0.95,
  covariates,
  cov_grids = NULL,
  cov_domains = NULL,
  cov_nbasis = NULL,
  cov_pve = 0.95,
  normalize = TRUE,
  tol = 1e-08,
  maxit = 1000
)

Arguments

`treatment`	n x T numeric matrix of observed treatment trajectories, or an `fd` object from the fda package.
`treat_grid`	Numeric vector of length T giving the observation grid of the treatment. Required when `treatment` is a matrix; inferred automatically when `treatment` is an `fd` object.
`treat_domain`	Numeric vector `c(a, b)` specifying the domain of the treatment. If `NULL` (default) and `treatment` is a matrix, the domain is inferred as `c(min(treat_grid), max(treat_grid))`. Inferred automatically when `treatment` is an `fd` object.
`domain_name`	Character string naming the domain variable (default `"s"`). Used in axis labels and domain-overlap checks.
`nbasis`	Integer. Number of B-spline basis functions used for the treatment FPCA. If `NULL` (default), chosen automatically as `max(10, round(0.6 * length(treat_grid)))`.
`pve`	Numeric in (0, 1]. Proportion of variance explained threshold for the treatment FPCA (default 0.95).
`covariates`	Either (a) an n x p numeric matrix of scalar covariates, or (b) a named list with elements `scalar` (n x p matrix, may be `NULL`) and `functional` (a list of matrices or `fd` objects representing functional covariates).
`cov_grids`	A list of numeric vectors (one per functional covariate) giving the observation grids. Required if `covariates$functional` contains matrices; inferred from the domain when `NULL`.
`cov_domains`	A list of numeric vectors `c(a, b)` (one per functional covariate). If `NULL`, inferred from `cov_grids` extremes.
`cov_nbasis`	A list of integers (or `NULL`) for B-spline basis sizes of functional covariates. Defaults to auto-selection.
`cov_pve`	Numeric in (0, 1]. PVE threshold for functional covariate FPCA (default 0.95).
`normalize`	Logical. If `TRUE` (default), standardise FPC scores and confounders before the dual optimisation.
`tol`	Relative convergence tolerance for the BFGS optimiser (default 1e-8).
`maxit`	Maximum number of BFGS iterations (default 1000).

Value

An object of class "fps_weighting", which is a named list with the following components:

weights: Numeric vector of length n. Positive weights summing to 1.
fpca_treatment: List returned by the internal FPCA routine, containing FPC scores (scr), eigenfunctions (efn), mean function (mean), eigenvalues (eval), variance proportions (varprop), cumulative PVE (perc), raw pca.fd object (pca_fd), number of components retained (L), and the t_grid and domain used.
fpca_covariates: List of FPCA results for functional covariates, or NULL if none were supplied.
scalar_covariates: The n x p scalar covariate matrix used.
conf_matrix: Full augmented confounder matrix fed to the optimiser (scalar covariates column-bound with FPC scores of functional covariates).
convergence: Convergence code from optim (0 = success).
domain_name: The domain name passed via domain_name.
call: The matched call.

Examples


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

# Scalar covariates only (treat_domain inferred from treat_grid)
w <- fps_weighting(
  treatment   = dat$X,
  treat_grid  = dat$t_grid,
  covariates  = dat$C
)
print(w)
plot(w, type = "balance")

# Include one functional covariate
w2 <- fps_weighting(
  treatment   = dat$X,
  treat_grid  = dat$t_grid,
  treat_domain = c(0, 1),
  covariates  = list(scalar = dat$C, functional = list(dat$D)),
  cov_grids   = list(dat$t_grid)
)
plot(w2, type = "balance")

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