feasible: Estimate Feasible Intervention Strategies

Description

Estimate a family of feasible intervention strategies for a continuous treatment (and optionally time-varying covariates). The method returns, for each intervention strategy, the corresponding “feasible” intervention values and a summary of overlap and positivity-violation diagnostics.

Usage

feasible(
  X, Anodes = NULL, Ynodes = NULL, Lnodes = NULL, Cnodes = NULL,
  abar = NULL,
  alpha = 0.95, grid.size = 0.5, tol = 1e-2,
  left.boundary = NULL, right.boundary = NULL,
  screen = FALSE, survival = FALSE,
  d.method = c("hazardbinning", "binning", "parametric", "hal_density"),
  verbose = TRUE, ...
)

Value

An object of class "feasible" with the following components:

feasible: a list of length equal to the number of strategies (rows of abar). Each element is a matrix with one column per time point, containing the feasible intervention values for that strategy and time point across observations.
low_matrix: a list of length equal to the number of time points. Each element is a logical matrix indicating, on the internal grid, which cells were marked as below the density threshold.

The object additionally has a "summary" attribute, a data frame with at least the columns time, Strategy, Abar, Feasible, and Low, which is accessed and formatted by summary.feasible

and print.feasible.

Arguments

X

A data frame containing all nodes in temporal order. Columns must include the treatment, outcome, covariate and censoring nodes specified in Anodes, Ynodes, Lnodes, and Cnodes.

Anodes

Character vector giving the column names in X of the (possibly time-varying) treatment nodes. These define the treatment history.

Ynodes

Character vector giving the column names in X of the outcome nodes. At least one outcome node must be specified, and all of them must occur after the first treatment node in the column ordering of X.

Lnodes

Optional character vector of confounder nodes. May be NULL if there are no such nodes.

Cnodes

Optional character vector of censoring (or competing event) nodes. May be NULL if there is no censoring.

abar

Numeric vector or matrix specifying the target interventions.

If a vector, each element defines a static intervention that sets the treatment to that value at all time points. In this case, each strategy corresponds to a single scalar target value.
If a matrix, rows index intervention strategies and columns index time points (one column per element in Anodes). Then abar[k, t] is the target treatment value for strategy k at time t.

The argument must be numeric; NULL is not allowed.

alpha

Numeric scalar in (0, 1) controlling the density-truncation level. For each observation and time point, the method finds the smallest density threshold \(f_\alpha\) such that at most alpha of the total mass lies above this threshold. Cells with density below \(f_\alpha\) are treated as “infeasible”. Default is 0.95.

grid.size

Positive numeric scalar giving the spacing of the grid used to approximate the treatment density. If NULL, no internal grid is constructed and abar itself is used as the grid of evaluation points (this is only allowed when abar is a vector). Default is 0.5.

tol

Non-negative numeric tolerance used when combining abar with the grid. Points closer than tol to an element of abar are considered duplicates and are dropped from the internal grid before merging with abar. Default is 1e-2.

left.boundary

Optional numeric scalar setting the left boundary of the grid used to approximate the treatment density. If NULL, the minimum of the observed treatment values and abar is used.

right.boundary

Optional numeric scalar setting the right boundary of the density grid. If NULL, the maximum of the observed treatment values and abar is used.

screen

Logical; if TRUE, use variable-screening (via internal functions from CICI) for the treatment models, otherwise use the full treatment model formulae. Default is FALSE.

survival

Logical; indicates whether the outcome nodes correspond to a survival-type structure. Passed to the internal model-building function. Default is FALSE.

d.method

Character string specifying the density-estimation method used to estimate the conditional treatment density. Must be one of "hazardbinning", "binning", "parametric", or "hal_density".

verbose

Logical; if TRUE, print warnings about ignored arguments passed via ... and other diagnostic messages. Default is TRUE.

...

Additional arguments passed to the underlying density-estimation function determined by d.method. For example, these may include SL.library for Super Learner-based methods, or tuning parameters for specific density estimators. Arguments not recognised by the chosen d.method are silently ignored when verbose = FALSE and produce a warning when verbose = TRUE.

Details

The main steps of the algorithm are:

Model specification: Treatment models for each time point are constructed via helper routines from CICI. If screen = TRUE, a screening step updates the treatment formulas before density estimation (only recommended to address computational constraints).
Grid construction: A grid of treatment values, query_abar, is formed by combining:
- observed treatment values in X[, Anodes],
- the target values in abar, and
- a regular grid from left.boundary to right.boundary with spacing grid.size (when grid.size is not NULL).
If grid.size = NULL, the grid is restricted to the unique values in abar (only allowed when abar is a vector).
Density estimation: For each time point, the conditional treatment density is evaluated on the grid for each observation using the specified d.method. The resulting matrices are normalised so that each row integrates to one over the grid (accounting for bin width).
Feasibility threshold: For each observation and time point, a density threshold \(f_\alpha\) is computed such that the cumulative mass below the sorted densities first exceeds 1 - alpha. Cells with density below \(f_\alpha\) are flagged as “infeasible”.
Feasible mapping: For each grid cell with density below \(f_\alpha\), the algorithm finds the closest grid cell with density at or above \(f_\alpha\) (in terms of grid index) and maps its value to that cell. This defines a “feasible” intervention that avoids low-density regions.
Summary: For each time point \(t\) and each intervention strategy (row of abar), the method collects:
- the mean feasible value across individuals (column Feasible),
- the proportion of cells below the density threshold (column Low, interpreted as %infeasible in the associated S3 methods),
- the corresponding target value Abar at time \(t\), and
- the strategy index Strategy.
These are combined into a data frame stored as the "summary" attribute of the returned object.

Plotting and printing methods are available for visual and tabular diagnostics; see plot.feasible, print.feasible, and summary.feasible.

Examples

Run this code

data(EFV)

# \donttest{
Lnodes <- c("adherence.1","weight.1",
            "adherence.2","weight.2",
            "adherence.3","weight.3",
            "adherence.4","weight.4")
Ynodes <- c("VL.0","VL.1","VL.2","VL.3","VL.4")
Anodes <- c("efv.0","efv.1","efv.2","efv.3","efv.4")

## ------------------------------------------------------------------
## Example 1: Hazard binning with default grid
## Static grid of targets (vector abar) over the full support of efv.*
## ------------------------------------------------------------------

abar_static <- seq(0, 10, by = 1)

m_hazard <- feasible(
  X      = EFV,
  Anodes = Anodes,
  Lnodes = Lnodes,
  Ynodes = Ynodes,
  d.method      = "hazardbinning", # long computation, but appropriate
  abar          = abar_static,
  grid.size     = 0.5,
  left.boundary = 0,
  right.boundary = 10
)


## Individual-level feasible values (one matrix per strategy):
## rows = individuals, columns = time points
feasible_matrix <- m_hazard$feasible # pass on to gofrmula/sgf
lapply(feasible_matrix, head)

## Inspect feasability of strategies
m_hazard             # see also ?print.feasible
summary(m_hazard)    # see also ?summary.feasible


## ------------------------------------------------------------------
## Example 2: Parametric density, using abar as the grid
## Here grid.size = NULL, so only the target values are used as grid
## ------------------------------------------------------------------

abar_param <- seq(0, 10, by = 2)

m_param <- feasible(
  X      = EFV,
  Anodes = Anodes,
  Lnodes = Lnodes,
  Ynodes = Ynodes,
  # fast, but useful for reasonably symmetric distributions
  d.method      = "parametric", 
  abar          = abar_param,
  grid.size     = NULL,
  left.boundary = 0,
  right.boundary = 10
)

## Inspect feasability of strategies
m_param             # see also ?print.feasible
summary(m_param)    # see also ?summary.feasible


## ------------------------------------------------------------------
## Example 3: Matrix abar with non-constant strategies over time
## Each row is a strategy, each column corresponds to efv.0, ..., efv.4
## ------------------------------------------------------------------

abar_matrix <- rbind(
  c(0, 2, 4, 6, 8),  # strategy 1
  c(9, 6, 2, 1, 0),  # strategy 2
  c(1, 3, 5, 7, 9)   # strategy 3
)

m_matrix <- feasible(
  X      = EFV,
  Anodes = Anodes,
  Lnodes = Lnodes,
  Ynodes = Ynodes,
  d.method      = "parametric",
  abar          = abar_matrix,
  grid.size     = 1,
  left.boundary = 0,
  right.boundary = 10
)

## Inspect feasability of strategies
m_matrix             # see also ?print.feasible
summary(m_matrix)    # see also ?summary.feasible

# }