Skip to contents

Build the unified top-loci table for one fit and one method

Source: R/fineMappingWrappers.R
buildTopLoci.Rd

Returns the per-fit, per-method contribution to the unified top_loci table in the fixed 22-column shape. postprocessFinemappingFits() calls this once per method per fit and row-binds the results into the single top_loci returned by formatFinemappingOutput().

Usage

buildTopLoci(
  fit,
  csTables,
  variantNames,
  sumstats = NULL,
  af = NULL,
  n = NULL,
  method,
  signalCutoff = 0,
  dataY = NULL,
  otherQuantities = NULL,
  region = NULL,
  conditionIdx = NULL,
  fullFit = FALSE,
  fullFitAlphaOnly = TRUE,
  includeAllCs = FALSE
)

Arguments

fit

Fitted SuSiE-family object (must expose alpha, mu, mu2, pip).

csTables

List of CS tables (one per coverage) from computeCsTables().

variantNames

Character vector of variant IDs (chr:pos:A2:A1).

sumstats

Optional marginal-association summary (betahat, sebetahat) filling beta / se.

af

Optional numeric vector of effect-allele frequencies (frequency of the final effect allele / a1 after allele harmonization against the LD/reference variants). Exported directly as the af column. MAF is never exported; derive it from af at filter time. Default NULL -> af = NA_real_.

n

Optional per-variant sample size, one entry per variant, exported as the N column. Used by RSS fine-mapping, where the effective sample size varies by variant. Default NULL -> N falls back to the fit's scalar sample size (the outcome-matrix nrow for individual-level fits, NA otherwise).

method

Method name (e.g. "susie", "susieInf"). Required.

signalCutoff

PIP cutoff for retaining PIP-only (non-CS) variants.

dataY

Optional regional phenotype vector or matrix; nrow(as.matrix(dataY)) fills n, colnames(dataY)[1] fills gene. A list (the RSS list(z = ...) form) carries no sample count: n is left NA for the per-variant n argument to fill.

otherQuantities

Optional list. Default is NULL.

region

Optional "chr:start-end" string. Default is NULL.

conditionIdx

Integer or NULL. Index of the conditioned effect (per-condition output); NULL for the unconditioned fit.

fullFit

Logical. Retain the full fit object on each entry. Default FALSE.

fullFitAlphaOnly

Logical. When retaining the full fit, keep only the per-effect alpha matrix. Default TRUE.

includeAllCs

Logical. Include all credible sets rather than only the top one. Default FALSE.

Value

A data frame in the fixed 22-column shape for this fit and method, or an empty data frame if nothing is retained.

Details

Output columns, in order: #chr, start, end, a1, a2, variant, gene, event, n, af, beta, se, pip, posterior_effect_mean, posterior_effect_se, cs_95, cs_70, cs_50, cs_95_purity, method, grange_start, grange_end.

cs_95 / cs_70 / cs_50 are character strings of the form "<method>_<cs_index>" where each method numbers credible sets independently from 1. Variants retained by the PIP cutoff but not in any credible set at a coverage carry "<method>_0". cs_95_purity is the 0.95-coverage purity for the row's (method, cs_95); rows whose cs_95 is "<method>_0" carry 0.

Row uniqueness is (variant, gene, cs_membership) at the given method; overlapping CS within the same method produces one row per CS.

Examples

data(eqtlRegionExample)
X <- eqtlRegionExample$X[, 1:40]
y <- eqtlRegionExample$yRes
fit <- susieR::susie(X, y, L = 5)
#> HINT: nrow(X) = 415 >= 2 * ncol(X) = 80. Consider precomputing sufficient statistics with compute_suff_stat() and fitting with susie_ss() instead -- this avoids holding X in memory at every iteration and lets you reuse XtX across multiple y.
csTables <- computeCsTables(fit, dataX = X, method = "susie")
buildTopLoci(fit = fit, csTables = csTables, variantNames = colnames(X),
  method = "susie", dataY = y)
#> # A tibble: 40 × 27
#>    variant_id     chrom    pos A1    A2        N    af marginal_beta marginal_se
#>    <chr>          <chr>  <int> <chr> <chr> <int> <dbl>         <dbl>       <dbl>
#>  1 chr22:3211978… 22    3.21e7 C     T       415    NA            NA          NA
#>  2 chr22:3211986… 22    3.21e7 G     T       415    NA            NA          NA
#>  3 chr22:3211996… 22    3.21e7 G     T       415    NA            NA          NA
#>  4 chr22:3212005… 22    3.21e7 C     T       415    NA            NA          NA
#>  5 chr22:3212059… 22    3.21e7 G     A       415    NA            NA          NA
#>  6 chr22:3212063… 22    3.21e7 C     T       415    NA            NA          NA
#>  7 chr22:3212093… 22    3.21e7 A     G       415    NA            NA          NA
#>  8 chr22:3212097… 22    3.21e7 G     A       415    NA            NA          NA
#>  9 chr22:3212129… 22    3.21e7 T     C       415    NA            NA          NA
#> 10 chr22:3212149… 22    3.21e7 C     A       415    NA            NA          NA
#> # ℹ 30 more rows
#> # ℹ 18 more variables: marginal_z <dbl>, marginal_p <dbl>, pip <dbl>,
#> #   posterior_mean <dbl>, posterior_sd <dbl>, logBF <dbl>, cs_95 <chr>,
#> #   cs_70 <chr>, cs_50 <chr>, cs_95_purity <dbl>, cs_70_purity <dbl>,
#> #   cs_50_purity <dbl>, within_cs_pip <dbl>, method <chr>, gene <chr>,
#> #   event <chr>, grange_start <int>, grange_end <int>