Introduction to voiageR

voiageR: Value of Information Analysis in R

The voiageR package provides an R interface to the voiage Python library for Value of Information (VOI) analysis. This vignette demonstrates how to use the package to perform common VOI analyses.

Installation

To use voiageR, you first need to install the Python voiage package:

pip install voiage

Then you can install voiageR from GitHub:

# install.packages("devtools")
devtools::install_github("edithatogo/voiage", subdir = "r-package/voiageR")

Basic Usage

Calculating EVPI

The Expected Value of Perfect Information (EVPI) represents the maximum amount a decision-maker should be willing to pay to eliminate all uncertainty in a decision model.

library(voiageR)

# Create sample net benefit data
# 1000 PSA samples, 2 strategies
net_benefits <- matrix(rnorm(2000), nrow = 1000, ncol = 2)

# Calculate EVPI
evpi_value <- evpi(net_benefits)
print(evpi_value)

You can also scale the EVPI to a population:

# Calculate population-level EVPI
evpi_pop <- evpi(
  net_benefits = net_benefits,
  population = 100000,
  time_horizon = 10,
  discount_rate = 0.03
)
print(evpi_pop)

Calculating EVPPI

The Expected Value of Partial Perfect Information (EVPPI) quantifies the value of learning the true value of a specific subset of model parameters.

# Create parameter samples
param_samples <- list(
  param1 = rnorm(1000),
  param2 = rnorm(1000)
)

# Calculate EVPPI
evppi_value <- evppi(net_benefits, param_samples)
print(evppi_value)

Calculating EVSI

The Expected Value of Sample Information (EVSI) estimates the value of conducting a specific study to reduce uncertainty.

model_func <- function(params) {
  cbind(
    Treatment = 50000 * params$mean_treatment - 3000,
    Control = 50000 * params$mean_control
  )
}

set.seed(17)
draws <- 1000L
prior_samples <- list(
  mean_treatment = rnorm(draws, mean = 0.06, sd = 0.03),
  mean_control = rnorm(draws, mean = 0.00, sd = 0.02),
  sd_outcome = rep(1.0, draws)
)

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

evsi_value <- evsi(
  model_func = model_func,
  prior_samples = prior_samples,
  trial_design = trial_design,
  method = "two_loop",
  n_outer_loops = 100L,
  n_inner_loops = 1000L,
  seed = 20260724L
)
print(evsi_value)

The built-in two-loop model lowercases each arm name and replaces spaces with underscores to obtain the required mean_<normalised arm> parameter name. It also requires a finite, strictly positive sd_outcome fixed across all prior draws.

Custom trial-simulation and posterior-sampling callbacks remain Python-only. The R facade does not convert or execute those callbacks and does not claim custom-model parity.

Advanced Features

Using Different Python Environments

If you have installed voiage in a specific Python environment, you can specify which environment to use:

# Use a virtual environment
set_voiage_env("myenv", type = "virtualenv")

# Use a conda environment
set_voiage_env("myenv", type = "conda")

Checking Package Availability

You can check if the voiage Python package is available:

is_available <- is_voiage_available()
print(is_available)

Conclusion

The voiageR package provides a seamless interface between R and the powerful voiage Python library for Value of Information analysis. This allows R users to leverage advanced VOI methods while working in their preferred environment.