How cran/outstandr works
1. What this repository is
- outstandR is a pure R package for population-adjusted indirect treatment comparison.
- The core architectural idea is: one trial has IPD (individual patient data), the other has ALD (aggregate-level data), and the package standardizes the IPD model to estimate a marginal treatment contrast in the comparator population.
2. Primary workflow
- The package follows a pipeline:
1. Parse and validate the user’s model specification
2. Prepare IPD and ALD into compatible shapes
3. Fit an adjustment strategy
4. Compute marginal treatment effects and uncertainty
5. Return an S3 result object with summary/plot methods
- This is not a service architecture; it is an in-memory statistical computation library.
3. Input and data-shaping boundary
- prep_data, prep_ipd, prep_ald, reshape_ald, and reshape_ald_to_long/wide form the main data-ingestion boundary.
- These functions align the two-trial inputs into a common structure, including handling trial-specific covariates, treatment labels, and outcome formats.
- Supporting utilities like cor2cov and the trial-stat helpers indicate the package can reconstruct covariance information from summary inputs when only aggregate data are available.
4. Formula and specification layer
- parse_formula, check_formula, check_balance_formula, validate_outstandr, and the various get_* helpers are the package’s configuration/guardrail layer.
- This layer determines:
- outcome model structure,
- treatment naming,
- reference/comparator treatment,
- effect modifiers,
- covariate names,
- and allowed variance-estimation methods.
- It is the main boundary preventing invalid model setups from reaching the estimation engine.
5. Core estimation strategies
- The package exposes several distinct adjustment engines:
- maic for Matching-Adjusted Indirect Comparison,
- gcomp_ml for parametric g-computation via maximum likelihood,
- gcomp_bayes for Bayesian g-computation,
- mim for multiple-imputation marginalization,
- calc_stc for Simulated Treatment Comparison.
- These are implemented as separate strategy paths rather than a single monolithic estimator, which makes the architecture method-oriented.
6. Deprecated/legacy path
- STC is explicitly marked deprecated in the README and still retained in code for backward compatibility.
- Architecturally, it is a legacy branch alongside the newer g-computation methods, not the preferred path for new analyses.
7. Common statistical post-processing
- calculate_ate, result_stats, calc_IPD_stats, calc_ALD_stats, and estimate_var_sandwich indicate a shared post-estimation layer.
- This layer standardizes outputs across methods: treatment effect estimates, marginal means, variance estimates, and confidence intervals.
- Variance handling is abstracted through get_var_method and related helpers, suggesting pluggable uncertainty estimation.
8. Data-type-specific support
- The presence of functions such as calc_*_binary, calc_*_continuous, and calc_*_count shows the package is organized around outcome family as well as method.
- The bundled datasets (AC_IPD_*, BC_ALD_*) show the package supports multiple outcome types and mixed covariate structures, not just a single GLM family.
9. Object model and user-facing API
- outstandR-class, strategy-class, outstandR.R, strategy_.R, print.R, summary.R, plot.R, and related print helpers indicate S3-style object encapsulation.
- The package likely returns a main result object plus a strategy object that records the chosen method and settings.
- This separation is important for architecture diagrams: estimation is done first, then presentation methods operate on the stored result.
10. Simulation and compatibility machinery
- simulate_ALD_pseudo_pop suggests the package can generate pseudo-populations from aggregate data, which is critical when only ALD is available for one arm/trial.
- Together with mim and the g-computation methods, this is the compatibility layer that bridges limited subject-level data to a population-adjusted estimand.
11. Repository structure and tooling
- This is a standard R package layout:
- R/ for source,
- man/ for generated documentation,
- data/ for example datasets,
- tests/testthat/ for automated tests,
- inst/ for package metadata/references.
- DESCRIPTION, NAMESPACE, and the generated docs confirm the package is built and distributed as a CRAN-style R library.
12. How to diagram the architecture
- A good diagram would show:
- User/API layer: outstandR(), maic(), gcomp_*(), mim()
- Validation/config layer: formula parsing, strategy selection, treatment/covariate discovery
- Data preparation layer: IPD/ALD reshaping and pseudo-population generation
- Estimation layer: method-specific engines
- Inference/output layer: effect estimates, variance, summary/plot/print methods
- The key boundary is between input harmonization and method-specific estimation; most of the repository exists to make those two compatible.
Main entry points: outstandR.R outstandR · calculate_ate.R ATE calc · validate_outstandr.R Package validate · prep_data.R Prep data
Components 24
User API
Entry points for fitting and inspecting adjusted indirect comparison models.
- outstandR · Top-level user entry point that orchestrates validation, preparation, estimation, and result creation.
R/outstandR.R - MAIC · Matching-adjusted indirect comparison workflow.
R/maic.R - G-comp ML · Parametric g-computation via maximum likelihood.
R/gcomp_ml.R - G-comp Bayes · Bayesian g-computation workflow.
R/gcomp_bayes.R - MIM · Multiple-imputation marginalization workflow.
R/mim.R - STC · Deprecated simulated treatment comparison path retained for compatibility.
R/calc_stc.R
Specification
Formula parsing, treatment discovery, and model guardrails.
- Parse formula · Interprets outcome, treatment, and covariate structure from user formulas.
R/parse_formula.R - Validate spec · Checks formula consistency, balance constraints, and overall configuration validity.
R/check_formula.R - Package validate · Main package-level validation wrapper for allowed methods and model setup.
R/validate_outstandr.R
Data prep
IPD/ALD harmonization and pseudo-population construction.
- Prep data · Coordinates IPD and ALD preprocessing into compatible analysis inputs.
R/prep_data.R - Prep IPD · Standardizes individual-patient trial data and covariate handling.
R/prep_data.R - Prep ALD · Standardizes aggregate-level trial summaries and outcome inputs.
R/prep_data.R - Reshape ALD · Converts aggregate data between wide and long representations.
R/reshape_ald.R - Pseudo-population · Simulates or reconstructs subject-like data from aggregate summaries when needed.
R/simulate_ALD_pseudo_pop.R
Estimation
Method-specific adjustment engines and outcome-family branches.
- MAIC engine · Computes MAIC weights and adjusted contrasts.
R/maic.R - G-comp engine · Shared g-computation machinery for ML and Bayesian variants.
R/gcomp_ml.R - MIM engine · Computes marginal effects using multiple-imputation style averaging.
R/mim.R - STC engine · Legacy STC computation path aligned with older analyses.
R/calc_stc.R
Inference
Common effect estimation, uncertainty handling, and result assembly.
- ATE calc · Calculates marginal treatment effects and contrasts on the target scale.
R/calculate_ate.R - Result stats · Assembles estimates, uncertainty, and trial-level statistics across methods.
R/result_stats.R - Variance · Selects and computes variance estimates, including sandwich-style methods.
R/get_var_method.R
Objects
S3 result and strategy containers plus presentation methods.
- outstandR obj · Primary fitted result object storing estimates and settings.
R/outstandR-class.R - strategy obj · Stores the chosen adjustment strategy and analysis metadata.
R/strategy-class.R - Print/summary/plot · User-facing S3 methods for displaying fitted results.
R/print.R
Connections 28
- outstandR → Package validate: validate · Checks user inputs before fitting.
- outstandR → Parse formula: parse · Derives model structure and roles from formulas.
- Package validate → Validate spec: guard · Applies formula and configuration checks.
- Package validate → Prep data: dispatch · Sends validated inputs into data preparation.
- Parse formula → Validate spec: rules · Parsed specification is checked for consistency.
- Prep data → Prep IPD: IPD · Prepares individual-level trial data.
- Prep data → Prep ALD: ALD · Prepares aggregate-level trial data.
- Prep ALD → Reshape ALD: reshape · Normalizes ALD shape for downstream methods.
- Prep ALD → Pseudo-population: bridge · Builds pseudo-population inputs when only aggregate data are available.
- outstandR → MAIC: choose · Routes to MAIC strategy when requested.
- outstandR → G-comp ML: choose · Routes to maximum-likelihood g-computation.
- outstandR → G-comp Bayes: choose · Routes to Bayesian g-computation.
- outstandR → MIM: choose · Routes to multiple-imputation marginalization.
- outstandR → STC: choose · Routes to deprecated STC compatibility path.
- MAIC → MAIC engine: fit · Executes MAIC weighting and adjustment.
- G-comp ML → G-comp engine: fit · Uses shared g-computation estimation machinery.
- G-comp Bayes → G-comp engine: fit · Uses shared g-computation estimation machinery.
- MIM → MIM engine: fit · Executes marginalization via multiple imputation.
- STC → STC engine: fit · Executes legacy STC calculations.
- MAIC engine → ATE calc: contrast · Produces marginal treatment contrast estimates.
- G-comp engine → ATE calc: contrast · Produces marginal treatment contrast estimates.
- MIM engine → ATE calc: contrast · Produces marginal treatment contrast estimates.
- STC engine → ATE calc: contrast · Produces marginal treatment contrast estimates.
- ATE calc → Variance: uncertainty · Links effect estimates to variance selection and estimation.
- Variance → Result stats: assemble · Feeds uncertainty estimates into final result statistics.
- Result stats → outstandR obj: return · Wraps computed statistics in the main result object.
- outstandR obj → strategy obj: contains · Stores the selected strategy and settings alongside results.
- outstandR obj → Print/summary/plot: methods · Presentation methods operate on the fitted object.