voiage: Value of Information Analysis

voiage provides Value of Information (VOI) methods for comparing decisions under uncertainty and assessing whether additional evidence may be worth collecting. The v2.0 release combines:

• a Python API and command-line interface (CLI);
• binding-independent Rust domain, diagnostics, numerical, and serialization crates;
• selected Rust-backed aggregation kernels exposed to Python through PyO3;
• an R package and Julia package that call the versioned Rust C application binary interface (ABI) for Expected Value of Perfect Information (EVPI);
• labelled data structures, diagnostics, plotting, reporting, and provenance-aware interchange.

Python currently retains the broader model orchestration, validation, labelled data, plotting, and reporting paths. The R and Julia packages do not yet expose the full Python method surface. See Architecture and Language support for the precise boundary.

When voiage is useful

VOI analysis asks whether uncertainty could change a decision and whether the expected benefit of resolving some uncertainty justifies further research. voiage supports analyses including:

• EVPI for the expected cost of current decision uncertainty;
• Expected Value of Partial Perfect Information (EVPPI) for selected parameters;
• Expected Value of Sample Information (EVSI) and Expected Net Benefit of Sampling (ENBS) for proposed studies;
• cost-effectiveness acceptability and frontier analysis;
• structural, network meta-analysis, subgroup, sequential, adaptive, and portfolio-oriented VOI workflows;
• fixture-backed experimental work on perspective, equity, implementation, expected-utility information pricing, and adjacent VOI questions.

Stable and experimental surfaces are distinguished in the method documentation and frontier roadmap. An implemented method is not, by itself, evidence that it is appropriate for a particular decision problem; users remain responsible for model structure, inputs, assumptions, and interpretation.

Installation

Install the released Python package:

python -m pip install voiage

Python 3.12, 3.13, and 3.14 are supported. Wheels use the CPython 3.12 stable ABI and are published for the platforms listed in the v2.1.0 release.

The current source tree prepares v2.2.0; its publication and review submissions remain pending the release gates.

Optional features are installed explicitly:

python -m pip install "voiage[plotting]"       # Matplotlib and Seaborn
python -m pip install "voiage[jax]"            # experimental JAX backend
python -m pip install "voiage[experimental]"   # experimental serializers

Development installation and complete verification instructions are in CONTRIBUTING.md.

Quick start

import numpy as np

from voiage.analysis import DecisionAnalysis
from voiage.schema import ValueArray

net_benefit = ValueArray.from_numpy(
    np.array(
        [
            [10.0, 12.0],
            [11.0, 9.0],
            [13.0, 14.0],
        ]
    ),
    strategy_names=["Standard care", "New treatment"],
)

analysis = DecisionAnalysis(net_benefit)
print(f"EVPI: {analysis.evpi():.3f}")

The rows are uncertainty draws and the columns are decision strategies. For real analyses, preserve the units, population scaling, time horizon, discount rate, and strategy labels needed to interpret the result.

Command-line interface

The CLI supports batch workflows over CSV inputs:

voiage calculate-evpi examples/cli_samples/evpi_net_benefit.csv

voiage calculate-evpi examples/cli_samples/evpi_net_benefit.csv \
  --population 100000 \
  --time-horizon 10 \
  --discount-rate 0.03 \
  --output evpi-result.txt

voiage calculate-evppi \
  examples/cli_samples/evpi_net_benefit.csv \
  examples/cli_samples/evppi_parameters.csv

voiage --help

See the CLI reference for input schemas, output formats, logging controls, and additional commands.

Standardized dataset ingestion

voiage can also safely normalize conservative local profiles of Croissant ML 1.1 and Frictionless Data Package CSV descriptors before calculation. Source format parsers remain separate from the calculation runtime: each produces an Arrow-backed NormalizedInputBundle, and callers supply an explicit VOI binding. Use voiage ingest validate, voiage ingest inspect, and voiage ingest normalize for a descriptor workflow; remote URLs, archives, implicit column inference, and unsafe paths are rejected. See the standardized-ingestion guide for the supported-profile matrix, offline replay policy, and ML, engineering, and business examples.

Capability status

Architecture

The repository is moving towards a binding-independent Rust core, but v2.0 is still a hybrid implementation:

Python API / CLI / orchestration / labelled data / plots / reports
                              |
                         PyO3 adapter
                              |
Rust domain + diagnostics + selected numerical kernels + serialization
                              |
                    versioned C ABI adapter
                         /             \
                  R package        Julia package

The publishable Rust workspace crates live under rust/crates/:

• voiage-domain: validated binding-independent domain contracts;
• voiage-diagnostics: structured diagnostics and error contracts;
• voiage-numerics: binding-independent numerical kernels;
• voiage-serialization: canonical serialization adapters.

The voiage-ffi, voiage-python, and voiage-test-support crates are private adapters or test infrastructure. Python remains responsible for wider method orchestration and user-facing analytical features not yet migrated to Rust. The polyglot release documentation records the supported boundary and migration policy.

Language support

Registry readiness and actual registry publication are reported separately. The binding submission checklist is the maintained evidence record for conda-forge, CRAN, Julia General, crates.io, and other external channels.

Documentation and examples

• Documentation home
• Getting started
• Examples and tutorials
• Expected-utility information example
• Method reference
• Data structures
• Plotting
• Backends
• R package guide
• Julia package guide
• Developer guide

Example plots generated by the maintained documentation fixtures:

Acceptability curve	EVSI and ENBS	EVPI by threshold

Quality, testing, and security

The repository applies different forms of evidence to different failure modes:

Renovate manages Python/uv, Cargo, npm, and GitHub Actions updates. Dependabot version-update configuration is intentionally absent so the repository has one dependency-update bot and does not create duplicate pull requests. Full commands and control boundaries are in the quality and security guide and SECURITY.md.

Releases, citation, and archival

• Latest software release: v2.1.0
• Python package: PyPI
• Citation metadata: CITATION.cff
• Software metadata: codemeta.json
• Software Heritage snapshot: swh:1:snp:31f89375852737bb9eb62ebc03fadfbc7ff70c2d

The canonical preprint source is paper/main.tex. Repository automation builds, lints, audits, and packages the non-submitting arXiv source. Permanent arXiv announcement and identifier assignment remain an author-controlled external gate. The separate paper.md adaptation passes repository-owned JOSS preflight; no JOSS submission, review, or acceptance is claimed.

Project status and roadmap

The repository-owned v1 programme is implemented and archived. That does not mean every proposed extension or external publication is complete. Current boundaries include:

• migration of wider Python orchestration into the Rust core;
• broader native R and Julia API parity;
• experimental frontier-method validation and promotion;
• external registry review or indexing where not yet evidenced;
• SciCrunch registration was submitted on 27 July 2026 after a no-match duplicate check and account confirmation; curation and RRID assignment remain external, alongside later arXiv/JOSS author-led submissions;
• physical FPGA or fabricated-silicon evidence.

See roadmap.md, todo.md, and the Conductor registry for evidence-backed status.

Contributing and support

This is currently a solo-maintainer repository. Pull requests remain the auditable change boundary, with automated quality and security checks required but no independent approval requirement. See:

• Contributing guide
• Support
• Code of conduct
• Security policy
• Changelog

Use GitHub Issues for reproducible bugs and feature requests, and GitHub Discussions for design or usage questions.

License

voiage is licensed under the Apache License 2.0.