---
title: "Getting Started with voiageR"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with voiageR}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

# Overview

`voiageR` is the thin R interface to the `voiage` Python library. It exposes
the stable EVPI, EVPPI, and EVSI wrappers while keeping the package surface
small, predictable, and suitable for scripted use.

The examples below are intentionally non-interactive. They show the package
shape, the Python environment setup, and the canonical data contracts without
requiring the vignette build to depend on a live Python session.

# Set up the Python environment

```{r setup-env}
library(voiageR)

set_voiage_env("voiage", type = "virtualenv")
init_voiage()
```

If you manage Python through Conda, use:

```{r setup-conda}
set_voiage_env("voiage", type = "conda")
```

# EVPI

```{r evpi}
net_benefits <- matrix(
  c(10.0, 12.0, 11.0, 9.0, 13.0, 14.0),
  nrow = 3,
  byrow = TRUE,
  dimnames = list(NULL, c("Strategy A", "Strategy B"))
)

evpi(net_benefits)
```

# EVPPI

```{r evppi}
parameter_samples <- list(
  effect = c(0.10, 0.12, 0.11),
  cost = c(1000, 980, 1025)
)

evppi(net_benefits, parameter_samples, parameters_of_interest = "effect")
```

# EVSI

```{r evsi}
model_func <- function(params) {
  cbind(
    Strategy_A = params$effect * 100 - params$cost,
    Strategy_B = params$effect * 110 - params$cost
  )
}

prior_samples <- list(
  effect = c(0.10, 0.12, 0.11),
  cost = c(1000, 980, 1025)
)

trial_design <- list(
  arms = list(
    list(name = "Treatment", sample_size = 50),
    list(name = "Control", sample_size = 50)
  )
)

evsi(
  model_func,
  prior_samples,
  trial_design,
  method = "efficient",
  n_outer_loops = 100,
  n_inner_loops = 1000
)
```

# Current wrapper surface

The current R package exports the core analysis wrappers only:

- `evpi()` for perfect-information value
- `evppi()` for parameter-specific information value
- `evsi()` for sample-information value

Composite metrics such as ENBS are currently part of the Python surface and
can be composed from the results above when needed.

# Build outputs

The package ships a deterministic PDF manual build helper at
`tools/build-manual.R`. It is designed for non-interactive use from the package
root and produces a stable manual artifact from the package Rd files for
release packaging and local verification.