Read A Published Fine-Mapping Result

Rebuild a QtlFineMappingResult or GwasFineMappingResult from a file exportToBed or exportToVcf wrote – or from any file in the same vocabulary, which is what makes this the way into pecotmr for results produced elsewhere.

A merged table holding several (study, context, trait, method) tuples reads back as a multi-row collection, one row per tuple. Which class is returned follows the axes the file has: a result with a context or a trait is a QTL result, one without is a GWAS result.

Usage

readFineMappingResult(
  path,
  region = NULL,
  format = c("auto", "bed", "vcf"),
  studyName = NULL,
  context = NULL,
  trait = NULL,
  method = NULL,
  dataType = NULL,
  weightStandardized = NULL,
  sampleSelect = NULL,
  priorVariance = NULL
)

Arguments

path: Path to the published file. Bgzipped and tabix-indexed files can be read by region.
region: Optional region to restrict the read to – a "chr:start-end" string, a GRanges, or a one-row data.frame with chrom/start/end. Ignored with a warning when the file is not tabix-indexed.
format: "auto" (default) reads a .vcf / .bcf path as a VCF and anything else as a published table; "bed" / "vcf" say so explicitly for a file named otherwise.
studyName, context, trait, method: Identity values for a file that did not record them. Each FILLS IN the corresponding column when the file lacks it; a value that disagrees with what the file does record is an error rather than a silent override.
dataType: Optional assay / modality label, same fill-in rule.
weightStandardized: Whether the published posterior effect (WGT) is on the standardized genotype scale. Required when the file publishes WGT without weight_standardized: the scale is not recoverable from the weights, since converting between the two rescales every variant by its own allele-frequency-dependent factor.
sampleSelect: For a multi-sample VCF, which samples to read. Each sample is one fitted model. Defaults to all of them.
priorVariance: Opt-in Wakefield prior variance (W) for deriving per-variant log Bayes factors from z when the file has no LBF. These are an approximation under a prior you chose, not susie's lbf_variable, so nothing derives them unasked.

Value

A QtlFineMappingResult or GwasFineMappingResult.

What is required, and what is not

Only what the class cannot exist without: variant ids that encode coordinates (or the #chr / start / end / REF / ALT columns to build them from) and a PIP column. Everything else is optional, because each consumer needs a different few columns – Mendelian randomization the marginal effect and its standard error, colocalization the log Bayes factors – and a file converted from another tool will have some and not others. A consumer reached without what it needs says which column is missing.

The fit itself is not published. A VCF's ##SAMPLE header records the two per-effect quantities that no per-variant column could hold – the prior variances V and the credible sets' cs_index – and those are restored as a partial susieFit; a BED carries neither. Anything needing the posterior matrices (colocalization's LBF path) wants the LBF columns, not the fit.

What a round trip changes

Every published quantity comes back identical, in either format. Three things are not identities:

exportToBed() publishes the filtered top-loci table, so a default export holds the variants that passed signalCutoff / minPurity rather than every variant of the fit. Export with signalCutoff = 0 for the whole table.
Credible-set membership comes back as NA where the fit recorded the "<method>_0" not-captured sentinel. Both formats publish an integer index, and NA is what every reader of the column already treats as "in no credible set".
data_source and weight_standardized are populated on the way back – the writer derives the first and the reader is told the second – where a fit predating them left them empty.

Examples

data(qtlFineMappingExample)
path <- file.path(tempdir(), "top_loci.bed")
exportToBed(qtlFineMappingExample, path)
# This fit predates the provenance columns, so its published table does
# not say which genotype scale its posterior effects are on -- the reader
# will not guess.
readFineMappingResult(path, weightStandardized = TRUE)
#> QtlFineMappingResult: 1 entries
#>   1 studies, 1 contexts, 1 traits, 1 methods
#>   LD reference: NULL (individual-level fit)