Create an LD loader for on-demand block-wise LD retrieval

Constructs a loader function that retrieves per-block LD matrices on demand. This avoids loading all blocks into memory simultaneously, which is critical for genome-wide analyses with hundreds of blocks.

Usage

ldLoader(
  rList = NULL,
  xList = NULL,
  ldMetaPath = NULL,
  regions = NULL,
  ldInfo = NULL,
  returnGenotype = FALSE,
  maxVariants = NULL,
  seed = NULL
)

Arguments

rList

List of G precomputed LD correlation matrices (p_g x p_g).

xList

List of G genotype matrices (n x p_g).

ldMetaPath

Path to a pecotmr LD metadata TSV file (as used by loadLdMatrix).

regions

Character vector of G region strings (e.g., "chr22:17238266-19744294"). Required when ldMetaPath is used.

ldInfo

A data.frame with column LD_file (paths to genotype files or .cor.xz LD matrix files) and optionally SNP_file (paths to companion .bim files for pre-computed blocks; defaults to paste0(LD_file, ".bim") if absent). Genotype paths can be PLINK2 prefixes, PLINK1 prefixes, VCF files, or GDS files. As returned by cTWAS meta-data utilities.

returnGenotype

Logical. When using region mode, return the genotype matrix X (TRUE) or LD correlation R (FALSE, default).

maxVariants

Integer or NULL. If set, randomly subsample blocks larger than this to control memory usage.

seed

Integer or NULL. When maxVariants triggers subsampling, seeds the draw (offset by the block index so each block is independent yet reproducible) via a scoped withr::local_seed, so the session RNG is left untouched. NULL (default) leaves the draw under the session RNG, so an outer set.seed() still governs it.

Value

An ldLoaderSpec object (an opaque list describing the source). Pass it with a block index to loadLdBlock to load one block.

Details

Four modes are supported:

list mode (R)

Pre-loaded list of LD correlation matrices. Simple but uses more memory. Set R_list.

list mode (X)

Pre-loaded list of genotype matrices (n x p_g). Set X_list.

region mode

Loads LD from a pecotmr metadata TSV file on the fly via loadLdMatrix. Memory-efficient for large datasets. Set ld_meta_path and regions.

ldInfo mode

Loads pre-computed LD blocks from .cor.xz files listed in an ldInfo data.frame (as returned by cTWAS meta-data utilities). Set ldInfo.

See also

loadLdBlock

Examples

# List mode with pre-computed LD
R1 <- diag(10)
R2 <- diag(15)
spec <- ldLoader(rList = list(R1, R2))
loadLdBlock(spec, 1)  # returns R1
#>       [,1] [,2] [,3] [,4] [,5] [,6] [,7] [,8] [,9] [,10]
#>  [1,]    1    0    0    0    0    0    0    0    0     0
#>  [2,]    0    1    0    0    0    0    0    0    0     0
#>  [3,]    0    0    1    0    0    0    0    0    0     0
#>  [4,]    0    0    0    1    0    0    0    0    0     0
#>  [5,]    0    0    0    0    1    0    0    0    0     0
#>  [6,]    0    0    0    0    0    1    0    0    0     0
#>  [7,]    0    0    0    0    0    0    1    0    0     0
#>  [8,]    0    0    0    0    0    0    0    1    0     0
#>  [9,]    0    0    0    0    0    0    0    0    1     0
#> [10,]    0    0    0    0    0    0    0    0    0     1
loadLdBlock(spec, 2)  # returns R2
#>       [,1] [,2] [,3] [,4] [,5] [,6] [,7] [,8] [,9] [,10] [,11] [,12] [,13]
#>  [1,]    1    0    0    0    0    0    0    0    0     0     0     0     0
#>  [2,]    0    1    0    0    0    0    0    0    0     0     0     0     0
#>  [3,]    0    0    1    0    0    0    0    0    0     0     0     0     0
#>  [4,]    0    0    0    1    0    0    0    0    0     0     0     0     0
#>  [5,]    0    0    0    0    1    0    0    0    0     0     0     0     0
#>  [6,]    0    0    0    0    0    1    0    0    0     0     0     0     0
#>  [7,]    0    0    0    0    0    0    1    0    0     0     0     0     0
#>  [8,]    0    0    0    0    0    0    0    1    0     0     0     0     0
#>  [9,]    0    0    0    0    0    0    0    0    1     0     0     0     0
#> [10,]    0    0    0    0    0    0    0    0    0     1     0     0     0
#> [11,]    0    0    0    0    0    0    0    0    0     0     1     0     0
#> [12,]    0    0    0    0    0    0    0    0    0     0     0     1     0
#> [13,]    0    0    0    0    0    0    0    0    0     0     0     0     1
#> [14,]    0    0    0    0    0    0    0    0    0     0     0     0     0
#> [15,]    0    0    0    0    0    0    0    0    0     0     0     0     0
#>       [,14] [,15]
#>  [1,]     0     0
#>  [2,]     0     0
#>  [3,]     0     0
#>  [4,]     0     0
#>  [5,]     0     0
#>  [6,]     0     0
#>  [7,]     0     0
#>  [8,]     0     0
#>  [9,]     0     0
#> [10,]     0     0
#> [11,]     0     0
#> [12,]     0     0
#> [13,]     0     0
#> [14,]     1     0
#> [15,]     0     1