Explicit GLIMPSE2 Operations from R

Contract

RGlimpse2 is a thin interface to package-built GLIMPSE2 child executables. Each public operation accepts explicit paths, output names, intervals, seeds, and resource values. Calls do not search PATH, overwrite outputs, or retain workflow state.

Resolve one coherent executable set before running operations:

library(RGlimpse2)

executables <- rglimpse2_executables(phase_backend = "auto")
if (rglimpse2_is_error(executables)) {
  stop(executables@message)
}

Select an installed genetic map

The package includes GRCh37 and GRCh38 maps for chromosomes 1-22, X non-PAR, X PAR1, and X PAR2. It also includes explicitly labelled two-anchor, zero-recombination coordinate maps for Y non-PAR and mitochondrial sequence. Those derived files satisfy the GLIMPSE map format. Native tests run real haploid BCF targets through all four executables for prefixed and unprefixed Y and mitochondrial aliases; this validates mechanics, not scientific calibration of Y or mitochondrial imputation.

genetic_map <- rglimpse2_genetic_map("GRCh38", "22")
y37_nonpar_map <- rglimpse2_genetic_map("GRCh37", "Y")
y38_nonpar_map <- rglimpse2_genetic_map("GRCh38", "Y")
mt37_map <- rglimpse2_genetic_map("GRCh37", "chrM")
mt38_map <- rglimpse2_genetic_map("GRCh38", "MT")
rglimpse2_genetic_maps()

Chunk and split the reference

chunk_result <- rglimpse2_chunk(
  input_sites = "/data/reference.sites.bcf",
  region = "chr22",
  output_chunks = "/work/chunks.chr22.txt",
  executable = executables@chunk,
  genetic_map = genetic_map,
  seed = 101L,
  threads = 2L
)

Each chunk table row supplies a buffered input region and contained output region for rglimpse2_split_reference():

split_result <- rglimpse2_split_reference(
  reference_bcf = "/data/reference.bcf",
  input_region = "chr22:100000-600000",
  output_region = "chr22:150000-550000",
  output_prefix = "/work/reference",
  executable = executables@split_reference,
  genetic_map = genetic_map,
  seed = 102L,
  threads = 2L
)

Phase and ligate

The current deterministic phase contract requires threads = 1L. Parallelize across independent chunks rather than inside a phase child:

phase_result <- rglimpse2_phase(
  input_gl = "/data/sample.gl.bcf",
  reference_bin = split_result@outputs$reference_bin,
  output_bcf = "/work/phase.chr22.1.bcf",
  executable = executables@phase,
  seed = 103L,
  threads = 1L
)

For low-pass whole-genome sequencing, the phase executable can call SNP likelihoods directly from one coordinate-sorted BAM or CRAM. Supply the alignment index explicitly; it must use an adjacent name HTSlib can discover. CRAM also requires the reference FASTA and adjacent .fai.

phase_bam_result <- rglimpse2_phase_bam(
  input_bam = "/data/sample.bam",
  input_index = "/data/sample.bam.bai",
  reference_bin = split_result@outputs$reference_bin,
  output_bcf = "/work/phase-bam.chr22.1.bcf",
  executable = executables@phase,
  seed = 103L,
  sample_name = "sample",
  sample_ploidy = 2L
)

The default calls likelihoods at SNPs and keeps flat likelihoods at indels. Set call_indels = TRUE only when the GLIMPSE2 indel calling model is intended.

After writing an ordered file containing one absolute phase-output path per line, ligate the chunks:

ligate_result <- rglimpse2_ligate(
  input_list = "/work/phase-files.txt",
  output_bcf = "/work/phase.chr22.bcf",
  executable = executables@ligate,
  seed = 104L,
  threads = 2L
)

Successful operations return RGlimpse2RunResult. Expected missing inputs, occupied outputs, unavailable executables, and child-process failures return an RGlimpse2ErrorValue subclass. Contract violations signal an rglimpse2_contract_violation condition.

SIMD selection

info <- rglimpse2_simd_info()
info@compiled_backends
info@cpu_supported_backends
info@selected_backend

Automatic dispatch only selects the intersection of installed binaries and CPU/operating-system support. Explicit "scalar", "avx2", "avx512", or "neon" requests return a typed unavailable-backend value rather than starting an unsupported executable.