iconic identifies natural direct and indirect effects
(NDE/NIE) in observational omics data by combining genetic
instruments (for the exposure and, optionally, the mediator) with
negative controls that proxy the unmeasured confounders. In
practice these inputs come from external resources: GWAS summary
statistics for exposure instruments, cis-eQTL scans or
transcriptome-wide association study (TWAS) weights for mediator
instruments, and high-dimensional omics panels (for example DNA
methylation) for negative-control construction.
This vignette demonstrates the helper functions that bridge those
external resources into an iconic_data object:
qc_gwas_sumstats(), build_prs_ldpred2(),
score_pgs_panel(), and
check_instrument_strength() for exposure instruments;call_cis_eqtls() and
build_mediator_instruments() for mediator instruments;beta_to_m(), residualize_matrix(),
build_w_pcs(), and apply_fusion_weights() for
negative-control panel construction;as_iconic_data() for importing a
MultiAssayExperiment (or a single
SummarizedExperiment) directly.Genomic coordinates are handled with Bioconductor’s
GenomicRanges: gene models and variant positions can be
supplied as GRanges, or carried in the
rowRanges() of a
RangedSummarizedExperiment.
All examples use small simulated inputs so the vignette builds quickly; on real data the same calls apply unchanged.
iconic is being submitted to Bioconductor. Once
accepted, install the release version with:
if (!requireNamespace("BiocManager", quietly = TRUE))
install.packages("BiocManager")
BiocManager::install("iconic")The development version is available from GitHub:
qc_gwas_sumstats() standardises the column names of a
GWAS summary statistics table (recognising common aliases such as
chromosome/base_pair_location/effect_allele),
and applies the usual filters: missing values, extreme effect sizes,
strand-ambiguous A/T and C/G variants, and the standard-deviation-ratio
check that compares the implied phenotypic variance of each variant
against the bulk distribution.
ss <- data.frame(
chromosome = 1, base_pair_location = 1000 + 0:9 * 1000L,
effect_allele = rep(c("A", "C"), 5), other_allele = rep(c("G", "T"), 5),
beta = rnorm(10, 0, 0.05), standard_error = 0.01,
effect_allele_frequency = runif(10, 0.1, 0.5)
)
out <- qc_gwas_sumstats(ss, n_eff = 50000)
out$qc#> n_input dropped_missing dropped_extreme_beta dropped_ambiguous
#> 1 10 0 0 0
#> dropped_sd_ratio n_output
#> 1 0 10
When the bigsnpr package is available,
build_prs_ldpred2() matches the summary statistics to an LD
reference panel, runs LDpred2-auto (with a moment-estimator fallback for
the heritability), filters out non-convergent chains, and can optionally
score a target genotype panel.
# Tiny fake genotype panel standing in for an LD reference
# (snp_fake genotypes are all-missing mocks; fill with random dosages)
fake <- bigsnpr::snp_fake(100, 500)
fake$genotypes[] <- rbinom(100 * 500, 2, 0.3)
fake$map$chromosome <- 1L
fake$map$physical.pos <- sort(sample(1:1e6, 500))
ss <- data.frame(
chr = fake$map$chromosome, pos = fake$map$physical.pos,
a0 = fake$map$allele2, a1 = fake$map$allele1,
beta = rnorm(500, 0, 0.05), beta_se = 0.02, n_eff = 20000
)
prs <- build_prs_ldpred2(ss, ld_ref = fake, n_chains = 3,
burn_in = 50, num_iter = 50, verbose = FALSE)
str(prs$beta)#> 'data.frame': 500 obs. of 5 variables:
#> $ chr : chr "chr1" "chr1" "chr1" "chr1" ...
#> $ pos : int 641 2214 3291 3328 4408 5202 16397 18023 18235 19677 ...
#> $ a0 : chr "C" "T" "C" "C" ...
#> $ a1 : chr "T" "C" "T" "T" ...
#> $ beta: num -0.01351 -0.01108 -0.02115 0.00702 0.00673 ...
On real data the chain-convergence filter and the sd-ratio QC do the heavy lifting; on this tiny fake panel the warning about non-convergent chains is expected.
If you already have effect weights (for example from the PGS Catalog
or a published score), score_pgs_panel() applies them to a
dosage matrix directly, matching variants by
chr:pos:ref:alt key with automatic strand-flip
handling.
dos <- matrix(rbinom(4 * 50, 2, 0.3), nrow = 4,
dimnames = list(c("1:100:A:G", "1:200:C:T",
"1:300:G:A", "2:400:T:C"),
paste0("S", 1:50)))
wts <- data.frame(chr = c(1, 1, 2), pos = c(100, 300, 400),
a1 = c("A", "G", "T"), a0 = c("G", "A", "C"),
weight = c(0.1, -0.2, 0.05))
out <- score_pgs_panel(wts, dos)
head(out$score)#> S1 S2 S3 S4 S5 S6
#> 0.66042273 -2.06296996 -0.02042545 0.31999864 -0.70127362 -1.38212179
Whatever the source of the instrument, check the first-stage partial F-statistic before relying on it. The conventional rule of thumb is F >= 10.
n <- 300
G <- rnorm(n)
X <- 0.3 * G + rnorm(n)
pcs <- matrix(rnorm(n * 3), n, 3, dimnames = list(NULL, paste0("PC", 1:3)))
check_instrument_strength(G, X, covariates = pcs)#> $F
#> [1] 24.52549
#>
#> $df1
#> [1] 1
#>
#> $df2
#> [1] 295
#>
#> $pvalue
#> [1] 1.236496e-06
#>
#> $partial_r2
#> [1] 0.07675598
#>
#> $n
#> [1] 300
#>
#> $weak
#> [1] FALSE
call_cis_eqtls() residualises expression and genotypes
on covariates (FWL) and runs a per-gene cis scan with Benjamini-Hochberg
correction within gene. Cis variants are found with
GenomicRanges::findOverlaps() between variant positions and
windows of cis_dist bp around each gene’s transcription
start site (TSS; the strand-aware 5’ end of the gene model).
The most natural inputs are RangedSummarizedExperiments:
an expression object whose rowRanges() are the gene models,
and a dosage object whose rowRanges() are the variant
positions. Chromosome naming styles are harmonised before overlapping,
so UCSC-style ("chr1") gene annotation and
Ensembl/PLINK-style ("1") genotypes can be combined
directly.
library(GenomicRanges)
library(SummarizedExperiment)
set.seed(7)
n <- 80
dos <- matrix(rbinom(200 * n, 2, 0.3), nrow = 200,
dimnames = list(paste0("1:", 1:200, ":A:G"), NULL))
expr <- matrix(rnorm(20 * n), nrow = 20,
dimnames = list(paste0("Gene", 1:20), NULL))
expr[1, ] <- expr[1, ] + 0.5 * dos[5, ] # one true cis-eQTL
# Gene models (UCSC style) and variant positions (Ensembl style)
genes <- GRanges("chr1", IRanges(start = seq(1, 191, by = 10), width = 5),
strand = "+")
names(genes) <- rownames(expr)
variants <- GRanges("1", IRanges(start = 1:200, width = 1))
names(variants) <- rownames(dos)
rse_expr <- SummarizedExperiment(assays = list(expr = expr),
rowRanges = genes)
rse_geno <- SummarizedExperiment(assays = list(dosage = dos),
rowRanges = variants)
hits <- call_cis_eqtls(rse_expr, rse_geno, cis_dist = 20)
head(hits$best)#> gene snp beta se t p q
#> 1 Gene1 1:5:A:G 0.6181967 0.1640093 3.769278 0.0003165763 0.006648103
#> 2 Gene10 1:74:A:G -0.4362906 0.1768633 -2.466824 0.0158241401 0.504412540
#> 3 Gene11 1:92:A:G -0.3887910 0.1881792 -2.066068 0.0421420269 0.800644121
#> 4 Gene12 1:125:A:G -0.3453209 0.1819631 -1.897753 0.0614287383 0.754174506
#> 5 Gene13 1:125:A:G 0.3883823 0.1641637 2.365823 0.0204733125 0.465017272
#> 6 Gene14 1:122:A:G -0.3436106 0.1642469 -2.092037 0.0396884248 0.636760165
#> pass
#> 1 TRUE
#> 2 FALSE
#> 3 FALSE
#> 4 FALSE
#> 5 FALSE
#> 6 FALSE
Plain matrices with GRanges coordinates, or with the
legacy data.frame coordinates
(gene/chr/tss and
snp/chr/pos columns), give
identical results:
gp <- data.frame(gene = names(genes), chr = "1", tss = start(genes))
sp <- data.frame(snp = names(variants), chr = "1", pos = start(variants))
hits_df <- call_cis_eqtls(expr, dos, gp, sp, cis_dist = 20)
identical(hits$best, hits_df$best)#> [1] TRUE
build_mediator_instruments() fits an elastic-net
cis-prediction model per gene (via glmnet), keeps genes
whose cross-validated out-of-fold prediction passes quality gates, and
returns the predicted mediator matrix Gm in the genes x
samples orientation expected by iconic_data().
set.seed(42)
n <- 150; p <- 80
dos <- matrix(rbinom(p * n, 2, 0.3), nrow = p,
dimnames = list(paste0("1:", 1:p, ":A:G"),
paste0("S", 1:n)))
expr <- matrix(rnorm(4 * n), nrow = 4,
dimnames = list(paste0("Gene", 1:4), paste0("S", 1:n)))
expr[1, ] <- expr[1, ] + 0.9 * scale(dos[5, ]) + 0.9 * scale(dos[15, ])
gene_tss <- GRanges("1", IRanges(start = c(5, 25, 45, 65), width = 1))
names(gene_tss) <- rownames(expr)
snp_pos <- GRanges("1", IRanges(start = 1:p, width = 1))
names(snp_pos) <- rownames(dos)
fit <- build_mediator_instruments(expr, dos, gene_tss, snp_pos, seed = 1)
fit$qc#> gene n_cis_snps n_nonzero cv_r2 cor_oof cv_p lambda_min
#> 1 Gene1 80 14 0.603994566 0.79234657 7.091717e-34 0.3699326
#> 2 Gene2 80 0 -0.016596372 -0.14033085 9.566256e-01 0.7635586
#> 3 Gene3 80 10 -0.004780502 0.07266243 1.884416e-01 0.4009905
#> 4 Gene4 80 0 -0.014790698 -0.16869659 9.804737e-01 0.5855206
#> pass
#> 1 TRUE
#> 2 FALSE
#> 3 FALSE
#> 4 FALSE
Only Gene1, which carries the two planted cis-eQTLs, passes the cross-validation gates.
Methylation beta values are heteroscedastic at the extremes;
beta_to_m() applies the logit transform with clipping.
b <- matrix(runif(200, 0.01, 0.99), nrow = 20,
dimnames = list(paste0("cg", 1:20), paste0("S", 1:10)))
m <- beta_to_m(b)
range(m)#> [1] -5.243843 6.478614
Before extracting negative-control factors, remove technical covariates (for example batch) from the panel.
x <- matrix(rnorm(100 * 40), nrow = 100,
dimnames = list(paste0("f", 1:100), paste0("S", 1:40)))
batch <- factor(rep(c("A", "B"), each = 20))
cv <- model.matrix(~ batch)[, -1, drop = FALSE]
xr <- residualize_matrix(x, cv)
cor(as.numeric(xr[1, ]), as.numeric(cv))#> [1] -1.581456e-17
build_w_pcs() computes the top principal components of
the (residualised) panel — the W matrix used by the
proximal and COCA estimators.
x <- matrix(rnorm(500 * 60), nrow = 500,
dimnames = list(paste0("f", 1:500), paste0("S", 1:60)))
w <- build_w_pcs(x, n_pcs = 5)
dim(w$W)#> [1] 5 60
#> [1] 3.120368 2.967639 2.823363 2.772791 2.757102
Pre-computed transcriptomic weights (FUSION .wgt.RDat
files, or an in-memory list with the same structure) can be applied to a
dosage panel to build a genetically predicted expression panel, which
can itself serve as a negative-control or mediator-instrument panel.
dos <- matrix(rbinom(10 * 50, 2, 0.3), nrow = 10,
dimnames = list(paste0("rs", 1:10), paste0("S", 1:50)))
mk_wgt <- function(snps, w) {
list(wgt.matrix = matrix(w, ncol = 1, dimnames = list(NULL, "enet")),
snps = data.frame(V2 = snps),
cv.performance = matrix(0.2, nrow = 1,
dimnames = list("rsq", "enet")))
}
wlist <- list(GeneA = mk_wgt(paste0("rs", 1:5), rep(0.1, 5)),
GeneB = mk_wgt(paste0("rs", 6:10), rep(-0.2, 5)))
pos <- data.frame(ID = c("GeneA", "GeneB"), WGT = c("a.wgt.RDat", "b.wgt.RDat"))
out <- apply_fusion_weights(dos, pos = pos, weights = wlist)
dim(out$predicted)#> [1] 2 50
Multi-omic cohorts are best supplied as a
MultiAssayExperiment. Each omics panel is an experiment
(features x samples) and each sample-level variable is a
colData column; as_iconic_data() maps them to
their causal roles by name. Here the outcome is a transcriptome panel,
the mediator is a methylation probe, the negative controls are principal
components of a residualised panel (as returned by
build_w_pcs()), the exposure instrument is a polygenic
score, and the mediator instrument is the genetically predicted mediator
from build_mediator_instruments(). The methylation assay
deliberately covers only 55 of the 60 samples:
as_iconic_data() uses the sampleMap to keep
the 55 samples shared by every experiment used and to align their
order.
library(MultiAssayExperiment)
set.seed(3)
ids <- paste0("S", 1:60)
mk <- function(p, prefix, cols = ids) {
matrix(rnorm(p * length(cols)), p, length(cols),
dimnames = list(paste0(prefix, seq_len(p)), cols))
}
mae <- MultiAssayExperiment(
experiments = ExperimentList(
rna = SummarizedExperiment(assays = list(expr = mk(20, "gene"))),
methyl = SummarizedExperiment(assays = list(m = mk(1, "cg", ids[6:60]))),
nc_pcs = SummarizedExperiment(assays = list(pcs = mk(5, "PC")))
),
colData = DataFrame(bmi = rnorm(60), prs = rnorm(60),
grex_cg1 = rnorm(60), age = rnorm(60),
row.names = ids)
)
data <- as_iconic_data(mae, exposure = "bmi", outcome = "rna",
mediator = "methyl", instrument = "prs",
mediator_instrument = "grex_cg1",
negative_controls = "nc_pcs", covariates = "age")
print(data)#> <iconic_data> 55 samples, 20 outcome features, 1 mediator(s)
#> Available: G (exposure instrument), Gm (mediator instrument), W (negative controls), W1/W2 (path-specific NCs)
#> Covariates: age
#> Mode: mediation
Each role accepts either an experiment name or colData
column name(s), so a small negative-control set can equally be given as
colData columns, and path-specific negative-control panels
are supplied with W1 = / W2 =.
as_MultiAssayExperiment() performs the reverse
conversion.
A single-assay study can be supplied as a
SummarizedExperiment: the selected assay becomes the
outcome panel Y, an optional second assay becomes the
mediator panel M, and colData columns supply
the exposure, instruments, negative controls, covariates, and survival
endpoints.
se <- SummarizedExperiment(
assays = list(expr = matrix(rnorm(20 * 60), 20, 60,
dimnames = list(paste0("gene", 1:20),
paste0("S", 1:60)))),
colData = DataFrame(
bmi = rnorm(60), prs = rnorm(60),
nc1 = rnorm(60), nc2 = rnorm(60), age = rnorm(60))
)
data <- as_iconic_data(se, assay = "expr", exposure = "bmi",
instrument = "prs",
negative_controls = c("nc1", "nc2"),
covariates = "age")
print(data)#> <iconic_data> 60 samples, 20 outcome features
#> Available: G (exposure instrument), W (negative controls), W1/W2 (path-specific NCs)
#> Covariates: age
#> Mode: total effect
From here the standard workflow applies:
iconic_diagnose(), iconic_estimate(), and the
sensitivity machinery described in
vignette("iconic-walkthrough").
#> R version 4.6.2 (2026-10-29)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 26.04.1 LTS
#>
#> Matrix products: default
#> BLAS: /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
#> LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.32.so; LAPACK version 3.12.0
#>
#> locale:
#> [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C
#> [3] LC_TIME=en_US.UTF-8 LC_COLLATE=en_US.UTF-8
#> [5] LC_MONETARY=en_US.UTF-8 LC_MESSAGES=en_US.UTF-8
#> [7] LC_PAPER=en_US.UTF-8 LC_NAME=C
#> [9] LC_ADDRESS=C LC_TELEPHONE=C
#> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
#>
#> time zone: Etc/UTC
#> tzcode source: system (glibc)
#>
#> attached base packages:
#> [1] stats4 stats graphics grDevices utils datasets methods
#> [8] base
#>
#> other attached packages:
#> [1] MultiAssayExperiment_1.39.1 SummarizedExperiment_1.43.0
#> [3] Biobase_2.73.2 MatrixGenerics_1.25.0
#> [5] matrixStats_1.5.0 GenomicRanges_1.65.4
#> [7] Seqinfo_1.3.2 IRanges_2.47.5
#> [9] S4Vectors_0.51.10 BiocGenerics_0.59.13
#> [11] generics_0.1.4 doRNG_1.8.6.3
#> [13] rngtools_1.5.2 foreach_1.5.2
#> [15] iconic_0.99.5 BiocStyle_2.41.0
#>
#> loaded via a namespace (and not attached):
#> [1] shape_1.4.6.1 gtable_0.3.6 xfun_0.62
#> [4] bslib_0.12.0 ggplot2_4.0.4 lattice_0.23-1
#> [7] bigassertr_0.2.0 ps_1.9.3 vctrs_0.7.3
#> [10] tools_4.6.2 parallel_4.6.2 tibble_3.3.1
#> [13] pkgconfig_2.0.3 Matrix_1.7-6 data.table_1.18.6.1
#> [16] RColorBrewer_1.1-3 bigstatsr_1.6.2 S7_0.2.2
#> [19] lifecycle_1.0.5 compiler_4.6.2 farver_2.1.2
#> [22] bigparallelr_0.3.2 codetools_0.2-20 htmltools_0.5.9
#> [25] sys_3.4.3 buildtools_1.0.0 sass_0.4.10
#> [28] glmnet_5.2 yaml_2.3.12 pillar_1.11.1
#> [31] jquerylib_0.1.4 DelayedArray_0.39.8 cachem_1.1.0
#> [34] iterators_1.0.14 abind_1.4-8 tidyselect_1.2.1
#> [37] digest_0.6.39 dplyr_1.2.1 splines_4.6.2
#> [40] maketools_1.3.2 cowplot_1.2.0 fastmap_1.2.0
#> [43] grid_4.6.2 cli_3.6.6 SparseArray_1.13.5
#> [46] magrittr_2.0.5 S4Arrays_1.13.2 survival_3.8-12
#> [49] withr_3.0.3 scales_1.4.0 bigsparser_0.7.3
#> [52] rmarkdown_2.32 XVector_0.53.0 rmio_0.4.0
#> [55] bit_4.6.0 otel_0.3.0 evaluate_1.0.5
#> [58] ff_4.5.3 knitr_1.52 doParallel_1.0.17
#> [61] irlba_2.4.1 rlang_1.3.0 Rcpp_1.1.2
#> [64] glue_1.8.1 BiocManager_1.30.27 jsonlite_2.0.0
#> [67] R6_2.6.1 bigsnpr_1.12.21 flock_0.7