Welcome to voiage’s documentation!

voiage is a Python library for Value of Information (VOI) analysis. VOI methods help quantify the economic value of acquiring additional information to reduce uncertainty in decision-making, particularly in fields like health economics, risk analysis, and decision sciences.

This library aims to provide a comprehensive suite of tools for calculating various VOI metrics, including:

  • Expected Value of Perfect Information (EVPI)

  • Expected Value of Partial Perfect Information (EVPPI)

  • Expected Value of Sample Information (EVSI)

  • Expected Net Benefit of Sampling (ENBS)

  • And advanced VOI analyses for structural uncertainty, network meta-analysis, adaptive designs, research portfolios, sequential decisions, observational data, and model calibration.

Contents:

Indices and tables

—

Note: This documentation is currently under development alongside the voiage library. Content will be expanded as features are implemented.

Getting Help

If you encounter any issues or have questions, please raise an issue on GitHub.

Introduction to voiage

What is Value of Information (VOI) Analysis?

Value of Information (VOI) analysis is a quantitative decision analysis technique used to estimate the economic benefit of collecting additional information before making a decision under uncertainty. It helps answer questions like:

  • “Is it worth investing in more research to reduce uncertainty about this decision?”

  • “Which specific uncertainties, if resolved, would provide the most value?”

  • “What is the maximum amount we should be willing to pay for a particular piece of research?”

  • “Which proposed study design offers the best value for money?”

VOI is particularly prominent in health technology assessment (HTA), where decisions about adopting new medical treatments or technologies involve significant uncertainty and potentially large population health and budget impacts. However, its principles are applicable across many fields including environmental management, engineering, finance, and public policy.

Key VOI Metrics

voiage aims to implement a range of VOI metrics, including:

  • Expected Value of Perfect Information (EVPI): The expected increase in net benefit if all uncertainty about model parameters were eliminated. It represents the maximum value of any further research.

  • Expected Value of Partial Perfect Information (EVPPI): The expected increase in net benefit if uncertainty about a specific subset of model parameters were eliminated. Useful for identifying key drivers of decision uncertainty.

  • Expected Value of Sample Information (EVSI): The expected increase in net benefit from conducting a particular research study (e.g., a clinical trial of a specific design and sample size). This is often the most practical VOI metric for guiding research decisions.

  • Expected Net Benefit of Sampling (ENBS): Calculated as EVSI minus the cost of the proposed research. A positive ENBS suggests the research is economically worthwhile.

Why voiage?

While VOI methods are well-established, and implementations exist (notably in R, e.g., BCEA, dampack, voi packages), a comprehensive, modern, and extensible Python library for VOI analysis is still a developing area. voiage aims to:

  • Provide a user-friendly Python API for common and advanced VOI calculations.

  • Leverage the Python scientific computing ecosystem (NumPy, SciPy, Pandas, xarray, NumPyro, JAX) for performance and flexibility.

  • Offer implementations for a wide range of VOI analyses, including those not commonly found in existing packages (e.g., structural VOI, adaptive design EVSI, portfolio VOI).

  • Facilitate integration with modern Bayesian modeling tools (like NumPyro).

  • Support computationally intensive analyses through efficient algorithms and potential backend abstractions (e.g., JAX for GPU/TPU acceleration).

  • Be well-documented and tested to ensure reliability and ease of use for researchers, health economists, and decision analysts.

Target Audience

voiage is intended for:

  • Health economists and HTA practitioners.

  • Decision analysts and operations researchers.

  • Statisticians involved in clinical trial design and Bayesian analysis.

  • Researchers in any field applying decision theory and uncertainty quantification.

  • Students learning about VOI methods.

This documentation will guide you through installing voiage, understanding its core concepts, using its API for various analyses, and contributing to its development.

Installation

voiage can be installed from PyPI using pip, or directly from the source code if you want the latest development version or intend to contribute.

Prerequisites

  • Python 3.8 or higher.

  • pip and setuptools (usually included with Python).

We recommend using a virtual environment (e.g., via venv or conda) to manage project dependencies.

Dependencies

voiage relies on the following core libraries: * NumPy, SciPy, Pandas, and xarray for data structures and numerical computing. * NumPyro for Bayesian modeling. * scikit-learn and statsmodels for statistical modeling and machine learning. * Typer for the command-line interface.

Getting Started

This section provides a quick introduction to using voiage.

Installation

First, ensure you have voiage installed. For the v0.1 release, you can install it from TestPyPI:

pip install --index-url https://test.pypi.org/simple/ --no-deps voiage

Basic Usage: Expected Value of Perfect Information (EVPI)

The Expected Value of Perfect Information (EVPI) is the maximum amount one should be willing to pay to eliminate all uncertainty.

Here’s a simple example of how to calculate EVPI using voiage.

import numpy as np
from voiage.core.data_structures import NetBenefitArray
from voiage.methods.basic import evpi

# Simulate net monetary benefit (NMB) for two interventions across PSA samples
# Let's assume 1000 PSA samples
num_samples = 1000
nmb_intervention_A = np.random.normal(loc=20000, scale=5000, size=num_samples)
nmb_intervention_B = np.random.normal(loc=25000, scale=7000, size=num_samples)

# Combine into a NetBenefitArray
# The columns represent interventions, rows represent PSA samples
nmb_data = np.vstack([nmb_intervention_A, nmb_intervention_B]).T
net_benefit_array = NetBenefitArray(nmb_data)

# Calculate EVPI
# The `population`, `time_horizon`, and `discount_rate` parameters are optional
# and used for scaling the EVPI to a population level. If not provided,
# EVPI is calculated per-decision.

# Example: Calculate per-decision EVPI
evpi_value_per_decision = evpi(net_benefit_array)
print(f"The per-decision EVPI is: {evpi_value_per_decision:.2f}")

# Example: Calculate population-level EVPI
population_size = 100000
time_horizon_years = 10
annual_discount_rate = 0.03

evpi_value_population = evpi(
    net_benefit_array,
    population=population_size,
    time_horizon=time_horizon_years,
    discount_rate=annual_discount_rate,
)
print(f"The population-level EVPI is: {evpi_value_population:.2f}")

This example demonstrates how to set up your net benefit data and call the evpi function.

Basic Usage: Expected Net Benefit of Sampling (ENBS)

Once you have an EVSI (Expected Value of Sample Information) result and know the cost of research, you can calculate the Expected Net Benefit of Sampling (ENBS).

from voiage.methods.sample_information import enbs

# Assume a calculated EVSI value (e.g., from a previous EVSI analysis)
# For this example, we'll use a dummy value.
dummy_evsi_result = 500000.0 # Example EVSI value (e.g., population-level EVSI)
cost_of_research = 150000.0 # Example cost of the research study

# Calculate ENBS
enbs_value = enbs(dummy_evsi_result, cost_of_research)
print(f"The Expected Net Benefit of Sampling (ENBS) is: {enbs_value:.2f}")

if enbs_value > 0:
    print("The research is potentially worthwhile as ENBS is positive.")
else:
    print("The research may not be worthwhile as ENBS is non-positive.")

For more detailed usage and other VOI metrics (EVPPI, EVSI), please refer to the User Guide and API Reference sections.

User Guide:

API Reference:

Examples: