---
title: "Explicit GLIMPSE2 Operations from R"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Explicit GLIMPSE2 Operations from R}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", eval = FALSE)
```

## 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:

```{r resolve}
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.

```{r maps}
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

```{r chunk}
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()`:

```{r split}
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:

```{r phase}
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`.

```{r phase-bam}
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:

```{r ligate}
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

```{r dispatch}
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.