voiage 2.0.0

Value of Information analysis with a Rust core and Python, R, and Julia interfaces.

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, 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.0.0 release.

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.

Capability status

Capability	Status	Scope
EVPI, EVPPI, ENBS	Stable	Python API and CLI with Rust-owned numerical policy
EVSI	Method-specific	The analytical two-arm normal path is stable; the developing two-loop path uses one coherent fitted Gaussian prior or explicit custom sampling and joint-posterior callbacks; compatibility estimators without a complete validated study-model contract are non-stable
Acceptability, frontier, dominance, heterogeneity	Stable	Analysis and plotting helpers
Structural and network meta-analysis VOI	Stable	Python method surface
Adaptive, calibration, observational, sequential VOI	Stable	Python study-design workflows
Portfolio VOI	Stable	Budget-constrained portfolio analysis
Diagnostics and data interchange	Stable	Versioned contracts; Arrow/Parquet is the canonical tabular interchange
R and Julia EVPI	Released binding source	Direct versioned Rust interface; both require the separately supplied voiage-ffi library
Broader R and Julia method parity	Partial	Advanced R paths retain the documented Python bridge; Julia is EVPI-focused
Perspective and frontier extensions	Experimental	Fixture-backed contracts; not represented as stable
Mojo binding	Not released	No publishable Mojo package is claimed
FPGA and ASIC execution	Evidence only	Simulation and pre-silicon evidence do not establish production hardware support

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

Surface	Source	Current use	Distribution status
Python	voiage/	Primary API, CLI, orchestration, plots, reports	PyPI v2.0.0 and TestPyPI
Rust	rust/	Domain contracts, diagnostics, selected kernels, serialization	Crates are package-ready; consult the release checklist for verified registry state
R	r-package/voiageR/	Direct C-ABI EVPI; documented bridge for wider Python methods	r-universe; CRAN review remains external
Julia	bindings/julia/	Direct C-ABI EVPI	Prepared for Julia General; registry entry is not yet verified

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

Area	Repository controls
Style and prose	Ruff formatting/linting, Vale, ChkTeX, LaCheck
Static analysis	ty, BasedPyright, Bandit, Vulture, Clippy, CodeQL
Unit and contract testing	Pytest and Cargo tests across APIs, schemas, versions, provenance, and registries
Integration and end-to-end testing	CLI, package, clean-install, workflow, FFI, and cross-language paths
Generative testing	Hypothesis, proptest, metamorphic, differential, and parity checks
Mutation testing	Ratcheted Python mutation cohorts and critical-kernel policy
Coverage	Branch coverage, changed-line policy, critical-module checks, Codecov, and a 90% Python threshold
Rust-specific assurance	MSRV, Clippy, Miri, fuzzing, sanitizer jobs, advisory and license policy
Supply chain	Pinned Actions, Dependency Review, OpenSSF Scorecard, Zizmor, SBOMs, checksums, provenance attestations, and release signatures
Platform assurance	Linux, macOS, Windows, UTF-8/LF, Python 3.12–3.14, minimum and maximum dependencies
Documentation and papers	Astro/Starlight builds, link/semantic checks, arXiv source and PDF audits, deterministic readability evidence

Dependabot manages Python, Cargo, npm, and GitHub Actions updates. Renovate is not also enabled because running two update bots over the same manifests would 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.0.0
• Python package: PyPI
• Citation metadata: CITATION.cff
• Software metadata: codemeta.json
• Software Heritage snapshot: swh:1:snp:767efde24c97d9f6d730764c1b3bc1a91ba20c32

The canonical preprint source is paper/main.tex. Repository automation builds, lints, audits, and packages the manuscript. Authenticated arXiv submission 7861466 is verified as submitted, but a permanent arXiv identifier and announcement have not yet been assigned. 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/RRID curation and 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.