pkg_architecture

The goal of this vignette is to help users understand the overall structure of the rsmart package. While the ‘Reference’ page on the pkgdown website is helpful for examining functions individually, we want to provide a high-level view of the package’s conceptual structure.

The rsmart package has 3 user-facing functions, along with a hierarchy of internal helpers. These functions can be organized into five conceptual groups, each of which we will unpack here in this vignette.

1. User-Facing Entry Points

iaipwe() — The main estimation workhorse. Orchestrates the entire pipeline: computes kappa, nu, propensity scores, regime values, and then the sandwich variance (or bootstrap variance). This is what users call directly.
gen_no_trt_resp() — Data generation for simulation studies.
regime_list_no_trt_resp() — Builds the regime/indicator matrices that iaipwe() needs.

2. Nuisance Parameter Estimation (called by `iaipwe`)

These are called first inside iaipwe() to estimate the building blocks:

get_kappa() — Computes how far each individual progressed (stage reached).
get_nu() — Estimates stage-arrival probabilities \(\nu_k\).
pi_fits() — Fits propensity models at all stages (calls pstep() per stage).

3. Value Estimation (called by `iaipwe`)

estimate_values() — Loops over regimes and for each one:
- get_q_fits() — Fits Q-functions backwards through stages (calls qstep() per stage).
- value_terms() — Computes the \(2K+1\) coarsening-level value terms (augmentation + IPW).

4. Sandwich Variance — \(B_n\) (empirical variance of estimating equations)

get_bn() assembles \(\Psi_i \Psi_i^T / n\) by collecting individual-level estimating equation contributions:

ee_psi_pi() — Estimating equation contributions for \(\pi\) parameters.
ee_psi_nu() — Estimating equation contributions for \(\nu\) parameters.
ee_psi_beta() — Estimating equation contributions for \(\beta\) (Q-function) parameters.
ee_psi_v() — Estimating equation contributions for the value parameters \(V\).

5. Sandwich Variance — \(A_n\) (derivative of estimating equations)

get_an() assembles \(-\partial\Psi/\partial\theta\) by collecting derivatives:

ee_dpsi_pi() — Derivative block for \(\pi\).
ee_dpsi_nu() — Derivative block for \(\nu\).
ee_dpsi_beta() — Derivative block for \(\beta\).
ee_dpsiv() (AIPW) or ee_dpsiv_ipw() (IPW) — Derivative rows for \(V\), which internally call:
- ee_dpsiv_dpi() / ee_dpsiv_dpi_ipw()
- ee_dpsiv_dnu() / ee_dpsiv_dnu_ipw()
- ee_dpsiv_dbeta() (AIPW only)
- ee_dpsiv_dv()

6. Trial Design Utilities (standalone)

get_bounds() — Group sequential stopping boundaries (calls get_first_bound() + get_next_bound()).
get_sample_size() — Sample size determination.
get_q_coefs() — Coefficient extraction utility.