Read a Genotype Panel

Read genotype data (VCF, plink1, plink2, GDS or BGEN) as a RangedSummarizedExperiment: variants in rowRanges, samples in colData, and dosages in a DelayedArray assay that reads from the file only when something touches it. Nothing is read here beyond the variant and sample metadata.

The panel is the same shape a QtlDataset uses for its genotypes and the same shape a collection carries as its ldReference, so the Bioconductor and tidy surfaces apply throughout: subset it with panel[i, j], ask rowRanges() for the variants, colnames() for the samples, and hand it to computeLd.

A panel that is not one self-describing file is named by keyword instead of by path: pass plink1Prefix or plink2Prefix for a triplet stem, bed/bim/fam or pgen/pvar/psam for explicit triplet paths, genoMeta for a one-file-per-chromosome panel (optionally narrowed with chroms), or ldMeta plus region to resolve a block out of an LD-meta table. Exactly one source may be given.

Usage

readGenotypes(path, format = NULL, ...)

# S4 method for class 'character'
readGenotypes(path, format = NULL, vcfArgs = list())

# S4 method for class 'missing'
readGenotypes(
  path,
  plink1Prefix = NULL,
  plink2Prefix = NULL,
  bed = NULL,
  bim = NULL,
  fam = NULL,
  pgen = NULL,
  pvar = NULL,
  psam = NULL,
  ldMeta = NULL,
  region = NULL,
  genoMeta = NULL,
  chroms = NULL,
  format = NULL,
  vcfArgs = list()
)

Arguments

path

Character, path to a single self-describing genotype file (.vcf.gz, .vcf.bgz, .gds or .bgen). Omit it when naming the panel by one of the keyword sources described above.

A VCF must be bgzip-compressed with its tabix index (.tbi) beside it, through which its records are read a block at a time; a BCF cannot be read. Its dosage is its FORMAT/DS when the header declares one, else the copies of the ALT allele in each GT call, a call with a missing allele being missing.

A GDS file is SNPRelate's, whose genotype codes count the first of each SNP's two alleles (A1), or SeqArray's, read like a VCF: its FORMAT/DS when it stores one, else its genotype calls.

A BGEN file of any layout (BGEN 1.1, 1.2 or 1.3), phased or unphased and of any ploidy, needs its .bgi index beside it and its sample ids in the file or in a .sample file beside it. Its dosage is the expected count of A1, from 0 to the sample's ploidy.

A PLINK1 fileset, a .bed with its .bim and .fam beside it, is read through the PlinkMatrix package: its dosage counts each variant's A1 allele, the .bim's fifth column, a missing call being missing. Its samples are named by the .fam's individual ids.

In a VCF, a SeqArray GDS or a BGEN file, A2 is each record's first (REF) allele, and a record with more than one other allele is read, with a warning, as one variant per other allele, each counting its own.

format

Character, one of "vcf", "plink1", "plink2", "gds", "bgen". If NULL, inferred from file extension.

...

The keyword source arguments described above, plus any further arguments forwarded to the format-specific reader.

vcfArgs

Optional named list of arguments forwarded to VariantAnnotation::readVcf when a VCF's records are read (its genotypes are read a block at a time, as they are needed).

plink1Prefix, plink2Prefix

Character. Stem of a plink1 (.bed/.bim/.fam) or plink2 (.pgen/.pvar/.psam) triplet, without the extension.

bed, bim, fam

Character. Explicit paths to the three files of a plink1 triplet, when they do not share a stem.

pgen, pvar, psam

Character. Explicit paths to the three files of a plink2 triplet, when they do not share a stem.

ldMeta

Path to an LD-meta TSV (columns chrom, start, end, path). Requires region: the row covering it is resolved and the file it names is read with the matching backend.

region

Region to resolve out of ldMeta: a "chr:start-end" string, or a one-row data.frame with chrom, start, end.

genoMeta

One-file-per-chromosome specification: a path to a #chr,path meta file, or a named character vector (names = chromosomes, values = payload paths / prefixes). Every file must be of one format and hold the same samples in the same order.

chroms

Optional character vector of chromosomes. Only the genoMeta shards whose chromosome is listed are read; chromosome labels are compared canonically. Meaningful only with genoMeta.

Value

A RangedSummarizedExperiment of variants x samples.

Examples

panel <- readGenotypes(
  system.file("extdata", "toy_ref.bed", package = "pecotmr")
)
dim(panel)
#> [1] 17421   165
head(rownames(panel))
#> [1] "rs11089128" "rs7288972"  "rs11167319" "rs8138488"  "rs2186521" 
#> [6] "rs2027649" 

# The same panel named by its PLINK1 stem rather than by a file.
stem <- sub("\\.bed$", "", system.file(
  "extdata", "toy_ref.bed",
  package = "pecotmr"
))
dim(readGenotypes(plink1Prefix = stem))
#> [1] 17421   165

Usage

Arguments

Value

See also

Examples