Skip to contents

Generate gene sets conditional on known causal SNPs

Source: R/gsim_gene_sets.R
gsim_gene_sets.Rd

Construct controlled gene-set compositions for prioritization experiments. A gene is causal when at least one supplied causal SNP maps to it. This is structural truth, not a significance or enrichment label. No SNP effects, phenotypes, or enrichment statistics are generated or modified.

Usage

gsim_gene_sets(
  snp_gene_map,
  causal_snps,
  set_size,
  n_causal,
  n_sets = 1L,
  seed = NULL
)

Arguments

snp_gene_map

Data frame with character snp and gene columns. IDs must be nonmissing and nonempty and are matched exactly. Duplicate pairs are removed; a SNP may map to multiple genes. Represent intergenic SNPs by absent mappings, not the reserved gene label "intergenic". All unique mapped genes form the universe; genes with no mapped SNPs cannot be represented by this interface. Extra columns are ignored.

causal_snps

Unique character vector of known causal SNP IDs, normally simulation$causal_rsids. character(0) permits all-null experiments. IDs absent from the map are returned and produce a concise warning.

set_size

Positive integer counts of genes per set.

n_causal

Nonnegative integer counts of causal genes per set, no larger than set_size. Equal-length vectors define paired scenarios; either scalar may be broadcast. Other length mismatches and infeasible pool sizes are errors. There is no implicit Cartesian product.

n_sets

One positive integer: replicates per scenario.

seed

Optional seed, passed to set.seed() at entry as in gsim(). The global RNG state is advanced, not restored. NULL uses the current RNG stream. Reproducibility assumes the same R RNG kind and version.

Value

A serializable ordinary list:

sets

Named list of unique gene-ID vectors.

membership

Data frame with set_id, gene, and logical causal.

truth

One row per set: set_id, integer scenario and replicate, requested_size, requested_n_causal, realized_size, realized_n_causal, and causal_fraction.

genes

Canonical gene, logical causal, and integer n_snps and n_causal_snps, counting unique SNPs per gene.

unmapped_causal_snps

Canonical causal SNP IDs absent from the map.

settings

Seed, paired scenarios, n_sets, and ordering, sampling, overlap and RNG semantics.

Details

Genes are sorted in UTF-8 radix order before sampling. Each set samples uniformly without replacement from the causal pool, then from the noncausal pool; its combined members are returned in canonical order. Pools are reused across sets, so natural overlap and identical replicates are allowed. Mapping-row and causal-SNP order do not affect seeded results. Set IDs are scenario_<i>_replicate_<j>, in scenario-major order.

Storage scales with mappings, genes, scenarios, and generated memberships; no dense gene-by-set or SNP-by-set matrix is allocated. If deriving SNP memberships downstream, deduplicate shared SNPs within each set. Multiple annotations must never multiply a SNP's supplied effect.

References

Gholipourshahraki et al. (2024). Evaluation of Bayesian Linear Regression models for gene set prioritization in complex diseases. PLoS Genetics 20(11): e1011463. doi:10.1371/journal.pgen.1011463 .

Examples

mapping <- data.frame(snp = paste0("s", 1:6), gene = paste0("g", 1:6))
sets <- gsim_gene_sets(mapping, c("s1", "s2"), set_size = 3,
                       n_causal = 0:2, n_sets = 2, seed = 41)
sets$truth