Export a result to a published BED table

Writes fine-mapping results or TWAS weights to a published FunGen-xQTL BED table, bgzipping and tabix-indexing the output when the path ends in .gz / .bgz. The tabular counterpart of exportToVcf: the VCF is one record per variant with the models as samples, while these tables are long-format, one row per published observation.

Usage

exportToBed(x, outputPath, ...)

# S4 method for class 'list'
exportToBed(x, outputPath, ...)

# S4 method for class 'FineMappingResultBase'
exportToBed(
  x,
  outputPath,
  schema = c("topLoci", "fsusie"),
  signalCutoff = 0.025,
  minPurity = NULL,
  coverage = NULL,
  levels = c("wavelet", "trait"),
  columns = NULL,
  extraColumns = NULL
)

# S4 method for class 'TwasWeights'
exportToBed(
  x,
  outputPath,
  coverage = NULL,
  columns = NULL,
  extraColumns = NULL
)

Arguments

x: A QtlFineMappingResult, GwasFineMappingResult or TwasWeights object, or a list of them, to combine first.
outputPath: Output path. A .gz / .bgz extension selects bgzip + tabix (via Rsamtools, so no htslib binary is needed); any other extension writes a plain table.
...: Additional arguments passed to methods.
schema: Fine-mapping results only: which published schema to write, "topLoci" (default) or "fsusie".
signalCutoff: PIP cutoff passed to topLoci (fine-mapping results, "topLoci" schema only). Default 0.025.
minPurity: Optional credible-set purity cutoff passed to topLoci (fine-mapping results, "topLoci" schema only). Default NULL for no purity filter.
coverage: Which credible-set coverage levels to publish, as proportions (c(0.95, 0.5)). NULL (default) publishes every level the input carries. Which levels exist is fixed at FIT time by CredibleSetParam and the stored cs_<n> columns are read rather than recomputed, so this selects a subset and errors – naming what is available – for a level the fit never computed.
levels: "fsusie" schema only: which resolution(s) of the fitted effect to write. fSuSiE carries the same effect twice – "wavelet", the curve on the fit's own grid (fsusieCredibleBand), and "trait", that curve reinterpolated onto the positions of the traits the fit ran over (fsusieTraitEffects). They are complementary, so both are written by default; naming one drops the other's columns, leaving a strict subset of the full table.
columns: Which of the SOURCE view's own variant-level columns to append after the published schema. NULL (default) appends none; "all" appends every column the view carries that the schema does not already write; a character vector appends exactly those. The published columns always lead, so adding to them never moves an existing one. The fine-mapping views carry a long tail worth asking for (grange_start / grange_end, the legacy gene / event aliases, and whatever a custom build added); a TwasWeights element carries only its alleles and weight, so there is nothing further to add unless the collection was built by hand. Not accepted by the "performance" schema, which has no variant axis.
extraColumns: Optional NAMED list of trailing columns to append after the published schema. Each element is either length 1 (recycled across every row) or one value per row. For fields no S4 object can know – the legacy top-loci BED's block_id, parsed from the source filename, is the motivating case. Names that collide with a published column are an error rather than a silent overwrite.

Value

outputPath, invisibly.

Details

A TwasWeights writes one table, a row per (variant, weight column). A fine-mapping result offers two, selected with schema:

"topLoci": (default) the posterior view joined to the marginal one, a row per (variant, context).
"fsusie": the functional view, a row per (context, credible set), carrying the fitted curve at both resolutions levels selects.

Every table identifies the fit a row came from – study_ID, gene_ID, event_ID and (where it spans methods) method – because these collections are keyed by that tuple and several of them are routinely folded into one output.

Cross-validation results are NOT exported, in any schema. They describe how a model scored on held-out FOLDS; nothing about them is per-variant, and a published file has no data-secure way to express anything fold-level, because fold membership is sample-level information and sample names can be protected. They remain on the object, where cvResult returns them and the caller tabulates whatever they need. For the same reason an export REQUIRES the full-data fit: a cross-validation-only collection (what twasWeightsPipeline(fitFullData = FALSE) produces) is refused rather than written out empty.

Examples

data(qtlFineMappingExample)
exportToBed(qtlFineMappingExample, tempfile(fileext = ".bed"))
exportToBed(
    qtlFineMappingExample, tempfile(fileext = ".bed"),
    schema = "topLoci", columns = "all"
)
data(twasWeightsExample)
exportToBed(twasWeightsExample, tempfile(fileext = ".bed"))
#> exportToBed: skipping 2 fine-mapping-derived row(s) (susie, susie_inf). Those weights are the fine-mapping posterior re-expressed -- export the fine-mapping result instead, which carries the posterior, its standard error and the credible sets.