Package 'RGlimpse2'

Create deterministic GLIMPSE2 imputation chunks

Description

Invokes GLIMPSE2_chunk once. All paths are explicit and the output file must not already exist.

Usage

rglimpse2_chunk(
  input_sites,
  region,
  output_chunks,
  executable,
  genetic_map,
  seed,
  threads = 1L,
  algorithm = c("sequential", "recursive"),
  window_cm = 2.5,
  window_mb = 2,
  window_count = 20000L,
  buffer_cm = 0.5,
  buffer_mb = 0.4,
  buffer_count = 2000L,
  sparse_maf = 0.001,
  log = character()
)

Arguments

input_sites	Absolute VCF/BCF sites path.
region	Contig or genomic interval to split.
output_chunks	Absolute output chunk-table path.
executable	Absolute GLIMPSE2_chunk path.
genetic_map	Absolute genetic-map path, such as one returned by rglimpse2_genetic_map().
seed	Non-negative random seed.
threads	Positive worker count.
algorithm	Chunking algorithm.
window_cm, window_mb	Positive minimum window sizes.
window_count	Positive minimum window variant count.
buffer_cm, buffer_mb	Positive minimum buffer sizes.
buffer_count	Positive minimum buffer variant count.
sparse_maf	Rare-variant threshold in ⁠[0, 0.5)⁠.
log	Empty or one absolute log output path.

Value

RGlimpse2RunResult or an RGlimpse2ErrorValue.

---

Construct a typed RGlimpse2 contract condition

Description

Construct a typed RGlimpse2 contract condition

Usage

rglimpse2_contract_violation(
  message,
  call = NULL,
  code = "invalid_contract",
  details = list()
)

Arguments

message	Human-readable description.
call	Call associated with the violation.
code	Stable machine-readable code.
details	Structured condition details.

Value

An rglimpse2_contract_violation condition.

---

Construct a typed RGlimpse2 operational error

Description

Construct a typed RGlimpse2 operational error

Usage

rglimpse2_error_value(
  message,
  kind = c("input", "output", "process"),
  code,
  details = list(),
  source = NULL,
  operation = character(),
  status = integer()
)

Arguments

message	Human-readable description.
kind	Operational error category.
code	Stable machine-readable code.
details	Structured error details.
source	Optional source condition or backend value.
operation	Child-process operation for process errors.
status	Child-process exit status when available.

Value

An RGlimpse2ErrorValue subclass.

---

Resolve packaged or explicitly supplied GLIMPSE2 executables

Description

This function never searches PATH. Supply either one absolute directory containing all four standard executable names or all four absolute paths. With no supplied paths, only the installed package directory is inspected; phase_backend then selects a portable or AVX2 phase executable.

Usage

rglimpse2_executables(
  directory = character(),
  chunk = character(),
  split_reference = character(),
  phase = character(),
  ligate = character(),
  phase_backend = "auto"
)

Arguments

directory	Empty or one absolute executable directory.
chunk	Absolute path to GLIMPSE2_chunk.
split_reference	Absolute path to GLIMPSE2_split_reference.
phase	Absolute path to the selected GLIMPSE2_phase executable.
ligate	Absolute path to GLIMPSE2_ligate.
phase_backend	Packaged phase backend: "auto", "scalar", "avx2", "avx512", or "neon". It must remain "auto" for explicitly supplied executables.

Value

RGlimpse2Executables or RGlimpse2InputErrorValue.

---

Resolve packaged GRCh37 or GRCh38 genetic maps

Description

rglimpse2_genetic_map() resolves one absolute installed map path. rglimpse2_genetic_maps() returns the complete packaged inventory. The autosomal and chromosome X files are byte-identical copies from the pinned GLIMPSE source tree. The Y non-PAR and mitochondrial files are derived two-anchor, zero-recombination coordinate maps, not empirical maps.

Usage

rglimpse2_genetic_maps()

rglimpse2_genetic_map(assembly = "GRCh38", chromosome, region = character())

Arguments

assembly	Reference assembly, either "GRCh37" or "GRCh38".
chromosome	One autosome named "1" through "22", "X", "Y", or "MT". A leading "chr" is accepted. Mitochondrial aliases "M", "MT", "chrM", and "chrMT" all resolve to the same map.
region	Empty to select the chromosome default, or one of "full", "nonpar", "par1", or "par2". The default is "nonpar" for X and Y and "full" otherwise.

Value

rglimpse2_genetic_map() returns one absolute file path. rglimpse2_genetic_maps() returns a data frame describing every map and its absolute installed path.

Examples

rglimpse2_genetic_map("GRCh38", "22")
rglimpse2_genetic_map("GRCh37", "Y")
rglimpse2_genetic_map("GRCh38", "Y")
rglimpse2_genetic_map("GRCh37", "chrM")
rglimpse2_genetic_map("GRCh38", "MT")
head(rglimpse2_genetic_maps())

---

Test whether a value is an RGlimpse2 operational error

Description

Test whether a value is an RGlimpse2 operational error

Usage

rglimpse2_is_error(value)

Arguments

value

Any R value.

Value

A logical scalar.

---

Ligate ordered GLIMPSE2 chunk outputs

Description

Invokes GLIMPSE2_ligate once. The input list must contain exactly one existing absolute VCF/BCF path per line in chromosome order. Blank lines and surrounding whitespace are rejected because the native reader treats them as part of a path.

Usage

rglimpse2_ligate(
  input_list,
  output_bcf,
  executable,
  seed,
  threads = 1L,
  log = character()
)

Arguments

input_list	Absolute text-file path containing ordered chunk paths.
output_bcf	Absolute output .bcf, .vcf, or .vcf.gz path.
executable	Absolute GLIMPSE2_ligate path.
seed	Non-negative random seed.
threads	Positive worker count.
log	Empty or one absolute log output path.

Value

RGlimpse2RunResult or an RGlimpse2ErrorValue.

---

Phase and impute one GLIMPSE2 chunk from genotype likelihoods

Description

Invokes GLIMPSE2_phase once against a binary reference chunk. RGlimpse2 currently requires one internal phase thread so a fixed seed is not coupled to worker scheduling; parallelism belongs across independent chunks.

Usage

rglimpse2_phase(
  input_gl,
  reference_bin,
  output_bcf,
  executable,
  seed,
  threads = 1L,
  sample_ploidy = character(),
  input_field = c("PL", "GL"),
  burnin = 5L,
  main = 15L,
  ne = 100000L,
  pbwt_depth = 12L,
  pbwt_modulo_cm = 0.1,
  k_init = 1000L,
  k_pbwt = 2000L,
  impute_reference_only_variants = FALSE,
  use_gl_indels = FALSE,
  log = character()
)

Arguments

input_gl	Absolute VCF/BCF genotype-likelihood path.
reference_bin	Absolute GLIMPSE2 binary reference path.
output_bcf	Absolute .bcf, .vcf, or .vcf.gz output path.
executable	Absolute selected GLIMPSE2_phase path.
seed	Non-negative random seed.
threads	Must be 1L under the current deterministic contract.
sample_ploidy	Empty or one absolute sample/ploidy table path.
input_field	Genotype likelihood field, "PL" or "GL".
burnin	Number of burn-in iterations.
main	Number of main iterations, at most 15.
ne	Positive effective diploid population size.
pbwt_depth	Positive PBWT neighbour depth.
pbwt_modulo_cm	Positive PBWT selection spacing in cM.
k_init, k_pbwt	Positive conditioning-state limits.
impute_reference_only_variants	Whether to admit sporadically absent target likelihood records from the reference.
use_gl_indels	Whether to consume input likelihoods at indels rather than use the default flat-likelihood scaffold behavior.
log	Empty or one absolute log output path.

Value

RGlimpse2RunResult or an RGlimpse2ErrorValue.

---

Phase and impute one GLIMPSE2 chunk directly from one BAM or CRAM

Description

Invokes GLIMPSE2_phase once against a binary reference chunk and one coordinate-sorted, indexed alignment. The alignment index is an explicit input and must use a filename that HTSlib's sam_index_load() will discover beside the alignment. RGlimpse2 fixes the internal phase thread count at one so a supplied seed is not coupled to worker scheduling; callers should parallelize independent chunks.

Usage

rglimpse2_phase_bam(
  input_bam,
  input_index,
  reference_bin,
  output_bcf,
  executable,
  seed,
  sample_name = character(),
  sample_ploidy = integer(),
  reference_fasta = character(),
  reference_fasta_index = character(),
  mapq = 10L,
  baseq = 10L,
  max_depth = 40L,
  call_indels = FALSE,
  keep_orphan_reads = FALSE,
  ignore_orientation = FALSE,
  check_proper_pairing = FALSE,
  keep_failed_qc = FALSE,
  keep_duplicates = FALSE,
  burnin = 5L,
  main = 15L,
  ne = 100000L,
  pbwt_depth = 12L,
  pbwt_modulo_cm = 0.1,
  k_init = 1000L,
  k_pbwt = 2000L,
  log = character()
)

Arguments

input_bam	Absolute .bam or .cram alignment path.
input_index	Absolute BAM/CRAM index path. BAM accepts adjacent .bai or .csi naming; CRAM accepts adjacent .crai naming.
reference_bin	Absolute GLIMPSE2 binary reference path.
output_bcf	Absolute .bcf output path.
executable	Absolute selected GLIMPSE2_phase path.
seed	Non-negative random seed.
sample_name	Empty or one output sample name. When omitted, GLIMPSE2 derives the name from the alignment filename.
sample_ploidy	Empty or one integer, 1L or 2L. If supplied without sample_name, the alignment filename stem is used for the temporary sample/ploidy table passed to GLIMPSE2.
reference_fasta	Empty or one absolute faidx-indexed reference FASTA. Required for CRAM input.
reference_fasta_index	Empty or one absolute FASTA index path. Required with reference_fasta and must be paste0(reference_fasta, ".fai"), which is the path HTSlib will discover.
mapq	Minimum read mapping quality.
baseq	Minimum base quality.
max_depth	Maximum reads retained at one site before downsampling.
call_indels	Whether to compute genotype likelihoods at reference indels. The default leaves indel likelihoods flat while retaining the reference haplotype scaffold.
keep_orphan_reads	Whether to keep paired reads whose mate is unmapped.
ignore_orientation	Whether to ignore mate-pair orientation.
check_proper_pairing	Whether to discard reads not marked as properly paired.
keep_failed_qc	Whether to keep reads marked as failed sequencing QC.
keep_duplicates	Whether to keep reads marked as duplicates.
burnin	Number of burn-in iterations.
main	Number of main iterations, at most 15.
ne	Positive effective diploid population size.
pbwt_depth	Positive PBWT neighbour depth.
pbwt_modulo_cm	Positive PBWT selection spacing in cM.
k_init, k_pbwt	Positive conditioning-state limits.
log	Empty or one absolute log output path.

Value

RGlimpse2RunResult or an RGlimpse2ErrorValue.

---

Phase and impute one GLIMPSE2 chunk directly from several BAMs or CRAMs

Description

Invokes GLIMPSE2_phase once with its native --bam-list input. Genotype likelihoods are computed from every alignment inside that process; no intermediate likelihood VCF or BCF is written. The BAM list and the complete sample/ploidy file are private temporary inputs removed before this function returns.

Usage

rglimpse2_phase_bams(
  alignments,
  reference_bin,
  output_bcf,
  executable,
  seed,
  reference_fasta = character(),
  reference_fasta_index = character(),
  mapq = 10L,
  baseq = 10L,
  max_depth = 40L,
  call_indels = FALSE,
  keep_orphan_reads = FALSE,
  ignore_orientation = FALSE,
  check_proper_pairing = FALSE,
  keep_failed_qc = FALSE,
  keep_duplicates = FALSE,
  burnin = 5L,
  main = 15L,
  ne = 100000L,
  pbwt_depth = 12L,
  pbwt_modulo_cm = 0.1,
  k_init = 1000L,
  k_pbwt = 2000L,
  log = character()
)

Arguments

alignments	A non-empty data frame with one row per sample and columns: input_bam (character absolute .bam or .cram path), input_index (character absolute adjacent index path), sample_name (character unique sample name without whitespace), and sample_ploidy (numeric integer value 1 or 2). Alignment paths cannot contain whitespace because GLIMPSE2_phase --bam-list uses a whitespace-delimited native format.
reference_bin	Absolute GLIMPSE2 binary reference path.
output_bcf	Absolute .bcf output path.
executable	Absolute selected GLIMPSE2_phase path.
seed	Non-negative random seed.
reference_fasta	Empty or one absolute faidx-indexed reference FASTA. Required when any row in alignments is a CRAM.
reference_fasta_index	Empty or one absolute FASTA index path. Required with reference_fasta and must be paste0(reference_fasta, ".fai"), which is the path HTSlib will discover.
mapq	Minimum read mapping quality.
baseq	Minimum base quality.
max_depth	Maximum reads retained at one site before downsampling.
call_indels	Whether to compute genotype likelihoods at reference indels. The default leaves indel likelihoods flat while retaining the reference haplotype scaffold.
keep_orphan_reads	Whether to keep paired reads whose mate is unmapped.
ignore_orientation	Whether to ignore mate-pair orientation.
check_proper_pairing	Whether to discard reads not marked as properly paired.
keep_failed_qc	Whether to keep reads marked as failed sequencing QC.
keep_duplicates	Whether to keep reads marked as duplicates.
burnin	Number of burn-in iterations.
main	Number of main iterations, at most 15.
ne	Positive effective diploid population size.
pbwt_depth	Positive PBWT neighbour depth.
pbwt_modulo_cm	Positive PBWT selection spacing in cM.
k_init, k_pbwt	Positive conditioning-state limits.
log	Empty or one absolute log output path.

Details

RGlimpse2 fixes the internal phase thread count at one so a supplied seed is not coupled to worker scheduling. The final BCF and its CSI index are published without replacing existing paths only after the child process succeeds.

Value

RGlimpse2RunResult with output_bcf and output_index paths, or an RGlimpse2ErrorValue.

---

Inspect and resolve packaged GLIMPSE2 phase SIMD executables

Description

This function does not set process-global state. Pass the same backend to rglimpse2_executables() to obtain the selected executable explicitly. AVX-512 means AVX-512F, AVX-512BW, and AVX-512VL with enabled OS ZMM state.

Usage

rglimpse2_simd_info(phase_backend = "auto")

Arguments

phase_backend

One of "auto", "scalar", "avx2", "avx512", or "neon".

Value

RGlimpse2SimdInfo or RGlimpse2InputErrorValue when the requested backend is unavailable.

---

Build one GLIMPSE2 binary reference chunk

Description

Invokes GLIMPSE2_split_reference once. output_region must be contained within input_region; both regions must name the same contig. Before the child process starts, RGlimpse2 scans the requested reference region and rejects records whose allele count is not exactly two. Reference preparation must split or otherwise resolve multiallelic records before this call.

Usage

rglimpse2_split_reference(
  reference_bcf,
  input_region,
  output_region,
  output_prefix,
  executable,
  genetic_map,
  seed,
  threads = 1L,
  sparse_maf = 0.001,
  keep_monomorphic_ref_sites = FALSE,
  log = character()
)

Arguments

reference_bcf	Absolute phased reference VCF/BCF path.
input_region	Buffered region in contig:start-end form.
output_region	Unbuffered region in contig:start-end form.
output_prefix	Absolute output prefix. GLIMPSE2 appends the normalized input region and .bin.
executable	Absolute GLIMPSE2_split_reference path.
genetic_map	Absolute genetic-map path, such as one returned by rglimpse2_genetic_map().
seed	Non-negative random seed.
threads	Positive worker count.
sparse_maf	Rare-variant threshold in ⁠[0, 0.5)⁠.
keep_monomorphic_ref_sites	Whether to retain monomorphic reference records.
log	Empty or one absolute log output path.

Value

RGlimpse2RunResult or an RGlimpse2ErrorValue.

---

A typed RGlimpse2 operational error value

Description

Invalid calls signal rglimpse2_contract_violation() conditions. Expected missing inputs, occupied outputs, unavailable executables, and child-process failures are returned as values so callers can branch without parsing messages.

Usage

RGlimpse2ErrorValue(
  message = character(0),
  code = character(0),
  details = list(),
  source = NULL,
  operation = character(0),
  status = integer(0)
)

RGlimpse2InputErrorValue(
  message = character(0),
  code = character(0),
  details = list(),
  source = NULL,
  operation = character(0),
  status = integer(0)
)

RGlimpse2OutputErrorValue(
  message = character(0),
  code = character(0),
  details = list(),
  source = NULL,
  operation = character(0),
  status = integer(0)
)

RGlimpse2ProcessErrorValue(
  message = character(0),
  code = character(0),
  details = list(),
  source = NULL,
  operation = character(0),
  status = integer(0)
)

Arguments

message	Human-readable description.
code	Stable machine-readable code.
details	Structured error details.
source	Optional source condition or backend value.
operation	Empty or one stable child-process operation identifier.
status	Empty or one child-process exit status.

---

Explicit GLIMPSE2 child executables

Description

Explicit GLIMPSE2 child executables

Usage

RGlimpse2Executables(
  chunk = character(0),
  split_reference = character(0),
  phase = character(0),
  ligate = character(0),
  phase_backend = character(0)
)

Arguments

chunk	Absolute path to GLIMPSE2_chunk.
split_reference	Absolute path to GLIMPSE2_split_reference.
phase	Absolute path to the selected GLIMPSE2_phase executable.
ligate	Absolute path to GLIMPSE2_ligate.
phase_backend	Backend represented by phase.

---

A completed RGlimpse2 child-process operation

Description

A completed RGlimpse2 child-process operation

Usage

RGlimpse2RunResult(
  operation = character(0),
  outputs = list(),
  status = integer(0),
  stdout = character(0),
  stderr = character(0)
)

Arguments

operation	Stable operation identifier.
outputs	Named output paths produced by the operation.
status	Child-process exit status.
stdout	Captured standard output.
stderr	Captured standard error.

---

RGlimpse2 phasing-executable dispatch information

Description

RGlimpse2 dispatches whole child executables rather than mutating a backend in the R process. The scalar SIMDe executable is always the fallback. A native executable is selected only when it was built and the package's baseline CPUID/HWCAP probe confirms CPU and operating-system support.

Usage

RGlimpse2SimdInfo(
  requested_backend = character(0),
  selected_backend = character(0),
  compiled_backends = character(0),
  cpu_supported_backends = character(0),
  available_backends = character(0),
  phase_executable = character(0),
  target_arch = character(0),
  target_os = character(0)
)

Arguments

requested_backend	Requested backend ("auto", "scalar", "avx2", "avx512", or "neon").
selected_backend	Resolved backend.
compiled_backends	Backends represented by installed executables.
cpu_supported_backends	Backends supported by the runtime CPU and OS.
available_backends	Intersection of compiled and CPU-supported backends.
phase_executable	Selected absolute executable path.
target_arch, target_os	Baseline probe target identifiers.

---