Package: iconic 0.99.5

Sean T. Bresnahan

iconic: Causal Model Selection with Genetic Instruments and Negative Controls

Provides a model selection workflow for causal inference with genetic instruments and negative controls in observational omics data. The package fits eight estimators of the natural direct and indirect effects (NDE/NIE), diagnoses which are valid for the user's data via instrument-strength checks and negative-control validity screens (A1, A2, A2'), stress-tests them against confounding and pleiotropy violations, and recommends the estimator most likely to be unbiased. A hybrid generative texture model (a torch GAN for sample-level structure and a Gaussian copula for the mediator panel) lets the sensitivity analysis mirror the marginal and joint structure of the user's cohort. The modular API comprises iconic_data() to standardize data, iconic_diagnose() to assess estimator eligibility, iconic_estimate() to fit all eligible estimators, iconic_sensitivity() to sweep instrument exogeneity, iconic_recommend() to rank estimators by identification strength and robustness, and iconic_prospect() to plan future studies. infer_confounding() estimates held-fixed confounding parameters from the data. Multi-omic cohorts are supplied as MultiAssayExperiment objects (omics panels as experiments, sample-level exposure, instruments and covariates as colData), and analysis data can be exported back to MultiAssayExperiment. Helper functions construct exposure instruments (polygenic scores from GWAS summary statistics or PGS Catalog scoring files), mediator instruments (GenomicRanges-based cis-eQTL scans and elastic-net predicted-expression composites from RangedSummarizedExperiment or matrix inputs), and negative-control panels (principal components of residualized omics matrices). Time-to-event outcomes are supported on the Cox log-hazard-ratio and restricted-mean-survival-time scales. Binary outcomes are supported on the log-odds-ratio (logistic two-stage predictor-substitution outcome stage) and risk-difference (linear probability model) scales. The torch package is required for the generative texture model (sensitivity and prospective analysis); all other functionality works without it. The methods are described in Bresnahan et al. (2026) <doi:10.64898/2026.08.26.26361466>.

Authors:Sean T. Bresnahan [aut, cre], Charis Xiong [aut]

iconic_0.99.5.tar.gz
iconic_0.99.5.zip(r-4.7-any)iconic_0.99.5.zip(r-4.6-any)iconic_0.99.5.zip(r-4.5-any)
iconic_0.99.5.tgz(r-4.6-any)iconic_0.99.5.tgz(r-4.5-any)
iconic_0.99.5.tar.gz(r-4.7-any)iconic_0.99.5.tar.gz(r-4.6-any)
iconic_0.99.5.tgz(r-4.6-emscripten)
manual.pdf |manual.html✨
DESCRIPTION |NEWS
card.svg |card.png
iconic/json (API)

# Install 'iconic' in R:
install.packages('iconic', repos = c('https://bioc.r-universe.dev', 'https://cloud.r-project.org'))

Bug tracker:https://github.com/sbresnahan/iconic/issues

Pkgdown/docs site:https://seantbresnahan.com

On CRAN:

Conda:

statisticalmethodgeneticsmultiplecomparisonregressiontranscriptomicsrnaseqsurvivalgeneexpressionsnpgeneticvariabilitybioinformaticscausal-inferencecopulaepigenomicsgangenomicsinstrumental-variablesmediation-analysismendelian-randomizationnegative-controlsomicssensitivity-analysis

4.62 score 2 stars 116 exports 85 dependencies

Last updated from:c7ba0c57d6. Checks:1 NOTE, 9 OK. Indexed: yes.

TargetResultTimeFilesSyslog
bioc-checksNOTE216
linux-develOK831
source / vignettesOK370
linux-releaseOK806
macos-releaseOK1043
macos-oldrelOK785
windows-develOK903
windows-releaseOK878
windows-oldrelOK560
wasm-releaseOK136

Exports:analyze_mediation_robustanalyze_methods_parallelanalyze_methods_robustapply_fusion_weightsas_iconic_dataas_MultiAssayExperimentbeta_to_mbuild_mediator_instrumentsbuild_prs_ldpred2build_w_pcscall_cis_eqtlscheck_instrument_strengthcheck_torch_setupcomposite_p_valuefit_cocafit_coca_binfit_coca_mediationfit_coca_mediation_binfit_coca_mediation_survfit_coca_survfit_directfit_direct_binfit_direct_mediationfit_direct_mediation_binfit_direct_mediation_survfit_direct_survfit_iv2slsfit_iv2sls_binfit_iv2sls_mediationfit_iv2sls_mediation_binfit_iv2sls_mediation_survfit_iv2sls_mediation2fit_iv2sls_mediation2_binfit_iv2sls_mediation2_survfit_iv2sls_survfit_pgcfit_pgc_binfit_pgc_mediationfit_pgc_mediation_binfit_pgc_mediation_survfit_pgc_mediation2fit_pgc_mediation2_binfit_pgc_mediation2_survfit_pgc_scalarfit_pgc_scalar_mediationfit_pgc_survfit_unadj_binfit_unadj_mediationfit_unadj_mediation_binfit_unadj_mediation_survfit_unadj_survgan_mediation_sensitivitygan_pleiotropy_sensitivitygan_sensitivitygenerate_toy_dataiconic_dataiconic_diagnoseiconic_estimateiconic_method_colorsiconic_method_ordericonic_prospecticonic_recommendiconic_sensitivityinfer_confoundinglist_nc_modelsload_real_input_datanc_completeness_capturenc_completeness_checknc_cpgnc_independence_checknc_independence_check_gmnc_proxync_support_checknc_validity_checknc_validity_screenplot_biasplot_bias_boxplotplot_bias_distributionplot_degradation_surfaceplot_estimate_distributionplot_estimated_vs_trueplot_estimator_benchmarkplot_feature_correlation_sweepplot_gan_diagnosticsplot_instrument_strength_sweepplot_model_selectionplot_nc_coverage_comparisonplot_nc_validity_diagnosticsplot_pleiotropy_sweepplot_powerplot_prospective_analysisplot_sensitivity_heatmapplot_type1_boxplotplot_type1_errorplot_type1_vs_confqc_gwas_sumstatsrecommend_estimatorresidualize_matrixrun_mediation_simrun_null_mediation_simrun_null_simrun_simulationrun_single_iterationsample_feature_texturesample_texturescenario_manifestscore_pgs_panelsimulate_single_genetic_instrumentsweep_instrument_strengthsweep_mediation_null_by_confsweep_mediation_paramsweep_nc_validitysweep_null_by_confsweep_paramtrain_feature_texturetrain_gan_on_real_data

Dependencies:abindAERbackportsBiobaseBiocBaseUtilsBiocGenericsbootbroomcarcarDataclicolorspacecowplotcpp11DelayedArrayDerivdoBydplyrfarverforecastFormulafracdiffgenericsGenomicRangesggplot2gluegtableIRangesisobandlabelinglatticelifecyclelme4lmtestmagrittrMASSMatrixMatrixGenericsMatrixModelsmatrixStatsmgcvminqamodelrMultiAssayExperimentnlmenloptrnnetnumDerivpbkrtestpillarpkgconfigpurrrquantregR6rbibutilsRColorBrewerRcppRcppArmadilloRcppEigenRdpackreformulasrlangS4ArraysS4VectorsS7sandwichscalesSeqinfoSparseArraySparseMstringistringrSummarizedExperimentsurvivaltibbletidyrtidyselecttimeDateurcautf8vctrsviridisLitewithrXVectorzoo

Diagnosing Estimator Eligibility
Introduction | Installation | What diagnosis checks | A minimal example | Instrument strength | Negative-control validity | Proceeding without instruments or controls | Further reading | Session information

Last update: 2026-11-17
Started: 2026-07-26

ICONIC: Causal Model Selection with Genetic Instruments and Negative Controls
Introduction | Installation | What this package is for | Quick start | Input as a MultiAssayExperiment | Step 1: Diagnose | Step 2: Estimate | Step 3: Train a texture model once | Step 4: Sensitivity analysis | Step 5: Recommend | Step 6: Prospective analysis | Survival outcomes | Putting it together | Further reading | Session information

Last update: 2026-11-17
Started: 2026-07-22

Sensitivity Analysis and Confounding Inference
Introduction | Installation | What sensitivity analysis does | A minimal example | Inferring confounding from the data | Inferred vs. default confounding | Further reading | Session information

Last update: 2026-11-17
Started: 2026-07-26

Survival Outcomes
Introduction | Installation | Time-to-event outcomes in ICONIC | Two effect scales | COCA incompatibility | A minimal example | Cox log-HR scale | RMST scale | Diagnosis and eligibility | Further reading | Session information

Last update: 2026-11-17
Started: 2026-07-26

The Generative Texture Model
Introduction | Installation | Two simulation modes | The hybrid GAN + copula architecture | Training the texture model | Attaching the texture model | When to use each mode | Further reading | Session information

Last update: 2026-11-17
Started: 2026-07-26

Genetic Instruments and Negative Controls from External Data
Introduction | Installation | Exposure instruments from GWAS summary statistics | Quality-control the summary statistics | Build a polygenic score with LDpred2 | Score a panel of pre-computed weights | Verify instrument strength | Mediator instruments | Scan for cis-eQTLs | Build a genetically predicted mediator (GReX-style) | Negative controls from high-dimensional panels | Methylation beta to M-values | Residualise on covariates | Extract negative-control factors with PCA | Apply FUSION-style TWAS weights | Importing Bioconductor containers | MultiAssayExperiment | SummarizedExperiment | Session information

Last update: 2026-11-16
Started: 2026-08-12

Readme and manuals

Help Manual

Help pageTopics
Run all mediation estimators on one synthetic datasetanalyze_mediation_robust
Parallel version of 'analyze_methods_robust()'analyze_methods_parallel
Run all five estimators (plus UNADJ) on one synthetic datasetanalyze_methods_robust
Apply FUSION/TWAS eQTL weights to a dosage matrixapply_fusion_weights
Convert external data containers to iconic_dataas_iconic_data as_iconic_data.default as_iconic_data.MultiAssayExperiment as_iconic_data.SummarizedExperiment
Convert an iconic_data object to a MultiAssayExperimentas_MultiAssayExperiment
Convert methylation beta values to M-valuesbeta_to_m
Build mediator instruments via per-gene elastic netbuild_mediator_instruments
Build an exposure polygenic score with LDpred2-autobuild_prs_ldpred2
Build a negative-control panel from principal componentsbuild_w_pcs
Scan for cis-eQTLs of each genecall_cis_eqtls
Check first-stage instrument strength (partial F)check_instrument_strength
Check whether a working torch installation is availablecheck_torch_setup
Composite null hypothesis test p-valuecomposite_p_value
COCA estimator: Negative-Control Outcome Correction via ratiofit_coca
COCA binary estimator: NOT supported (returns NA)fit_coca_bin
COCA mediation estimator: negative-control calibration of both stagesfit_coca_mediation
COCA binary mediation estimator: NOT supported (returns NA)fit_coca_mediation_bin
COCA survival mediation estimator: NOT supported (returns NA)fit_coca_mediation_surv
COCA survival estimator: NOT supported (returns NA)fit_coca_surv
DIRECT estimator: OLS with instrument and negative-control as covariatesfit_direct
DIRECT binary estimator: logistic / LPM with instrument and NC covariatesfit_direct_bin
DIRECT mediation estimator: OLS with instrument and NC as covariatesfit_direct_mediation
DIRECT binary mediation estimator: logistic / LPM with G and W covariatesfit_direct_mediation_bin
DIRECT survival mediation estimator: Cox / RMST with G and W covariatesfit_direct_mediation_surv
DIRECT survival estimator: Cox / RMST with instrument and NC covariatesfit_direct_surv
IV2SLS estimator: Two-Stage Least Squares with genetic instrumentfit_iv2sls
IV2SLS binary estimator: two-stage predictor substitution with logistic / LPMfit_iv2sls_bin
IV2SLS mediation estimator: instrumented exposure in both stagesfit_iv2sls_mediation
IV2SLS binary mediation estimator: single-instrument 2SPS with logistic / LPMfit_iv2sls_mediation_bin
IV2SLS survival mediation estimator: single-instrument 2SPS with Cox / RMSTfit_iv2sls_mediation_surv
IV2SLS2 mediation estimator: 2-stage MR with instruments for both X and Mfit_iv2sls_mediation2
IV2SLS2 binary mediation estimator: 2-stage MR with logistic / LPM outcomefit_iv2sls_mediation2_bin
IV2SLS2 survival mediation estimator: 2-stage MR with Cox / RMST outcomefit_iv2sls_mediation2_surv
IV2SLS survival estimator: two-stage predictor substitution with Cox / RMSTfit_iv2sls_surv
PGC estimator: Proxy G-Component Correction (matrix bridge)fit_pgc
PGC binary estimator: proxy G-component correction with logistic / LPMfit_pgc_bin
PGC mediation estimator: bridge-function-adjusted natural effects (matrix bridge)fit_pgc_mediation
PGC binary mediation estimator: single-panel bridge with logistic / LPMfit_pgc_mediation_bin
PGC survival mediation estimator: single-panel bridge with Cox / RMSTfit_pgc_mediation_surv
PGC-2 mediation estimator: two-stage proximal mediation with path-specific bridgesfit_pgc_mediation2
PGC2 / PGC2Gm binary mediation estimator: path-specific bridges with logistic / LPMfit_pgc_mediation2_bin
PGC2 / PGC2Gm survival mediation estimator: path-specific bridges with Cox / RMSTfit_pgc_mediation2_surv
PGC estimator: Proxy G-Component Correction (scalar bridge)fit_pgc_scalar
PGC mediation estimator: bridge-function-adjusted natural effects (scalar bridge)fit_pgc_scalar_mediation
PGC survival estimator: proxy G-component correction with Cox / RMSTfit_pgc_surv
UNADJ binary estimator: unadjusted logistic / linear-probability regressionfit_unadj_bin
UNADJ mediation estimator: naive Baron-Kenny stylefit_unadj_mediation
UNADJ binary mediation estimator: naive Baron-Kenny with logistic / LPMfit_unadj_mediation_bin
UNADJ survival mediation estimator: naive Baron-Kenny with Cox / RMSTfit_unadj_mediation_surv
UNADJ survival estimator: unadjusted Cox / RMST regressionfit_unadj_surv
Benchmark mediation estimators across confounding scenariosgan_mediation_sensitivity
Benchmark estimators across pleiotropy and confounding scenariosgan_pleiotropy_sensitivity
Benchmark estimators across confounding scenarios on synthetic datagan_sensitivity
Generate one synthetic dataset (internal)generate_toy_data
Construct a standardized data object for ICONIC model selectioniconic_data
Diagnose data and determine estimator eligibilityiconic_diagnose
Fit all eligible estimators on real dataiconic_estimate
Colour palette for iconic methodsiconic_method_colors
Default method display ordericonic_method_order
Prospective bias-reduction analysis for data without instruments or negative controlsbias_reduction_prospective iconic_prospect
Recommend the best causal estimator for the user's dataiconic_recommend
Sensitivity (degradation) surface and effect-decomposition bias sweepeffect_decomposition_bias_sweep iconic_sensitivity
Infer confounding parameters from the user's datainfer_confounding
List the built-in negative-control modelslist_nc_models
Load and standardise a real multi-omic dataset for GAN trainingload_real_input_data
Covariance-capture completeness testnc_completeness_capture
Check negative-control completeness (dimensional + covariance-capture)nc_completeness_check
CpG-predicted-expression negative-control model (SCENIC case)nc_cpg
Test instrument-independence of negative controls (W _|_ G | C)nc_independence_check
Test mediator-instrument independence of negative controls (W _|_ Gm | C)nc_independence_check_gm
Direct-proxy negative-control modelnc_proxy
Negative-control support/range checknc_support_check
Check negative-control validity across confounding scenariosnc_validity_check
Screen negative controls for exposure dependence (W _|_ X | C)nc_validity_screen
Plot absolute bias vs a swept parameterplot_bias
Grouped boxplots of per-seed bias across a parameter sweepplot_bias_boxplot
Baseline bias distribution (single-setting hero plot)plot_bias_distribution
Degradation surface figureplot_degradation_surface
Boxplot of estimate distributions from run_simulation()plot_estimate_distribution
Plot estimated effect vs true effectplot_estimated_vs_true
Estimator benchmark figureplot_estimator_benchmark
Feature correlation sweep figureplot_feature_correlation_sweep
Compare real vs synthetic marginals from a trained generatorplot_gan_diagnostics
Instrument strength sweep figureplot_instrument_strength_sweep
Model selection workflow figureplot_model_selection
NC coverage comparison figureplot_nc_coverage_comparison
NC validity diagnostics figure (5 panels)plot_nc_validity_diagnostics
Pleiotropy sweep figureplot_pleiotropy_sweep
Plot detection rate (power) vs a swept parameterplot_power
Prospective analysis figureplot_prospective_analysis
Heatmap of a sensitivity metric across the scenario gridplot_sensitivity_heatmap
Type I error boxplot per methodplot_type1_boxplot
Bar chart of Type I error ratesplot_type1_error
Type I error rate vs confounding strengthplot_type1_vs_conf
Print method for iconic_confounding objectsprint.iconic_confounding
Print method for iconic_data objectsprint.iconic_data
Print method for iconic_diagnosis objectsprint.iconic_diagnosis
Print method for iconic_feature_texture objectsprint.iconic_feature_texture
Print method for iconic_gan objectsprint.iconic_gan
Print method for iconic_prospect objectsprint.iconic_prospect
Print method for iconic_recommendation objectsprint.iconic_recommendation
Print method for iconic_sensitivity objectsprint.iconic_sensitivity
Standardize and QC GWAS summary statisticsqc_gwas_sumstats
Recommend the preferred estimator from a sensitivity sweeprecommend_estimator
Residualize a feature matrix on covariatesresidualize_matrix
Run repeated mediation simulations for a single parameter configurationrun_mediation_sim
Run null mediation simulations to estimate Type I error ratesrun_null_mediation_sim
Run null simulations to estimate Type I error ratesrun_null_sim
Run repeated simulations for a single parameter configurationrun_simulation
Generate one synthetic dataset under the generalised SCMrun_single_iteration
Draw synthetic feature vectors from a trained feature texture modelsample_feature_texture
Draw synthetic base rows from a trained texture modelsample_texture
Scenario manifest: truth and parameter ranges for a simulationscenario_manifest
Score a published polygenic-score panel on a dosage matrixscore_pgs_panel
Simulate a single genetic instrumentsimulate_single_genetic_instrument
Summary method for iconic_diagnosis objectssummary.iconic_diagnosis
Summary method for iconic_prospect objectssummary.iconic_prospect
Summary method for iconic_recommendation objectssummary.iconic_recommendation
Summary method for iconic_sensitivity objectssummary.iconic_sensitivity
Sweep instrument strengthsweep_instrument_strength
Sweep mediation Type I error across confounding strength levelssweep_mediation_null_by_conf
Sweep a single mediation simulation parameter across a gridsweep_mediation_param
Sweep negative-control validity diagnosticssweep_nc_validity
Sweep Type I error rate across confounding strength levelssweep_null_by_conf
Sweep a single simulation parameter across a gridsweep_param
Train a feature-level texture model for the mediator paneltrain_feature_texture
Train a generative texture model on real datatrain_gan_on_real_data