Skip to contents

Write a result to VCF/BCF

Source: R/AllGenerics.R, R/resultWriters.R
writeGwasVcf.Rd

Writes GWAS summary statistics, fine-mapping results or TWAS weights to a GWAS-VCF-style file: one record per variant, one SAMPLE per study / fitted model, and the per-variant statistics as FORMAT fields. The file is written with VariantAnnotation's writeVcf, so that package must be installed. Supports bgzipped VCF (.vcf.gz/.vcf.bgz); BCF (.bcf) additionally needs a working Rsamtools::asBcf(), which recent Rsamtools releases disable, so prefer .vcf.bgz.

Usage

writeGwasVcf(obj, filename, ...)

# S4 method for class 'list'
writeGwasVcf(obj, filename, sampleName = NULL, ...)

# S4 method for class 'GwasSumStats'
writeGwasVcf(obj, filename, sampleName = NULL, studyName = NULL)

# S4 method for class 'FineMappingResultBase'
writeGwasVcf(
  obj,
  filename,
  sampleName = NULL,
  studyName = NULL,
  context = NULL,
  trait = NULL,
  method = NULL,
  splitByContext = FALSE,
  splitByTrait = FALSE,
  splitByBlock = FALSE
)

# S4 method for class 'TwasWeights'
writeGwasVcf(
  obj,
  filename,
  sampleName = NULL,
  studyName = NULL,
  context = NULL,
  trait = NULL,
  method = NULL
)

Arguments

obj

A GwasSumStats, QtlFineMappingResult, GwasFineMappingResult or TwasWeights object, or a list of fine-mapping results or of TwasWeights objects to combine first.

filename

File path for output. Extension determines format: .vcf.gz or .vcf.bgz for bgzipped VCF, .bcf for BCF, .vcf for uncompressed VCF.

...

Additional arguments passed to methods.

sampleName

Name(s) for the VCF sample column(s). Default NULL derives them from the object's identity tuple.

studyName

Character or NULL. Restrict the written records to this study; NULL includes all studies.

context

Character or NULL. Restrict the written records to this context; NULL includes all contexts.

trait

Character or NULL. Restrict the written records to this trait; NULL includes all traits.

method

Character or NULL. Restrict the written records to this method; NULL includes all methods.

splitByContext

Logical. If TRUE, write one VCF per context. Default FALSE.

splitByTrait

Logical. If TRUE, write one VCF per trait. Default FALSE.

splitByBlock

Logical. GwasFineMappingResult only: if TRUE, write one VCF per LD block instead of joining a study's blocks into one file. Default FALSE.

Value

Invisible path(s) to the written file(s).

Details

Which FORMAT fields are written depends on the input:

GwasSumStats

ES / SE / EZ / NS / AF / MAF for one study, whichever its variants carry.

a fine-mapping result

the marginal fields (ES, SE, EZ, LP, NS), the fit's own (AF, WGT, WGTSE, THETA) and the posterior ones (PIP, LBF, LFSR, and a CS/PUR pair per credible-set coverage present).

TwasWeights

WGT, the prediction weight.

Every fit the selectors match becomes a SAMPLE of ONE file: the records are the union of their variants, the FORMAT schema is the union of their fields, and a fit that did not include a variant – or does not report a field – leaves those cells empty. So two methods over a region, or a dozen weight methods for one gene, are compared by reading one file rather than a dozen. Each sample is described in its own ##SAMPLE header line, carrying the fit's identity tuple and how many variants it contributed. Cross-validation results are not written – see writeBed for why – and writing requires the full-data fit.

A GWAS study fine-mapped block by block is ONE fit, so its blocks are joined into one sample. A BID FORMAT field then names each variant's LD block – credible-set indices are numbered within a block, so a set is the (BID, CS) pair – and the per-block header values (block id, analysis window and whether it was given, V, cs_index) are packed in block order, separated by |. readFineMappingResult splits such a sample back into its blocks.

splitByContext / splitByTrait opt out of that and write one file per context / trait, at a path decorated with the axis value, holding the fits that share it. splitByBlock writes one file per LD block of a GWAS result, each holding every fit's part of that block.

See also

writeBed, readFineMappingResult

Examples

data(gwasSumStatsS4Example)
writeGwasVcf(gwasSumStatsS4Example, tempfile(fileext = ".vcf"))