Build an LdScore from an LD reference

Compute per-variant LD scores from an LD reference, block by block, into the LdScore that estimateH2 consumes for method = "gldsc". This is the supported route from an LD reference to an h2 input: LdScore itself is the low-level constructor and expects the scores to have been computed already.

The score is \(\ell_j = \sum_k r^2_{jk}\) within each block, with each term ldsc's unbiased estimate of \(r^2\) (Bulik-Sullivan et al. 2015, ldscore.py): r^2 - (1 - r^2) / (n - 2), where n is the reference panel sample size. A sample \(r^2\) overstates the population value by about (1 - r^2) / (n - 2), and a block sums many of them. A variant's own term stays 1, and negative estimates are kept, as in ldsc. computeLdScores gives the same scores from an LdEigen built on the same reference.

Usage

buildLdScore(
  ldReference,
  ldBlocks = NULL,
  nSamples = NULL,
  inSample = FALSE,
  genome = NA_character_,
  ldScoreWeights = NULL,
  keepLdMatrices = TRUE
)

Arguments

ldReference

The LD reference, block by block: a list of LdMatrix objects, one per LD block (a single LdMatrix is one block), or a genotype panel (see readGenotypes) together with ldBlocks. Blocks are kept in the order given, and that order defines the variant order of the result.

Block structure matters downstream: estimateH2 takes its standard error from a delete-one-block jackknife, so it requires at least two blocks and wants many more.

ldBlocks

With a genotype panel, the LD blocks to cut it into: a GRanges, or a data frame with columns chrom, start and end. Each block's LD is computed from the panel variants inside it; variants outside every block are left out. Not used with LdMatrix blocks.

nSamples

Integer, the number of samples the reference's LD was estimated from. Defaults to a panel's sample count (a stochastic sketch's effective size), or the size the LdMatrix blocks record; required when they record none, and an error when they disagree. It is also the n of the unbiased \(r^2\), and it must exceed 2.

inSample

Logical, whether the reference is the GWAS cohort itself.

genome

Character, genome build. Defaults to the build recorded by the reference's variants.

ldScoreWeights

Optional numeric regression weights, one per variant. Defaults to the conventional \(1/\max(\ell_j, 1)\).

keepLdMatrices

Logical, for LdMatrix blocks: keep each block's LD matrix on the result. TRUE (the default) is required for method = "gldsc" and for annotation-stratified scores, which need each block's LD. FALSE drops them, leaving a scores-only object. A genotype panel is never copied into matrices: the result keeps the panel and reads each block's LD from it when it is needed, so it serves every method either way.

Value

An LdScore over every variant in the reference's blocks.

Examples

panel <- readGenotypes(plink2Prefix = file.path(system.file("extdata",
  "ld_reference", "chr22", package = "pecotmr"),
  "protocol_example.LD.chr22"))
blocks <- data.frame(chrom = "chr22", start = c(10000000, 15000001),
  end = c(15000000, 19000000))
ldScore <- buildLdScore(panel, ldBlocks = blocks, genome = "hg38")
ldScore
#> LdScore: 175 SNPs, 1 LD score columns
#>   Block LD: read from the genotype panel when needed
#>   Reference N: 57, In-sample: FALSE
head(S4Vectors::mcols(ldScore)$ldScores)
#>        base_l2
#> [1,] 1.2453567
#> [2,] 1.3216232
#> [3,] 0.9576850
#> [4,] 1.1357775
#> [5,] 0.8809636
#> [6,] 1.0722234

Usage

Arguments

Value

See also

Examples