Package index • iconic

Data input & containers

Standardise exposure, outcome, mediator, instrument, and negative-control data into the object used across the package, and simulate ground-truth panels.

iconic_data(): Construct a standardized data object for ICONIC model selection
as_iconic_data(): Convert external data containers to iconic_data
load_real_input_data(): Load and standardise a real multi-omic dataset for GAN training
generate_toy_data(): Generate one synthetic dataset (internal)
simulate_single_genetic_instrument(): Simulate a single genetic instrument

Exposure instruments

Build and validate a genetic instrument for the exposure from GWAS summary statistics or a published polygenic-score panel.

qc_gwas_sumstats(): Standardize and QC GWAS summary statistics
build_prs_ldpred2(): Build an exposure polygenic score with LDpred2-auto
score_pgs_panel(): Score a published polygenic-score panel on a dosage matrix
check_instrument_strength(): Check first-stage instrument strength (partial F)

Mediator instruments

Call cis-eQTLs and train genetically-predicted expression instruments for the mediator panel.

call_cis_eqtls(): Scan for cis-eQTLs of each gene
build_mediator_instruments(): Build mediator instruments via per-gene elastic net

Negative controls

Construct negative-control panels and run the validity, independence, support, and completeness diagnostics.

beta_to_m(): Convert methylation beta values to M-values
residualize_matrix(): Residualize a feature matrix on covariates
build_w_pcs(): Build a negative-control panel from principal components
apply_fusion_weights(): Apply FUSION/TWAS eQTL weights to a dosage matrix
nc_proxy(): Direct-proxy negative-control model
nc_cpg(): CpG-predicted-expression negative-control model (SCENIC case)
list_nc_models(): List the built-in negative-control models
nc_validity_check(): Check negative-control validity across confounding scenarios
nc_validity_screen(): Screen negative controls for exposure dependence (W | X | C)
nc_independence_check(): Test instrument-independence of negative controls (W | G | C)
nc_independence_check_gm(): Test mediator-instrument independence of negative controls (W | Gm | C)
nc_support_check(): Negative-control support/range check
nc_completeness_check(): Check negative-control completeness (dimensional + covariance-capture)
nc_completeness_capture(): Covariance-capture completeness test

Core workflow

The end-to-end model-selection pipeline: diagnose eligibility, estimate effects, stress-test robustness, and recommend an estimator.

iconic_diagnose(): Diagnose data and determine estimator eligibility
iconic_estimate(): Fit all eligible estimators on real data
iconic_sensitivity(): Sensitivity (degradation) surface and effect-decomposition bias sweep
iconic_recommend(): Recommend the best causal estimator for the user's data
iconic_prospect(): Prospective bias-reduction analysis for data without instruments or negative controls
infer_confounding(): Infer confounding parameters from the user's data
recommend_estimator(): Recommend the preferred estimator from a sensitivity sweep

Estimators (low-level)

Individual NDE/NIE estimators. Most users call these through iconic_estimate() rather than directly.

fit_coca(): COCA estimator: Negative-Control Outcome Correction via ratio
fit_coca_mediation(): COCA mediation estimator: negative-control calibration of both stages
fit_coca_mediation_surv(): COCA survival mediation estimator: NOT supported (returns NA)
fit_coca_surv(): COCA survival estimator: NOT supported (returns NA)
fit_direct(): DIRECT estimator: OLS with instrument and negative-control as covariates
fit_direct_mediation(): DIRECT mediation estimator: OLS with instrument and NC as covariates
fit_direct_mediation_surv(): DIRECT survival mediation estimator: Cox / RMST with G and W covariates
fit_direct_surv(): DIRECT survival estimator: Cox / RMST with instrument and NC covariates
fit_iv2sls(): IV2SLS estimator: Two-Stage Least Squares with genetic instrument
fit_iv2sls_mediation(): IV2SLS mediation estimator: instrumented exposure in both stages
fit_iv2sls_mediation2(): IV2SLS2 mediation estimator: 2-stage MR with instruments for both X and M
fit_iv2sls_mediation2_surv(): IV2SLS2 survival mediation estimator: 2-stage MR with Cox / RMST outcome
fit_iv2sls_mediation_surv(): IV2SLS survival mediation estimator: single-instrument 2SPS with Cox / RMST
fit_iv2sls_surv(): IV2SLS survival estimator: two-stage predictor substitution with Cox / RMST
fit_pgc(): PGC estimator: Proxy G-Component Correction (matrix bridge)
fit_pgc_mediation(): PGC mediation estimator: bridge-function-adjusted natural effects (matrix bridge)
fit_pgc_mediation2(): PGC-2 mediation estimator: two-stage proximal mediation with path-specific bridges
fit_pgc_mediation2_surv(): PGC2 / PGC2Gm survival mediation estimator: path-specific bridges with Cox / RMST
fit_pgc_mediation_surv(): PGC survival mediation estimator: single-panel bridge with Cox / RMST
fit_pgc_scalar(): PGC estimator: Proxy G-Component Correction (scalar bridge)
fit_pgc_scalar_mediation(): PGC mediation estimator: bridge-function-adjusted natural effects (scalar bridge)
fit_pgc_surv(): PGC survival estimator: proxy G-component correction with Cox / RMST
fit_unadj_mediation(): UNADJ mediation estimator: naive Baron-Kenny style
fit_unadj_mediation_surv(): UNADJ survival mediation estimator: naive Baron-Kenny with Cox / RMST
fit_unadj_surv(): UNADJ survival estimator: unadjusted Cox / RMST regression

Sensitivity & robustness analysis

Generative-model stress tests of instrument exogeneity and pleiotropy, and p-value combination helpers.

gan_sensitivity(): Benchmark estimators across confounding scenarios on synthetic data
gan_mediation_sensitivity(): Benchmark mediation estimators across confounding scenarios
gan_pleiotropy_sensitivity(): Benchmark estimators across pleiotropy and confounding scenarios
composite_p_value(): Composite null hypothesis test p-value

Simulation & sweeps

Simulation drivers and parameter-sweep machinery used for estimator validation and benchmarking.

run_simulation(): Run repeated simulations for a single parameter configuration
run_single_iteration(): Generate one synthetic dataset under the generalised SCM
run_mediation_sim(): Run repeated mediation simulations for a single parameter configuration
run_null_sim(): Run null simulations to estimate Type I error rates
run_null_mediation_sim(): Run null mediation simulations to estimate Type I error rates
sweep_instrument_strength(): Sweep instrument strength
sweep_mediation_null_by_conf(): Sweep mediation Type I error across confounding strength levels
sweep_mediation_param(): Sweep a single mediation simulation parameter across a grid
sweep_nc_validity(): Sweep negative-control validity diagnostics
sweep_null_by_conf(): Sweep Type I error rate across confounding strength levels
sweep_param(): Sweep a single simulation parameter across a grid
analyze_methods_robust(): Run all five estimators (plus UNADJ) on one synthetic dataset
analyze_methods_parallel(): Parallel version of analyze_methods_robust()
analyze_mediation_robust(): Run all mediation estimators on one synthetic dataset
scenario_manifest(): Scenario manifest: truth and parameter ranges for a simulation

Generative texture model

Train and sample from the hybrid GAN + Gaussian-copula texture model that calibrates synthetic data to a cohort.

train_gan_on_real_data(): Train a generative texture model on real data
train_feature_texture(): Train a feature-level texture model for the mediator panel
sample_texture(): Draw synthetic base rows from a trained texture model
sample_feature_texture(): Draw synthetic feature vectors from a trained feature texture model
check_torch_setup(): Check whether a working torch installation is available

Plotting

Visualization functions for diagnostics, sensitivity, and results.

plot_bias(): Plot absolute bias vs a swept parameter
plot_bias_boxplot(): Grouped boxplots of per-seed bias across a parameter sweep
plot_bias_distribution(): Baseline bias distribution (single-setting hero plot)
plot_degradation_surface(): Degradation surface figure
plot_estimate_distribution(): Boxplot of estimate distributions from run_simulation()
plot_estimated_vs_true(): Plot estimated effect vs true effect
plot_estimator_benchmark(): Estimator benchmark figure
plot_feature_correlation_sweep(): Feature correlation sweep figure
plot_gan_diagnostics(): Compare real vs synthetic marginals from a trained generator
plot_instrument_strength_sweep(): Instrument strength sweep figure
plot_model_selection(): Model selection workflow figure
plot_nc_coverage_comparison(): NC coverage comparison figure
plot_nc_validity_diagnostics(): NC validity diagnostics figure (5 panels)
plot_pleiotropy_sweep(): Pleiotropy sweep figure
plot_power(): Plot detection rate (power) vs a swept parameter
plot_prospective_analysis(): Prospective analysis figure
plot_sensitivity_heatmap(): Heatmap of a sensitivity metric across the scenario grid
plot_type1_boxplot(): Type I error boxplot per method
plot_type1_error(): Bar chart of Type I error rates
plot_type1_vs_conf(): Type I error rate vs confounding strength

Data constants

Package data constants for estimator display (colours and ordering).

iconic_method_colors: Colour palette for iconic methods
iconic_method_order: Default method display order

S3 print & summary methods

Print and summary methods for the result objects returned above.

print(<iconic_confounding>): Print method for iconic_confounding objects
print(<iconic_data>): Print method for iconic_data objects
print(<iconic_diagnosis>): Print method for iconic_diagnosis objects
print(<iconic_feature_texture>): Print method for iconic_feature_texture objects
print(<iconic_gan>): Print method for iconic_gan objects
print(<iconic_prospect>): Print method for iconic_prospect objects
print(<iconic_recommendation>): Print method for iconic_recommendation objects
print(<iconic_sensitivity>): Print method for iconic_sensitivity objects
summary(<iconic_diagnosis>): Summary method for iconic_diagnosis objects
summary(<iconic_prospect>): Summary method for iconic_prospect objects
summary(<iconic_recommendation>): Summary method for iconic_recommendation objects
summary(<iconic_sensitivity>): Summary method for iconic_sensitivity objects