# cran/outstandr architecture

> Architecture diagram of the GitHub repository cran/outstandr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cran/outstandr
- Repository: https://github.com/cran/outstandr

## Overview

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: [`R/outstandR.R`](https://github.com/cran/outstandr/blob/master/R/outstandR.R) (outstandR), [`R/calculate_ate.R`](https://github.com/cran/outstandr/blob/master/R/calculate_ate.R) (ATE calc), [`R/validate_outstandr.R`](https://github.com/cran/outstandr/blob/master/R/validate_outstandr.R) (Package validate), [`R/prep_data.R`](https://github.com/cran/outstandr/blob/master/R/prep_data.R) (Prep data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_api["User API"]
  node_node_outstandr["outstandR<br/>main API<br/>[outstandR.R]"]
  node_node_maic["MAIC<br/>strategy API<br/>[maic.R]"]
  node_node_gcomp_ml["G-comp ML<br/>strategy API<br/>[gcomp_ml.R]"]
  node_node_gcomp_bayes["G-comp Bayes<br/>strategy API<br/>[gcomp_bayes.R]"]
  node_node_mim["MIM<br/>strategy API<br/>[mim.R]"]
  node_node_stc["STC<br/>legacy API<br/>[calc_stc.R]"]
end

subgraph group_group_validate["Specification"]
  node_node_parse["Parse formula<br/>spec parser<br/>[parse_formula.R]"]
  node_node_check["Validate spec<br/>guardrails<br/>[check_formula.R]"]
  node_node_validate["Package validate<br/>entry validation"]
end

subgraph group_group_data["Data prep"]
  node_node_prep[("Prep data<br/>data harmonizer<br/>[prep_data.R]")]
  node_node_prep_ipd["Prep IPD<br/>ipd prep<br/>[prep_data.R]"]
  node_node_prep_ald["Prep ALD<br/>ald prep<br/>[prep_data.R]"]
  node_node_reshape["Reshape ALD<br/>shape adapter<br/>[reshape_ald.R]"]
  node_node_pseudo(("Pseudo-population<br/>bridge generator"))
end

subgraph group_group_methods["Estimation"]
  node_node_maic_eng["MAIC engine<br/>estimator<br/>[maic.R]"]
  node_node_gcomp_eng["G-comp engine<br/>estimator<br/>[gcomp_ml.R]"]
  node_node_mim_eng["MIM engine<br/>estimator<br/>[mim.R]"]
  node_node_stc_eng["STC engine<br/>legacy estimator<br/>[calc_stc.R]"]
end

subgraph group_group_post["Inference"]
  node_node_ate["ATE calc<br/>effect summary<br/>[calculate_ate.R]"]
  node_node_stats["Result stats<br/>summary layer<br/>[result_stats.R]"]
  node_node_var["Variance<br/>uncertainty<br/>[get_var_method.R]"]
end

subgraph group_group_object["Objects"]
  node_node_result["outstandR obj<br/>S3 result<br/>[outstandR-class.R]"]
  node_node_strategy["strategy obj<br/>S3 config<br/>[strategy-class.R]"]
  node_node_printsumplot["Print/summary/plot<br/>methods<br/>[print.R]"]
end

node_node_outstandr -->|"validate"| node_node_validate
node_node_outstandr -->|"parse"| node_node_parse
node_node_validate -->|"guard"| node_node_check
node_node_validate -->|"dispatch"| node_node_prep
node_node_parse -->|"rules"| node_node_check
node_node_prep -->|"IPD"| node_node_prep_ipd
node_node_prep -->|"ALD"| node_node_prep_ald
node_node_prep_ald -->|"reshape"| node_node_reshape
node_node_prep_ald -->|"bridge"| node_node_pseudo
node_node_outstandr -->|"choose"| node_node_maic
node_node_outstandr -->|"choose"| node_node_gcomp_ml
node_node_outstandr -->|"choose"| node_node_gcomp_bayes
node_node_outstandr -->|"choose"| node_node_mim
node_node_outstandr -->|"choose"| node_node_stc
node_node_maic -->|"fit"| node_node_maic_eng
node_node_gcomp_ml -->|"fit"| node_node_gcomp_eng
node_node_gcomp_bayes -->|"fit"| node_node_gcomp_eng
node_node_mim -->|"fit"| node_node_mim_eng
node_node_stc -->|"fit"| node_node_stc_eng
node_node_maic_eng -->|"contrast"| node_node_ate
node_node_gcomp_eng -->|"contrast"| node_node_ate
node_node_mim_eng -->|"contrast"| node_node_ate
node_node_stc_eng -->|"contrast"| node_node_ate
node_node_ate -->|"uncertainty"| node_node_var
node_node_var -->|"assemble"| node_node_stats
node_node_stats -->|"return"| node_node_result
node_node_result -->|"contains"| node_node_strategy
node_node_result -->|"methods"| node_node_printsumplot

click node_node_outstandr "https://github.com/cran/outstandr/blob/master/R/outstandR.R"
click node_node_maic "https://github.com/cran/outstandr/blob/master/R/maic.R"
click node_node_gcomp_ml "https://github.com/cran/outstandr/blob/master/R/gcomp_ml.R"
click node_node_gcomp_bayes "https://github.com/cran/outstandr/blob/master/R/gcomp_bayes.R"
click node_node_mim "https://github.com/cran/outstandr/blob/master/R/mim.R"
click node_node_stc "https://github.com/cran/outstandr/blob/master/R/calc_stc.R"
click node_node_parse "https://github.com/cran/outstandr/blob/master/R/parse_formula.R"
click node_node_check "https://github.com/cran/outstandr/blob/master/R/check_formula.R"
click node_node_validate "https://github.com/cran/outstandr/blob/master/R/validate_outstandr.R"
click node_node_prep "https://github.com/cran/outstandr/blob/master/R/prep_data.R"
click node_node_prep_ipd "https://github.com/cran/outstandr/blob/master/R/prep_data.R"
click node_node_prep_ald "https://github.com/cran/outstandr/blob/master/R/prep_data.R"
click node_node_reshape "https://github.com/cran/outstandr/blob/master/R/reshape_ald.R"
click node_node_pseudo "https://github.com/cran/outstandr/blob/master/R/simulate_ALD_pseudo_pop.R"
click node_node_maic_eng "https://github.com/cran/outstandr/blob/master/R/maic.R"
click node_node_gcomp_eng "https://github.com/cran/outstandr/blob/master/R/gcomp_ml.R"
click node_node_mim_eng "https://github.com/cran/outstandr/blob/master/R/mim.R"
click node_node_stc_eng "https://github.com/cran/outstandr/blob/master/R/calc_stc.R"
click node_node_ate "https://github.com/cran/outstandr/blob/master/R/calculate_ate.R"
click node_node_stats "https://github.com/cran/outstandr/blob/master/R/result_stats.R"
click node_node_var "https://github.com/cran/outstandr/blob/master/R/get_var_method.R"
click node_node_result "https://github.com/cran/outstandr/blob/master/R/outstandR-class.R"
click node_node_strategy "https://github.com/cran/outstandr/blob/master/R/strategy-class.R"
click node_node_printsumplot "https://github.com/cran/outstandr/blob/master/R/print.R"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_outstandr,node_node_maic,node_node_gcomp_ml,node_node_gcomp_bayes,node_node_mim,node_node_stc toneBlue
class node_node_parse,node_node_check,node_node_validate toneAmber
class node_node_prep,node_node_prep_ipd,node_node_prep_ald,node_node_reshape,node_node_pseudo toneMint
class node_node_maic_eng,node_node_gcomp_eng,node_node_mim_eng,node_node_stc_eng toneRose
class node_node_ate,node_node_stats,node_node_var toneIndigo
class node_node_result,node_node_strategy,node_node_printsumplot toneTeal
```

## Components

### User API

Entry points for fitting and inspecting adjusted indirect comparison models.

- [outstandR](https://github.com/cran/outstandr/blob/master/R/outstandR.R): main API · Top-level user entry point that orchestrates validation, preparation, estimation, and result creation. · `R/outstandR.R`
- [MAIC](https://github.com/cran/outstandr/blob/master/R/maic.R): strategy API · Matching-adjusted indirect comparison workflow. · `R/maic.R`
- [G-comp ML](https://github.com/cran/outstandr/blob/master/R/gcomp_ml.R): strategy API · Parametric g-computation via maximum likelihood. · `R/gcomp_ml.R`
- [G-comp Bayes](https://github.com/cran/outstandr/blob/master/R/gcomp_bayes.R): strategy API · Bayesian g-computation workflow. · `R/gcomp_bayes.R`
- [MIM](https://github.com/cran/outstandr/blob/master/R/mim.R): strategy API · Multiple-imputation marginalization workflow. · `R/mim.R`
- [STC](https://github.com/cran/outstandr/blob/master/R/calc_stc.R): legacy API · Deprecated simulated treatment comparison path retained for compatibility. · `R/calc_stc.R`

### Specification

Formula parsing, treatment discovery, and model guardrails.

- [Parse formula](https://github.com/cran/outstandr/blob/master/R/parse_formula.R): spec parser · Interprets outcome, treatment, and covariate structure from user formulas. · `R/parse_formula.R`
- [Validate spec](https://github.com/cran/outstandr/blob/master/R/check_formula.R): guardrails · Checks formula consistency, balance constraints, and overall configuration validity. · `R/check_formula.R`
- [Package validate](https://github.com/cran/outstandr/blob/master/R/validate_outstandr.R): entry validation · 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](https://github.com/cran/outstandr/blob/master/R/prep_data.R): data harmonizer · Coordinates IPD and ALD preprocessing into compatible analysis inputs. · `R/prep_data.R`
- [Prep IPD](https://github.com/cran/outstandr/blob/master/R/prep_data.R): ipd prep · Standardizes individual-patient trial data and covariate handling. · `R/prep_data.R`
- [Prep ALD](https://github.com/cran/outstandr/blob/master/R/prep_data.R): ald prep · Standardizes aggregate-level trial summaries and outcome inputs. · `R/prep_data.R`
- [Reshape ALD](https://github.com/cran/outstandr/blob/master/R/reshape_ald.R): shape adapter · Converts aggregate data between wide and long representations. · `R/reshape_ald.R`
- [Pseudo-population](https://github.com/cran/outstandr/blob/master/R/simulate_ALD_pseudo_pop.R): bridge generator · 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](https://github.com/cran/outstandr/blob/master/R/maic.R): estimator · Computes MAIC weights and adjusted contrasts. · `R/maic.R`
- [G-comp engine](https://github.com/cran/outstandr/blob/master/R/gcomp_ml.R): estimator · Shared g-computation machinery for ML and Bayesian variants. · `R/gcomp_ml.R`
- [MIM engine](https://github.com/cran/outstandr/blob/master/R/mim.R): estimator · Computes marginal effects using multiple-imputation style averaging. · `R/mim.R`
- [STC engine](https://github.com/cran/outstandr/blob/master/R/calc_stc.R): legacy estimator · Legacy STC computation path aligned with older analyses. · `R/calc_stc.R`

### Inference

Common effect estimation, uncertainty handling, and result assembly.

- [ATE calc](https://github.com/cran/outstandr/blob/master/R/calculate_ate.R): effect summary · Calculates marginal treatment effects and contrasts on the target scale. · `R/calculate_ate.R`
- [Result stats](https://github.com/cran/outstandr/blob/master/R/result_stats.R): summary layer · Assembles estimates, uncertainty, and trial-level statistics across methods. · `R/result_stats.R`
- [Variance](https://github.com/cran/outstandr/blob/master/R/get_var_method.R): uncertainty · 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](https://github.com/cran/outstandr/blob/master/R/outstandR-class.R): S3 result · Primary fitted result object storing estimates and settings. · `R/outstandR-class.R`
- [strategy obj](https://github.com/cran/outstandr/blob/master/R/strategy-class.R): S3 config · Stores the chosen adjustment strategy and analysis metadata. · `R/strategy-class.R`
- [Print/summary/plot](https://github.com/cran/outstandr/blob/master/R/print.R): methods · User-facing S3 methods for displaying fitted results. · `R/print.R`

## Connections

- 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.
