Post-hoc causal-configuration probabilities for one or more SuSiE-class fits — susie_post_outcome

Runs one of two complementary post-hoc analyses, selected by method: "susiex" (default) for the SuSiEx $2^N$ combinatorial enumeration, reporting posterior probabilities over binary causality patterns across the $N$ input traits; "coloc_pairwise" for the coloc pairwise ABF, reporting the five colocalisation hypothesis posteriors (H0/H1/H2/H3/H4) for every pair of traits. To get both views, call the function twice and combine.

Usage

susie_post_outcome_configuration(
  input,
  by = c("fit", "outcome"),
  outcome_names = NULL,
  method = c("susiex", "coloc_pairwise"),
  prob_thresh = 0.8,
  single_effect_lfsr_cutoff = 0.05,
  cs_only = TRUE,
  p1 = 1e-04,
  p2 = 1e-04,
  p12 = 5e-06,
  ...
)

Arguments

input: A single fit of class susie, mvsusie, or mfsusie, OR a list of such fits.
by: Either "fit" (one trait per input fit; default) or "outcome" (multi-output fits expand into per-outcome traits).
outcome_names: Optional character vector of trait-view names. If NULL, names are taken from the input list when available, otherwise trait_1, trait_2, ... are used. If provided, its length must match the number of trait views after applying by.
method: Character scalar; one of "susiex" (default), or "coloc_pairwise". Pick the analysis to run; for both analyses, call the function twice.
prob_thresh: Per-trait marginal threshold for the convenience $active flags in the SuSiEx output. Default 0.8.
single_effect_lfsr_cutoff: LFSR threshold used to flag outcome-specific CS evidence when method = "susiex" is applied to one multi-output mvsusie or mfsusie fit. The LFSR is read from fit$lfsr at each CS sentinel SNP. Default 0.05.
cs_only: Logical. If TRUE (default) only enumerate over CSs present in each fit's $sets$cs; if FALSE loop over all L rows of $alpha. Either way, effects whose entire alpha row is zero are skipped. When TRUE, trait views without credible sets are skipped with a warning; if fewer than two trait views remain, the function returns NULL.
p1, p2, p12: Coloc per-SNP causal priors: p1 for trait 1 alone, p2 for trait 2 alone, p12 for shared causal. Defaults match coloc::coloc.bf_bf: p1 = p2 = 1e-4, p12 = 5e-6. Only used when "coloc_pairwise" is in method.
...: Currently ignored.

Value

NULL if fewer than two trait views are available for post-hoc analysis; otherwise a list of class "susie_post_outcome_configuration" with exactly one of the following components, depending on method:

$susiex: (when method = "susiex") A list of length equal to the number of CS tuples considered, named config_1, config_2, etc. Each element has components config_probability (binary trait-activation table with a config_prob column) and config_summary (CS-level post-hoc activation summary, with one row per trait). For one multi-output mvsusie or mfsusie fit, both $susiex and $mvsusie are named by CS label, e.g. L1; each $mvsusie element has cs_summary, config_summary, and cs_variant_summary.
$coloc_pairwise: (when method = "coloc_pairwise") A data.frame with one row per (trait1, trait2, l1, l2) combination, columns trait1, trait2, l1, l2, hit1, hit2, PP.H0, PP.H1, PP.H2, PP.H3, PP.H4.

Pretty-print with summary(out).

Details

Two input organizations are supported:

by = "fit": Each input fit contributes a single trait view. Multi-output fits (mvsusie, mfsusie) are kept whole: the trait's per-(CS, SNP) log Bayes factors are the joint composite stored on the fit as lbf_variable. Configuration enumeration loops over the cross-product $L_1 \times \dots \times L_N$ of CS indices.
by = "outcome": Multi-output fits fan out into per-outcome views, each with its own per-(CS, SNP) log Bayes factors read from fit$lbf_variable_outcome (an $L \times J \times R$ or $L \times J \times M$ array). All per-outcome views share the joint fit's PIP matrix and CS list, so the configuration enumeration reduces to a single index $l \in 1..L$. Single-output susie fits pass through unchanged. Requires $lbf_variable_outcome on the fit (set attach_lbf_variable_outcome = TRUE when fitting).

After SuSiE has been fit, the post-hoc step can answer two related questions:

"susiex": SuSiEx $2^N$ activation probabilities for each credible-set tuple. It asks which traits have evidence for a proposed shared CS-level event. In two traits, the both-active state uses same-SNP evidence such as $\sum_j \exp(\ell_{1j}+\ell_{2j})$, where $\ell_{tj}$ is the SNP-level log Bayes factor for trait $t$.
"coloc_pairwise": Pairwise coloc H0-H4 posteriors for every trait pair and CS pair. It asks whether same-SNP evidence is stronger than distinct-causal evidence, represented by terms such as $\sum_{j \ne k}\exp(\ell_{1j}+\ell_{2k})$; this separates H3, two distinct causal variants, from H4, one shared causal variant. Per-SNP log Bayes factors are aligned by variant name when available.

Two-trait example

For two traits and one CS pair, SuSiEx has four activation states: $(0,0)$, $(1,0)$, $(0,1)$, and $(1,1)$. The state $(1,1)$ means both traits are active for the candidate shared event; it does not introduce a separate distinct-causal state.

Coloc has five hypotheses: H0, no causal variant; H1, trait 1 only; H2, trait 2 only; H3, two distinct causal variants; and H4, one shared causal variant. Thus coloc splits the active two-trait case into H3 and H4, whereas SuSiEx represents it as the single activation state $(1,1)$.

The "susiex" output is an $2$-trait post-hoc activation model over CS tuples. The "coloc_pairwise" output is a pairwise colocalisation model over H0-H4 for each CS pair. Both are summaries of already fitted SuSiE-class models; neither refits the single-trait effects.

More generally, in $N$-trait analysis, the difference between SuSiEx-style activation and colocalization is a difference in hypothesis space:

SuSiEx activation space: "susiex" is an $N$-trait post-hoc activation, or meta-analysis-style, model over CS tuples. It enumerates the $2^N$ binary activity patterns and asks which traits participate in a proposed shared event.
Colocalization partition space: A theoretical generalization to $N$-trait colocalization has a larger hypothesis space: inactive traits plus all ways of grouping active traits by shared causal variant, of size Bell($N+1$) (see HyPrColoc, Figure 1). This space asks not only which traits are active, but which active traits share the same causal variant versus distinct causal variants.

References

SuSiEx, Nature Genetics 2024 (combinatorial $2^N$ enumeration). Wallace, PLoS Genetics 2020 (coloc pairwise H0/H1/H2/H3/H4 ABF). Foley et al., Nature Communications 2021 (HyPrColoc; multi-trait colocalisation hypothesis space in Figure 1).