Complete pipeline: split genotype matrix by ancestry, return dosage matrices. Handles sample and variant mismatches by using only overlapping data. Memory efficient: single-pass subsetting using index vectors.
ancestry_split_dosage(
gt_matrix = NULL,
pt_matrix = NULL,
vcf_path = NULL,
msp_path = NULL,
chrom = NULL,
verbose = TRUE
)Integer matrix of genotypes (rows=variants, cols=samples).
Values: 0=homozygous ref, 1=heterozygous, 2=homozygous alt.
rownames: variant IDs (e.g., "chr:pos"). colnames: sample IDs.
May be NULL when vcf_path and msp_path are supplied.
Integer matrix of parent-of-origin ancestry codes
(rows=samples, cols=regions/variants).
Values: 1=EUR/EUR, 2=AFR/EUR (mixed), 3=AFR/AFR.
rownames: sample IDs (must match colnames of gt_matrix).
colnames: region IDs (e.g., "chr:start-end").
May be NULL when vcf_path and msp_path are supplied.
Path to a phased VCF or BCF file. When supplied together
with msp_path, the function delegates to
ancestry_split (Step 1, mode = "dosage"), bypassing
the gt_matrix/pt_matrix arguments.
Path to an RFMix MSP file (plain text or gzipped TSV).
Used together with vcf_path as a shortcut input.
Chromosome name to restrict to (e.g. "chr19").
Only used when vcf_path/msp_path are supplied.
Print progress messages (default TRUE)
List with elements:
African ancestry-specific dosage matrix
European ancestry-specific dosage matrix
List of ancestry counts per region/sample
Overlap information
The vcf_path/msp_path shortcut
delegates to ancestry_split, which computes and applies
per-arm global local ancestry (GLA) shrinkage automatically from tract
positions. The direct gt_matrix/pt_matrix path has no
genomic position information and cannot derive GLA automatically, so it
always uses the original (unshrunk) p1/p2 estimator; this path also
reorders and filters variants internally (sample/region overlap,
monomorphic removal), so a caller-supplied gla/arm_id
could not be reliably kept aligned. Call split_diploid
directly (no internal reordering) if you need GLA shrinkage with a
pre-computed gla/arm_id of your own.
# Example with mismatched dimensions
gt <- matrix(c(2, 1, 0, 1, 2, 1), nrow = 2, ncol = 3,
dimnames = list(c("chr1:100", "chr1:200"),
c("sample_A", "sample_B", "sample_C")))
pt <- matrix(c(3, 2, 1, 3, 2, 1), nrow = 3, ncol = 2,
dimnames = list(c("sample_A", "sample_B", "sample_D"),
c("chr1:50-150", "chr1:150-250")))
result <- ancestry_split_dosage(gt, pt)
#> === LANTERN Ancestry Pipeline ===
#> Step 1: Finding sample overlap...
#> Samples: 3 in GT, 3 in PT
#> Common samples: 2
#> Dropped: sample_C, sample_D
#>
#> Step 2: Finding variant/region overlap...
#> No exact matches. Trying coordinate-based matching...
#> Found 2 variants in 2 regions
#> Variants in GT: 2
#> Regions in PT: 2
#> Common variants/regions: 4
#>
#> Step 3: Subsetting matrices...
#>
#> Step 3b: Filtering monomorphic variants...
#>
#> Step 4: Splitting genotypes by ancestry...
#> -> African dosage matrix: 2 x 2
#> -> European dosage matrix: 2 x 2
#>
#> Step 5: Counting ancestries per region...
#> -> African (3): median = 1
#> -> European (1): median = 0
#> -> Mixed (2): median = 1
#>
#> === Pipeline Complete ===
# Only sample_A and sample_B are kept (common to both)
# Only chr1:100 and chr1:200 that overlap regions are kept
# Shortcut: build matrices directly from VCF + MSP
vcf <- system.file("extdata", "toy.vcf.gz", package = "lantern")
msp <- system.file("extdata", "toy.msp.tsv", package = "lantern")
result <- ancestry_split_dosage(vcf_path = vcf, msp_path = msp,
chrom = "chr19", verbose = FALSE)